Merge branch 'feat/adhoc-steps-import-export': ad-hoc steps, step import/export, default steps, auto-derived outputs

.gitea/workflows/agent-release.yml

@@ -68,20 +68,23 @@ jobs:
                   cache: true
                   cache-dependency-path: agent/go.sum
 
+            - name: Extract version
+              id: version
+              shell: pwsh
+              run: |
+                  $v = "${{ github.ref_name }}" -replace '^agent/v', ''
+                  "VERSION=$v" | Out-File -Append $env:GITHUB_OUTPUT
+                  # MSI ProductVersion must be numeric x.x.x.x
+                  "MSIVERSION=$v.0" | Out-File -Append $env:GITHUB_OUTPUT
+
             - name: Build agent exe
               working-directory: agent
               shell: pwsh
+              env:
+                  VERSION: ${{ steps.version.outputs.VERSION }}
               run: |
                   $env:GOOS = "windows"; $env:GOARCH = "amd64"
-                  go build -o ../installer/vantage-agent-windows-amd64.exe ./cmd
-
-            - name: Fetch nssm
-              working-directory: installer
-              shell: pwsh
-              run: |
-                  Invoke-WebRequest -Uri https://nssm.cc/release/nssm-2.24.zip -OutFile nssm.zip
-                  Expand-Archive -Path nssm.zip -DestinationPath nssm-extract -Force
-                  Copy-Item nssm-extract/nssm-2.24/win64/nssm.exe -Destination nssm.exe
+                  go build -ldflags="-s -w -X main.Version=$env:VERSION" -o ../installer/vantage-agent-windows-amd64.exe ./cmd
 
             - name: Install WiX
               shell: pwsh
@@ -92,7 +95,7 @@ jobs:
               shell: pwsh
               run: |
                   $env:PATH = "$env:PATH;$env:USERPROFILE\.dotnet\tools"
-                  wix build vantage-agent.wxs -o vantage-agent.msi
+                  wix build vantage-agent.wxs -d Version=${{ steps.version.outputs.MSIVERSION }} -o vantage-agent.msi
                   (Get-FileHash vantage-agent.msi -Algorithm SHA256).Hash.ToLower() + "  vantage-agent.msi" | Out-File -Encoding ascii checksums-msi.txt
 
             - name: Attach MSI to release

.gitignore

@@ -4,7 +4,7 @@ build
 .env
 docs
 .superpowers
-installer/*.exe
+installer/vantage-agent-windows-amd64.exe
 installer/*.msi
 installer/nssm.zip
 installer/checksums-msi.txt

agent/internal/exec/exec.go

@@ -0,0 +1,164 @@
+package exec
+
+import (
+	"bufio"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
+)
+
+// streamWriter forwards every write to emit() as an ordered chunk. Used as both
+// Stdout and Stderr so output interleaves in real execution order. The mutex
+// ensures a single stdout/stderr write is not interleaved mid-slice with another.
+type streamWriter struct {
+	mu   sync.Mutex
+	seq  uint64
+	emit func(seq uint64, data []byte)
+}
+
+func (w *streamWriter) Write(p []byte) (int, error) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.emit != nil {
+		buf := make([]byte, len(p))
+		copy(buf, p)
+		w.emit(w.seq, buf)
+		w.seq++
+	}
+	return len(p), nil
+}
+
+// WorkspacePath returns the per-run working directory for a workspace id. The
+// same id always maps to the same path so RunStep and the cleanup command agree.
+func WorkspacePath(workspaceID string) string {
+	return filepath.Join(os.TempDir(), "vantage-run-"+workspaceID)
+}
+
+// RunStep writes the script to a temp file, provides a WORKFLOW_ENV file for
+// the script to append KEY=value output to, executes it under the requested
+// interpreter, and streams output via emit, returning the terminal result
+// with empty stdout/stderr but populated exit_code/output_env.
+//
+// When the command carries a WorkspaceId the step runs with that per-run working
+// directory as its cwd (created here if missing); the server removes it once the
+// run finishes. The script and env files always live in a private temp dir so
+// they never leak into the shared workspace.
+func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepResult {
+	res := &pb.StepResult{CommandId: "", OutputEnv: map[string]string{}}
+
+	dir, err := os.MkdirTemp("", "vantage-step-")
+	if err != nil {
+		res.ExitCode = 1
+		res.Stderr = "create temp dir: " + err.Error()
+		return res
+	}
+	defer os.RemoveAll(dir)
+
+	workDir := ""
+	if cmd.WorkspaceId != "" {
+		workDir = WorkspacePath(cmd.WorkspaceId)
+		if err := os.MkdirAll(workDir, 0700); err != nil {
+			res.ExitCode = 1
+			res.Stderr = "create workspace: " + err.Error()
+			return res
+		}
+	}
+
+	envFile := filepath.Join(dir, "workflow_env")
+	if err := os.WriteFile(envFile, nil, 0600); err != nil {
+		res.ExitCode = 1
+		res.Stderr = "create env file: " + err.Error()
+		return res
+	}
+
+	var scriptPath string
+	var c *exec.Cmd
+	timeout := time.Duration(cmd.TimeoutSeconds) * time.Second
+	if timeout <= 0 {
+		timeout = 30 * time.Minute
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+
+	switch cmd.Interpreter {
+	case "powershell":
+		scriptPath = filepath.Join(dir, "step.ps1")
+		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0600); err != nil {
+			res.ExitCode = 1
+			res.Stderr = err.Error()
+			return res
+		}
+		shell := "pwsh"
+		if runtime.GOOS == "windows" {
+			if _, err := exec.LookPath("pwsh"); err != nil {
+				shell = "powershell.exe"
+			}
+		}
+		c = exec.CommandContext(ctx, shell, "-NoProfile", "-NonInteractive", "-File", scriptPath)
+	default: // "bash"
+		scriptPath = filepath.Join(dir, "step.sh")
+		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0700); err != nil {
+			res.ExitCode = 1
+			res.Stderr = err.Error()
+			return res
+		}
+		c = exec.CommandContext(ctx, "bash", scriptPath)
+	}
+
+	if workDir != "" {
+		c.Dir = workDir
+	}
+
+	c.Env = append(os.Environ(), "WORKFLOW_ENV="+envFile)
+	for k, v := range cmd.Env {
+		c.Env = append(c.Env, k+"="+v)
+	}
+
+	sw := &streamWriter{emit: emit}
+	c.Stdout = sw
+	c.Stderr = sw
+	runErr := c.Run()
+
+	// stdout/stderr are streamed via emit, not returned in the result.
+	if ctx.Err() == context.DeadlineExceeded {
+		res.ExitCode = 124
+		res.Stderr = "[vantage] step timed out"
+	} else if ee, ok := runErr.(*exec.ExitError); ok {
+		res.ExitCode = ee.ExitCode()
+	} else if runErr != nil {
+		res.ExitCode = 1
+		res.Stderr = "[vantage] " + runErr.Error()
+	}
+
+	res.OutputEnv = parseEnvFile(envFile)
+	return res
+}
+
+// parseEnvFile reads KEY=value lines (last write wins). Blank lines and lines
+// without '=' are ignored.
+func parseEnvFile(path string) map[string]string {
+	out := map[string]string{}
+	f, err := os.Open(path)
+	if err != nil {
+		return out
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for sc.Scan() {
+		line := sc.Text()
+		i := strings.IndexByte(line, '=')
+		if i <= 0 {
+			continue
+		}
+		out[line[:i]] = line[i+1:]
+	}
+	return out
+}

agent/internal/grpc/pb/vantage.pb.go

@@ -63,11 +63,19 @@ type ReportUpdatesResponse struct{}
 type ApplyUpdatesCmd struct{}
 
 type ServerCommand struct {
-	CommandId    string           `json:"command_id"`
-	GenerateKey  *GenerateKeyCmd  `json:"generate_key,omitempty"`
-	DeleteKey    *DeleteKeyCmd    `json:"delete_key,omitempty"`
-	UpdateAgent  *UpdateAgentCmd  `json:"update_agent,omitempty"`
-	ApplyUpdates *ApplyUpdatesCmd `json:"apply_updates,omitempty"`
+	CommandId        string               `json:"command_id"`
+	GenerateKey      *GenerateKeyCmd      `json:"generate_key,omitempty"`
+	DeleteKey        *DeleteKeyCmd        `json:"delete_key,omitempty"`
+	UpdateAgent      *UpdateAgentCmd      `json:"update_agent,omitempty"`
+	ApplyUpdates     *ApplyUpdatesCmd     `json:"apply_updates,omitempty"`
+	RunStep          *RunStepCmd          `json:"run_step,omitempty"`
+	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
+}
+
+// CleanupWorkspaceCmd tells the agent to recursively remove the run's working
+// directory once all steps on that server have finished.
+type CleanupWorkspaceCmd struct {
+	WorkspaceId string `json:"workspace_id"`
 }
 
 type DeleteKeyCmd struct {
@@ -88,10 +96,12 @@ type GenerateKeyCmd struct {
 }
 
 type AgentMessage struct {
-	ServerId   string         `json:"server_id"`
-	AgentToken string         `json:"agent_token"`
-	Ready      *AgentReady    `json:"ready,omitempty"`
-	Result     *CommandResult `json:"result,omitempty"`
+	ServerId   string            `json:"server_id"`
+	AgentToken string            `json:"agent_token"`
+	Ready      *AgentReady       `json:"ready,omitempty"`
+	Result     *CommandResult    `json:"result,omitempty"`
+	StepResult *StepResult       `json:"step_result,omitempty"`
+	StepOutput *StepOutputChunk  `json:"step_output,omitempty"`
 }
 
 type AgentReady struct{}
@@ -102,6 +112,31 @@ type CommandResult struct {
 	Message   string `json:"message"`
 }
 
+type RunStepCmd struct {
+	Interpreter    string            `json:"interpreter"`
+	Script         string            `json:"script"`
+	Env            map[string]string `json:"env,omitempty"`
+	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
+	// WorkspaceId names the per-run working directory the agent creates and uses
+	// as the step's cwd. Empty means run in the agent's default directory.
+	WorkspaceId string `json:"workspace_id,omitempty"`
+}
+
+type StepResult struct {
+	CommandId string            `json:"command_id"`
+	ExitCode  int               `json:"exit_code"`
+	Stdout    string            `json:"stdout,omitempty"`
+	Stderr    string            `json:"stderr,omitempty"`
+	OutputEnv map[string]string `json:"output_env,omitempty"`
+}
+
+type StepOutputChunk struct {
+	CommandId string `json:"command_id"`
+	Seq       uint64 `json:"seq"`
+	Data      []byte `json:"data,omitempty"`
+	Eof       bool   `json:"eof,omitempty"`
+}
+
 // CommandStream client-side interface
 
 type Vantage_CommandStreamClient interface {

agent/internal/sync/sync.go

@@ -11,11 +11,14 @@ import (
 	"net/http"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"runtime"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/mrhid6/vantage/agent/internal/config"
+	agentexec "github.com/mrhid6/vantage/agent/internal/exec"
 	grpcclient "github.com/mrhid6/vantage/agent/internal/grpc"
 	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
 	"github.com/mrhid6/vantage/agent/internal/keys"
@@ -167,6 +170,16 @@ func connectAndHandleStream(ctx context.Context, cfg *config.Config) error {
 
 	log.Println("command stream connected")
 
+	// grpc streams are not safe for concurrent Send; RunStep results are sent
+	// from per-command goroutines, so all sends on this stream must go through
+	// this mutex-protected helper.
+	var sendMu sync.Mutex
+	send := func(msg *pb.AgentMessage) error {
+		sendMu.Lock()
+		defer sendMu.Unlock()
+		return stream.Send(msg)
+	}
+
 	for {
 		cmd, err := stream.Recv()
 		if err != nil {
@@ -185,6 +198,34 @@ func connectAndHandleStream(ctx context.Context, cfg *config.Config) error {
 		if cmd.ApplyUpdates != nil {
 			go handleApplyUpdates(cfg, cmd)
 		}
+		if cmd.CleanupWorkspace != nil {
+			go handleCleanupWorkspace(cmd)
+		}
+		if cmd.RunStep != nil {
+			go func(rc *pb.RunStepCmd, cid string) {
+				emit := func(seq uint64, data []byte) {
+					_ = send(&pb.AgentMessage{
+						ServerId:   cfg.ServerID,
+						AgentToken: cfg.AgentToken,
+						StepOutput: &pb.StepOutputChunk{CommandId: cid, Seq: seq, Data: data},
+					})
+				}
+				res := agentexec.RunStep(rc, emit)
+				res.CommandId = cid
+				// Final eof marker so the server closes the log file.
+				_ = send(&pb.AgentMessage{
+					ServerId:   cfg.ServerID,
+					AgentToken: cfg.AgentToken,
+					StepOutput: &pb.StepOutputChunk{CommandId: cid, Eof: true},
+				})
+				_ = send(&pb.AgentMessage{
+					ServerId:   cfg.ServerID,
+					AgentToken: cfg.AgentToken,
+					StepResult: res,
+				})
+			}(cmd.RunStep, cmd.CommandId)
+			continue
+		}
 	}
 }
 
@@ -248,6 +289,16 @@ func handleApplyUpdates(cfg *config.Config, cmd *pb.ServerCommand) {
 	_ = client.ReportUpdates(cfg.ServerID, cfg.AgentToken, nil)
 }
 
+func handleCleanupWorkspace(cmd *pb.ServerCommand) {
+	id := cmd.CleanupWorkspace.WorkspaceId
+	dir := agentexec.WorkspacePath(id)
+	if err := os.RemoveAll(dir); err != nil {
+		log.Printf("cleanup workspace %s failed (cmd=%s): %v", dir, cmd.CommandId, err)
+		return
+	}
+	log.Printf("removed run workspace %s (cmd=%s)", dir, cmd.CommandId)
+}
+
 func handleDeleteKey(cmd *pb.ServerCommand) {
 	label := cmd.DeleteKey.Label
 	keyPath := fmt.Sprintf("/root/.ssh/vantage_%s", strings.ReplaceAll(label, " ", "_"))
@@ -265,6 +316,11 @@ func handleDeleteKey(cmd *pb.ServerCommand) {
 }
 
 func handleUpdateAgent(cmd *pb.ServerCommand) {
+	if runtime.GOOS == "windows" {
+		handleUpdateAgentWindows(cmd)
+		return
+	}
+
 	u := cmd.UpdateAgent
 	arch := runtime.GOARCH // "amd64" or "arm64"
 	tag := "agent%2Fv" + u.Version
@@ -305,6 +361,47 @@ func handleUpdateAgent(cmd *pb.ServerCommand) {
 	exec.Command("systemctl", "restart", "vantage-agent").Run()
 }
 
+// handleUpdateAgentWindows downloads the latest MSI and launches msiexec to
+// perform a MajorUpgrade. msiexec is started DETACHED (via "cmd /c start") so
+// that when the upgrade stops the VantageAgent service, nssm's process-tree
+// kill of this agent does not also kill the installer mid-flight. Config
+// (server_id, agent_token) is preserved by setup.ps1 on upgrade.
+func handleUpdateAgentWindows(cmd *pb.ServerCommand) {
+	u := cmd.UpdateAgent
+	tag := "agent%2Fv" + u.Version
+	msiURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/vantage-agent.msi", u.GiteaBaseURL, tag)
+	checksumURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/checksums-msi.txt", u.GiteaBaseURL, tag)
+
+	log.Printf("updating agent to v%s from %s (cmd=%s)", u.Version, u.GiteaBaseURL, cmd.CommandId)
+
+	msiPath := filepath.Join(os.TempDir(), "vantage-agent-update.msi")
+	if err := downloadFile(msiURL, msiPath); err != nil {
+		log.Printf("update download failed (cmd=%s): %v", cmd.CommandId, err)
+		return
+	}
+
+	checksumData, err := httpGetBytes(checksumURL)
+	if err != nil {
+		log.Printf("update checksum fetch failed (cmd=%s): %v", cmd.CommandId, err)
+		return
+	}
+	if err := verifyChecksum(msiPath, "vantage-agent.msi", checksumData); err != nil {
+		log.Printf("update checksum mismatch (cmd=%s): %v", cmd.CommandId, err)
+		os.Remove(msiPath)
+		return
+	}
+
+	logPath := filepath.Join(os.TempDir(), "vantage-agent-msi.log")
+	log.Printf("launching msiexec for upgrade to v%s (cmd=%s)", u.Version, cmd.CommandId)
+	// "start" detaches msiexec from this process tree so the service stop
+	// during the upgrade does not terminate the installer.
+	up := exec.Command("cmd", "/c", "start", "", "/wait", "msiexec", "/i", msiPath, "/qn", "/norestart", "/l*v", logPath)
+	if err := up.Start(); err != nil {
+		log.Printf("failed to launch msiexec (cmd=%s): %v", cmd.CommandId, err)
+		return
+	}
+}
+
 func downloadFile(url, dest string) error {
 	resp, err := http.Get(url) //nolint:gosec
 	if err != nil {

docs/superpowers/plans/2026-07-20-fleet-inventory.md

@@ -0,0 +1,653 @@
+# Fleet Inventory Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Agents collect CPU/RAM/swap/disk/partition inventory and report it to the server via a new `ReportInventory` RPC; the server stores the latest snapshot per server and the UI displays it.
+
+**Architecture:** New unary gRPC `ReportInventory` (mirrors existing `ReportUpdates`). Agent runs a 30s metrics ticker (CPU/RAM/swap usage) and, every 15 min, a full static collection (disks, partitions, CPU model, kernel). Server upserts an embedded `inventory` sub-doc on the `servers` document with merge rules that preserve static fields between slow ticks.
+
+**Tech Stack:** Go (gin, mongo-driver v2, hand-written JSON-codec gRPC), `/proc` readers, Next.js 16 + react-query + Tailwind.
+
+## Global Constraints
+
+- **No tests this iteration.** Verify with `go build ./...`, `go vet ./...`, `npm run build`.
+- gRPC uses a JSON codec: edit **both** `server/internal/grpc/pb/vantage.pb.go` and `agent/internal/grpc/pb/vantage.pb.go` identically, plus `proto/vantage/v1/vantage.proto` as documentation. No codegen. Mirror the existing `ReportUpdates` RPC wiring exactly (service interface, `_Vantage_*_Handler`, client method, `Vantage_ServiceDesc`).
+- Mongo: `db.Col("servers")`, `context.WithTimeout`. Follow `server/internal/services/servers.go`.
+- Agent already runs as root; `/proc` is readable. Linux is primary; Windows collectors may return empty.
+- Module path `github.com/mrhid6/vantage`.
+- Do not add heavy dependencies; implement `/proc` parsing directly.
+
+---
+
+## Task 1: Inventory model + gRPC messages
+
+**Files:**
+- Modify: `server/internal/models/server.go`
+- Modify: `proto/vantage/v1/vantage.proto`
+- Modify: `server/internal/grpc/pb/vantage.pb.go`
+- Modify: `agent/internal/grpc/pb/vantage.pb.go`
+
+**Interfaces:**
+- Produces: `models.Inventory` (+ `CPUInfo`, `MemInfo`, `Partition`) and `Server.Inventory *Inventory`. pb structs `InventoryReport`, `CPUReport`, `MemReport`, `PartitionReport`, `InventoryReportResponse`. Service method `ReportInventory` on both client and server interfaces.
+
+- [ ] **Step 1: Add model structs**
+
+In `server/internal/models/server.go` add (keep the existing `import "time"`):
+
+```go
+type CPUInfo struct {
+	Model    string  `bson:"model,omitempty" json:"model,omitempty"`
+	Cores    int     `bson:"cores,omitempty" json:"cores,omitempty"`
+	UsagePct float64 `bson:"usage_pct" json:"usage_pct"`
+	Load1    float64 `bson:"load1,omitempty" json:"load1,omitempty"`
+}
+
+type MemInfo struct {
+	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
+	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
+}
+
+type Partition struct {
+	Device     string `bson:"device" json:"device"`
+	Mountpoint string `bson:"mountpoint" json:"mountpoint"`
+	Fstype     string `bson:"fstype,omitempty" json:"fstype,omitempty"`
+	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
+	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
+}
+
+type Inventory struct {
+	CPU            CPUInfo     `bson:"cpu" json:"cpu"`
+	Memory         MemInfo     `bson:"memory" json:"memory"`
+	SwapTotalBytes uint64      `bson:"swap_total_bytes" json:"swap_total_bytes"`
+	SwapUsedBytes  uint64      `bson:"swap_used_bytes" json:"swap_used_bytes"`
+	Partitions     []Partition `bson:"partitions,omitempty" json:"partitions,omitempty"`
+	Kernel         string      `bson:"kernel,omitempty" json:"kernel,omitempty"`
+	MetricsAt      *time.Time  `bson:"metrics_at,omitempty" json:"metrics_at,omitempty"`
+	StaticAt       *time.Time  `bson:"static_at,omitempty" json:"static_at,omitempty"`
+}
+```
+
+Add to the `Server` struct: `Inventory *Inventory \`bson:"inventory,omitempty" json:"inventory,omitempty"\``.
+
+- [ ] **Step 2: Document RPC in proto**
+
+In `proto/vantage/v1/vantage.proto`, add to the service: `rpc ReportInventory(InventoryReport) returns (InventoryReportResponse);` and the messages `InventoryReport`, `CPUReport`, `MemReport`, `PartitionReport`, `InventoryReportResponse` per spec §4.
+
+- [ ] **Step 3: Add pb structs + RPC wiring (server pb)**
+
+In `server/internal/grpc/pb/vantage.pb.go` add the message structs:
+
+```go
+type CPUReport struct {
+	Model    string  `json:"model,omitempty"`
+	Cores    int     `json:"cores,omitempty"`
+	UsagePct float64 `json:"usage_pct"`
+	Load1    float64 `json:"load1,omitempty"`
+}
+type MemReport struct {
+	TotalBytes uint64 `json:"total_bytes"`
+	UsedBytes  uint64 `json:"used_bytes"`
+}
+type PartitionReport struct {
+	Device     string `json:"device"`
+	Mountpoint string `json:"mountpoint"`
+	Fstype     string `json:"fstype,omitempty"`
+	TotalBytes uint64 `json:"total_bytes"`
+	UsedBytes  uint64 `json:"used_bytes"`
+}
+type InventoryReport struct {
+	ServerId      string            `json:"server_id"`
+	AgentToken    string            `json:"agent_token"`
+	IncludeStatic bool              `json:"include_static"`
+	CPU           *CPUReport        `json:"cpu,omitempty"`
+	Memory        *MemReport        `json:"memory,omitempty"`
+	SwapTotal     uint64            `json:"swap_total"`
+	SwapUsed      uint64            `json:"swap_used"`
+	Partitions    []PartitionReport `json:"partitions,omitempty"`
+	Kernel        string            `json:"kernel,omitempty"`
+}
+type InventoryReportResponse struct{}
+```
+
+Then mirror the `ReportUpdates` RPC plumbing for `ReportInventory`. Locate every `ReportUpdates` reference in this file and add the parallel `ReportInventory`:
+- `VantageServer` interface: add `ReportInventory(context.Context, *InventoryReport) (*InventoryReportResponse, error)`.
+- `UnimplementedVantageServer`: add the stub returning `Unimplemented`.
+- `VantageClient` interface + `keyManagerClient`: add the client method `Invoke`-ing `/vantage.v1.Vantage/ReportInventory`.
+- `Vantage_ServiceDesc.Methods`: add `{MethodName: "ReportInventory", Handler: _Vantage_ReportInventory_Handler}`.
+- Add `_Vantage_ReportInventory_Handler` copied from `_Vantage_ReportUpdates_Handler` with types swapped.
+
+- [ ] **Step 4: Mirror pb structs + wiring (agent pb)**
+
+Apply the identical additions to `agent/internal/grpc/pb/vantage.pb.go`.
+
+- [ ] **Step 5: Verify build**
+
+Run: `cd server && go build ./... && cd ../agent && go build ./...`
+Expected: both succeed.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add server/internal/models/server.go proto/vantage/v1/vantage.proto server/internal/grpc/pb/vantage.pb.go agent/internal/grpc/pb/vantage.pb.go
+git commit -m "feat(proto): add ReportInventory RPC and inventory model"
+```
+
+---
+
+## Task 2: Server handler + store service
+
+**Files:**
+- Create: `server/internal/services/inventory.go`
+- Modify: `server/internal/grpc/server.go`
+
+**Interfaces:**
+- Consumes: `pb.InventoryReport` (T1), `db.Col("servers")`.
+- Produces: `services.StoreInventory(serverID string, r *pb.InventoryReport) error`; gRPC method `(*vantageServer).ReportInventory`.
+
+- [ ] **Step 1: Write the store service**
+
+```go
+package services
+
+import (
+	"context"
+	"time"
+
+	"github.com/mrhid6/vantage/server/internal/db"
+	"github.com/mrhid6/vantage/server/internal/grpc/pb"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// StoreInventory upserts the latest inventory snapshot onto the server document.
+// Metrics fields update every call; static fields only when r.IncludeStatic.
+func StoreInventory(serverID string, r *pb.InventoryReport) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	now := time.Now()
+	set := bson.M{"inventory.metrics_at": now}
+	if r.CPU != nil {
+		set["inventory.cpu.usage_pct"] = r.CPU.UsagePct
+		set["inventory.cpu.load1"] = r.CPU.Load1
+	}
+	if r.Memory != nil {
+		set["inventory.memory.used_bytes"] = r.Memory.UsedBytes
+	}
+	set["inventory.swap_used_bytes"] = r.SwapUsed
+
+	if r.IncludeStatic {
+		set["inventory.static_at"] = now
+		set["inventory.swap_total_bytes"] = r.SwapTotal
+		set["inventory.kernel"] = r.Kernel
+		if r.CPU != nil {
+			set["inventory.cpu.model"] = r.CPU.Model
+			set["inventory.cpu.cores"] = r.CPU.Cores
+		}
+		if r.Memory != nil {
+			set["inventory.memory.total_bytes"] = r.Memory.TotalBytes
+		}
+		parts := make([]bson.M, 0, len(r.Partitions))
+		for _, p := range r.Partitions {
+			parts = append(parts, bson.M{
+				"device": p.Device, "mountpoint": p.Mountpoint, "fstype": p.Fstype,
+				"total_bytes": p.TotalBytes, "used_bytes": p.UsedBytes,
+			})
+		}
+		set["inventory.partitions"] = parts
+	}
+
+	_, err := db.Col("servers").UpdateOne(ctx, bson.M{"server_id": serverID}, bson.M{"$set": set})
+	return err
+}
+```
+
+- [ ] **Step 2: Add the gRPC handler**
+
+In `server/internal/grpc/server.go`, add (mirroring the existing `ReportUpdates` handler that validates the agent token):
+
+```go
+func (s *vantageServer) ReportInventory(ctx context.Context, req *pb.InventoryReport) (*pb.InventoryReportResponse, error) {
+	srv, err := services.ValidateAgentToken(req.ServerId, req.AgentToken)
+	if err != nil {
+		return nil, status.Errorf(codes.Unauthenticated, "invalid agent token")
+	}
+	if err := services.StoreInventory(srv.ServerID, req); err != nil {
+		log.Printf("store inventory for %s: %v", srv.ServerID, err)
+	}
+	return &pb.InventoryReportResponse{}, nil
+}
+```
+
+Confirm `status`, `codes`, `log` are already imported in the file (they are, used by other handlers).
+
+- [ ] **Step 3: Verify build**
+
+Run: `cd server && go build ./... && go vet ./...`
+Expected: success.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add server/internal/services/inventory.go server/internal/grpc/server.go
+git commit -m "feat(server): store inventory and handle ReportInventory RPC"
+```
+
+---
+
+## Task 3: Agent collectors
+
+**Files:**
+- Create: `agent/internal/inventory/collect_linux.go`
+- Create: `agent/internal/inventory/collect_other.go`
+- Create: `agent/internal/inventory/inventory.go`
+
+**Interfaces:**
+- Produces: `inventory.Collect(includeStatic bool) *pb.InventoryReport`.
+
+- [ ] **Step 1: Common entry (`inventory.go`)**
+
+```go
+package inventory
+
+import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
+
+// Collect gathers metrics always and static hardware info when includeStatic.
+// Platform specifics are provided by collect_linux.go / collect_other.go.
+func Collect(includeStatic bool) *pb.InventoryReport {
+	r := &pb.InventoryReport{IncludeStatic: includeStatic, CPU: &pb.CPUReport{}, Memory: &pb.MemReport{}}
+	collect(r, includeStatic)
+	return r
+}
+```
+
+- [ ] **Step 2: Linux collector (`collect_linux.go`)**
+
+Build-tagged `//go:build linux`. Implement `collect(r *pb.InventoryReport, includeStatic bool)`:
+- CPU usage: read `/proc/stat` first line twice ~100ms apart, compute `1 - idleDelta/totalDelta` × 100 → `r.CPU.UsagePct`.
+- Load: first field of `/proc/loadavg` → `r.CPU.Load1`.
+- Mem/swap: parse `/proc/meminfo` (`MemTotal`, `MemAvailable`, `SwapTotal`, `SwapFree`; used = total − available; swap used = swaptotal − swapfree) → `r.Memory.*`, `r.SwapUsed`, and on static `r.SwapTotal`.
+- Static only: `/proc/cpuinfo` (`model name`, count `processor` lines) → `r.CPU.Model/Cores`; `/proc/meminfo MemTotal` → `r.Memory.TotalBytes`; kernel via `syscall.Uname` or read `/proc/sys/kernel/osrelease` → `r.Kernel`; partitions from `/proc/mounts` filtered to fstypes in {ext4,xfs,btrfs,zfs,vfat,ntfs} then `syscall.Statfs` for total/used → `r.Partitions`.
+
+```go
+//go:build linux
+
+package inventory
+
+import (
+	"bufio"
+	"os"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
+)
+
+func collect(r *pb.InventoryReport, includeStatic bool) {
+	r.CPU.UsagePct = cpuUsage()
+	r.CPU.Load1 = load1()
+	memTotal, memAvail, swapTotal, swapFree := meminfo()
+	if memTotal > memAvail {
+		r.Memory.UsedBytes = memTotal - memAvail
+	}
+	if swapTotal > swapFree {
+		r.SwapUsed = swapTotal - swapFree
+	}
+	if includeStatic {
+		r.Memory.TotalBytes = memTotal
+		r.SwapTotal = swapTotal
+		r.CPU.Model, r.CPU.Cores = cpuStatic()
+		r.Kernel = kernel()
+		r.Partitions = partitions()
+	}
+}
+
+func readProc(path string) string { b, _ := os.ReadFile(path); return string(b) }
+
+func cpuSample() (idle, total uint64) {
+	f, err := os.Open("/proc/stat")
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	if sc.Scan() {
+		fields := strings.Fields(sc.Text()) // cpu user nice system idle iowait ...
+		for i, v := range fields[1:] {
+			n, _ := strconv.ParseUint(v, 10, 64)
+			total += n
+			if i == 3 { // idle
+				idle = n
+			}
+		}
+	}
+	return
+}
+
+func cpuUsage() float64 {
+	i1, t1 := cpuSample()
+	time.Sleep(100 * time.Millisecond)
+	i2, t2 := cpuSample()
+	dt := float64(t2 - t1)
+	if dt <= 0 {
+		return 0
+	}
+	return (1 - float64(i2-i1)/dt) * 100
+}
+
+func load1() float64 {
+	fields := strings.Fields(readProc("/proc/loadavg"))
+	if len(fields) > 0 {
+		v, _ := strconv.ParseFloat(fields[0], 64)
+		return v
+	}
+	return 0
+}
+
+func meminfo() (total, avail, swapTotal, swapFree uint64) {
+	f, err := os.Open("/proc/meminfo")
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 2 {
+			continue
+		}
+		kb, _ := strconv.ParseUint(fields[1], 10, 64)
+		b := kb * 1024
+		switch strings.TrimSuffix(fields[0], ":") {
+		case "MemTotal":
+			total = b
+		case "MemAvailable":
+			avail = b
+		case "SwapTotal":
+			swapTotal = b
+		case "SwapFree":
+			swapFree = b
+		}
+	}
+	return
+}
+
+func cpuStatic() (model string, cores int) {
+	f, err := os.Open("/proc/cpuinfo")
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if strings.HasPrefix(line, "processor") {
+			cores++
+		} else if strings.HasPrefix(line, "model name") && model == "" {
+			if i := strings.Index(line, ":"); i >= 0 {
+				model = strings.TrimSpace(line[i+1:])
+			}
+		}
+	}
+	return
+}
+
+func kernel() string {
+	return strings.TrimSpace(readProc("/proc/sys/kernel/osrelease"))
+}
+
+func partitions() []pb.PartitionReport {
+	allowed := map[string]bool{"ext4": true, "xfs": true, "btrfs": true, "zfs": true, "vfat": true, "ntfs": true, "ext3": true}
+	f, err := os.Open("/proc/mounts")
+	if err != nil {
+		return nil
+	}
+	defer f.Close()
+	var out []pb.PartitionReport
+	seen := map[string]bool{}
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 3 || !allowed[fields[2]] || seen[fields[1]] {
+			continue
+		}
+		seen[fields[1]] = true
+		var st syscall.Statfs_t
+		if syscall.Statfs(fields[1], &st) != nil {
+			continue
+		}
+		total := st.Blocks * uint64(st.Bsize)
+		free := st.Bavail * uint64(st.Bsize)
+		out = append(out, pb.PartitionReport{
+			Device: fields[0], Mountpoint: fields[1], Fstype: fields[2],
+			TotalBytes: total, UsedBytes: total - free,
+		})
+	}
+	return out
+}
+```
+
+- [ ] **Step 3: Non-linux stub (`collect_other.go`)**
+
+```go
+//go:build !linux
+
+package inventory
+
+import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
+
+// collect is a no-op best-effort stub on non-Linux platforms.
+func collect(r *pb.InventoryReport, includeStatic bool) {}
+```
+
+- [ ] **Step 4: Verify build**
+
+Run: `cd agent && go build ./... && go vet ./...`
+Expected: success (build both native and, if convenient, `GOOS=windows go build ./...`).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add agent/internal/inventory/
+git commit -m "feat(agent): /proc-based inventory collectors"
+```
+
+---
+
+## Task 4: Agent client method + scheduler
+
+**Files:**
+- Modify: `agent/internal/grpc/client.go`
+- Modify: the agent main loop (`agent/cmd/main.go` or `agent/internal/sync/sync.go` — wherever the poll loop/tickers live).
+
+**Interfaces:**
+- Consumes: `inventory.Collect` (T3), pb (T1).
+- Produces: `(*Client).ReportInventory(report *pb.InventoryReport) error`; a running ticker that reports metrics every 30s and static every 15 min.
+
+- [ ] **Step 1: Add client method**
+
+In `agent/internal/grpc/client.go`, mirroring `ReportUpdates`:
+
+```go
+func (c *Client) ReportInventory(report *pb.InventoryReport) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	_, err := c.client.ReportInventory(ctx, report)
+	return err
+}
+```
+
+The report already carries `ServerId`/`AgentToken`; ensure the caller sets them (see Step 2).
+
+- [ ] **Step 2: Add the scheduler to the agent loop**
+
+Find where the agent starts its poll loop (the goroutine that calls `SyncKeys`/`ReportUpdates`). Add a parallel inventory ticker. `serverID`, `agentToken`, and the `*Client` are in scope there:
+
+```go
+	go func() {
+		tick := 0
+		t := time.NewTicker(30 * time.Second)
+		defer t.Stop()
+		report := func(static bool) {
+			r := inventory.Collect(static)
+			r.ServerId = serverID
+			r.AgentToken = agentToken
+			if err := client.ReportInventory(r); err != nil {
+				log.Printf("report inventory: %v", err)
+			}
+		}
+		report(true) // send a full snapshot on startup
+		for range t.C {
+			tick++
+			report(tick%30 == 0) // every 30th tick = 15 min → include static
+		}
+	}()
+```
+
+Add imports `"github.com/mrhid6/vantage/agent/internal/inventory"`, `time`, `log` if missing. Match variable names to the actual loop (e.g. the client may be named `c`).
+
+- [ ] **Step 3: Verify build**
+
+Run: `cd agent && go build ./... && go vet ./...`
+Expected: success.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add agent/internal/grpc/client.go agent/
+git commit -m "feat(agent): schedule inventory reporting (30s metrics, 15m static)"
+```
+
+---
+
+## Task 5: Frontend — inventory panel on server detail
+
+**Files:**
+- Modify: `web/lib/api.ts` (extend the `Server`/server-detail type with `inventory`)
+- Modify: `web/app/servers/[id]/page.tsx` (add panel; enable polling)
+
+**Interfaces:**
+- Consumes: server-detail query.
+
+- [ ] **Step 1: Add the inventory type**
+
+In `web/lib/api.ts`, add and attach to the server type used by the detail page:
+
+```ts
+export interface Inventory {
+  cpu: { model?: string; cores?: number; usage_pct: number; load1?: number };
+  memory: { total_bytes: number; used_bytes: number };
+  swap_total_bytes: number;
+  swap_used_bytes: number;
+  partitions?: { device: string; mountpoint: string; fstype?: string; total_bytes: number; used_bytes: number }[];
+  kernel?: string;
+  metrics_at?: string;
+  static_at?: string;
+}
+```
+
+Add `inventory?: Inventory;` to the server detail interface.
+
+- [ ] **Step 2: Add a `formatBytes` helper + Inventory panel**
+
+In `web/app/servers/[id]/page.tsx`, add a helper and a panel component. Enable polling on the server-detail `useQuery` with `refetchInterval: 30000`.
+
+```tsx
+function formatBytes(n: number): string {
+  if (!n) return "0 B";
+  const u = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(n) / Math.log(1024));
+  return `${(n / Math.pow(1024, i)).toFixed(1)} ${u[i]}`;
+}
+
+function UsageBar({ used, total }: { used: number; total: number }) {
+  const pct = total > 0 ? Math.min(100, (used / total) * 100) : 0;
+  return (
+    <div className="h-2 w-full overflow-hidden rounded-full bg-surface-2">
+      <div className={`h-full rounded-full ${pct > 90 ? "bg-danger" : "bg-accent"}`} style={{ width: `${pct}%` }} />
+    </div>
+  );
+}
+
+function InventoryPanel({ inv }: { inv: Inventory }) {
+  return (
+    <Card>
+      <h2 className="mb-4 text-lg font-semibold text-text-primary">Inventory</h2>
+      <div className="grid gap-4 sm:grid-cols-2">
+        <div>
+          <div className="mb-1 flex justify-between text-sm"><span className="text-text-secondary">CPU</span><span className="text-text-primary">{inv.cpu.usage_pct.toFixed(0)}%</span></div>
+          <UsageBar used={inv.cpu.usage_pct} total={100} />
+          <p className="mt-1 text-xs text-text-secondary">{inv.cpu.model} · {inv.cpu.cores} cores · load {inv.cpu.load1?.toFixed(2)}</p>
+        </div>
+        <div>
+          <div className="mb-1 flex justify-between text-sm"><span className="text-text-secondary">Memory</span><span className="text-text-primary">{formatBytes(inv.memory.used_bytes)} / {formatBytes(inv.memory.total_bytes)}</span></div>
+          <UsageBar used={inv.memory.used_bytes} total={inv.memory.total_bytes} />
+          <div className="mb-1 mt-3 flex justify-between text-sm"><span className="text-text-secondary">Swap</span><span className="text-text-primary">{formatBytes(inv.swap_used_bytes)} / {formatBytes(inv.swap_total_bytes)}</span></div>
+          <UsageBar used={inv.swap_used_bytes} total={inv.swap_total_bytes} />
+        </div>
+      </div>
+      {inv.partitions && inv.partitions.length > 0 && (
+        <div className="mt-5">
+          <h3 className="mb-2 text-sm font-medium text-text-secondary">Partitions</h3>
+          <div className="space-y-3">
+            {inv.partitions.map((p) => (
+              <div key={p.mountpoint}>
+                <div className="mb-1 flex justify-between text-xs">
+                  <span className="font-mono text-text-primary">{p.mountpoint}</span>
+                  <span className="text-text-secondary">{formatBytes(p.used_bytes)} / {formatBytes(p.total_bytes)} · {p.fstype}</span>
+                </div>
+                <UsageBar used={p.used_bytes} total={p.total_bytes} />
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+      {inv.kernel && <p className="mt-4 text-xs text-text-secondary">Kernel {inv.kernel}</p>}
+    </Card>
+  );
+}
+```
+
+Render `{server.inventory && <InventoryPanel inv={server.inventory} />}` in the page body (ensure `Card`, `Inventory` are imported). Match how the page currently reads the server object.
+
+- [ ] **Step 3: Verify build**
+
+Run: `cd web && npm run build`
+Expected: success.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/lib/api.ts web/app/servers/[id]/page.tsx
+git commit -m "feat(web): inventory panel on server detail"
+```
+
+---
+
+## Task 6: End-to-end manual verification
+
+- [ ] **Step 1: Build all**
+
+Run: `cd server && go build ./... && cd ../agent && go build ./... && cd ../web && npm run build`
+Expected: all succeed.
+
+- [ ] **Step 2: Smoke (if environment available)**
+
+With server + Mongo + a connected Linux agent: within ~30s the server detail page shows CPU %, RAM/swap bars; within 15 min (or on agent restart, which sends a full snapshot immediately) partitions, CPU model and kernel appear. Confirm metrics update roughly every 30s.
+
+- [ ] **Step 3: Commit any fixes**
+
+```bash
+git add -A
+git commit -m "fix: fleet inventory verification fixes"
+```
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** §3 model → T1; §4 RPC → T1; §5 collectors + scheduler → T3, T4; §6 handler/store → T2; §7 frontend → T5. Split cadence (30s metrics / 15m static) in T4 scheduler; merge rules preserving static in T2 `StoreInventory`. Tests omitted per Global Constraints.
+- **Startup snapshot:** agent sends `Collect(true)` immediately so static fields populate without waiting 15 min.
+- **Types consistent:** `InventoryReport` field names identical across proto, both pb files, store service, and TS interface (`usage_pct`, `used_bytes`, `total_bytes`, `swap_*`).
+- **Follow-ups (out of scope):** time-series history, usage alerting, Windows collectors, servers-list CPU/RAM badges.

docs/superpowers/specs/2026-07-17-web-console-design.md

@@ -1,241 +0,0 @@
-# Vantage Web Console (Guacamole Replacement) — Design
-
-**Date:** 2026-07-17
-**Status:** Approved design, pre-implementation
-
-## Goal
-
-Add a browser-based remote-access console to Vantage — SSH, RDP, and VNC into
-managed servers — as a self-hosted Guacamole replacement. Users select an SSH
-key to connect over SSH. RDP targets are reachable from a new Windows agent that
-registers the host and reports status. Windows agent ships as an MSI installer
-produced by CI.
-
-## Non-Goals (YAGNI)
-
-- Session recording / replay (may be added later).
-- Native Go RDP implementation (guacd handles protocol translation).
-- Per-user Linux/Windows account management from the agent.
-- Tunneling console traffic through the agent (direct network path assumed).
-
----
-
-## Architecture
-
-```
-Browser (guacamole-common-js, vendored — no CDN)
-   │  Guacamole protocol over WebSocket
-   ▼
-Go server: /api/console/tunnel   (github.com/wwt/guac)
-   │  Guacamole protocol over TCP :4822
-   ▼
-guacd container (Apache Guacamole daemon)
-   │  SSH :22 / RDP :3389 / VNC :5900  — direct to target IP
-   ▼
-Target host (LAN / VPN line-of-sight from server)
-```
-
-- **Browser:** loads vendored `guacamole-common-js`, renders RDP/VNC display and
-  SSH terminal. No external CDN (matches existing infra rules).
-- **Go server:** exposes a WebSocket tunnel endpoint using `github.com/wwt/guac`
-  (Go Guacamole tunnel library). No Java `guacamole-client` required.
-- **guacd:** new container in `deploy/docker-compose.yml`, bound to the internal
-  docker network only, reachable by the server on `:4822`.
-- **Network path:** guacd connects **directly** to the target IP. Requires the
-  central server to have network line-of-sight to hosts (homelab LAN / VPN). The
-  agent's outbound-only guarantee is unchanged — the console path is
-  server→target, not agent-mediated.
-
----
-
-## Data Model Changes
-
-### `keys` — extend to hold private material
-
-```json
-{
-  "key_id": "uuid",
-  "label": "dom-macbook",
-  "public_key": "ssh-ed25519 AAAA...",
-  "private_key_enc": "<AES-256-GCM ciphertext | null>",
-  "has_private": true,
-  "passphrase_enc": "<AES-256-GCM ciphertext | null>",
-  "fingerprint": "SHA256:...",
-  "source": "uploaded|generated",
-  "created_at": "ISODate"
-}
-```
-
-- A key may be created from an uploaded **private+public** pair, upload of a
-  public key only, or agent generation.
-- Agent key generation now also uploads `private_key_enc` (reuses the existing
-  AES-256 key used for at-rest encryption). Private key no longer stays local
-  only — it is stored encrypted so the console can reuse it.
-- Optional `passphrase_enc` for passphrase-protected private keys.
-- Console lists only keys where `has_private = true`.
-
-### `servers` — extend with console metadata
-
-```json
-{
-  "...": "...existing fields...",
-  "os_type": "linux|windows",
-  "console_protocols": ["ssh"],
-  "ssh_port": 22,
-  "rdp_port": 3389
-}
-```
-
-- `os_type` set at registration from the agent.
-- `console_protocols` lists enabled protocols per server (`ssh`, `rdp`, `vnc`).
-- Port fields default to standard ports, overridable in the UI.
-
-### `console_sessions` — new collection (audit)
-
-```json
-{
-  "session_id": "uuid",
-  "server_id": "uuid",
-  "protocol": "ssh|rdp|vnc",
-  "key_id": "uuid | null",
-  "user": "who opened it",
-  "started_at": "ISODate",
-  "ended_at": "ISODate | null",
-  "client_ip": "string"
-}
-```
-
----
-
-## Session Broker + Connection Flow
-
-New service: `server/internal/services/console.go`.
-
-1. Browser `POST /api/console/connect`
-   `{ server_id, protocol, key_id?, rdp_username?, rdp_password? }`.
-2. Broker validates request, loads the server (host IP, port for protocol),
-   loads the key and **decrypts `private_key_enc` in memory only**.
-3. Builds the guacd connection parameter map:
-   - **SSH:** `hostname`, `port`, `username`, `private-key` (decrypted),
-     `passphrase` (if any).
-   - **RDP:** `hostname`, `port`, `username`, `password`, `security=any`,
-     `ignore-cert=true`.
-   - **VNC:** `hostname`, `port`, `password`.
-4. Creates a `console_sessions` document, returns a short-lived signed session
-   token.
-5. Browser opens WebSocket `/api/console/tunnel?token=…`. The `wwt/guac` handler
-   validates the token, dials guacd `:4822`, and pipes bytes in both directions.
-6. On socket close, the broker sets `ended_at` on the session doc.
-
-### Security
-
-- Decrypted private keys and RDP passwords are **never persisted, never logged,
-  never sent to the browser** — passed only to guacd.
-- Session token: short TTL (~60s to open the WebSocket), single-use,
-  HMAC-signed, bound to the authenticated user.
-- guacd is bound to the internal docker network only; not exposed publicly.
-- At-rest encryption (`private_key_enc`, `passphrase_enc`) reuses the existing
-  AES-256 key already used for agent-generated private keys.
-
----
-
-## Windows Agent
-
-Same Go codebase as the Linux agent, with a reduced role: **register +
-heartbeat + status only**. No `authorized_keys` management (meaningless on
-Windows).
-
-- Build target: `GOOS=windows GOARCH=amd64` → `vantage-agent-windows-amd64.exe`.
-- Agent detects OS at registration and sends `os_type=windows`.
-- The key-sync loop is disabled on Windows via a runtime OS check (or build tag)
-  — no `authorized_keys` writes are ever attempted.
-- Config file: `C:\ProgramData\vantage\config.yaml`, locked down via ACL to the
-  equivalent of `0600`.
-- Runs as a Windows service via **nssm**.
-
----
-
-## Windows Installer (MSI)
-
-Agent ships as a WiX v4 MSI produced in CI.
-
-- **WiX v4** chosen because it is a dotnet tool that builds MSIs
-  **cross-platform** — runs on the Linux Gitea act_runner. (Inno Setup is
-  Windows-only and does not fit the runner.)
-- MSI bundles `vantage-agent.exe`, installs it to `C:\Program Files\Vantage\`,
-  and registers the nssm service (ships nssm or uses a CustomAction).
-- Accepts install parameters as MSI properties for silent/headless install:
-  ```
-  msiexec /i vantage-agent.msi /qn SERVERID=<id> TOKEN=<token> SERVERURL=vantage..:9090
-  ```
-- GUI install (double-click) prompts for server-id / token / server-url via a
-  dialog.
-
-### Two install paths
-
-1. **Installer direct** — user downloads `vantage-agent.msi`, double-clicks,
-   fills the dialog. No script required.
-2. **PowerShell one-liner** — served dynamically (like the existing bash
-   `/install`). Script downloads the `.msi`, verifies SHA-256, then runs
-   `msiexec /qn` with injected `SERVERID` / `TOKEN` / `SERVERURL`. Used by the
-   copy-paste "Add Server" flow.
-
-The PowerShell script (`/install.ps1`) steps:
-1. Detect arch.
-2. Download `vantage-agent.msi` from the latest Gitea `agent/v*` release.
-3. Verify SHA-256 against `checksums.txt`.
-4. Run `msiexec /i vantage-agent.msi /qn SERVERID=.. TOKEN=.. SERVERURL=..`.
-
----
-
-## Frontend Routes
-
-| Route                     | Change                                                        |
-| ------------------------- | ------------------------------------------------------------- |
-| `/servers`                | Show `os_type` badge, enabled console protocols               |
-| `/servers/[id]`           | Add **Connect** button(s) per enabled protocol                |
-| `/servers/[id]/console`   | New — full-screen console (guacamole-common-js), key picker   |
-| `/servers/new`            | Offer Windows (MSI) vs Linux (bash) install instructions      |
-
-Console page: select protocol + SSH key (SSH) or enter RDP credentials, call
-`/api/console/connect`, open the tunnel WebSocket, mount the Guacamole client.
-
----
-
-## CI/CD Changes
-
-### `agent-release.yml`
-
-- Add `windows/amd64` build: `vantage-agent-windows-amd64.exe`.
-- Add WiX v4 MSI build job → `vantage-agent.msi`.
-- Add both to `checksums.txt` and release assets.
-
-Release assets become:
-- `vantage-agent-linux-amd64`
-- `vantage-agent-linux-arm64`
-- `vantage-agent-windows-amd64.exe`
-- `vantage-agent.msi`
-- `checksums.txt`
-
-### `server-deploy.yml`
-
-- Add guacd service to `deploy/docker-compose.yml` (deployed alongside server).
-
----
-
-## New Dependencies
-
-- **Go:** `github.com/wwt/guac` (Guacamole tunnel/WebSocket in Go).
-- **Container:** `guacamole/guacd` official image.
-- **Frontend:** vendored `guacamole-common-js` (no CDN).
-- **CI:** WiX v4 dotnet tool; nssm binary bundled for the MSI.
-
----
-
-## Open Implementation Notes
-
-- Confirm `wwt/guac` API surface for connection-parameter passing and token auth
-  binding during implementation.
-- nssm packaging inside MSI: bundle the nssm binary as a payload + CustomAction,
-  or run `sc.exe`-based service install if nssm proves awkward in WiX.
-- ACL hardening of `C:\ProgramData\vantage\config.yaml` in the MSI CustomAction.

docs/superpowers/specs/2026-07-20-fleet-inventory-design.md

@@ -0,0 +1,142 @@
+# Fleet Inventory — Design
+
+**Date:** 2026-07-20
+**Status:** Approved (design) — ready for implementation planning
+**Scope:** Fleet Inventory only. Server Workflows and SaaS/auth are separate sub-projects.
+
+---
+
+## 1. Summary
+
+Each agent collects hardware/OS inventory about its host and reports it to the server, which stores the latest snapshot per server and surfaces it in the UI. Two cadences:
+
+- **Metrics (near-real-time):** CPU load/usage, RAM used/total, swap used/total — every **30s** (aligned with existing poll rhythm).
+- **Static inventory (slow):** disks, partitions and their usage, CPU model/cores, total RAM, OS details — every **15 min**.
+
+Transport: a **new unary gRPC `ReportInventory` RPC** (mirrors the existing `ReportUpdates` pattern). No streaming.
+
+---
+
+## 2. Locked decisions
+
+| Topic | Decision |
+|-------|----------|
+| Transport | New `ReportInventory` unary RPC. |
+| Cadence | Metrics every 30s; static inventory every 15 min. One RPC carries both, but static fields are only populated on the 15-min tick (empty/omitted otherwise → server keeps prior static snapshot). |
+| Storage | Latest snapshot embedded on the `servers` document (`inventory` sub-doc). No history/time-series in v1. |
+| Collection | Pure-Go where practical (`/proc`, `gopsutil`-style). Agent already runs as root. |
+| Platform | Linux primary; Windows agent populates what it can, leaves the rest empty. |
+
+---
+
+## 3. Data model
+
+Add an `Inventory` sub-document to the existing `Server` model (`server/internal/models/server.go`):
+
+```go
+type CPUInfo struct {
+	Model    string  `bson:"model,omitempty" json:"model,omitempty"`
+	Cores    int     `bson:"cores,omitempty" json:"cores,omitempty"`
+	UsagePct float64 `bson:"usage_pct" json:"usage_pct"`         // metrics tick
+	Load1    float64 `bson:"load1,omitempty" json:"load1,omitempty"`
+}
+
+type MemInfo struct {
+	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
+	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`       // metrics tick
+}
+
+type Partition struct {
+	Device     string `bson:"device" json:"device"`
+	Mountpoint string `bson:"mountpoint" json:"mountpoint"`
+	Fstype     string `bson:"fstype,omitempty" json:"fstype,omitempty"`
+	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
+	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
+}
+
+type Inventory struct {
+	CPU            CPUInfo     `bson:"cpu" json:"cpu"`
+	Memory         MemInfo     `bson:"memory" json:"memory"`
+	SwapTotalBytes uint64      `bson:"swap_total_bytes" json:"swap_total_bytes"`
+	SwapUsedBytes  uint64      `bson:"swap_used_bytes" json:"swap_used_bytes"`
+	Partitions     []Partition `bson:"partitions,omitempty" json:"partitions,omitempty"`
+	Kernel         string      `bson:"kernel,omitempty" json:"kernel,omitempty"`
+	MetricsAt      *time.Time  `bson:"metrics_at,omitempty" json:"metrics_at,omitempty"`
+	StaticAt       *time.Time  `bson:"static_at,omitempty" json:"static_at,omitempty"`
+}
+```
+
+Add `Inventory *Inventory` field to `Server`.
+
+Server-side update rules:
+- Metrics fields (`cpu.usage_pct`, `cpu.load1`, `memory.used_bytes`, swap used) always updated + `metrics_at`.
+- Static fields (`cpu.model/cores`, `memory.total_bytes`, `partitions`, `kernel`, swap total) updated only when the report includes them (non-zero/non-empty) + `static_at`.
+
+---
+
+## 4. gRPC protocol (`proto/vantage/v1/vantage.proto` + both `pb.go` files)
+
+```protobuf
+rpc ReportInventory(InventoryReport) returns (InventoryReportResponse);
+
+message InventoryReport {
+  string server_id    = 1;
+  string agent_token  = 2;
+  bool   include_static = 3; // true on the 15-min tick
+  CPUReport cpu       = 4;
+  MemReport memory    = 5;
+  uint64 swap_total   = 6;
+  uint64 swap_used    = 7;
+  repeated PartitionReport partitions = 8; // only when include_static
+  string kernel       = 9;                 // only when include_static
+}
+message CPUReport { string model = 1; int32 cores = 2; double usage_pct = 3; double load1 = 4; }
+message MemReport { uint64 total_bytes = 1; uint64 used_bytes = 2; }
+message PartitionReport { string device = 1; string mountpoint = 2; string fstype = 3; uint64 total_bytes = 4; uint64 used_bytes = 5; }
+message InventoryReportResponse {}
+```
+
+Hand-written JSON-codec structs added to `server/internal/grpc/pb/vantage.pb.go` and `agent/internal/grpc/pb/vantage.pb.go`, plus the RPC method wiring (service interface, client method, handler registration) mirroring `ReportUpdates`.
+
+---
+
+## 5. Agent collection (`agent/internal/inventory/`)
+
+- `Collect(includeStatic bool) *pb.InventoryReport` — reads:
+  - CPU usage: sample `/proc/stat` delta; load from `/proc/loadavg`; model/cores from `/proc/cpuinfo` (static).
+  - Memory/swap: `/proc/meminfo`.
+  - Partitions: `/proc/mounts` filtered to real filesystems + `statfs` for total/used (static).
+  - Kernel: `uname` / `/proc/version` (static).
+  - Windows: best-effort via `wmic`/PS or leave empty.
+- Scheduler in the agent main loop: a 30s ticker calls `Collect(false)` and `ReportInventory`; every 30th tick (15 min) calls `Collect(true)`.
+- Reuse existing gRPC client; add `Client.ReportInventory(...)` like `ReportUpdates`.
+
+Prefer implementing the `/proc` readers directly (no new heavy deps) unless a `gopsutil` dependency is already vendored.
+
+---
+
+## 6. Server handler + service
+
+- gRPC handler `ReportInventory` in `server/internal/grpc/server.go`: validate agent token (`ValidateAgentToken`), then call `services.StoreInventory(serverID, report)`.
+- `services.StoreInventory` (in `server/internal/services/inventory.go`): builds the `$set` per the update rules in §3 and `UpdateOne` on `servers`.
+
+---
+
+## 7. Frontend
+
+Surface inventory on the existing server detail page (`web/app/servers/[id]/page.tsx`) — add an "Inventory" panel:
+- CPU usage gauge + model/cores, load.
+- RAM used/total bar, swap bar.
+- Partitions table: device, mount, fstype, used/total with a usage bar.
+- "Updated Xs ago" from `metrics_at`/`static_at`.
+
+Optionally add compact CPU/RAM badges to the servers list (`web/app/servers/page.tsx`). Reuse `@/components/ui` + Tailwind tokens. Poll the server detail query while the page is open (react-query `refetchInterval` ~30s) so metrics stay fresh.
+
+---
+
+## 8. Out of scope
+
+- Time-series history / graphs (only latest snapshot stored).
+- Alerting thresholds on usage (settings/alerts is a separate concern).
+- Per-process / network / GPU inventory.
+- Tests (skipped, consistent with the Workflows iteration).

docs/superpowers/specs/2026-07-20-saas-auth-orgs-design.md

@@ -0,0 +1,142 @@
+# SaaS: Auth + Organizations — Design
+
+**Date:** 2026-07-20
+**Status:** Approved (design) — ready for implementation planning
+**Scope:** Local auth + organizations + per-org OIDC, and org-scoping of existing data. Billing/plan-limits explicitly deferred. Fleet Inventory and Server Workflows are separate sub-projects.
+
+---
+
+## 1. Summary
+
+Turn Vantage from a single-admin, single global-OIDC tool into a multi-tenant app:
+
+1. **Replace** the global Authentik/env-based OIDC with **local email/password accounts** as the primary login.
+2. **Organizations** — every user belongs to an org; every domain object (servers, keys, secrets, assignments, workflows, steps, runs, audit) carries an `org_id` and all queries are scoped to the caller's org.
+3. **Per-org OpenID** — an org admin can configure their own OIDC provider (issuer/client id/secret); users in that org can then sign in through it.
+
+No billing, no seat/server limits this iteration (schema leaves room).
+
+---
+
+## 2. Locked decisions
+
+| Topic | Decision |
+|-------|----------|
+| Primary auth | Local email + password (bcrypt). Replaces global Authentik. |
+| Org SSO | Per-org OIDC provider, configured by org admin, resolved dynamically at login. |
+| Isolation | `org_id` on every collection; every service query filtered by org. Enforced in the request layer via session→org. |
+| Roles | `owner`, `admin`, `member` (v1: owner/admin can manage users + org OIDC + all resources; member can use resources). Keep minimal. |
+| Bootstrapping | First-run creates the initial org + owner account (setup flow) when no users exist. |
+| Sessions | Keep existing Redis session store; session now carries `user_id`, `org_id`, `role`, `email`. |
+| Agent auth | Unchanged (per-server agent tokens). Servers gain `org_id`; agent RPCs resolve org from the server record. |
+
+---
+
+## 3. Data model
+
+### `orgs`
+```json
+{ "_id":"ObjectId", "org_id":"uuid", "name":"Acme", "created_at":"ISODate" }
+```
+
+### `users`
+```json
+{
+  "_id":"ObjectId", "user_id":"uuid", "org_id":"uuid",
+  "email":"a@b.com", "password_hash":"bcrypt...", "role":"owner|admin|member",
+  "auth_source":"local|oidc", "created_at":"ISODate", "last_login":"ISODate|null"
+}
+```
+Unique index on `email` (global — email identifies the account and its org).
+
+### `org_oidc` (per-org provider config)
+```json
+{
+  "_id":"ObjectId", "org_id":"uuid",
+  "issuer":"https://id.acme.com", "client_id":"...",
+  "client_secret_enc":"AES...",         // encrypted with existing crypto.go
+  "redirect_url":"https://vantage.../auth/oidc/callback",
+  "enabled": true, "updated_at":"ISODate"
+}
+```
+
+### Existing collections — add `org_id`
+`servers`, `keys`, `assignments`, `secrets`, `workflows`, `workflow_steps`, `workflow_runs`, `audit` each gain `org_id string`. A **migration** backfills all existing documents into a default org (see §7).
+
+---
+
+## 4. Auth flows
+
+### Local
+- `POST /auth/register` — only allowed during first-run bootstrap (creates org + owner) OR by an org admin inviting a user (see below). Not open self-serve.
+- `POST /auth/login` — email + password → verify bcrypt → create session with `{user_id, org_id, role, email}`.
+- `POST /auth/logout` — destroy session.
+- `GET /auth/me` — returns current user + org.
+
+### Org-admin user management
+- `GET /api/org/users` / `POST /api/org/users` (create local user in caller's org) / `PUT /api/org/users/:id/role` / `DELETE /api/org/users/:id`.
+
+### Per-org OIDC
+- `GET/PUT /api/org/oidc` — read/save the caller org's provider config (admin only). Secret stored encrypted.
+- `GET /auth/oidc/start?org=<org_id or slug>` — look up org's `org_oidc`, build the OIDC provider on demand (cache per org), redirect to authorize.
+- `GET /auth/oidc/callback` — exchange code, match/provision the user by email **within that org**, create session.
+  - If the email exists in the org → log in. If not → provision a `member` with `auth_source=oidc` (org admin can promote). Reject if email belongs to a different org.
+
+### First-run bootstrap
+- `GET /auth/bootstrap-status` → `{ needs_setup: bool }` (true when `users` is empty).
+- Setup page collects org name + owner email/password → creates org + owner → session.
+
+---
+
+## 5. Request scoping
+
+- `auth.Middleware` already loads the session; extend `Session` to include `OrgID`, `UserID`, `Role`. Add helper `auth.OrgID(c) string`.
+- **Every service function that reads/writes a scoped collection takes an `orgID` argument** and adds `"org_id": orgID` to its filter and on insert. Handlers pass `auth.OrgID(c)`.
+- Add a `requireRole(role)` gin middleware for admin-only routes (org user mgmt, org OIDC).
+- Agent-facing gRPC: resolve `org_id` from the `servers` record (already tied to `server_id`); inventory/keys/sync operate on that org implicitly.
+
+---
+
+## 6. Removing global Authentik
+
+- Delete/retire env-driven `InitOIDC` global provider (`OIDC_ISSUER` etc.). Keep the `go-oidc`/`oauth2` machinery but move it behind the per-org resolver.
+- `authEnabled` global replaced by "auth always on" (there is always local auth). Update `middleware.go` accordingly (no more `if !authEnabled { next }` bypass — except the bootstrap endpoints and login/register which are unauthenticated).
+- Login page (`web/app/login` or existing) offers: email/password form + "Sign in with your organization's SSO" (enter org, redirect to `/auth/oidc/start`).
+
+---
+
+## 7. Migration
+
+One-shot migration run at startup (idempotent):
+1. If `orgs` is empty AND `servers`/`keys`/etc. contain documents without `org_id`: create a **default org** ("Default").
+2. Set `org_id = <default>` on all existing `servers`, `keys`, `assignments`, `secrets`, `workflows`, `workflow_steps`, `workflow_runs`, `audit` documents missing it.
+3. If `OIDC_ISSUER` env was set previously and an admin email is known, optionally seed an owner user (documented manual step) — otherwise first-run bootstrap handles owner creation.
+Guard with a marker (e.g. a `migrations` collection entry) so it runs once.
+
+---
+
+## 8. Frontend
+
+- **Login/Setup:** `web/app/login/page.tsx` (email/password + org SSO entry) and `web/app/setup/page.tsx` (first-run). Redirect logic based on `bootstrap-status` and `auth/me`.
+- **Org settings:** `web/app/settings/org/` — members list + invite/create user + role management; OIDC provider form (issuer/client id/secret/enabled).
+- Existing pages unchanged functionally but now implicitly org-scoped by the backend. Show current org + user in the sidebar/header.
+
+---
+
+## 9. Security
+
+- Passwords: bcrypt (cost ≥ 12). Never returned.
+- Org OIDC client secret encrypted at rest (reuse `services/crypto.go` AES).
+- Cross-org access prevented at the service layer (org_id in every filter) — the primary isolation boundary. Handlers must never accept an `org_id` from the client; always derive from session.
+- OIDC callback must bind the returned identity to the org that initiated the flow (state carries org_id) to prevent org-mixing.
+- Role checks on all org-admin mutations.
+
+---
+
+## 10. Out of scope
+
+- Billing, plans, seat/server limits.
+- Cross-org resource sharing, org switching for a single user (one user = one org in v1).
+- SCIM / directory sync, SAML.
+- Email delivery for invites (create-user sets a password or invite token; email sending deferred — document as manual/console output).
+- Tests (skipped, consistent with prior iterations).

docs/superpowers/specs/2026-07-21-adhoc-steps-import-export-defaults-design.md

@@ -0,0 +1,267 @@
+# Ad-hoc Steps, Step Import/Export, and Default Steps — Design
+
+Date: 2026-07-21
+
+## Summary
+
+Four related additions to the workflow step system:
+
+1. **Ad-hoc steps** — steps defined inline in a single workflow, not written to the
+   shared step library.
+2. **Import/Export** — single-step portable JSON (`vantage.step/v1`). Import can
+   target the shared library or a workflow as an inline ad-hoc step.
+3. **Default steps** — JSON files in a bind-mounted directory, seeded into the
+   library on boot and re-syncable on demand. Org-ready for a future SaaS plan.
+4. **Auto-derived outputs** — `declared_outputs` is scanned from the script
+   (writes to `$WORKFLOW_ENV`) instead of being entered by hand.
+
+Existing model: shared steps live in the `workflow_steps` collection; a
+`Workflow.Steps[]` is a list of `WorkflowStepRef` that reference a library step by
+`step_id` and may carry `Overrides` + `Inputs`. `resolveSteps` freezes each ref
+into a `ResolvedStep` snapshot at run time.
+
+## 1. Data model
+
+`server/internal/models/workflow.go`.
+
+### WorkflowStep
+
+Add a provenance field:
+
+```go
+Source string `bson:"source" json:"source"` // "user" | "default"
+Slug   string `bson:"slug" json:"slug"`     // kebab of name; stable key for default seeding
+```
+
+`Slug` is set for `source="default"` steps (used as the upsert key by the seeder).
+For `source="user"` steps it may be empty. Existing steps default to
+`source="user"` (absent field decodes to "").
+
+### WorkflowStepRef
+
+Add an inline definition. A ref is **either** a library ref (`StepID` set) **or**
+ad-hoc (`Inline` set). Never both.
+
+```go
+type WorkflowStepRef struct {
+    StepID     string            `bson:"step_id,omitempty" json:"step_id"`
+    Inline     *WorkflowStep     `bson:"inline,omitempty" json:"inline,omitempty"`
+    Order      int               `bson:"order" json:"order"`
+    OnFailure  string            `bson:"on_failure" json:"on_failure"`
+    MaxRetries int               `bson:"max_retries" json:"max_retries"`
+    Overrides  *StepOverride     `bson:"overrides,omitempty" json:"overrides,omitempty"` // library-ref only
+    Inputs     map[string]string `bson:"inputs,omitempty" json:"inputs,omitempty"`
+}
+```
+
+`Inline` reuses `WorkflowStep` (name, description, interpreter, script,
+declared_inputs, declared_outputs, secret_refs). Its `ID`, `StepID`, `Slug`,
+`Source`, and timestamps stay empty and are never persisted to `workflow_steps`.
+
+Validation on workflow create/update: for each ref, exactly one of `StepID` /
+`Inline` must be set. `Overrides` is ignored when `Inline` is set.
+
+## 2. Resolve at run time
+
+`server/internal/services/workflow_runner.go`, `resolveSteps`.
+
+For each ref:
+
+- If `ref.Inline != nil`: build `ResolvedStep` from `ref.Inline` directly
+  (name/interpreter/script/secret_refs), apply `ref.Inputs` against
+  `Inline.DeclaredInputs` defaults. Skip `getStep`, skip `Overrides`.
+- Else: current library path unchanged (load step, apply overrides).
+
+`ResolvedStep` output shape and the run snapshot are unchanged, so the runner and
+the run-history UI need no changes.
+
+`DeleteStep` cascade is unaffected — ad-hoc refs carry no `step_id`, so they never
+match the cascade query.
+
+## 3. Import / Export
+
+Portable single-step JSON, `kind: "vantage.step/v1"`:
+
+```json
+{
+  "kind": "vantage.step/v1",
+  "name": "...",
+  "description": "...",
+  "interpreter": "bash",
+  "script": "...",
+  "declared_inputs": [ { "name": "...", "default": "...", "description": "..." } ],
+  "declared_outputs": ["..."],
+  "secret_refs": ["NAME"]
+}
+```
+
+Export strips `_id`, `step_id`, `slug`, `source`, and timestamps.
+Secret refs are exported as names only. On import, dangling secret refs are kept
+verbatim (not auto-created).
+
+### Service functions (`services/workflows.go`)
+
+- `ExportStep(stepID string) ([]byte, error)` — load library step, marshal to the
+  v1 shape.
+- `ParseStepDoc(b []byte) (models.WorkflowStep, error)` — validate `kind`, decode
+  into a `WorkflowStep` (no id/source). Shared by both import targets.
+- `ImportStepToLibrary(b []byte) (*models.WorkflowStep, error)` — `ParseStepDoc`
+  then `CreateStep` (fresh `step_id`, `source="user"`).
+
+Import-to-inline needs no new service fn: the web editor calls `ParseStepDoc`'s
+API equivalent (see routes) and drops the returned step object into a new
+`WorkflowStepRef.Inline` in the workflow it's editing, then saves the workflow
+normally.
+
+### Routes (`api/workflows.go`)
+
+- `GET  /api/steps/:id/export` — returns JSON as a downloadable attachment
+  (`Content-Disposition`).
+- `POST /api/steps/import` — body is the v1 JSON; imports to library; returns the
+  created step. (Used by the "import to library" flow.)
+- `POST /api/steps/parse` — body is the v1 JSON; validates and returns the
+  normalized step object **without** persisting. Used by "import to inline" so the
+  editor can insert it as an ad-hoc ref. (Keeps parsing/validation server-side.)
+
+Audit: `workflow.step_imported` logged on library import.
+
+## 4. Default steps (seed + admin re-sync)
+
+Mirrors the existing `WorkflowLogDir` pattern — a bind-mounted directory, no Go
+`embed`.
+
+### Directory
+
+```go
+// DefaultStepsDir returns the directory holding default step JSON files, creating it.
+func DefaultStepsDir() string {
+    dir := os.Getenv("VANTAGE_DEFAULT_STEPS_DIR")
+    if dir == "" {
+        dir = filepath.Join("data", "default-steps")
+    }
+    _ = os.MkdirAll(dir, 0700)
+    return dir
+}
+```
+
+Compose already bind-mounts `./data:/data`. Set
+`VANTAGE_DEFAULT_STEPS_DIR=/data/default-steps` for explicitness (optional).
+Operator drops `*.json` (`vantage.step/v1`) files into that folder.
+
+### Seeder
+
+`SeedDefaultSteps() (created, updated int, err error)`:
+
+1. Glob `DefaultStepsDir()/*.json`.
+2. For each file: `ParseStepDoc`, compute `slug = kebab(name)`.
+3. Upsert into `workflow_steps` keyed on `{ slug, source: "default" }`:
+   - absent → insert with fresh `step_id`, `source="default"`, `slug`. (`created++`)
+   - present → `$set` name/description/interpreter/script/declared_*/secret_refs +
+     `updated_at`. (`updated++`)
+
+**Override rule (confirmed):** re-sync is authoritative for `source="default"`
+steps and overwrites their content, reverting any user edits to those steps.
+`source="user"` steps are never touched by the seeder, even on a slug collision
+(the seeder query is scoped to `source: "default"`).
+
+Add a partial unique index on `slug` where `source == "default"` (or enforce
+uniqueness in the seeder loop) to keep default slugs unambiguous.
+
+### Boot
+
+Call `SeedDefaultSteps()` from server startup after `EnsureWorkflowIndexes()`
+(alongside index setup in `server/cmd/main.go`). Log the created/updated counts;
+a seed error is logged but non-fatal (server still boots).
+
+### Route
+
+- `POST /api/steps/seed-defaults` (admin) — runs `SeedDefaultSteps()`, returns
+  `{ "created": n, "updated": m }`. Audit `workflow.defaults_synced`.
+
+### Org readiness
+
+Signature stays global today. When Orgs land, `SeedDefaultSteps(orgID)` seeds
+per-org and the upsert key becomes `{ org_id, slug, source }`. No schema churn
+blocks that later change.
+
+## 5. Auto-derived outputs
+
+Today `WorkflowStep.DeclaredOutputs` is entered by hand and consumed only by the
+UI (no runtime reads it — outputs are captured at run time by `parseEnvFile` on
+the agent). Replace manual entry with a server-side scan of the script.
+
+At run time the agent exposes an env file path in `$WORKFLOW_ENV` (bash) /
+`$env:WORKFLOW_ENV` (powershell); a step emits an output by appending a
+`KEY=value` line to it, e.g. `echo "test=123" >> $WORKFLOW_ENV`.
+
+### Scanner
+
+`services.DeriveOutputs(script string) []string`:
+
+- Scan line by line. For each line that references `WORKFLOW_ENV`, extract every
+  `KEY=` assignment target on that line, where `KEY` matches
+  `[A-Za-z_][A-Za-z0-9_]*`.
+- Covers the common forms across both interpreters (line mentions `WORKFLOW_ENV`
+  and contains `KEY=...`):
+  - `echo "test=123" >> $WORKFLOW_ENV`
+  - `echo "test=123" >> "$WORKFLOW_ENV"`
+  - `printf 'k=v\n' >> $WORKFLOW_ENV`
+  - `"k=v" >> $env:WORKFLOW_ENV` / `Add-Content $env:WORKFLOW_ENV "k=v"`
+- Deduplicate, preserve first-seen order. Best-effort heuristic — false positives
+  are acceptable (they only widen the documented output list); it never affects
+  what the agent actually captures.
+
+### Wiring
+
+- `CreateStep` and `UpdateStep` set `DeclaredOutputs = DeriveOutputs(s.Script)`,
+  ignoring any client-sent value.
+- Inline ad-hoc steps: `DeriveOutputs` is applied when the workflow is saved (for
+  each `ref.Inline`), so inline outputs are derived too.
+- `ParseStepDoc` (import) also derives outputs, so `declared_outputs` in an
+  imported/exported file is informational and always recomputed on import.
+- `SeedDefaultSteps` derives outputs the same way when upserting.
+
+`DeclaredOutputs` stays in the model and JSON (still shown in the UI and used to
+wire step-to-step input references), it is just no longer user-authored.
+
+### Web
+
+The step editor's "declared outputs" input becomes a read-only, auto-populated
+display (derived from the script, refreshed on save / on script edit). No manual
+add/remove.
+
+## 6. Web
+
+`web/app/workflows/[id]/page.tsx` and the steps list page.
+
+- **Steps list:** per-row **Export** (downloads JSON) and top-level **Import**
+  (file picker → `POST /api/steps/import` → library). **Sync defaults** admin
+  button → `POST /api/steps/seed-defaults`, toast the counts. `source="default"`
+  rows get a "default" badge.
+- **Workflow editor — Add step:** existing "add from library" plus **Add ad-hoc
+  step** (inline mini-form: name, interpreter, script, optional inputs) stored as
+  a `WorkflowStepRef.Inline`. Also **Import ad-hoc from file** → `POST
+  /api/steps/parse` → inserts the returned step as a new inline ref.
+- Ad-hoc rows in the editor are visually distinguished from library refs (badge)
+  and are editable in place; library refs keep the existing override UI.
+
+## Testing
+
+- `resolveSteps`: inline ref resolves without touching the library; inputs apply
+  from `Inline.DeclaredInputs` defaults and ref overrides; library path unchanged.
+- Workflow validation: rejects a ref with both `StepID` and `Inline`, and one with
+  neither.
+- Export → import round-trips to an equivalent library step with a new `step_id`.
+- `ParseStepDoc` rejects a wrong/missing `kind`.
+- `SeedDefaultSteps`: insert-then-update idempotency; user steps untouched;
+  user-edited default step reverted on re-sync; counts correct.
+- `DeleteStep` cascade ignores ad-hoc refs.
+- `DeriveOutputs`: extracts keys from each interpreter form above, dedupes,
+  preserves order, ignores lines not referencing `WORKFLOW_ENV`; create/update/
+  import/seed all populate `declared_outputs` from it and ignore client input.
+
+## Out of scope
+
+- Whole-workflow export/import.
+- Auto-creating secret refs on import.
+- Multi-tenant Org model (design is forward-compatible only).

installer/setup.ps1

@@ -2,11 +2,85 @@ param(
   [string]$ServerId,
   [string]$Token,
   [string]$ServerUrl,
-  [string]$InstallDir
+  [string]$InstallDir,
+  [switch]$Uninstall
 )
-$cfgDir = Join-Path $env:ProgramData "vantage"
-New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
-$cfg = @"
+
+$ErrorActionPreference = "Stop"
+$logDir = Join-Path $env:ProgramData "vantage"
+New-Item -ItemType Directory -Force -Path $logDir | Out-Null
+$log = Join-Path $logDir "install.log"
+
+function Write-Log($msg) {
+  $line = "{0} {1}" -f (Get-Date -Format "s"), $msg
+  Add-Content -Path $log -Value $line
+}
+
+# Fail native-exe (nssm) calls loudly: check $LASTEXITCODE after each call
+function Invoke-Native {
+  param([string]$File, [string[]]$Arguments)
+  Write-Log ("RUN: {0} {1}" -f $File, ($Arguments -join " "))
+  $out = & $File @Arguments 2>&1
+  if ($out) { Write-Log ("OUT: {0}" -f ($out -join "`n")) }
+  if ($LASTEXITCODE -ne 0) {
+    throw ("{0} exited {1}" -f $File, $LASTEXITCODE)
+  }
+}
+
+# Like Invoke-Native but never throws — for teardown, where a missing/stopped
+# service must not abort the uninstall.
+function Invoke-NativeSoft {
+  param([string]$File, [string[]]$Arguments)
+  Write-Log ("RUN(soft): {0} {1}" -f $File, ($Arguments -join " "))
+  # Native stderr merged via 2>&1 becomes terminating errors under
+  # ErrorActionPreference=Stop; force Continue in this scope so a benign nssm
+  # message (e.g. "service has not been started") never aborts setup.
+  $ErrorActionPreference = "Continue"
+  $out = & $File @Arguments 2>&1
+  if ($out) { Write-Log ("OUT: {0}" -f ($out -join "`n")) }
+  Write-Log ("EXIT: {0}" -f $LASTEXITCODE)
+}
+
+if ($Uninstall) {
+  try {
+    Write-Log "=== teardown start ==="
+    if (-not $InstallDir) { $InstallDir = $PSScriptRoot }
+    $nssm = Join-Path $InstallDir "nssm.exe"
+    if (Test-Path $nssm) {
+      Invoke-NativeSoft -File $nssm -Arguments @("stop", "VantageAgent")
+      Invoke-NativeSoft -File $nssm -Arguments @("remove", "VantageAgent", "confirm")
+    } else {
+      Write-Log "nssm.exe not found at $nssm - using sc.exe fallback"
+      Invoke-NativeSoft -File "sc.exe" -Arguments @("stop", "VantageAgent")
+      Invoke-NativeSoft -File "sc.exe" -Arguments @("delete", "VantageAgent")
+    }
+    Write-Log "=== teardown ok ==="
+    exit 0
+  }
+  catch {
+    Write-Log ("TEARDOWN ERROR: {0}" -f $_.Exception.Message)
+    # Never block uninstall
+    exit 0
+  }
+}
+
+try {
+  Write-Log "=== setup start ==="
+  Write-Log ("ServerId={0} ServerUrl={1} InstallDir={2}" -f $ServerId, $ServerUrl, $InstallDir)
+
+  $cfgDir = Join-Path $env:ProgramData "vantage"
+  New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
+  $cfgPath = Join-Path $cfgDir "config.yaml"
+
+  # Preserve existing config on upgrade. A MajorUpgrade re-runs this script with
+  # no SERVERID/TOKEN, so blindly rewriting would wipe the agent_token the agent
+  # persisted after Register(). Only (re)write when a ServerId is supplied
+  # (fresh install / explicit re-register).
+  if ((Test-Path $cfgPath) -and (-not $ServerId)) {
+    Write-Log "config.yaml exists and no ServerId supplied - preserving existing config (upgrade)"
+  }
+  else {
+    $cfg = @"
 server_url: "$ServerUrl"
 server_id: "$ServerId"
 pre_reg_token: "$Token"
@@ -14,12 +88,53 @@ agent_token: ""
 poll_interval: 30s
 tls: true
 "@
-Set-Content -Path (Join-Path $cfgDir "config.yaml") -Value $cfg -Encoding utf8
-# Lock down ACL: SYSTEM + Administrators only
-icacls (Join-Path $cfgDir "config.yaml") /inheritance:r /grant:r "SYSTEM:F" "Administrators:F" | Out-Null
+    Set-Content -Path $cfgPath -Value $cfg -Encoding utf8
+    Write-Log "wrote $cfgPath"
 
-$nssm = Join-Path $InstallDir "nssm.exe"
-$exe  = Join-Path $InstallDir "vantage-agent.exe"
-& $nssm install VantageAgent $exe
-& $nssm set VantageAgent Start SERVICE_AUTO_START
-& $nssm start VantageAgent
+    # Lock down ACL: SYSTEM + Administrators only
+    Invoke-Native -File "icacls" -Arguments @($cfgPath, "/inheritance:r", "/grant:r", "SYSTEM:F", "Administrators:F")
+  }
+
+  if (-not $InstallDir) { $InstallDir = $PSScriptRoot }
+  $nssm = Join-Path $InstallDir "nssm.exe"
+  $exe  = Join-Path $InstallDir "vantage-agent.exe"
+
+  if (-not (Test-Path $nssm)) { throw "nssm.exe not found at $nssm" }
+  if (-not (Test-Path $exe))  { throw "vantage-agent.exe not found at $exe" }
+
+  # Install only if the service isn't already registered (an upgrade may leave
+  # it in place). "nssm install" on an existing service errors otherwise.
+  $exists = Get-Service -Name "VantageAgent" -ErrorAction SilentlyContinue
+  if (-not $exists) {
+    Invoke-Native -File $nssm -Arguments @("install", "VantageAgent", $exe)
+  } else {
+    Write-Log "VantageAgent service already exists - updating binary path"
+    Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "Application", $exe)
+  }
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "Start", "SERVICE_AUTO_START")
+
+  # Redirect service stdout/stderr to log files (nssm discards them otherwise)
+  # with online rotation at ~1MB.
+  $outLog = Join-Path $logDir "agent-stdout.log"
+  $errLog = Join-Path $logDir "agent-stderr.log"
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStdout", $outLog)
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStderr", $errLog)
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStdoutCreationDisposition", "4")
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStderrCreationDisposition", "4")
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppRotateFiles", "1")
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppRotateOnline", "1")
+  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppRotateBytes", "1048576")
+
+  # Service is freshly (re)installed and stopped here (teardown removed the old
+  # one on upgrade), so start it. "restart" would try to stop a not-running
+  # service and emit a stderr error.
+  Invoke-NativeSoft -File $nssm -Arguments @("start", "VantageAgent")
+
+  Write-Log "=== setup ok ==="
+  exit 0
+}
+catch {
+  Write-Log ("ERROR: {0}" -f $_.Exception.Message)
+  Write-Log ($_.ScriptStackTrace)
+  exit 1
+}

installer/vantage-agent.wxs

@@ -1,9 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<?ifndef Version ?>
+<?define Version = "0.0.0.0" ?>
+<?endif?>
 <Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
   <Package Name="Vantage Agent" Manufacturer="Vantage"
-           Version="1.0.0.0" UpgradeCode="7d1e6d2c-2a5f-4b3e-9c3a-8a1b2c3d4e5f"
+           Version="$(var.Version)" UpgradeCode="7d1e6d2c-2a5f-4b3e-9c3a-8a1b2c3d4e5f"
            Scope="perMachine">
-    <MajorUpgrade DowngradeErrorMessage="A newer version is already installed." />
+    <MajorUpgrade DowngradeErrorMessage="A newer version is already installed."
+                  Schedule="afterInstallInitialize" />
     <MediaTemplate EmbedCab="yes" />
 
     <!-- Public properties settable via msiexec: SERVERID, TOKEN, SERVERURL -->
@@ -54,13 +58,25 @@
          actual Windows machine before this is trusted in production. -->
     <SetProperty Id="WriteConfig"
       Before="WriteConfig" Sequence="execute" Condition="NOT Installed"
-      Value='cmd.exe /c powershell -ExecutionPolicy Bypass -File "[INSTALLDIR]setup.ps1" -ServerId "[SERVERID]" -Token "[TOKEN]" -ServerUrl "[SERVERURL]" -InstallDir "[INSTALLDIR]"' />
+      Value='cmd.exe /c powershell -ExecutionPolicy Bypass -File "[INSTALLDIR]setup.ps1" -ServerId "[SERVERID]" -Token "[TOKEN]" -ServerUrl "[SERVERURL]"' />
 
     <CustomAction Id="WriteConfig" Directory="INSTALLDIR" ExeCommand="[WriteConfig]"
       Execute="deferred" Impersonate="no" Return="check" />
 
+    <!-- Teardown on uninstall: stop + remove the service BEFORE RemoveFiles
+         deletes nssm.exe/setup.ps1. Same CustomActionData marshaling pattern
+         as WriteConfig. REMOVE="ALL" = full uninstall (not a component-level
+         repair/modify). -->
+    <SetProperty Id="RemoveService"
+      Before="RemoveService" Sequence="execute" Condition="REMOVE=&quot;ALL&quot;"
+      Value='cmd.exe /c powershell -ExecutionPolicy Bypass -File "[INSTALLDIR]setup.ps1" -Uninstall' />
+
+    <CustomAction Id="RemoveService" Directory="INSTALLDIR" ExeCommand="[RemoveService]"
+      Execute="deferred" Impersonate="no" Return="ignore" />
+
     <InstallExecuteSequence>
       <Custom Action="WriteConfig" After="InstallFiles" Condition="NOT Installed" />
+      <Custom Action="RemoveService" Before="RemoveFiles" Condition="REMOVE=&quot;ALL&quot;" />
     </InstallExecuteSequence>
   </Package>
 </Wix>

proto/vantage/v1/vantage.proto

@@ -55,6 +55,8 @@ message AgentMessage {
   oneof payload {
     AgentReady    ready  = 3;
     CommandResult result = 4;
+    StepResult step_result = 5;
+    StepOutputChunk step_output = 6;
   }
 }
 
@@ -89,9 +91,17 @@ message ServerCommand {
     DeleteKeyCmd    delete_key    = 3;
     UpdateAgentCmd  update_agent  = 4;
     ApplyUpdatesCmd apply_updates = 5;
+    RunStepCmd      run_step      = 6;
+    CleanupWorkspaceCmd cleanup_workspace = 7;
   }
 }
 
+// CleanupWorkspaceCmd tells the agent to recursively remove the run's working
+// directory once all steps on that server have finished.
+message CleanupWorkspaceCmd {
+  string workspace_id = 1;
+}
+
 message DeleteKeyCmd {
   string label = 1;
 }
@@ -108,3 +118,26 @@ message GenerateKeyCmd {
   string passphrase = 4; // empty = no passphrase
   string comment    = 5; // embedded in public key
 }
+
+message RunStepCmd {
+  string interpreter      = 1; // "bash" | "powershell"
+  string script           = 2;
+  map<string, string> env = 3;
+  int32  timeout_seconds  = 4;
+  string workspace_id     = 5; // per-run working dir the agent creates & uses as cwd
+}
+
+message StepResult {
+  string command_id             = 1;
+  int32  exit_code              = 2;
+  string stdout                 = 3;
+  string stderr                 = 4;
+  map<string, string> output_env = 5;
+}
+
+message StepOutputChunk {
+  string command_id = 1;
+  uint64 seq        = 2;
+  bytes  data       = 3;
+  bool   eof        = 4;
+}

server/cmd/main.go

@@ -27,6 +27,18 @@ func main() {
 		log.Printf("warning: failed to ensure secret indexes: %v", err)
 	}
 
+	if err := services.EnsureWorkflowIndexes(); err != nil {
+		log.Printf("warning: failed to ensure workflow indexes: %v", err)
+	}
+
+	if created, updated, err := services.SeedDefaultSteps(); err != nil {
+		log.Printf("warning: failed to seed default steps: %v", err)
+	} else {
+		log.Printf("default steps seeded: %d created, %d updated", created, updated)
+	}
+
+	services.StartLogSweeper()
+
 	redisAddr := getEnv("REDIS_ADDR", "localhost:6379")
 	if err := auth.InitRedis(redisAddr); err != nil {
 		log.Fatalf("failed to connect to Redis: %v", err)

server/internal/api/console.go

@@ -4,6 +4,7 @@ import (
 	"net"
 	"net/http"
 	"os"
+	"strconv"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -69,6 +70,16 @@ func consoleConnect(c *gin.Context) {
 	})
 }
 
+// queryIntDefault reads a positive integer query param, falling back to def
+// when absent, unparseable, or non-positive.
+func queryIntDefault(r *http.Request, key string, def int) int {
+	v, err := strconv.Atoi(r.URL.Query().Get(key))
+	if err != nil || v <= 0 {
+		return def
+	}
+	return v
+}
+
 // GET /api/console/tunnel?token=... (WebSocket upgrade)
 func consoleTunnel(c *gin.Context) {
 	token := c.Query("token")
@@ -139,9 +150,9 @@ func consoleTunnel(c *gin.Context) {
 		for k, v := range gp.Params {
 			config.Parameters[k] = v
 		}
-		config.OptimalScreenWidth = 1024
-		config.OptimalScreenHeight = 768
-		config.OptimalResolution = 96
+		config.OptimalScreenWidth = queryIntDefault(r, "width", 1024)
+		config.OptimalScreenHeight = queryIntDefault(r, "height", 768)
+		config.OptimalResolution = queryIntDefault(r, "dpi", 96)
 
 		addr, err := net.ResolveTCPAddr("tcp", guacdAddr)
 		if err != nil {

server/internal/api/handlers.go

@@ -23,6 +23,7 @@ func RegisterRoutes(r *gin.Engine) {
 	r.GET("/install", handleInstallScript)
 	r.GET("/install.ps1", handleInstallScriptWindows)
 	r.GET("/update", handleUpdateScript)
+	r.GET("/update.ps1", handleUpdateScriptWindows)
 
 	// ESO read endpoint — bearer-token auth, not session auth, so Kubernetes
 	// External Secrets Operator can call it. Lives under /api (so the reverse
@@ -77,6 +78,8 @@ func RegisterRoutes(r *gin.Engine) {
 
 		apiGroup.POST("/console/connect", consoleConnect)
 		apiGroup.GET("/console/tunnel", consoleTunnel)
+
+		registerWorkflowRoutes(apiGroup)
 	}
 }
 
@@ -124,10 +127,16 @@ func newServer(c *gin.Context) {
 		host, s.ServerID, token,
 	)
 
+	installCmdPS := fmt.Sprintf(
+		`irm "%s/install.ps1?server_id=%s&token=%s" | iex`,
+		host, s.ServerID, token,
+	)
+
 	c.JSON(http.StatusOK, gin.H{
-		"server_id":       s.ServerID,
-		"pre_reg_token":   token,
-		"install_command": installCmd,
+		"server_id":          s.ServerID,
+		"pre_reg_token":      token,
+		"install_command":    installCmd,
+		"install_command_ps": installCmdPS,
 	})
 }
 
@@ -441,14 +450,15 @@ func getSettings(c *gin.Context) {
 
 func saveSettings(c *gin.Context) {
 	var body struct {
-		Alerts models.AlertSettings `json:"alerts"`
-		Email  models.EmailSettings `json:"email"`
+		Alerts                   models.AlertSettings `json:"alerts"`
+		Email                    models.EmailSettings `json:"email"`
+		WorkflowLogRetentionDays *int                 `json:"workflow_log_retention_days"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	if err := services.SaveSettings(body.Alerts, body.Email); err != nil {
+	if err := services.SaveSettings(body.Alerts, body.Email, body.WorkflowLogRetentionDays); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}

server/internal/api/install_ps1.go

@@ -54,3 +54,40 @@ func handleInstallScriptWindows(c *gin.Context) {
 	c.Header("Content-Type", "text/plain; charset=utf-8")
 	c.String(http.StatusOK, script)
 }
+
+// handleUpdateScriptWindows serves a PowerShell one-liner that upgrades an
+// already-installed Windows agent. No server_id/token needed: the MSI is a
+// MajorUpgrade and setup.ps1 preserves the existing config on upgrade.
+func handleUpdateScriptWindows(c *gin.Context) {
+	giteaHost := os.Getenv("GITEA_HOST")
+	if giteaHost == "" {
+		giteaHost = "gitea.example.com"
+	}
+
+	script := fmt.Sprintf(
+		"#Requires -RunAsAdministrator\n"+
+			"$ErrorActionPreference = \"Stop\"\n"+
+			"\n"+
+			"$GiteaHost = \"%s\"\n"+
+			"\n"+
+			"$rel = Invoke-RestMethod -Uri \"https://$GiteaHost/api/v1/repos/mrhid6/vantage/releases?limit=10\"\n"+
+			"$tag = ($rel | Where-Object { $_.tag_name -like 'agent/v*' } | Select-Object -First 1).tag_name\n"+
+			"if (-not $tag) { throw \"Could not determine latest agent version\" }\n"+
+			"$enc = $tag -replace '/','%%2F'\n"+
+			"$base = \"https://$GiteaHost/mrhid6/vantage/releases/download/$enc\"\n"+
+			"\n"+
+			"$tmp = Join-Path $env:TEMP \"vantage-agent.msi\"\n"+
+			"Invoke-WebRequest -Uri \"$base/vantage-agent.msi\" -OutFile $tmp\n"+
+			"Invoke-WebRequest -Uri \"$base/checksums-msi.txt\" -OutFile \"$env:TEMP\\checksums-msi.txt\"\n"+
+			"\n"+
+			"$expected = (Get-Content \"$env:TEMP\\checksums-msi.txt\" | Select-String 'vantage-agent.msi').ToString().Split()[0]\n"+
+			"$actual = (Get-FileHash $tmp -Algorithm SHA256).Hash.ToLower()\n"+
+			"if ($expected -ne $actual) { throw \"Checksum mismatch\" }\n"+
+			"\n"+
+			"Start-Process msiexec.exe -Wait -ArgumentList \"/i `\"$tmp`\" /qn /norestart\"\n"+
+			"Write-Host \"Vantage agent updated to $tag.\"\n",
+		giteaHost)
+
+	c.Header("Content-Type", "text/plain; charset=utf-8")
+	c.String(http.StatusOK, script)
+}

server/internal/api/workflows.go

@@ -0,0 +1,352 @@
+package api
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mrhid6/vantage/server/internal/models"
+	"github.com/mrhid6/vantage/server/internal/services"
+)
+
+func registerWorkflowRoutes(g *gin.RouterGroup) {
+	g.GET("/steps", listSteps)
+	g.POST("/steps", createStep)
+	g.PUT("/steps/:id", updateStep)
+	g.DELETE("/steps/:id", deleteStep)
+	g.GET("/steps/:id/export", exportStep)
+	g.POST("/steps/import", importStep)
+	g.POST("/steps/seed-defaults", seedDefaults)
+	g.POST("/steps/parse", parseStep)
+
+	g.GET("/workflows", listWorkflows)
+	g.POST("/workflows", createWorkflow)
+	g.GET("/workflows/:id", getWorkflow)
+	g.PUT("/workflows/:id", updateWorkflow)
+	g.DELETE("/workflows/:id", deleteWorkflow)
+	g.POST("/workflows/:id/run", runWorkflow)
+	g.GET("/workflows/:id/runs", listWorkflowRuns)
+
+	g.GET("/runs/:runId", getRun)
+	g.POST("/runs/:runId/cancel", cancelRun)
+	g.GET("/runs/:runId/servers/:serverId/logs", getServerRunLog)
+	g.GET("/runs/:runId/servers/:serverId/logs/stream", streamServerRunLog)
+}
+
+var uuidLike = regexp.MustCompile(`^[a-zA-Z0-9-]{1,64}$`)
+
+func getServerRunLog(c *gin.Context) {
+	runID, serverID := c.Param("runId"), c.Param("serverId")
+	if !uuidLike.MatchString(runID) || !uuidLike.MatchString(serverID) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+	path := services.ServerRunLogPath(runID, serverID)
+	b, err := os.ReadFile(path)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no logs"})
+		return
+	}
+	c.Data(http.StatusOK, "text/plain; charset=utf-8", b)
+}
+
+func streamServerRunLog(c *gin.Context) {
+	runID, serverID := c.Param("runId"), c.Param("serverId")
+	if !uuidLike.MatchString(runID) || !uuidLike.MatchString(serverID) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
+		return
+	}
+	path := services.ServerRunLogPath(runID, serverID)
+
+	c.Writer.Header().Set("Content-Type", "text/event-stream")
+	c.Writer.Header().Set("Cache-Control", "no-cache")
+	c.Writer.Header().Set("Connection", "keep-alive")
+	c.Writer.Header().Set("X-Accel-Buffering", "no")
+
+	flusher, ok := c.Writer.(http.Flusher)
+	if !ok {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "stream unsupported"})
+		return
+	}
+
+	var offset int64
+	sendNew := func() {
+		f, err := os.Open(path)
+		if err != nil {
+			return // file may not exist yet; keep waiting
+		}
+		defer f.Close()
+		if _, err := f.Seek(offset, 0); err != nil {
+			return
+		}
+		buf := make([]byte, 32*1024)
+		for {
+			n, _ := f.Read(buf)
+			if n <= 0 {
+				break
+			}
+			offset += int64(n)
+			// SSE data frame; split on newlines to keep frames well-formed.
+			for _, line := range splitSSE(buf[:n]) {
+				_, _ = c.Writer.WriteString("data: " + line + "\n")
+			}
+			_, _ = c.Writer.WriteString("\n")
+			flusher.Flush()
+		}
+	}
+
+	ctx := c.Request.Context()
+	ticker := time.NewTicker(500 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		sendNew()
+		if serverRunTerminal(runID, serverID) {
+			sendNew() // final drain
+			_, _ = c.Writer.WriteString("event: done\ndata: end\n\n")
+			flusher.Flush()
+			return
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}
+
+// serverRunTerminal reports whether the given server-run has reached a terminal status.
+func serverRunTerminal(runID, serverID string) bool {
+	r, err := services.GetRun(runID)
+	if err != nil {
+		return true
+	}
+	for _, sr := range r.ServerRuns {
+		if sr.ServerID == serverID {
+			switch sr.Status {
+			case "success", "failed", "skipped", "cancelled":
+				return true
+			}
+			return false
+		}
+	}
+	return true
+}
+
+// splitSSE turns a raw byte slice into SSE-safe payload lines (newlines become
+// separate data lines; carriage returns stripped).
+func splitSSE(b []byte) []string {
+	s := strings.ReplaceAll(string(b), "\r", "")
+	return strings.Split(s, "\n")
+}
+
+func listSteps(c *gin.Context) {
+	steps, err := services.ListSteps()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, steps)
+}
+
+func createStep(c *gin.Context) {
+	var s models.WorkflowStep
+	if err := c.ShouldBindJSON(&s); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	out, err := services.CreateStep(s)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.step_created", actorFromCtx(c), "", out.StepID, fmt.Sprintf("step '%s' created", out.Name))
+	c.JSON(http.StatusCreated, out)
+}
+
+func updateStep(c *gin.Context) {
+	var s models.WorkflowStep
+	if err := c.ShouldBindJSON(&s); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := services.UpdateStep(c.Param("id"), s); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.step_updated", actorFromCtx(c), "", c.Param("id"), "step updated")
+	c.JSON(http.StatusOK, gin.H{"updated": true})
+}
+
+func deleteStep(c *gin.Context) {
+	if err := services.DeleteStep(c.Param("id")); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.step_deleted", actorFromCtx(c), "", c.Param("id"), "step deleted")
+	c.JSON(http.StatusOK, gin.H{"deleted": true})
+}
+
+func exportStep(c *gin.Context) {
+	b, err := services.ExportStep(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.Header("Content-Disposition", fmt.Sprintf("attachment; filename=step-%s.json", c.Param("id")))
+	c.Data(http.StatusOK, "application/json", b)
+}
+
+func seedDefaults(c *gin.Context) {
+	created, updated, err := services.SeedDefaultSteps()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.defaults_synced", actorFromCtx(c), "", "", fmt.Sprintf("default steps synced: %d created, %d updated", created, updated))
+	c.JSON(http.StatusOK, gin.H{"created": created, "updated": updated})
+}
+
+const maxStepBodyBytes = 1 << 20 // 1 MiB
+
+func importStep(c *gin.Context) {
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxStepBodyBytes)
+	body, err := io.ReadAll(c.Request.Body)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	out, err := services.ImportStepToLibrary(body)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.step_imported", actorFromCtx(c), "", out.StepID, fmt.Sprintf("step '%s' imported", out.Name))
+	c.JSON(http.StatusCreated, out)
+}
+
+// parseStep validates a step doc and returns the normalized step WITHOUT
+// persisting — used by the editor to insert an imported ad-hoc (inline) step.
+func parseStep(c *gin.Context) {
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxStepBodyBytes)
+	body, err := io.ReadAll(c.Request.Body)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	s, err := services.ParseStepDoc(body)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, s)
+}
+
+func listWorkflows(c *gin.Context) {
+	wfs, err := services.ListWorkflows()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, wfs)
+}
+
+func createWorkflow(c *gin.Context) {
+	var w models.Workflow
+	if err := c.ShouldBindJSON(&w); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	out, err := services.CreateWorkflow(w)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.created", actorFromCtx(c), "", out.WorkflowID, fmt.Sprintf("workflow '%s' created", out.Name))
+	c.JSON(http.StatusCreated, out)
+}
+
+func getWorkflow(c *gin.Context) {
+	w, err := services.GetWorkflow(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, w)
+}
+
+func updateWorkflow(c *gin.Context) {
+	var w models.Workflow
+	if err := c.ShouldBindJSON(&w); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := services.UpdateWorkflow(c.Param("id"), w); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.updated", actorFromCtx(c), "", c.Param("id"), "workflow updated")
+	updated, err := services.GetWorkflow(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, updated)
+}
+
+func deleteWorkflow(c *gin.Context) {
+	if err := services.DeleteWorkflow(c.Param("id")); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.deleted", actorFromCtx(c), "", c.Param("id"), "workflow deleted")
+	c.JSON(http.StatusOK, gin.H{"deleted": true})
+}
+
+func runWorkflow(c *gin.Context) {
+	runID, err := services.TriggerWorkflow(c.Param("id"), actorFromCtx(c))
+	if err != nil {
+		c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.run_triggered", actorFromCtx(c), "", c.Param("id"), fmt.Sprintf("run %s triggered", runID))
+	c.JSON(http.StatusAccepted, gin.H{"run_id": runID})
+}
+
+func listWorkflowRuns(c *gin.Context) {
+	limit := int64(50)
+	if l := c.Query("limit"); l != "" {
+		if n, err := strconv.ParseInt(l, 10, 64); err == nil && n > 0 {
+			limit = n
+		}
+	}
+	runs, err := services.ListRuns(c.Param("id"), limit)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, runs)
+}
+
+func getRun(c *gin.Context) {
+	r, err := services.GetRun(c.Param("runId"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, r)
+}
+
+func cancelRun(c *gin.Context) {
+	if err := services.CancelRun(c.Param("runId")); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent("workflow.run_cancelled", actorFromCtx(c), "", c.Param("runId"), "run cancelled")
+	c.JSON(http.StatusOK, gin.H{"cancelled": true})
+}

server/internal/grpc/pb/vantage.pb.go

@@ -66,11 +66,19 @@ type ReportUpdatesResponse struct{}
 type ApplyUpdatesCmd struct{}
 
 type ServerCommand struct {
-	CommandId    string           `json:"command_id"`
-	GenerateKey  *GenerateKeyCmd  `json:"generate_key,omitempty"`
-	DeleteKey    *DeleteKeyCmd    `json:"delete_key,omitempty"`
-	UpdateAgent  *UpdateAgentCmd  `json:"update_agent,omitempty"`
-	ApplyUpdates *ApplyUpdatesCmd `json:"apply_updates,omitempty"`
+	CommandId        string               `json:"command_id"`
+	GenerateKey      *GenerateKeyCmd      `json:"generate_key,omitempty"`
+	DeleteKey        *DeleteKeyCmd        `json:"delete_key,omitempty"`
+	UpdateAgent      *UpdateAgentCmd      `json:"update_agent,omitempty"`
+	ApplyUpdates     *ApplyUpdatesCmd     `json:"apply_updates,omitempty"`
+	RunStep          *RunStepCmd          `json:"run_step,omitempty"`
+	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
+}
+
+// CleanupWorkspaceCmd tells the agent to recursively remove the run's working
+// directory once all steps on that server have finished.
+type CleanupWorkspaceCmd struct {
+	WorkspaceId string `json:"workspace_id"`
 }
 
 type DeleteKeyCmd struct {
@@ -91,10 +99,12 @@ type GenerateKeyCmd struct {
 }
 
 type AgentMessage struct {
-	ServerId   string         `json:"server_id"`
-	AgentToken string         `json:"agent_token"`
-	Ready      *AgentReady    `json:"ready,omitempty"`
-	Result     *CommandResult `json:"result,omitempty"`
+	ServerId   string            `json:"server_id"`
+	AgentToken string            `json:"agent_token"`
+	Ready      *AgentReady       `json:"ready,omitempty"`
+	Result     *CommandResult    `json:"result,omitempty"`
+	StepResult *StepResult       `json:"step_result,omitempty"`
+	StepOutput *StepOutputChunk  `json:"step_output,omitempty"`
 }
 
 type AgentReady struct{}
@@ -105,6 +115,31 @@ type CommandResult struct {
 	Message   string `json:"message"`
 }
 
+type RunStepCmd struct {
+	Interpreter    string            `json:"interpreter"`
+	Script         string            `json:"script"`
+	Env            map[string]string `json:"env,omitempty"`
+	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
+	// WorkspaceId names the per-run working directory the agent creates and uses
+	// as the step's cwd. Empty means run in the agent's default directory.
+	WorkspaceId string `json:"workspace_id,omitempty"`
+}
+
+type StepResult struct {
+	CommandId string            `json:"command_id"`
+	ExitCode  int               `json:"exit_code"`
+	Stdout    string            `json:"stdout,omitempty"`
+	Stderr    string            `json:"stderr,omitempty"`
+	OutputEnv map[string]string `json:"output_env,omitempty"`
+}
+
+type StepOutputChunk struct {
+	CommandId string `json:"command_id"`
+	Seq       uint64 `json:"seq"`
+	Data      []byte `json:"data,omitempty"`
+	Eof       bool   `json:"eof,omitempty"`
+}
+
 // CommandStream server-side interface
 
 type Vantage_CommandStreamServer interface {

server/internal/grpc/server.go

@@ -43,6 +43,10 @@ func (s *vantageServer) SyncKeys(ctx context.Context, req *pb.SyncRequest) (*pb.
 		log.Printf("failed to update last seen for %s: %v", srv.ServerID, err)
 	}
 
+	if err := services.BackfillConsoleConfig(srv); err != nil {
+		log.Printf("failed to backfill console config for %s: %v", srv.ServerID, err)
+	}
+
 	keys, err := services.BuildAuthorizedKeys(req.ServerId)
 	if err != nil {
 		return nil, status.Errorf(codes.Internal, "failed to build authorized keys: %v", err)
@@ -125,6 +129,16 @@ func (s *vantageServer) CommandStream(stream pb.Vantage_CommandStreamServer) err
 				r := m.Result
 				log.Printf("agent %s cmd %s: success=%v %s", srv.ServerID, r.CommandId, r.Success, r.Message)
 			}
+			if m.StepResult != nil {
+				services.StepResults.Deliver(m.StepResult)
+			}
+			if m.StepOutput != nil {
+				if m.StepOutput.Eof {
+					services.StepLogs.Close(m.StepOutput.CommandId)
+				} else {
+					services.StepLogs.Append(m.StepOutput.CommandId, m.StepOutput.Data)
+				}
+			}
 		}
 	}()
 

server/internal/models/settings.go

@@ -36,4 +36,6 @@ type Settings struct {
 	Alerts  AlertSettings   `bson:"alerts" json:"alerts"`
 	Email   EmailSettings   `bson:"email" json:"email"`
 	Secrets SecretsSettings `bson:"secrets" json:"secrets"`
+	// WorkflowLogRetentionDays: nil = default 30, 0 = keep forever, N = N days.
+	WorkflowLogRetentionDays *int `bson:"workflow_log_retention_days,omitempty" json:"workflow_log_retention_days,omitempty"`
 }

server/internal/models/workflow.go

@@ -0,0 +1,101 @@
+package models
+
+import (
+	"time"
+
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type InputParam struct {
+	Name        string `bson:"name" json:"name"`
+	Default     string `bson:"default" json:"default"`
+	Description string `bson:"description" json:"description"`
+}
+
+type WorkflowStep struct {
+	ID              bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	StepID          string        `bson:"step_id" json:"step_id"`
+	Name            string        `bson:"name" json:"name"`
+	Description     string        `bson:"description" json:"description"`
+	Interpreter     string        `bson:"interpreter" json:"interpreter"` // "bash" | "powershell"
+	Script          string        `bson:"script" json:"script"`
+	DeclaredOutputs []string      `bson:"declared_outputs" json:"declared_outputs"`
+	DeclaredInputs  []InputParam  `bson:"declared_inputs" json:"declared_inputs"`
+	SecretRefs      []string      `bson:"secret_refs" json:"secret_refs"`
+	Source          string        `bson:"source" json:"source"` // "user" | "default"
+	Slug            string        `bson:"slug,omitempty" json:"slug,omitempty"`
+	CreatedAt       time.Time     `bson:"created_at" json:"created_at"`
+	UpdatedAt       time.Time     `bson:"updated_at" json:"updated_at"`
+}
+
+type WorkflowStepRef struct {
+	StepID     string            `bson:"step_id,omitempty" json:"step_id,omitempty"`
+	Inline     *WorkflowStep     `bson:"inline,omitempty" json:"inline,omitempty"`
+	Order      int               `bson:"order" json:"order"`
+	OnFailure  string            `bson:"on_failure" json:"on_failure"` // "stop" | "continue" | "retry"
+	MaxRetries int               `bson:"max_retries" json:"max_retries"`
+	Overrides  *StepOverride     `bson:"overrides,omitempty" json:"overrides,omitempty"`
+	Inputs     map[string]string `bson:"inputs,omitempty" json:"inputs,omitempty"`
+}
+
+type StepOverride struct {
+	Script     *string  `bson:"script,omitempty" json:"script,omitempty"`
+	SecretRefs []string `bson:"secret_refs,omitempty" json:"secret_refs,omitempty"`
+}
+
+type Workflow struct {
+	ID              bson.ObjectID     `bson:"_id,omitempty" json:"-"`
+	WorkflowID      string            `bson:"workflow_id" json:"workflow_id"`
+	Name            string            `bson:"name" json:"name"`
+	TargetServerIDs []string          `bson:"target_server_ids" json:"target_server_ids"`
+	Steps           []WorkflowStepRef `bson:"steps" json:"steps"`
+	CreatedAt       time.Time         `bson:"created_at" json:"created_at"`
+	UpdatedAt       time.Time         `bson:"updated_at" json:"updated_at"`
+}
+
+// ResolvedStep is a step frozen into a run snapshot (library step + overrides applied).
+type ResolvedStep struct {
+	Order       int      `bson:"order" json:"order"`
+	Name        string   `bson:"name" json:"name"`
+	Interpreter string   `bson:"interpreter" json:"interpreter"`
+	Script      string   `bson:"script" json:"script"`
+	SecretRefs  []string          `bson:"secret_refs" json:"secret_refs"`
+	OnFailure   string            `bson:"on_failure" json:"on_failure"`
+	MaxRetries  int               `bson:"max_retries" json:"max_retries"`
+	Inputs      map[string]string `bson:"inputs" json:"inputs"`
+}
+
+type StepRun struct {
+	Order      int               `bson:"order" json:"order"`
+	Name       string            `bson:"name" json:"name"`
+	Status     string            `bson:"status" json:"status"` // queued|running|success|failed|skipped
+	Attempts   int               `bson:"attempts" json:"attempts"`
+	ExitCode   int               `bson:"exit_code" json:"exit_code"`
+	LogOffset  int64             `bson:"log_offset" json:"log_offset"`
+	OutputEnv  map[string]string `bson:"output_env" json:"output_env"`
+	StartedAt  *time.Time        `bson:"started_at,omitempty" json:"started_at,omitempty"`
+	FinishedAt *time.Time        `bson:"finished_at,omitempty" json:"finished_at,omitempty"`
+}
+
+type ServerRun struct {
+	ServerID   string            `bson:"server_id" json:"server_id"`
+	Hostname   string            `bson:"hostname" json:"hostname"`
+	Status     string            `bson:"status" json:"status"` // queued|running|success|failed|skipped
+	StartedAt  *time.Time        `bson:"started_at,omitempty" json:"started_at,omitempty"`
+	FinishedAt *time.Time        `bson:"finished_at,omitempty" json:"finished_at,omitempty"`
+	RunEnv     map[string]string `bson:"run_env" json:"run_env"`
+	Steps      []StepRun         `bson:"steps" json:"steps"`
+}
+
+type WorkflowRun struct {
+	ID          bson.ObjectID  `bson:"_id,omitempty" json:"-"`
+	RunID       string         `bson:"run_id" json:"run_id"`
+	WorkflowID  string         `bson:"workflow_id" json:"workflow_id"`
+	Name        string         `bson:"name" json:"name"`
+	Steps       []ResolvedStep `bson:"steps_snapshot" json:"steps_snapshot"`
+	Status      string         `bson:"status" json:"status"` // running|success|failed|cancelled
+	TriggeredBy string         `bson:"triggered_by" json:"triggered_by"`
+	StartedAt   time.Time      `bson:"started_at" json:"started_at"`
+	FinishedAt  *time.Time     `bson:"finished_at,omitempty" json:"finished_at,omitempty"`
+	ServerRuns  []ServerRun    `bson:"server_runs" json:"server_runs"`
+}

server/internal/services/defaults.go

@@ -0,0 +1,94 @@
+package services
+
+import (
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/server/internal/db"
+	"github.com/mrhid6/vantage/server/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+// DefaultStepsDir returns the directory holding default step JSON files.
+func DefaultStepsDir() string {
+	dir := os.Getenv("VANTAGE_DEFAULT_STEPS_DIR")
+	if dir == "" {
+		dir = filepath.Join("data", "default-steps")
+	}
+	_ = os.MkdirAll(dir, 0700)
+	return dir
+}
+
+// readDefaultStepFiles parses every *.json in the defaults dir into
+// source=default library steps (with slug set). Non-json and invalid files are
+// skipped silently; a slug is derived from the step name.
+func readDefaultStepFiles() ([]models.WorkflowStep, error) {
+	matches, err := filepath.Glob(filepath.Join(DefaultStepsDir(), "*.json"))
+	if err != nil {
+		return nil, err
+	}
+	out := []models.WorkflowStep{}
+	for _, path := range matches {
+		b, err := os.ReadFile(path)
+		if err != nil {
+			continue
+		}
+		s, err := ParseStepDoc(b)
+		if err != nil {
+			continue
+		}
+		s.Source = "default"
+		s.Slug = Slugify(s.Name)
+		if s.Slug == "" {
+			continue
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// SeedDefaultSteps upserts default steps from disk keyed on {slug, source}.
+// Re-sync overwrites default-step content; user steps are never touched.
+func SeedDefaultSteps() (created, updated int, err error) {
+	steps, err := readDefaultStepFiles()
+	if err != nil {
+		return 0, 0, err
+	}
+	ctx, cancel := wfCtx()
+	defer cancel()
+	col := db.Col("workflow_steps")
+	for _, s := range steps {
+		filter := bson.M{"slug": s.Slug, "source": "default"}
+		set := bson.M{
+			"name":             s.Name,
+			"description":      s.Description,
+			"interpreter":      s.Interpreter,
+			"script":           s.Script,
+			"declared_outputs": s.DeclaredOutputs,
+			"declared_inputs":  s.DeclaredInputs,
+			"secret_refs":      s.SecretRefs,
+			"updated_at":       time.Now(),
+		}
+		res, uerr := col.UpdateOne(ctx, filter, bson.M{
+			"$set": set,
+			"$setOnInsert": bson.M{
+				"step_id":    uuid.New().String(),
+				"slug":       s.Slug,
+				"source":     "default",
+				"created_at": time.Now(),
+			},
+		}, options.UpdateOne().SetUpsert(true))
+		if uerr != nil {
+			return created, updated, uerr
+		}
+		if res.UpsertedCount > 0 {
+			created++
+		} else if res.ModifiedCount > 0 {
+			updated++
+		}
+	}
+	return created, updated, nil
+}

server/internal/services/defaults_test.go

@@ -0,0 +1,38 @@
+package services
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestDefaultStepsDirEnv(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "ds")
+	t.Setenv("VANTAGE_DEFAULT_STEPS_DIR", dir)
+	got := DefaultStepsDir()
+	if got != dir {
+		t.Fatalf("got %q want %q", got, dir)
+	}
+	if _, err := os.Stat(dir); err != nil {
+		t.Fatalf("dir not created: %v", err)
+	}
+}
+
+func TestReadDefaultStepFiles(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("VANTAGE_DEFAULT_STEPS_DIR", dir)
+	good := `{"kind":"vantage.step/v1","name":"Ping Host","interpreter":"bash","script":"ping -c1 x=1 >> $WORKFLOW_ENV"}`
+	os.WriteFile(filepath.Join(dir, "ping.json"), []byte(good), 0600)
+	os.WriteFile(filepath.Join(dir, "notes.txt"), []byte("ignore me"), 0600)
+
+	steps, err := readDefaultStepFiles()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 {
+		t.Fatalf("want 1 step, got %d", len(steps))
+	}
+	if steps[0].Slug != "ping-host" || steps[0].Source != "default" {
+		t.Fatalf("bad seed step: %+v", steps[0])
+	}
+}

server/internal/services/dispatch.go

@@ -62,6 +62,25 @@ func (d *commandDispatcher) dispatch(serverID string, cmd *pb.ServerCommand) err
 	}
 }
 
+// DispatchRunStep pushes a RunStepCmd to a server's agent. Caller must have
+// registered StepResults.Await(commandID) first.
+func DispatchRunStep(serverID, commandID string, cmd *pb.RunStepCmd) error {
+	return Dispatcher.dispatch(serverID, &pb.ServerCommand{CommandId: commandID, RunStep: cmd})
+}
+
+// DispatchCleanupWorkspace tells a server's agent to remove a run's working
+// directory. Best-effort and fire-and-forget: if the agent is gone the temp dir
+// is reclaimed by the OS on reboot anyway.
+func DispatchCleanupWorkspace(serverID, workspaceID string) {
+	if !Dispatcher.IsConnected(serverID) {
+		return
+	}
+	_ = Dispatcher.dispatch(serverID, &pb.ServerCommand{
+		CommandId:        uuid.New().String(),
+		CleanupWorkspace: &pb.CleanupWorkspaceCmd{WorkspaceId: workspaceID},
+	})
+}
+
 // KeyGenParams carries all options for a generate-key command.
 type KeyGenParams struct {
 	Label      string

server/internal/services/resolve_test.go

@@ -0,0 +1,37 @@
+package services
+
+import (
+	"testing"
+
+	"github.com/mrhid6/vantage/server/internal/models"
+)
+
+func TestResolveInlineStep(t *testing.T) {
+	ref := models.WorkflowStepRef{
+		Order:     2,
+		OnFailure: "",
+		Inline: &models.WorkflowStep{
+			Name:        "adhoc",
+			Interpreter: "bash",
+			Script:      "echo hi",
+			SecretRefs:  []string{"TOKEN"},
+			DeclaredInputs: []models.InputParam{
+				{Name: "REGION", Default: "eu"},
+			},
+		},
+		Inputs: map[string]string{"REGION": "us"},
+	}
+	rs := resolveInlineStep(ref)
+	if rs.Name != "adhoc" || rs.Script != "echo hi" || rs.Order != 2 {
+		t.Fatalf("bad resolve: %+v", rs)
+	}
+	if rs.OnFailure != "stop" {
+		t.Fatalf("want default on_failure=stop, got %q", rs.OnFailure)
+	}
+	if rs.Inputs["REGION"] != "us" {
+		t.Fatalf("want input override us, got %q", rs.Inputs["REGION"])
+	}
+	if len(rs.SecretRefs) != 1 || rs.SecretRefs[0] != "TOKEN" {
+		t.Fatalf("bad secret refs: %v", rs.SecretRefs)
+	}
+}

server/internal/services/servers.go

@@ -167,6 +167,37 @@ func ValidateAgentToken(serverID, agentToken string) (*models.Server, error) {
 	return &s, nil
 }
 
+// BackfillConsoleConfig sets default console_protocols/ports for a server that
+// predates the console feature (or was updated without re-registering). Servers
+// register only once via a single-use pre_reg_token, so Register() never runs
+// again to populate these fields — this runs on every sync as a cheap no-op
+// once the fields are present.
+func BackfillConsoleConfig(srv *models.Server) error {
+	if srv == nil || len(srv.ConsoleProtocols) > 0 {
+		return nil
+	}
+
+	osType := srv.OSType
+	if osType == "" {
+		osType = OSTypeFromInfo(srv.OSInfo)
+	}
+	protocols, sshPort, rdpPort := defaultConsoleFields(osType)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	_, err := db.Col("servers").UpdateOne(ctx,
+		bson.M{"server_id": srv.ServerID, "console_protocols": bson.M{"$in": []interface{}{nil, bson.A{}}}},
+		bson.M{"$set": bson.M{
+			"os_type":           osType,
+			"console_protocols": protocols,
+			"ssh_port":          sshPort,
+			"rdp_port":          rdpPort,
+		}},
+	)
+	return err
+}
+
 func UpdateServerLastSeen(serverID, agentVersion string) error {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()

server/internal/services/settings.go

@@ -100,7 +100,7 @@ func VerifySecretsReadToken(token string) bool {
 	return subtle.ConstantTimeCompare(expected, got[:]) == 1
 }
 
-func SaveSettings(alerts models.AlertSettings, email models.EmailSettings) error {
+func SaveSettings(alerts models.AlertSettings, email models.EmailSettings, retentionDays *int) error {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 
@@ -111,14 +111,31 @@ func SaveSettings(alerts models.AlertSettings, email models.EmailSettings) error
 		email.SMTPPort = 587
 	}
 
+	set := bson.M{"alerts": alerts, "email": email}
+	if retentionDays != nil {
+		set["workflow_log_retention_days"] = *retentionDays
+	}
 	_, err := db.Col("settings").UpdateOne(ctx,
 		bson.M{},
-		bson.M{"$set": bson.M{"alerts": alerts, "email": email}},
+		bson.M{"$set": set},
 		options.UpdateOne().SetUpsert(true),
 	)
 	return err
 }
 
+// GetWorkflowLogRetentionDays returns the log retention in days: 30 when unset,
+// 0 for keep-forever, or the configured value.
+func GetWorkflowLogRetentionDays() (int, error) {
+	s, err := GetSettings()
+	if err != nil {
+		return 30, err
+	}
+	if s.WorkflowLogRetentionDays == nil {
+		return 30, nil
+	}
+	return *s.WorkflowLogRetentionDays, nil
+}
+
 func SendOfflineWebhook(webhookURL, hostname, serverID, ipAddress string) {
 	payload := map[string]any{
 		"event":      "server.offline",

server/internal/services/stepio.go

@@ -0,0 +1,86 @@
+package services
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/mrhid6/vantage/server/internal/models"
+)
+
+const StepDocKind = "vantage.step/v1"
+
+// StepDoc is the portable, id-free representation of a step.
+type StepDoc struct {
+	Kind            string              `json:"kind"`
+	Name            string              `json:"name"`
+	Description     string              `json:"description"`
+	Interpreter     string              `json:"interpreter"`
+	Script          string              `json:"script"`
+	DeclaredOutputs []string            `json:"declared_outputs"`
+	DeclaredInputs  []models.InputParam `json:"declared_inputs"`
+	SecretRefs      []string            `json:"secret_refs"`
+}
+
+// ExportStepDoc builds a portable doc from a library step (ids/source stripped).
+func ExportStepDoc(s models.WorkflowStep) StepDoc {
+	return StepDoc{
+		Kind:            StepDocKind,
+		Name:            s.Name,
+		Description:     s.Description,
+		Interpreter:     s.Interpreter,
+		Script:          s.Script,
+		DeclaredOutputs: s.DeclaredOutputs,
+		DeclaredInputs:  s.DeclaredInputs,
+		SecretRefs:      s.SecretRefs,
+	}
+}
+
+// ParseStepDoc validates a v1 doc and returns a normalized (id-free) step with
+// declared_outputs recomputed from the script.
+func ParseStepDoc(b []byte) (models.WorkflowStep, error) {
+	var d StepDoc
+	if err := json.Unmarshal(b, &d); err != nil {
+		return models.WorkflowStep{}, fmt.Errorf("invalid step JSON: %w", err)
+	}
+	if d.Kind != StepDocKind {
+		return models.WorkflowStep{}, fmt.Errorf("unsupported kind %q (want %q)", d.Kind, StepDocKind)
+	}
+	if d.Name == "" || d.Interpreter == "" {
+		return models.WorkflowStep{}, fmt.Errorf("step name and interpreter are required")
+	}
+	if d.SecretRefs == nil {
+		d.SecretRefs = []string{}
+	}
+	if d.DeclaredInputs == nil {
+		d.DeclaredInputs = []models.InputParam{}
+	}
+	return models.WorkflowStep{
+		Name:            d.Name,
+		Description:     d.Description,
+		Interpreter:     d.Interpreter,
+		Script:          d.Script,
+		DeclaredOutputs: DeriveOutputs(d.Script),
+		DeclaredInputs:  d.DeclaredInputs,
+		SecretRefs:      d.SecretRefs,
+	}, nil
+}
+
+// ImportStepToLibrary parses a doc and persists it as a new user library step.
+func ImportStepToLibrary(b []byte) (*models.WorkflowStep, error) {
+	s, err := ParseStepDoc(b)
+	if err != nil {
+		return nil, err
+	}
+	return CreateStep(s)
+}
+
+// ExportStep loads a library step and marshals it to a portable doc.
+func ExportStep(stepID string) ([]byte, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	s, err := getStep(ctx, stepID)
+	if err != nil {
+		return nil, err
+	}
+	return json.MarshalIndent(ExportStepDoc(*s), "", "  ")
+}

server/internal/services/stepio_test.go

@@ -0,0 +1,60 @@
+package services
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/mrhid6/vantage/server/internal/models"
+)
+
+func mkStep() models.WorkflowStep {
+	return models.WorkflowStep{
+		StepID: "should-not-export", Source: "default", Name: "Restart",
+		Interpreter: "bash", Script: "echo x=1 >> $WORKFLOW_ENV",
+		SecretRefs: []string{"TOK"},
+	}
+}
+
+func TestParseStepDocValid(t *testing.T) {
+	raw := `{"kind":"vantage.step/v1","name":"Restart","interpreter":"bash",
+	  "script":"echo x=1 >> $WORKFLOW_ENV","declared_outputs":["stale"],
+	  "declared_inputs":[{"name":"A","default":"1"}],"secret_refs":["TOK"]}`
+	s, err := ParseStepDoc([]byte(raw))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Name != "Restart" || s.Interpreter != "bash" {
+		t.Fatalf("bad parse: %+v", s)
+	}
+	// declared_outputs recomputed from script, ignoring the file's ["stale"].
+	if len(s.DeclaredOutputs) != 1 || s.DeclaredOutputs[0] != "x" {
+		t.Fatalf("outputs should be derived, got %v", s.DeclaredOutputs)
+	}
+	if s.StepID != "" || s.Source != "" {
+		t.Fatalf("parse must not set id/source")
+	}
+}
+
+func TestParseStepDocBadKind(t *testing.T) {
+	if _, err := ParseStepDoc([]byte(`{"kind":"nope","name":"x"}`)); err == nil {
+		t.Fatal("want error for bad kind")
+	}
+}
+
+func TestParseStepDocBadJSON(t *testing.T) {
+	if _, err := ParseStepDoc([]byte(`{`)); err == nil {
+		t.Fatal("want error for bad json")
+	}
+}
+
+func TestExportStepDocRoundTrip(t *testing.T) {
+	doc := ExportStepDoc(mkStep())
+	b, _ := json.Marshal(doc)
+	s, err := ParseStepDoc(b)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Name != "Restart" || s.Interpreter != "bash" {
+		t.Fatalf("round trip lost data: %+v", s)
+	}
+}

server/internal/services/steplogs.go

@@ -0,0 +1,217 @@
+package services
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/mrhid6/vantage/server/internal/db"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// WorkflowLogDir returns the base directory for workflow step logs, creating it.
+func WorkflowLogDir() string {
+	dir := os.Getenv("VANTAGE_WORKFLOW_LOG_DIR")
+	if dir == "" {
+		dir = filepath.Join("data", "workflow-logs")
+	}
+	_ = os.MkdirAll(dir, 0700)
+	return dir
+}
+
+// ServerRunLogPath is the per-server-run log file path.
+func ServerRunLogPath(runID, serverID string) string {
+	return filepath.Join(WorkflowLogDir(), runID, serverID+".log")
+}
+
+// logTS is the UTC timestamp prefix stamped on every log line. Stored in UTC
+// (RFC3339, millisecond precision); the UI renders it in the viewer's timezone.
+func logTS() string {
+	return time.Now().UTC().Format("2006-01-02T15:04:05.000") + "Z"
+}
+
+// AppendMarker writes a timestamped event line to the server-run log and returns
+// the byte offset at which the write began (used as a step's log_offset).
+func AppendMarker(runID, serverID, text string) (int64, error) {
+	path := ServerRunLogPath(runID, serverID)
+	if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return 0, err
+	}
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
+	if err != nil {
+		return 0, err
+	}
+	defer f.Close()
+	off, _ := f.Seek(0, 2) // current end = offset before write
+	if _, err := f.WriteString("[" + logTS() + "] " + text + "\n"); err != nil {
+		return off, err
+	}
+	return off, nil
+}
+
+// ---- streamed chunk writer, boundary-safe secret masking ----
+
+type stepLogWriter struct {
+	mu      sync.Mutex
+	f       *os.File
+	carry   []byte // bytes of an as-yet-unterminated line
+	secrets []string
+}
+
+type stepLogRegistry struct {
+	mu      sync.Mutex
+	writers map[string]*stepLogWriter
+}
+
+var StepLogs = &stepLogRegistry{writers: make(map[string]*stepLogWriter)}
+
+// Open opens (append) the server-run file for a step's streamed chunks.
+func (r *stepLogRegistry) Open(commandID, path string, secrets []string) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return err
+	}
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
+	if err != nil {
+		return err
+	}
+	w := &stepLogWriter{f: f, secrets: secrets}
+	r.mu.Lock()
+	r.writers[commandID] = w
+	r.mu.Unlock()
+	return nil
+}
+
+func (r *stepLogRegistry) get(commandID string) *stepLogWriter {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.writers[commandID]
+}
+
+// Append buffers chunks into whole lines, then writes each complete line with a
+// UTC timestamp prefix and secret masking applied. Buffering by line means a
+// secret split across a chunk boundary is always masked (the whole line is
+// assembled first) and every line carries its own timestamp.
+func (r *stepLogRegistry) Append(commandID string, data []byte) {
+	w := r.get(commandID)
+	if w == nil {
+		return
+	}
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	buf := append(w.carry, data...)
+	for {
+		i := bytes.IndexByte(buf, '\n')
+		if i < 0 {
+			break
+		}
+		w.writeLine(buf[:i])
+		buf = buf[i+1:]
+	}
+	w.carry = append([]byte{}, buf...)
+}
+
+// writeLine emits one masked, timestamped log line. Caller holds w.mu.
+func (w *stepLogWriter) writeLine(line []byte) {
+	masked := maskBytes(line, w.secrets)
+	_, _ = w.f.WriteString("[" + logTS() + "] ")
+	_, _ = w.f.Write(masked)
+	_, _ = w.f.WriteString("\n")
+}
+
+// Close flushes any trailing partial line and closes the file.
+func (r *stepLogRegistry) Close(commandID string) {
+	r.mu.Lock()
+	w := r.writers[commandID]
+	delete(r.writers, commandID)
+	r.mu.Unlock()
+	if w == nil {
+		return
+	}
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if len(w.carry) > 0 {
+		w.writeLine(w.carry)
+		w.carry = nil
+	}
+	_ = w.f.Close()
+}
+
+func maskBytes(b []byte, secrets []string) []byte {
+	s := string(b)
+	for _, v := range secrets {
+		if v == "" {
+			continue
+		}
+		s = strings.ReplaceAll(s, v, "***")
+	}
+	return []byte(s)
+}
+
+// ---- retention sweeper ----
+
+// StartLogSweeper sweeps expired run-log dirs hourly (and once now).
+func StartLogSweeper() {
+	go func() {
+		sweepLogs()
+		t := time.NewTicker(time.Hour)
+		defer t.Stop()
+		for range t.C {
+			sweepLogs()
+		}
+	}()
+}
+
+func sweepLogs() {
+	days := retentionDays()
+	if days <= 0 {
+		return
+	}
+	cutoff := time.Now().AddDate(0, 0, -days)
+	base := WorkflowLogDir()
+	entries, err := os.ReadDir(base)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		runID := e.Name()
+		dir := filepath.Join(base, runID)
+		if runExpired(runID, dir, cutoff) {
+			_ = os.RemoveAll(dir)
+		}
+	}
+}
+
+// runExpired is true when the run finished before cutoff (falling back to dir
+// mtime when the run doc is gone).
+func runExpired(runID, dir string, cutoff time.Time) bool {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	var run struct {
+		FinishedAt *time.Time `bson:"finished_at"`
+	}
+	err := db.Col("workflow_runs").FindOne(ctx, bson.M{"run_id": runID}).Decode(&run)
+	if err == nil {
+		if run.FinishedAt == nil {
+			return false // still running / never finished — keep
+		}
+		return run.FinishedAt.Before(cutoff)
+	}
+	// run doc gone: use dir mtime
+	if fi, e := os.Stat(dir); e == nil {
+		return fi.ModTime().Before(cutoff)
+	}
+	return false
+}
+
+func retentionDays() int {
+	if v, err := GetWorkflowLogRetentionDays(); err == nil {
+		return v
+	}
+	return 30
+}

server/internal/services/stepresults.go

@@ -0,0 +1,49 @@
+package services
+
+import (
+	"sync"
+
+	"github.com/mrhid6/vantage/server/internal/grpc/pb"
+)
+
+type stepResultRegistry struct {
+	mu      sync.Mutex
+	pending map[string]chan *pb.StepResult
+}
+
+// StepResults correlates agent StepResult replies back to the workflow runner
+// goroutine that dispatched the matching RunStepCmd, keyed by command_id.
+var StepResults = &stepResultRegistry{pending: make(map[string]chan *pb.StepResult)}
+
+// Await registers interest in a command's result BEFORE the command is
+// dispatched, and returns a buffered channel that receives the single result.
+func (r *stepResultRegistry) Await(commandID string) <-chan *pb.StepResult {
+	ch := make(chan *pb.StepResult, 1)
+	r.mu.Lock()
+	r.pending[commandID] = ch
+	r.mu.Unlock()
+	return ch
+}
+
+// Cancel removes a pending waiter (call on timeout to avoid leaks).
+func (r *stepResultRegistry) Cancel(commandID string) {
+	r.mu.Lock()
+	delete(r.pending, commandID)
+	r.mu.Unlock()
+}
+
+// Deliver routes an incoming StepResult to its waiter, if any.
+func (r *stepResultRegistry) Deliver(res *pb.StepResult) {
+	if res == nil {
+		return
+	}
+	r.mu.Lock()
+	ch, ok := r.pending[res.CommandId]
+	if ok {
+		delete(r.pending, res.CommandId)
+	}
+	r.mu.Unlock()
+	if ok {
+		ch <- res
+	}
+}

server/internal/services/stepscan.go

@@ -0,0 +1,44 @@
+package services
+
+import (
+	"regexp"
+	"strings"
+)
+
+// keyAssign matches an env-var assignment target: KEY= (captures KEY).
+var keyAssign = regexp.MustCompile(`([A-Za-z_][A-Za-z0-9_]*)=`)
+
+// DeriveOutputs scans a step script and returns the output keys it writes to
+// $WORKFLOW_ENV. Best-effort: only lines that reference WORKFLOW_ENV are
+// considered. Deduplicated, first-seen order preserved.
+func DeriveOutputs(script string) []string {
+	out := []string{}
+	seen := map[string]bool{}
+	for _, line := range strings.Split(script, "\n") {
+		if !strings.Contains(line, "WORKFLOW_ENV") {
+			continue
+		}
+		for _, m := range keyAssign.FindAllStringSubmatch(line, -1) {
+			key := m[1]
+			// Skip the sentinel itself (e.g. "WORKFLOW_ENV=..." assignments).
+			if key == "WORKFLOW_ENV" || key == "env" {
+				continue
+			}
+			if seen[key] {
+				continue
+			}
+			seen[key] = true
+			out = append(out, key)
+		}
+	}
+	return out
+}
+
+var slugStrip = regexp.MustCompile(`[^a-z0-9]+`)
+
+// Slugify converts a step name into a stable kebab-case slug.
+func Slugify(name string) string {
+	s := strings.ToLower(name)
+	s = slugStrip.ReplaceAllString(s, "-")
+	return strings.Trim(s, "-")
+}

server/internal/services/stepscan_test.go

@@ -0,0 +1,45 @@
+package services
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestDeriveOutputs(t *testing.T) {
+	script := `#!/bin/bash
+echo "test=123" >> $WORKFLOW_ENV
+echo "other=hi" >> "$WORKFLOW_ENV"
+printf 'third=1\n' >> $WORKFLOW_ENV
+echo "test=456" >> $WORKFLOW_ENV
+echo "ignored=nope"
+NORMAL=assignment
+`
+	got := DeriveOutputs(script)
+	want := []string{"test", "other", "third"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("got %v want %v", got, want)
+	}
+}
+
+func TestDeriveOutputsPowershell(t *testing.T) {
+	script := `"result=ok" >> $env:WORKFLOW_ENV
+Add-Content $env:WORKFLOW_ENV "count=5"`
+	got := DeriveOutputs(script)
+	want := []string{"result", "count"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("got %v want %v", got, want)
+	}
+}
+
+func TestDeriveOutputsNone(t *testing.T) {
+	got := DeriveOutputs("echo hello\nNOPE=1")
+	if len(got) != 0 {
+		t.Fatalf("got %v want empty", got)
+	}
+}
+
+func TestSlugify(t *testing.T) {
+	if got := Slugify("Restart NGINX  Service!"); got != "restart-nginx-service" {
+		t.Fatalf("got %q", got)
+	}
+}

server/internal/services/validate.go

@@ -0,0 +1,19 @@
+package services
+
+import (
+	"fmt"
+
+	"github.com/mrhid6/vantage/server/internal/models"
+)
+
+// ValidateWorkflow checks each step ref sets exactly one of step_id / inline.
+func ValidateWorkflow(w models.Workflow) error {
+	for i, ref := range w.Steps {
+		hasLib := ref.StepID != ""
+		hasInline := ref.Inline != nil
+		if hasLib == hasInline {
+			return fmt.Errorf("step %d: exactly one of step_id or inline must be set", i)
+		}
+	}
+	return nil
+}

server/internal/services/validate_test.go

@@ -0,0 +1,29 @@
+package services
+
+import (
+	"testing"
+
+	"github.com/mrhid6/vantage/server/internal/models"
+)
+
+func TestValidateWorkflow(t *testing.T) {
+	inline := &models.WorkflowStep{Name: "x", Interpreter: "bash", Script: "echo hi"}
+	cases := []struct {
+		name    string
+		ref     models.WorkflowStepRef
+		wantErr bool
+	}{
+		{"library only", models.WorkflowStepRef{StepID: "abc"}, false},
+		{"inline only", models.WorkflowStepRef{Inline: inline}, false},
+		{"both set", models.WorkflowStepRef{StepID: "abc", Inline: inline}, true},
+		{"neither set", models.WorkflowStepRef{}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidateWorkflow(models.Workflow{Steps: []models.WorkflowStepRef{tc.ref}})
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("got err=%v want wantErr=%v", err, tc.wantErr)
+			}
+		})
+	}
+}

server/internal/services/workflow_runner.go

@@ -0,0 +1,505 @@
+package services
+
+import (
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/server/internal/db"
+	"github.com/mrhid6/vantage/server/internal/grpc/pb"
+	"github.com/mrhid6/vantage/server/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+const stepDispatchGrace = 15 * time.Second
+
+// TriggerWorkflow snapshots the workflow, creates a run doc, and starts a
+// background goroutine per target server (parallel fan-out). Returns run_id.
+func TriggerWorkflow(workflowID, actor string) (string, error) {
+	wf, err := GetWorkflow(workflowID)
+	if err != nil {
+		return "", err
+	}
+	if len(wf.TargetServerIDs) == 0 {
+		return "", fmt.Errorf("workflow has no target servers")
+	}
+	if len(wf.Steps) == 0 {
+		return "", fmt.Errorf("workflow has no steps")
+	}
+
+	// Reject a concurrent run of the same workflow.
+	ctx, cancel := wfCtx()
+	running := db.Col("workflow_runs").FindOne(ctx, bson.M{"workflow_id": workflowID, "status": "running"})
+	cancel()
+	if running.Err() == nil {
+		return "", fmt.Errorf("workflow already has a run in progress")
+	}
+
+	resolved, err := resolveSteps(wf)
+	if err != nil {
+		return "", err
+	}
+
+	run := models.WorkflowRun{
+		RunID:       uuid.New().String(),
+		WorkflowID:  workflowID,
+		Name:        wf.Name,
+		Steps:       resolved,
+		Status:      "running",
+		TriggeredBy: actor,
+		StartedAt:   time.Now(),
+		ServerRuns:  make([]models.ServerRun, 0, len(wf.TargetServerIDs)),
+	}
+	for _, sid := range wf.TargetServerIDs {
+		hostname := sid
+		if s, e := GetServer(sid); e == nil {
+			hostname = s.Hostname
+		}
+		sr := models.ServerRun{ServerID: sid, Hostname: hostname, Status: "queued", RunEnv: map[string]string{}}
+		for _, rs := range resolved {
+			sr.Steps = append(sr.Steps, models.StepRun{Order: rs.Order, Name: rs.Name, Status: "queued", OutputEnv: map[string]string{}})
+		}
+		run.ServerRuns = append(run.ServerRuns, sr)
+	}
+
+	ictx, icancel := wfCtx()
+	defer icancel()
+	if _, err := db.Col("workflow_runs").InsertOne(ictx, run); err != nil {
+		return "", err
+	}
+
+	go executeRun(run.RunID)
+	return run.RunID, nil
+}
+
+// resolveSteps freezes each workflow step ref into a ResolvedStep by loading the
+// library step and applying overrides.
+func resolveSteps(wf *models.Workflow) ([]models.ResolvedStep, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	out := make([]models.ResolvedStep, 0, len(wf.Steps))
+	for _, ref := range wf.Steps {
+		if ref.Inline != nil {
+			out = append(out, resolveInlineStep(ref))
+			continue
+		}
+		lib, err := getStep(ctx, ref.StepID)
+		if err != nil {
+			return nil, err
+		}
+		inputs := map[string]string{}
+		for _, p := range lib.DeclaredInputs {
+			if ref.Inputs != nil {
+				if v, ok := ref.Inputs[p.Name]; ok {
+					inputs[p.Name] = v
+					continue
+				}
+			}
+			inputs[p.Name] = p.Default
+		}
+		rs := models.ResolvedStep{
+			Order:       ref.Order,
+			Name:        lib.Name,
+			Interpreter: lib.Interpreter,
+			Script:      lib.Script,
+			SecretRefs:  lib.SecretRefs,
+			OnFailure:   ref.OnFailure,
+			MaxRetries:  ref.MaxRetries,
+			Inputs:      inputs,
+		}
+		if ref.Overrides != nil {
+			if ref.Overrides.Script != nil {
+				rs.Script = *ref.Overrides.Script
+			}
+			if ref.Overrides.SecretRefs != nil {
+				rs.SecretRefs = ref.Overrides.SecretRefs
+			}
+		}
+		if rs.OnFailure == "" {
+			rs.OnFailure = "stop"
+		}
+		out = append(out, rs)
+	}
+	return out, nil
+}
+
+// resolveInlineStep freezes an ad-hoc (inline) step ref into a ResolvedStep.
+func resolveInlineStep(ref models.WorkflowStepRef) models.ResolvedStep {
+	in := ref.Inline
+	inputs := map[string]string{}
+	for _, p := range in.DeclaredInputs {
+		if ref.Inputs != nil {
+			if v, ok := ref.Inputs[p.Name]; ok {
+				inputs[p.Name] = v
+				continue
+			}
+		}
+		inputs[p.Name] = p.Default
+	}
+	onFailure := ref.OnFailure
+	if onFailure == "" {
+		onFailure = "stop"
+	}
+	return models.ResolvedStep{
+		Order:       ref.Order,
+		Name:        in.Name,
+		Interpreter: in.Interpreter,
+		Script:      in.Script,
+		SecretRefs:  in.SecretRefs,
+		OnFailure:   onFailure,
+		MaxRetries:  ref.MaxRetries,
+		Inputs:      inputs,
+	}
+}
+
+// executeRun fans out one goroutine per server run and waits for all to finish.
+func executeRun(runID string) {
+	run, err := GetRun(runID)
+	if err != nil {
+		return
+	}
+	done := make(chan int, len(run.ServerRuns))
+	for i := range run.ServerRuns {
+		go func(idx int) {
+			runServer(runID, idx, run.Steps, run.ServerRuns[idx].ServerID)
+			done <- idx
+		}(i)
+	}
+	for range run.ServerRuns {
+		<-done
+	}
+
+	// Aggregate status.
+	final, _ := GetRun(runID)
+	status := "success"
+	for _, sr := range final.ServerRuns {
+		if sr.Status == "failed" {
+			status = "failed"
+		}
+	}
+	now := time.Now()
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, _ = db.Col("workflow_runs").UpdateOne(ctx, bson.M{"run_id": runID, "status": "running"},
+		bson.M{"$set": bson.M{"status": status, "finished_at": now}})
+}
+
+// runServer executes the resolved steps sequentially on one server, threading
+// output env forward and applying per-step failure policy.
+func runServer(runID string, srvIdx int, steps []models.ResolvedStep, serverID string) {
+	now := time.Now()
+	setServerRun(runID, srvIdx, bson.M{"server_runs.$.status": "running", "server_runs.$.started_at": now})
+
+	if !Dispatcher.IsConnected(serverID) {
+		fin := time.Now()
+		_, _ = AppendMarker(runID, serverID, "agent not connected — server skipped")
+		setServerRun(runID, srvIdx, bson.M{"server_runs.$.status": "skipped", "server_runs.$.finished_at": fin})
+		return
+	}
+
+	_, _ = AppendMarker(runID, serverID, fmt.Sprintf("run started on %s — %d step(s), workspace vantage-run-%s", serverID, len(steps), runID))
+
+	runEnv := map[string]string{}
+	allSecrets := map[string]string{}
+	serverFailed := false
+
+	for i, step := range steps {
+		startStep(runID, serverID, i, "running")
+		stepStart := time.Now()
+		var res *pb.StepResult
+		attempts := 0
+		maxAttempts := 1
+		if step.OnFailure == "retry" {
+			maxAttempts = step.MaxRetries + 1
+		}
+
+		// Merge secrets into command env (kept out of persisted logs).
+		secretVals := resolveSecrets(step.SecretRefs)
+		for k, v := range secretVals {
+			allSecrets[k] = v
+		}
+		// Input values may template earlier step outputs and secrets, e.g.
+		// URL="http://example.com/$VersionNumber". Expand against runEnv (outputs
+		// threaded from prior steps) and this step's secrets before dispatch.
+		subst := map[string]string{}
+		for k, v := range runEnv {
+			subst[k] = v
+		}
+		for k, v := range secretVals {
+			subst[k] = v
+		}
+		cmdEnv := map[string]string{}
+		for k, v := range step.Inputs {
+			cmdEnv[k] = expandVars(v, subst)
+		}
+		for k, v := range runEnv {
+			cmdEnv[k] = v
+		}
+		for k, v := range secretVals {
+			cmdEnv[k] = v
+		}
+
+		// Write the step marker to the server-run log and remember the offset so
+		// the UI can slice this step's output later.
+		marker := fmt.Sprintf("===== step %d/%d: %s (%s) =====", step.Order+1, len(steps), step.Name, step.Interpreter)
+		offset, _ := AppendMarker(runID, serverID, marker)
+		logPath := ServerRunLogPath(runID, serverID)
+		secretsSlice := secretValues(secretVals)
+
+		commandID := uuid.New().String()
+		for attempts < maxAttempts {
+			attempts++
+			if attempts > 1 {
+				_, _ = AppendMarker(runID, serverID, fmt.Sprintf("retry %d/%d after failure", attempts-1, maxAttempts-1))
+			}
+			// Open a fresh writer per attempt; the agent's eof closes it, and the
+			// defensive Close below covers a missing result.
+			_ = StepLogs.Open(commandID, logPath, secretsSlice)
+			res = dispatchAndWait(serverID, commandID, &pb.RunStepCmd{
+				Interpreter:    step.Interpreter,
+				Script:         step.Script,
+				Env:            cmdEnv,
+				TimeoutSeconds: 0,
+				WorkspaceId:    runID,
+			})
+			StepLogs.Close(commandID) // idempotent; no-op if eof already closed it
+			if res != nil && res.ExitCode == 0 {
+				break
+			}
+		}
+
+		exit := 1
+		outEnv := map[string]string{} // masked copy, safe to persist
+		if res != nil {
+			exit = res.ExitCode
+			for k, v := range res.OutputEnv {
+				runEnv[k] = v // real, unmasked value threads forward to later steps
+				outEnv[k] = maskSecrets(v, allSecrets)
+			}
+		} else {
+			_, _ = AppendMarker(runID, serverID, "agent did not return a result")
+		}
+
+		status := "success"
+		if exit != 0 {
+			status = "failed"
+		}
+		finishStep(runID, serverID, i, status, attempts, exit, offset, outEnv)
+
+		dur := time.Since(stepStart).Round(time.Millisecond)
+		_, _ = AppendMarker(runID, serverID, fmt.Sprintf("step %d/%d %s — exit %d, %d attempt(s), %s",
+			step.Order+1, len(steps), status, exit, attempts, dur))
+
+		if exit != 0 {
+			switch step.OnFailure {
+			case "continue":
+				_, _ = AppendMarker(runID, serverID, "on_failure=continue — proceeding to next step")
+			default: // "stop" or exhausted "retry"
+				serverFailed = true
+			}
+			if serverFailed {
+				_, _ = AppendMarker(runID, serverID, "stopping run — remaining steps skipped")
+				markRemainingSkipped(runID, serverID, i+1)
+				break
+			}
+		}
+	}
+
+	// Tell the agent to remove the run's working directory now that its steps are
+	// done (success or failure). Best-effort; the OS reclaims temp dirs anyway.
+	DispatchCleanupWorkspace(serverID, runID)
+
+	fin := time.Now()
+	status := "success"
+	if serverFailed {
+		status = "failed"
+	}
+	_, _ = AppendMarker(runID, serverID, fmt.Sprintf("run %s in %s — workspace removed",
+		status, fin.Sub(now).Round(time.Millisecond)))
+	// Persist only a masked copy of runEnv; the real (unmasked) runEnv was already
+	// used above to build cmdEnv for each step and must never be written to the DB.
+	maskedRunEnv := make(map[string]string, len(runEnv))
+	for k, v := range runEnv {
+		maskedRunEnv[k] = maskSecrets(v, allSecrets)
+	}
+	setServerRun(runID, srvIdx, bson.M{
+		"server_runs.$.status":      status,
+		"server_runs.$.finished_at": fin,
+		"server_runs.$.run_env":     maskedRunEnv,
+	})
+}
+
+// dispatchAndWait registers a waiter, dispatches the step, and blocks for the
+// result or a timeout.
+func dispatchAndWait(serverID, commandID string, cmd *pb.RunStepCmd) *pb.StepResult {
+	ch := StepResults.Await(commandID)
+	if err := DispatchRunStep(serverID, commandID, cmd); err != nil {
+		StepResults.Cancel(commandID)
+		return &pb.StepResult{ExitCode: 1, Stderr: "[vantage] dispatch failed: " + err.Error()}
+	}
+	wait := time.Duration(cmd.TimeoutSeconds)*time.Second + stepDispatchGrace
+	if cmd.TimeoutSeconds == 0 {
+		wait = 30*time.Minute + stepDispatchGrace
+	}
+	select {
+	case res := <-ch:
+		return res
+	case <-time.After(wait):
+		StepResults.Cancel(commandID)
+		return &pb.StepResult{ExitCode: 124, Stderr: "[vantage] timed out waiting for agent result"}
+	}
+}
+
+// expandVars substitutes $VAR and ${VAR} references in an input value from the
+// given lookup (prior step outputs and secrets). Unknown references expand to
+// empty, matching shell behaviour; a literal "$" is written as "$$".
+func expandVars(v string, lookup map[string]string) string {
+	return os.Expand(v, func(name string) string {
+		if name == "$" {
+			return "$"
+		}
+		return lookup[name]
+	})
+}
+
+func resolveSecrets(refs []string) map[string]string {
+	out := map[string]string{}
+	for _, ref := range refs {
+		// ref format "group/KEY"; resolve via RevealSecret.
+		parts := strings.SplitN(ref, "/", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		if v, err := RevealSecret(parts[0], parts[1]); err == nil {
+			out[parts[1]] = v
+		}
+	}
+	return out
+}
+
+func maskSecrets(s string, secrets map[string]string) string {
+	for _, v := range secrets {
+		if v == "" {
+			continue
+		}
+		s = strings.ReplaceAll(s, v, "***")
+	}
+	return s
+}
+
+// ---- run doc mutation helpers ----
+
+func setServerRun(runID string, srvIdx int, set bson.M) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, _ = db.Col("workflow_runs").UpdateOne(ctx,
+		bson.M{"run_id": runID, "server_runs.server_id": serverIDAt(runID, srvIdx)},
+		bson.M{"$set": set})
+}
+
+// serverIDAt returns the server_id at an index (positional operator needs a match).
+func serverIDAt(runID string, srvIdx int) string {
+	r, err := GetRun(runID)
+	if err != nil || srvIdx >= len(r.ServerRuns) {
+		return ""
+	}
+	return r.ServerRuns[srvIdx].ServerID
+}
+
+func startStep(runID, serverID string, order int, status string) {
+	now := time.Now()
+	updateStep(runID, serverID, order, bson.M{
+		"server_runs.$[s].steps.$[t].status":     status,
+		"server_runs.$[s].steps.$[t].started_at": now,
+	})
+}
+
+func finishStep(runID, serverID string, order int, status string, attempts, exit int, logOffset int64, outEnv map[string]string) {
+	now := time.Now()
+	updateStep(runID, serverID, order, bson.M{
+		"server_runs.$[s].steps.$[t].status":      status,
+		"server_runs.$[s].steps.$[t].attempts":    attempts,
+		"server_runs.$[s].steps.$[t].exit_code":   exit,
+		"server_runs.$[s].steps.$[t].log_offset":  logOffset,
+		"server_runs.$[s].steps.$[t].output_env":  outEnv,
+		"server_runs.$[s].steps.$[t].finished_at": now,
+	})
+}
+
+// secretValues returns just the values of a secret map, for masking log output.
+func secretValues(m map[string]string) []string {
+	out := make([]string, 0, len(m))
+	for _, v := range m {
+		out = append(out, v)
+	}
+	return out
+}
+
+func markRemainingSkipped(runID, serverID string, fromOrder int) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, _ = db.Col("workflow_runs").UpdateMany(ctx,
+		bson.M{"run_id": runID},
+		bson.M{"$set": bson.M{"server_runs.$[s].steps.$[t].status": "skipped"}},
+		options.UpdateMany().SetArrayFilters([]interface{}{
+			bson.M{"s.server_id": serverID},
+			bson.M{"t.order": bson.M{"$gte": fromOrder}, "t.status": "queued"},
+		}),
+	)
+}
+
+func updateStep(runID, serverID string, order int, set bson.M) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, _ = db.Col("workflow_runs").UpdateOne(ctx,
+		bson.M{"run_id": runID},
+		bson.M{"$set": set},
+		options.UpdateOne().SetArrayFilters([]interface{}{
+			bson.M{"s.server_id": serverID},
+			bson.M{"t.order": order},
+		}),
+	)
+}
+
+// ---- reads ----
+
+func GetRun(runID string) (*models.WorkflowRun, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	var r models.WorkflowRun
+	err := db.Col("workflow_runs").FindOne(ctx, bson.M{"run_id": runID}).Decode(&r)
+	if err == mongo.ErrNoDocuments {
+		return nil, fmt.Errorf("run not found")
+	}
+	return &r, err
+}
+
+func ListRuns(workflowID string, limit int64) ([]models.WorkflowRun, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	cur, err := db.Col("workflow_runs").Find(ctx, bson.M{"workflow_id": workflowID},
+		options.Find().SetSort(bson.D{{Key: "started_at", Value: -1}}).SetLimit(limit))
+	if err != nil {
+		return nil, err
+	}
+	defer cur.Close(ctx)
+	runs := []models.WorkflowRun{}
+	if err := cur.All(ctx, &runs); err != nil {
+		return nil, err
+	}
+	return runs, nil
+}
+
+func CancelRun(runID string) error {
+	now := time.Now()
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, err := db.Col("workflow_runs").UpdateOne(ctx,
+		bson.M{"run_id": runID, "status": "running"},
+		bson.M{"$set": bson.M{"status": "cancelled", "finished_at": now}})
+	return err
+}

server/internal/services/workflows.go

@@ -0,0 +1,243 @@
+package services
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/server/internal/db"
+	"github.com/mrhid6/vantage/server/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func wfCtx() (context.Context, context.CancelFunc) {
+	return context.WithTimeout(context.Background(), 10*time.Second)
+}
+
+func EnsureWorkflowIndexes() error {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	if _, err := db.Col("workflow_steps").Indexes().CreateOne(ctx, mongo.IndexModel{
+		Keys: bson.D{{Key: "step_id", Value: 1}}, Options: options.Index().SetUnique(true),
+	}); err != nil {
+		return err
+	}
+	if _, err := db.Col("workflow_steps").Indexes().CreateOne(ctx, mongo.IndexModel{
+		Keys: bson.D{{Key: "slug", Value: 1}},
+		Options: options.Index().SetUnique(true).
+			SetPartialFilterExpression(bson.M{"source": "default"}),
+	}); err != nil {
+		return err
+	}
+	if _, err := db.Col("workflows").Indexes().CreateOne(ctx, mongo.IndexModel{
+		Keys: bson.D{{Key: "workflow_id", Value: 1}}, Options: options.Index().SetUnique(true),
+	}); err != nil {
+		return err
+	}
+	_, err := db.Col("workflow_runs").Indexes().CreateOne(ctx, mongo.IndexModel{
+		Keys: bson.D{{Key: "run_id", Value: 1}}, Options: options.Index().SetUnique(true),
+	})
+	return err
+}
+
+// ---- Steps ----
+
+func ListSteps() ([]models.WorkflowStep, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	cur, err := db.Col("workflow_steps").Find(ctx, bson.M{},
+		options.Find().SetSort(bson.D{{Key: "name", Value: 1}}))
+	if err != nil {
+		return nil, err
+	}
+	defer cur.Close(ctx)
+	steps := []models.WorkflowStep{}
+	if err := cur.All(ctx, &steps); err != nil {
+		return nil, err
+	}
+	return steps, nil
+}
+
+func CreateStep(s models.WorkflowStep) (*models.WorkflowStep, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	s.StepID = uuid.New().String()
+	s.CreatedAt = time.Now()
+	s.UpdatedAt = s.CreatedAt
+	s.DeclaredOutputs = DeriveOutputs(s.Script)
+	if s.Source == "" {
+		s.Source = "user"
+	}
+	if s.SecretRefs == nil {
+		s.SecretRefs = []string{}
+	}
+	if s.DeclaredInputs == nil {
+		s.DeclaredInputs = []models.InputParam{}
+	}
+	if _, err := db.Col("workflow_steps").InsertOne(ctx, s); err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+func UpdateStep(stepID string, s models.WorkflowStep) error {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, err := db.Col("workflow_steps").UpdateOne(ctx, bson.M{"step_id": stepID}, bson.M{"$set": bson.M{
+		"name":             s.Name,
+		"description":      s.Description,
+		"interpreter":      s.Interpreter,
+		"script":           s.Script,
+		"declared_outputs": DeriveOutputs(s.Script),
+		"declared_inputs":  s.DeclaredInputs,
+		"secret_refs":      s.SecretRefs,
+		"updated_at":       time.Now(),
+	}})
+	return err
+}
+
+func DeleteStep(stepID string) error {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	if _, err := db.Col("workflow_steps").DeleteOne(ctx, bson.M{"step_id": stepID}); err != nil {
+		return err
+	}
+	// Cascade: remove this step from every workflow that references it, re-sequencing orders.
+	cur, err := db.Col("workflows").Find(ctx, bson.M{"steps.step_id": stepID})
+	if err != nil {
+		return err
+	}
+	defer cur.Close(ctx)
+	var wfs []models.Workflow
+	if err := cur.All(ctx, &wfs); err != nil {
+		return err
+	}
+	for _, w := range wfs {
+		kept := make([]models.WorkflowStepRef, 0, len(w.Steps))
+		for _, ref := range w.Steps {
+			if ref.StepID == stepID {
+				continue
+			}
+			kept = append(kept, ref)
+		}
+		for i := range kept {
+			kept[i].Order = i
+		}
+		if _, err := db.Col("workflows").UpdateOne(ctx,
+			bson.M{"workflow_id": w.WorkflowID},
+			bson.M{"$set": bson.M{"steps": kept, "updated_at": time.Now()}},
+		); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func getStep(ctx context.Context, stepID string) (*models.WorkflowStep, error) {
+	var s models.WorkflowStep
+	err := db.Col("workflow_steps").FindOne(ctx, bson.M{"step_id": stepID}).Decode(&s)
+	if err == mongo.ErrNoDocuments {
+		return nil, fmt.Errorf("step %s not found", stepID)
+	}
+	return &s, err
+}
+
+// ---- Workflows ----
+
+func ListWorkflows() ([]models.Workflow, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	cur, err := db.Col("workflows").Find(ctx, bson.M{},
+		options.Find().SetSort(bson.D{{Key: "name", Value: 1}}))
+	if err != nil {
+		return nil, err
+	}
+	defer cur.Close(ctx)
+	wfs := []models.Workflow{}
+	if err := cur.All(ctx, &wfs); err != nil {
+		return nil, err
+	}
+	return wfs, nil
+}
+
+func GetWorkflow(id string) (*models.Workflow, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	var w models.Workflow
+	err := db.Col("workflows").FindOne(ctx, bson.M{"workflow_id": id}).Decode(&w)
+	if err == mongo.ErrNoDocuments {
+		return nil, fmt.Errorf("workflow not found")
+	}
+	return &w, err
+}
+
+func CreateWorkflow(w models.Workflow) (*models.Workflow, error) {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	w.WorkflowID = uuid.New().String()
+	w.CreatedAt = time.Now()
+	w.UpdatedAt = w.CreatedAt
+	if w.TargetServerIDs == nil {
+		w.TargetServerIDs = []string{}
+	}
+	if w.Steps == nil {
+		w.Steps = []models.WorkflowStepRef{}
+	}
+	if err := ValidateWorkflow(w); err != nil {
+		return nil, err
+	}
+	normalizeInlineSteps(&w)
+	if _, err := db.Col("workflows").InsertOne(ctx, w); err != nil {
+		return nil, err
+	}
+	return &w, nil
+}
+
+func UpdateWorkflow(id string, w models.Workflow) error {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	if err := ValidateWorkflow(w); err != nil {
+		return err
+	}
+	normalizeInlineSteps(&w)
+	_, err := db.Col("workflows").UpdateOne(ctx, bson.M{"workflow_id": id}, bson.M{"$set": bson.M{
+		"name":              w.Name,
+		"target_server_ids": w.TargetServerIDs,
+		"steps":             w.Steps,
+		"updated_at":        time.Now(),
+	}})
+	return err
+}
+
+// normalizeInlineSteps derives outputs for inline steps and strips fields that
+// only belong to library steps.
+func normalizeInlineSteps(w *models.Workflow) {
+	for i := range w.Steps {
+		in := w.Steps[i].Inline
+		if in == nil {
+			continue
+		}
+		in.DeclaredOutputs = DeriveOutputs(in.Script)
+		in.StepID = ""
+		in.Slug = ""
+		in.Source = ""
+		in.CreatedAt = time.Time{}
+		in.UpdatedAt = time.Time{}
+		if in.SecretRefs == nil {
+			in.SecretRefs = []string{}
+		}
+		if in.DeclaredInputs == nil {
+			in.DeclaredInputs = []models.InputParam{}
+		}
+	}
+}
+
+func DeleteWorkflow(id string) error {
+	ctx, cancel := wfCtx()
+	defer cancel()
+	_, err := db.Col("workflows").DeleteOne(ctx, bson.M{"workflow_id": id})
+	return err
+}

web/app/globals.css

@@ -36,3 +36,22 @@ body {
 ::-webkit-scrollbar-thumb:hover {
   background: #3e4160;
 }
+
+@keyframes led-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+.led-pulse { animation: led-pulse 1.4s ease-in-out infinite; }
+
+@keyframes cell-ring {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.5); }
+  50% { box-shadow: 0 0 0 4px rgba(99, 102, 241, 0); }
+}
+.cell-ring { animation: cell-ring 1.4s ease-in-out infinite; }
+
+@keyframes caret-blink { 50% { opacity: 0; } }
+.caret-blink { animation: caret-blink 1s step-end infinite; }
+
+@media (prefers-reduced-motion: reduce) {
+  .led-pulse, .cell-ring, .caret-blink { animation: none; }
+}

web/app/servers/[id]/console/page.tsx

@@ -15,7 +15,11 @@ export default function ServerConsolePage() {
     const serverId = params.id as string;
 
     const containerRef = useRef<HTMLDivElement>(null);
-    const connectionRef = useRef<{ disconnect: () => void } | null>(null);
+    const connectionRef = useRef<{
+        disconnect: () => void;
+        setScale: (scale: number) => void;
+        resize: (width: number, height: number) => void;
+    } | null>(null);
 
     const [protocol, setProtocol] = useState<string>(searchParams.get("protocol") || "");
     const [keyId, setKeyId] = useState<string>("");
@@ -26,6 +30,9 @@ export default function ServerConsolePage() {
     const [connecting, setConnecting] = useState(false);
     const [connected, setConnected] = useState(false);
     const [error, setError] = useState<string | null>(null);
+    const [pending, setPending] = useState<{ token: string; wsPath: string } | null>(null);
+    const [zoom, setZoom] = useState(1);
+    const dprRef = useRef(1);
 
     // Inject the vendored Guacamole client script once.
     useEffect(() => {
@@ -83,15 +90,10 @@ export default function ServerConsolePage() {
             }
 
             const { token, ws_path } = await api.connectConsole(body);
-
-            const wsProto = location.protocol === "https:" ? "wss" : "ws";
-            const wsUrl = `${wsProto}://${location.host}${ws_path}?token=${encodeURIComponent(token)}`;
-
-            if (containerRef.current) {
-                const conn = openConsole(containerRef.current, wsUrl);
-                connectionRef.current = conn;
-                setConnected(true);
-            }
+            // Defer the actual openConsole until after the form is unmounted so the
+            // container measures at full height (see effect below).
+            setPending({ token, wsPath: ws_path });
+            setConnected(true);
         } catch (e) {
             setError(e instanceof Error ? e.message : "Failed to connect");
         } finally {
@@ -99,6 +101,44 @@ export default function ServerConsolePage() {
         }
     }
 
+    // Runs after `connected` flips and the connection form is gone, so the
+    // container now occupies its full flex height.
+    useEffect(() => {
+        if (!connected || !pending || !containerRef.current) return;
+
+        const wsProto = location.protocol === "https:" ? "wss" : "ws";
+        const wsUrl = `${wsProto}://${location.host}${pending.wsPath}`;
+        const rect = containerRef.current.getBoundingClientRect();
+        const dpr = window.devicePixelRatio || 1;
+        dprRef.current = dpr;
+        // Request the remote at device-pixel resolution with a fixed 96 dpi, then
+        // scale the display back down by dpr. Folding dpr into `dpi` instead makes
+        // the remote enlarge everything, which reads as a zoomed-in view.
+        const connectData =
+            `token=${encodeURIComponent(pending.token)}` +
+            `&width=${Math.floor(rect.width * dpr)}` +
+            `&height=${Math.floor(rect.height * dpr)}` +
+            `&dpi=96`;
+
+        connectionRef.current = openConsole(containerRef.current, wsUrl, connectData);
+        connectionRef.current.setScale(zoom / dpr);
+        setPending(null);
+    }, [connected, pending]);
+
+    // Apply zoom live without reconnecting: resize the remote to a resolution
+    // that, once scaled to fit the container, yields the requested zoom. Higher
+    // zoom = fewer remote pixels rendered larger. Display always fits the
+    // container exactly, so no scrollbars appear.
+    useEffect(() => {
+        if (!connectionRef.current || !containerRef.current) return;
+        const rect = containerRef.current.getBoundingClientRect();
+        const dpr = dprRef.current;
+        const remoteW = Math.floor((rect.width * dpr) / zoom);
+        const remoteH = Math.floor((rect.height * dpr) / zoom);
+        connectionRef.current.resize(remoteW, remoteH);
+        connectionRef.current.setScale(zoom / dpr);
+    }, [zoom]);
+
     function handleDisconnect() {
         connectionRef.current?.disconnect();
         connectionRef.current = null;
@@ -231,12 +271,25 @@ export default function ServerConsolePage() {
                     <Button variant="danger" onClick={handleDisconnect}>
                         Disconnect
                     </Button>
+                    <label className="text-sm text-text-secondary">Scale</label>
+                    <select
+                        value={zoom}
+                        onChange={(e) => setZoom(Number(e.target.value))}
+                        className="rounded-lg border border-border bg-surface-2 px-3 py-2 text-sm text-text-primary focus:border-accent/50 focus:outline-none focus:ring-1 focus:ring-accent/30"
+                    >
+                        <option value={0.5}>50%</option>
+                        <option value={0.75}>75%</option>
+                        <option value={1}>100%</option>
+                        <option value={1.25}>125%</option>
+                        <option value={1.5}>150%</option>
+                        <option value={2}>200%</option>
+                    </select>
                 </div>
             )}
 
             <div
                 ref={containerRef}
-                className="min-h-[500px] flex-1 rounded-lg border border-border bg-black"
+                className="min-h-[500px] flex-1 overflow-hidden rounded-lg border border-border bg-black"
             />
         </div>
     );

web/app/servers/[id]/page.tsx

@@ -416,10 +416,10 @@ export default function ServerDetailPage() {
                             {updateSuccess ? "Update Sent!" : "Update Agent"}
                         </Button>
                         <div className="relative flex-1 min-w-64 rounded-lg border border-border bg-[#0a0c14] px-4 py-2.5 font-mono text-sm">
-                            <span className="text-accent">$</span> <span className="text-text-primary">{api.getUpdateCommand()}</span>
+                            <span className="text-accent">{server.os_info?.toLowerCase().includes("windows") ? "PS>" : "$"}</span> <span className="text-text-primary">{api.getUpdateCommand(server.os_info)}</span>
                             <button
                                 onClick={async () => {
-                                    await navigator.clipboard.writeText(api.getUpdateCommand());
+                                    await navigator.clipboard.writeText(api.getUpdateCommand(server.os_info));
                                     setCopiedUpdate(true);
                                     setTimeout(() => setCopiedUpdate(false), 2000);
                                 }}

web/app/servers/new/page.tsx

@@ -8,15 +8,18 @@ import { Button, Card, CardHeader, CardTitle } from "@/components/ui";
 export default function NewServerPage() {
   const [result, setResult] = useState<NewServerResponse | null>(null);
   const [copied, setCopied] = useState(false);
+  const [os, setOs] = useState<"linux" | "windows">("linux");
 
   const { mutate: createServer, isPending, error } = useMutation({
     mutationFn: api.createServer,
     onSuccess: (data) => setResult(data),
   });
 
+  const command = os === "windows" ? result?.install_command_ps : result?.install_command;
+
   const handleCopy = async () => {
-    if (!result?.install_command) return;
-    await navigator.clipboard.writeText(result.install_command);
+    if (!command) return;
+    await navigator.clipboard.writeText(command);
     setCopied(true);
     setTimeout(() => setCopied(false), 2000);
   };
@@ -65,14 +68,34 @@ export default function NewServerPage() {
                   Valid for 1 hour
                 </span>
               </CardHeader>
+              <div className="mb-4 flex gap-2">
+                {(["linux", "windows"] as const).map((o) => (
+                  <button
+                    key={o}
+                    onClick={() => { setOs(o); setCopied(false); }}
+                    className={`rounded-lg border px-3 py-1.5 text-sm font-medium transition-colors ${
+                      os === o
+                        ? "border-accent bg-accent/10 text-accent"
+                        : "border-border bg-surface-2 text-text-secondary hover:border-accent/40 hover:text-text-primary"
+                    }`}
+                  >
+                    {o === "linux" ? "Linux (bash)" : "Windows (PowerShell)"}
+                  </button>
+                ))}
+              </div>
+
               <p className="mb-4 text-sm text-text-secondary">
-                Run this command on the target server as <code className="rounded bg-surface-2 px-1 py-0.5 text-xs font-mono text-text-primary">root</code>:
+                {os === "windows" ? (
+                  <>Run this in an <strong className="text-text-primary">elevated PowerShell</strong> (Run as Administrator):</>
+                ) : (
+                  <>Run this command on the target server as <code className="rounded bg-surface-2 px-1 py-0.5 text-xs font-mono text-text-primary">root</code>:</>
+                )}
               </p>
 
               <div className="relative rounded-lg border border-border bg-[#0a0c14] p-4 font-mono text-sm">
                 <pre className="overflow-x-auto whitespace-pre-wrap break-all text-text-secondary leading-relaxed">
-                  <span className="text-accent">$</span>{" "}
-                  <span className="text-text-primary">{result.install_command}</span>
+                  <span className="text-accent">{os === "windows" ? "PS>" : "$"}</span>{" "}
+                  <span className="text-text-primary">{command}</span>
                 </pre>
                 <button
                   onClick={handleCopy}

web/app/settings/page.tsx

@@ -168,6 +168,9 @@ export default function SettingsPage() {
   const [toAddrs, setToAddrs] = useState(""); // comma-separated in UI
   const [useTLS, setUseTLS] = useState(false);
 
+  // Workflow log retention (days). 0 = keep forever.
+  const [logRetentionDays, setLogRetentionDays] = useState(30);
+
   const [saved, setSaved] = useState(false);
 
   useEffect(() => {
@@ -183,11 +186,15 @@ export default function SettingsPage() {
     setFromAddr(settings.email?.from_addr ?? "");
     setToAddrs((settings.email?.to_addrs ?? []).join(", "));
     setUseTLS(settings.email?.use_tls ?? false);
+    setLogRetentionDays(settings.workflow_log_retention_days ?? 30);
   }, [settings]);
 
   const { mutate: save, isPending } = useMutation({
-    mutationFn: (payload: { alerts: AlertSettings; email: EmailSettings }) =>
-      api.saveSettings(payload),
+    mutationFn: (payload: {
+      alerts: AlertSettings;
+      email: EmailSettings;
+      workflow_log_retention_days?: number | null;
+    }) => api.saveSettings(payload),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ["settings"] });
       setSaved(true);
@@ -218,6 +225,7 @@ export default function SettingsPage() {
         to_addrs: toList,
         use_tls: useTLS,
       },
+      workflow_log_retention_days: logRetentionDays,
     });
   }
 
@@ -374,6 +382,29 @@ export default function SettingsPage() {
           </div>
         </Card>
 
+        {/* Workflow logs */}
+        <Card>
+          <CardHeader>
+            <CardTitle>Workflow Logs</CardTitle>
+          </CardHeader>
+          <p className="mb-5 text-sm text-text-secondary">
+            How long to keep workflow run logs on the server before they are
+            automatically deleted.
+          </p>
+          <Field
+            label="Log retention (days)"
+            hint="0 = keep forever. Applies to per-run step output logs."
+          >
+            <input
+              type="number"
+              min={0}
+              value={logRetentionDays}
+              onChange={(e) => setLogRetentionDays(Number(e.target.value))}
+              className="w-32 rounded-lg border border-border bg-surface-2 px-3 py-2 text-sm text-text-primary focus:border-accent/50 focus:outline-none focus:ring-1 focus:ring-accent/30"
+            />
+          </Field>
+        </Card>
+
         <div className="flex items-center gap-3">
           <Button type="submit" variant="primary" loading={isPending}>
             {saved ? "Saved!" : "Save Settings"}

web/app/workflows/[id]/page.tsx

@@ -0,0 +1,772 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import Link from "next/link";
+import { useParams, useRouter } from "next/navigation";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { api, Workflow, WorkflowStep, WorkflowStepRef, SecretGroupSummary } from "@/lib/api";
+import { Button } from "@/components/ui";
+import { EditStepModal } from "@/components/workflows/EditStepModal";
+import { EditWorkflowModal } from "@/components/workflows/EditWorkflowModal";
+
+const inputClass =
+    "w-full rounded-lg border border-border bg-surface-2 px-3 py-2 text-sm text-text-primary placeholder-text-secondary/50 focus:border-signal focus:outline-none focus:ring-1 focus:ring-signal";
+
+type DragPayload = { kind: "lib"; stepId: string } | { kind: "move"; from: number };
+
+function ShellBadge({ interpreter }: { interpreter: "bash" | "powershell" }) {
+    const isBash = interpreter === "bash";
+    return (
+        <span
+            className={`rounded px-1.5 py-0.5 font-mono text-[10px] uppercase ${
+                isBash ? "bg-bash/15 text-bash" : "bg-pwsh/15 text-pwsh"
+            }`}
+        >
+            {isBash ? "bash" : "pwsh"}
+        </span>
+    );
+}
+
+function DefaultBadge() {
+    return (
+        <span className="rounded px-1.5 py-0.5 font-mono text-[10px] uppercase bg-surface-2 text-text-secondary">
+            default
+        </span>
+    );
+}
+
+function AdhocBadge() {
+    return (
+        <span className="rounded px-1.5 py-0.5 font-mono text-[10px] uppercase bg-signal/15 text-signal">
+            ad-hoc
+        </span>
+    );
+}
+
+export default function WorkflowBuilder() {
+    const params = useParams<{ id: string }>();
+    const id = params.id;
+    const router = useRouter();
+    const queryClient = useQueryClient();
+
+    const [wf, setWf] = useState<Workflow | null>(null);
+    const [selected, setSelected] = useState<number | null>(null);
+    const [search, setSearch] = useState("");
+    const [saving, setSaving] = useState(false);
+    const [running, setRunning] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const [notice, setNotice] = useState<string | null>(null);
+    const [importing, setImporting] = useState(false);
+    const [importingInline, setImportingInline] = useState(false);
+    const [syncing, setSyncing] = useState(false);
+    const fileInputRef = useRef<HTMLInputElement>(null);
+    const inlineFileInputRef = useRef<HTMLInputElement>(null);
+    const [groupKeys, setGroupKeys] = useState<Record<string, string[]>>({});
+    const [editWorkflowOpen, setEditWorkflowOpen] = useState(false);
+    const [editingStep, setEditingStep] = useState<WorkflowStep | null>(null);
+    const [editStepOpen, setEditStepOpen] = useState(false);
+    const [dragOverZone, setDragOverZone] = useState<number | null>(null);
+
+    const { data: loaded } = useQuery({
+        queryKey: ["workflow", id],
+        queryFn: () => api.getWorkflow(id),
+    });
+    const { data: library } = useQuery({ queryKey: ["steps"], queryFn: api.listSteps });
+    const { data: secretGroups } = useQuery({
+        queryKey: ["secret-groups"],
+        queryFn: api.listSecretGroups,
+    });
+
+    useEffect(() => {
+        if (loaded && !wf) setWf(loaded);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [loaded]);
+
+    // Lazily fetch the keys for every secret group so the inspector's
+    // secret-ref checklist can offer "group/KEY" options.
+    useEffect(() => {
+        if (!secretGroups) return;
+        secretGroups.forEach((g: SecretGroupSummary) => {
+            if (groupKeys[g.group] !== undefined) return;
+            api.getSecretGroup(g.group)
+                .then((res) =>
+                    setGroupKeys((prev) => ({
+                        ...prev,
+                        [g.group]: res.secrets.map((s) => s.key),
+                    })),
+                )
+                .catch(() => {
+                    setGroupKeys((prev) => ({ ...prev, [g.group]: [] }));
+                });
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [secretGroups]);
+
+    if (!wf) {
+        return <div className="p-8 text-text-secondary">Loading…</div>;
+    }
+
+    const libById = (sid?: string) => (sid ? library?.find((l) => l.step_id === sid) : undefined);
+
+    const sortedSteps = [...wf.steps].sort((a, b) => a.order - b.order);
+    const selectedRef = selected !== null ? sortedSteps[selected] : null;
+    const selectedLib = selectedRef ? libById(selectedRef.step_id) : null;
+    const selectedIdxInWf = selectedRef ? wf.steps.indexOf(selectedRef) : -1;
+
+    const save = async () => {
+        setSaving(true);
+        setError(null);
+        try {
+            const updated = await api.updateWorkflow(id, wf);
+            if (!updated || !Array.isArray(updated.steps)) {
+                setError("Save failed: server returned an unexpected response.");
+                return;
+            }
+            setWf(updated);
+        } catch (e) {
+            setError((e as Error).message);
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    const run = async () => {
+        setRunning(true);
+        setError(null);
+        try {
+            const { run_id } = await api.runWorkflow(id);
+            router.push(`/workflows/${id}/runs/${run_id}`);
+        } catch (e) {
+            setError((e as Error).message);
+            setRunning(false);
+        }
+    };
+
+    const resequence = (steps: WorkflowStepRef[]) => steps.map((r, i) => ({ ...r, order: i }));
+
+    const insertLibStep = (stepId: string, pos: number) => {
+        const next = [...sortedSteps];
+        next.splice(pos, 0, { step_id: stepId, order: 0, on_failure: "stop", max_retries: 0 });
+        setWf({ ...wf, steps: resequence(next) });
+    };
+
+    const appendRef = (ref: WorkflowStepRef) => {
+        setWf({ ...wf, steps: resequence([...sortedSteps, ref]) });
+    };
+
+    const addAdhocStep = () => {
+        appendRef({
+            inline: {
+                step_id: "",
+                name: "New ad-hoc step",
+                description: "",
+                interpreter: "bash",
+                script: "",
+                declared_outputs: [],
+                declared_inputs: [],
+                secret_refs: [],
+            },
+            order: wf.steps.length,
+            on_failure: "stop",
+            max_retries: 0,
+        });
+    };
+
+    const onImportInline = async (e: React.ChangeEvent<HTMLInputElement>) => {
+        const file = e.target.files?.[0];
+        if (!file) return;
+        setImportingInline(true);
+        setError(null);
+        try {
+            const doc = JSON.parse(await file.text());
+            const step = await api.parseStep(doc);
+            appendRef({ inline: step, order: wf.steps.length, on_failure: "stop", max_retries: 0 });
+        } catch (err) {
+            setError((err as Error).message);
+        } finally {
+            setImportingInline(false);
+            e.target.value = "";
+        }
+    };
+
+    const moveStep = (from: number, pos: number) => {
+        const next = [...sortedSteps];
+        const [item] = next.splice(from, 1);
+        const target = from < pos ? pos - 1 : pos;
+        next.splice(target, 0, item);
+        setWf({ ...wf, steps: resequence(next) });
+        if (selected === from) setSelected(target);
+        else if (selected !== null) {
+            if (from < selected && target >= selected) setSelected(selected - 1);
+            else if (from > selected && target <= selected) setSelected(selected + 1);
+        }
+    };
+
+    const handleDrop = (e: React.DragEvent, pos: number) => {
+        e.preventDefault();
+        setDragOverZone(null);
+        const raw = e.dataTransfer.getData("text/plain");
+        if (!raw) return;
+        let payload: DragPayload;
+        try {
+            payload = JSON.parse(raw);
+        } catch {
+            return;
+        }
+        if (payload.kind === "lib") {
+            insertLibStep(payload.stepId, pos);
+        } else if (payload.kind === "move") {
+            moveStep(payload.from, pos);
+        }
+    };
+
+    const updateRef = (idx: number, patch: Partial<WorkflowStepRef>) =>
+        setWf({
+            ...wf,
+            steps: wf.steps.map((r, i) => (i === idx ? { ...r, ...patch } : r)),
+        });
+
+    const updateInline = (idx: number, patch: Partial<WorkflowStep>) =>
+        setWf({
+            ...wf,
+            steps: wf.steps.map((r, i) => (i === idx && r.inline ? { ...r, inline: { ...r.inline, ...patch } } : r)),
+        });
+
+    const removeStep = (idx: number) => {
+        const remaining = resequence(wf.steps.filter((_, i) => i !== idx));
+        setWf({ ...wf, steps: remaining });
+        setSelected(null);
+    };
+
+    const toggleSecretRef = (ref: string) => {
+        if (selectedIdxInWf === -1 || !selectedRef) return;
+        if (selectedRef.inline) {
+            const current = selectedRef.inline.secret_refs ?? [];
+            const next = current.includes(ref) ? current.filter((r) => r !== ref) : [...current, ref];
+            updateInline(selectedIdxInWf, { secret_refs: next });
+            return;
+        }
+        const current = selectedRef.overrides?.secret_refs ?? [];
+        const next = current.includes(ref) ? current.filter((r) => r !== ref) : [...current, ref];
+        updateRef(selectedIdxInWf, { overrides: { ...selectedRef.overrides, secret_refs: next } });
+    };
+
+    const onImportFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
+        const file = e.target.files?.[0];
+        if (!file) return;
+        setImporting(true);
+        setError(null);
+        try {
+            const doc = JSON.parse(await file.text());
+            await api.importStep(doc);
+            await queryClient.invalidateQueries({ queryKey: ["steps"] });
+            setNotice("Step imported.");
+        } catch (err) {
+            setError((err as Error).message);
+        } finally {
+            setImporting(false);
+            e.target.value = "";
+        }
+    };
+
+    const onSyncDefaults = async () => {
+        setSyncing(true);
+        setError(null);
+        try {
+            const { created, updated } = await api.seedDefaults();
+            await queryClient.invalidateQueries({ queryKey: ["steps"] });
+            setNotice(`${created} created, ${updated} updated`);
+        } catch (err) {
+            setError((err as Error).message);
+        } finally {
+            setSyncing(false);
+        }
+    };
+
+    const filteredLibrary = (library ?? []).filter((s) => s.name.toLowerCase().includes(search.toLowerCase()));
+    const bashSteps = filteredLibrary.filter((s) => s.interpreter === "bash");
+    const pwshSteps = filteredLibrary.filter((s) => s.interpreter === "powershell");
+
+    const upstreamOutputsFor = (i: number) =>
+        Array.from(
+            new Set(
+                sortedSteps
+                    .slice(0, i)
+                    .flatMap((r) => r.inline?.declared_outputs ?? libById(r.step_id)?.declared_outputs ?? []),
+            ),
+        );
+
+    const DropZone = ({ pos }: { pos: number }) => (
+        <div
+            className={`h-3 w-full transition-all ${dragOverZone === pos ? "h-8 rounded bg-signal/15 border border-dashed border-signal/50" : ""}`}
+            onDragOver={(e) => {
+                e.preventDefault();
+                setDragOverZone(pos);
+            }}
+            onDragLeave={() => setDragOverZone((z) => (z === pos ? null : z))}
+            onDrop={(e) => handleDrop(e, pos)}
+        />
+    );
+
+    return (
+        <>
+            <div className="flex items-center gap-3 border-b border-border bg-surface px-4 py-3">
+                <span className="h-2.5 w-2.5 rounded-full bg-signal" />
+                <div className="flex items-center gap-1.5 text-sm">
+                    <span className="text-text-secondary">Workflows /</span>
+                    <span className="font-medium text-text-primary">{wf.name}</span>
+                    <span className="text-text-secondary">· draft</span>
+                </div>
+                <div className="ml-auto flex items-center gap-2">
+                    <span className="rounded-full border border-border bg-surface-2 px-3 py-1 text-xs text-text-secondary">
+                        {wf.target_server_ids.length} servers
+                    </span>
+                    <Link
+                        href={`/workflows/${id}/runs`}
+                        className="rounded-lg border border-border bg-surface-2 px-3 py-1.5 text-sm text-text-secondary hover:text-text-primary"
+                    >
+                        Runs
+                    </Link>
+                    <Button variant="secondary" size="sm" onClick={() => setEditWorkflowOpen(true)}>
+                        Edit
+                    </Button>
+                    <Button variant="secondary" size="sm" loading={saving} onClick={save}>
+                        Save
+                    </Button>
+                    <Button
+                        size="sm"
+                        loading={running}
+                        onClick={run}
+                        className="bg-signal text-signal-ink border-transparent hover:bg-signal/90"
+                    >
+                        Run workflow
+                    </Button>
+                </div>
+            </div>
+
+            {error && (
+                <div className="border-b border-danger/30 bg-danger/10 px-4 py-2 text-sm text-danger">{error}</div>
+            )}
+            {notice && (
+                <div className="border-b border-signal/30 bg-signal/10 px-4 py-2 text-sm text-signal">{notice}</div>
+            )}
+
+            <div className="grid h-[calc(100vh-53px)] grid-cols-[264px_1fr_320px]">
+                {/* LEFT: library */}
+                <aside className="overflow-auto border-r border-border bg-surface p-3">
+                    <div className="mb-2 flex items-center justify-between">
+                        <h2 className="text-xs font-bold uppercase tracking-wide text-text-secondary">Step Library</h2>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => {
+                                setEditingStep(null);
+                                setEditStepOpen(true);
+                            }}
+                        >
+                            +
+                        </Button>
+                    </div>
+                    <div className="mb-2 flex items-center gap-2">
+                        <input
+                            ref={fileInputRef}
+                            type="file"
+                            accept="application/json"
+                            className="hidden"
+                            onChange={onImportFile}
+                        />
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            loading={importing}
+                            onClick={() => fileInputRef.current?.click()}
+                        >
+                            Import
+                        </Button>
+                        <Button variant="ghost" size="sm" loading={syncing} onClick={onSyncDefaults}>
+                            Sync defaults
+                        </Button>
+                    </div>
+                    <div className="mb-3 flex items-center gap-2">
+                        <input
+                            ref={inlineFileInputRef}
+                            type="file"
+                            accept="application/json"
+                            className="hidden"
+                            onChange={onImportInline}
+                        />
+                        <Button variant="ghost" size="sm" onClick={addAdhocStep}>
+                            + Add ad-hoc step
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            loading={importingInline}
+                            onClick={() => inlineFileInputRef.current?.click()}
+                        >
+                            Import ad-hoc
+                        </Button>
+                    </div>
+                    <input
+                        className={`${inputClass} mb-3`}
+                        placeholder="Search steps…"
+                        value={search}
+                        onChange={(e) => setSearch(e.target.value)}
+                    />
+
+                    {bashSteps.length > 0 && (
+                        <>
+                            <h3 className="mb-1 mt-2 text-[11px] font-bold uppercase tracking-wide text-text-secondary">
+                                Shared · Bash
+                            </h3>
+                            {bashSteps.map((s) => (
+                                <LibraryCard key={s.step_id} step={s} onAdd={() => insertLibStep(s.step_id, sortedSteps.length)} onEdit={() => {
+                                    setEditingStep(s);
+                                    setEditStepOpen(true);
+                                }} />
+                            ))}
+                        </>
+                    )}
+
+                    {pwshSteps.length > 0 && (
+                        <>
+                            <h3 className="mb-1 mt-3 text-[11px] font-bold uppercase tracking-wide text-text-secondary">
+                                Shared · PowerShell
+                            </h3>
+                            {pwshSteps.map((s) => (
+                                <LibraryCard key={s.step_id} step={s} onAdd={() => insertLibStep(s.step_id, sortedSteps.length)} onEdit={() => {
+                                    setEditingStep(s);
+                                    setEditStepOpen(true);
+                                }} />
+                            ))}
+                        </>
+                    )}
+
+                    {filteredLibrary.length === 0 && <p className="mt-2 text-xs text-text-secondary">No steps found.</p>}
+                </aside>
+
+                {/* CENTER: canvas */}
+                <main
+                    className="overflow-auto bg-background bg-[radial-gradient(circle_at_1px_1px,theme(colors.border)_1px,transparent_0)] bg-[length:22px_22px] p-8"
+                >
+                    <div className="mx-auto flex w-[340px] flex-col items-center">
+                        <DropZone pos={0} />
+                        {sortedSteps.map((ref, i) => {
+                            const lib = libById(ref.step_id);
+                            const outs = upstreamOutputsFor(i);
+                            const script = ref.inline?.script ?? ref.overrides?.script ?? lib?.script ?? "";
+                            const wfIdx = wf.steps.indexOf(ref);
+                            const isSelected = selected === i;
+                            return (
+                                <div key={wfIdx} className="w-full">
+                                    {i > 0 && (
+                                        <div className="flex flex-col items-center py-1">
+                                            <div className="h-[13px] w-0.5 bg-border" />
+                                            {outs.length > 0 && (
+                                                <div className="flex w-fit max-w-[300px] flex-wrap items-center justify-center gap-1 rounded-full border border-dashed border-signal/55 bg-surface px-3 py-1">
+                                                    <span className="text-[10px] uppercase text-text-secondary">passes</span>
+                                                    {outs.map((o) => (
+                                                        <span
+                                                            key={o}
+                                                            className="rounded bg-signal px-2 py-0.5 font-mono text-[11px] text-signal-ink"
+                                                        >
+                                                            {o}
+                                                        </span>
+                                                    ))}
+                                                </div>
+                                            )}
+                                            <div className="h-[13px] w-0.5 bg-border" />
+                                        </div>
+                                    )}
+                                    <div
+                                        draggable
+                                        onDragStart={(e) => {
+                                            e.dataTransfer.setData("text/plain", JSON.stringify({ kind: "move", from: i }));
+                                        }}
+                                        onClick={() => setSelected(i)}
+                                        className={`w-[340px] cursor-pointer rounded-[10px] border bg-surface p-3 ${
+                                            isSelected ? "border-signal ring-2 ring-signal/40" : "border-border"
+                                        }`}
+                                    >
+                                        <div className="mb-2 flex items-center gap-2">
+                                            <span className="grid h-5 w-5 place-items-center rounded border border-border font-mono text-[10px] text-text-secondary">
+                                                {i + 1}
+                                            </span>
+                                            <span className="text-sm font-medium text-text-primary">{ref.inline?.name ?? lib?.name ?? ref.step_id}</span>
+                                            {ref.inline && <ShellBadge interpreter={ref.inline.interpreter} />}
+                                            {lib && !ref.inline && <ShellBadge interpreter={lib.interpreter} />}
+                                            {ref.inline && <AdhocBadge />}
+                                        </div>
+                                        <pre className="max-h-16 overflow-hidden text-ellipsis whitespace-pre-wrap rounded border border-border bg-surface-2 p-2 font-mono text-xs text-text-secondary">
+                                            {script.slice(0, 200)}
+                                        </pre>
+                                    </div>
+                                    <DropZone pos={i + 1} />
+                                </div>
+                            );
+                        })}
+                        {sortedSteps.length === 0 && (
+                            <button
+                                onDragOver={(e) => e.preventDefault()}
+                                onDrop={(e) => handleDrop(e, 0)}
+                                className="mt-2 w-full rounded-[10px] border border-dashed border-border bg-surface py-6 text-sm text-text-secondary hover:border-signal/50 hover:text-text-primary"
+                            >
+                                + Drop a step here
+                            </button>
+                        )}
+                    </div>
+                </main>
+
+                {/* RIGHT: inspector */}
+                <aside className="overflow-auto border-l border-border bg-surface p-4">
+                    {selected === null || !selectedRef ? (
+                        <p className="text-sm text-text-secondary">Select a step to configure it.</p>
+                    ) : (
+                        <div className="space-y-4">
+                            <div>
+                                <div className="mb-1 text-[11px] font-bold uppercase tracking-wide text-text-secondary">
+                                    Step {selected + 1} · Inspector
+                                </div>
+                                <div className="flex items-center gap-2">
+                                    {selectedRef.inline && <ShellBadge interpreter={selectedRef.inline.interpreter} />}
+                                    {selectedLib && !selectedRef.inline && <ShellBadge interpreter={selectedLib.interpreter} />}
+                                    {selectedRef.inline && <AdhocBadge />}
+                                    <h2 className="text-sm font-bold text-text-primary">{selectedRef.inline?.name ?? selectedLib?.name ?? selectedRef.step_id}</h2>
+                                </div>
+                            </div>
+
+                            {selectedRef.inline ? (
+                                <div className="space-y-4 border-b border-border pb-4">
+                                    <div>
+                                        <label className="mb-1 block text-xs uppercase text-text-secondary">Name</label>
+                                        <input
+                                            className={inputClass}
+                                            value={selectedRef.inline.name}
+                                            onChange={(e) => updateInline(selectedIdxInWf, { name: e.target.value })}
+                                        />
+                                    </div>
+                                    <div>
+                                        <label className="mb-1 block text-xs uppercase text-text-secondary">Interpreter</label>
+                                        <select
+                                            className={inputClass}
+                                            value={selectedRef.inline.interpreter}
+                                            onChange={(e) =>
+                                                updateInline(selectedIdxInWf, {
+                                                    interpreter: e.target.value as WorkflowStep["interpreter"],
+                                                })
+                                            }
+                                        >
+                                            <option value="bash">bash</option>
+                                            <option value="powershell">powershell</option>
+                                        </select>
+                                    </div>
+                                    <div>
+                                        <label className="mb-1 block text-xs uppercase text-text-secondary">Command</label>
+                                        <textarea
+                                            className={`${inputClass} h-32 font-mono text-xs`}
+                                            value={selectedRef.inline.script}
+                                            onChange={(e) => updateInline(selectedIdxInWf, { script: e.target.value })}
+                                        />
+                                        <p className="mt-1 text-xs text-text-secondary">
+                                            Write <code className="text-signal">KEY=value</code> to <code className="text-signal">$WORKFLOW_ENV</code> to
+                                            expose it to later steps. Outputs are derived automatically on save.
+                                        </p>
+                                    </div>
+                                </div>
+                            ) : (
+                                <div className="border-b border-border pb-4">
+                                    <label className="mb-1 block text-xs uppercase text-text-secondary">Command</label>
+                                    <textarea
+                                        className={`${inputClass} h-32 font-mono text-xs`}
+                                        value={selectedRef.overrides?.script ?? selectedLib?.script ?? ""}
+                                        onChange={(e) =>
+                                            updateRef(selectedIdxInWf, {
+                                                overrides: { ...selectedRef.overrides, script: e.target.value },
+                                            })
+                                        }
+                                    />
+                                    <p className="mt-1 text-xs text-text-secondary">
+                                        Write <code className="text-signal">KEY=value</code> to <code className="text-signal">$WORKFLOW_ENV</code> to expose
+                                        it to later steps.
+                                    </p>
+                                </div>
+                            )}
+
+                            {(selectedRef.inline?.declared_inputs ?? selectedLib?.declared_inputs ?? []).length > 0 && (
+                                <div className="border-b border-border pb-4">
+                                    <label className="mb-2 block text-xs uppercase text-text-secondary">Inputs</label>
+                                    <div className="space-y-2">
+                                        {(selectedRef.inline?.declared_inputs ?? selectedLib?.declared_inputs ?? []).map((param) => (
+                                            <div key={param.name}>
+                                                <div className="mb-1 font-mono text-xs text-text-primary">{param.name}</div>
+                                                {param.description && (
+                                                    <div className="mb-1 text-[11px] text-text-secondary">{param.description}</div>
+                                                )}
+                                                <input
+                                                    className={inputClass}
+                                                    placeholder={param.default}
+                                                    value={selectedRef.inputs?.[param.name] ?? ""}
+                                                    onChange={(e) =>
+                                                        updateRef(selectedIdxInWf, {
+                                                            inputs: { ...selectedRef.inputs, [param.name]: e.target.value },
+                                                        })
+                                                    }
+                                                />
+                                            </div>
+                                        ))}
+                                    </div>
+                                </div>
+                            )}
+
+                            <div className="border-b border-border pb-4">
+                                <label className="mb-2 block text-xs uppercase text-text-secondary">Inputs · from upstream</label>
+                                <div className="flex flex-wrap gap-1">
+                                    {upstreamOutputsFor(selected).length === 0 && (
+                                        <p className="text-xs text-text-secondary">No upstream outputs.</p>
+                                    )}
+                                    {upstreamOutputsFor(selected).map((o) => (
+                                        <span key={o} className="flex items-center gap-1 rounded bg-surface-2 border border-border px-2 py-0.5 font-mono text-[11px] text-text-primary">
+                                            <span className="text-[9px] uppercase text-text-secondary">in</span>
+                                            {o}
+                                        </span>
+                                    ))}
+                                </div>
+                            </div>
+
+                            <div className="border-b border-border pb-4">
+                                <label className="mb-2 block text-xs uppercase text-text-secondary">Outputs · to $WORKFLOW_ENV</label>
+                                <div className="flex flex-wrap gap-1">
+                                    {(selectedRef.inline?.declared_outputs ?? selectedLib?.declared_outputs ?? []).length === 0 && (
+                                        <p className="text-xs text-text-secondary">No declared outputs.</p>
+                                    )}
+                                    {(selectedRef.inline?.declared_outputs ?? selectedLib?.declared_outputs ?? []).map((o) => (
+                                        <span key={o} className="flex items-center gap-1 rounded bg-signal px-2 py-0.5 font-mono text-[11px] text-signal-ink">
+                                            <span className="text-[9px] uppercase">out</span>
+                                            {o}
+                                        </span>
+                                    ))}
+                                </div>
+                            </div>
+
+                            <div className="border-b border-border pb-4">
+                                <label className="mb-2 block text-xs uppercase text-text-secondary">Secret refs</label>
+                                <div className="max-h-56 space-y-2 overflow-auto rounded-lg border border-border p-2">
+                                    {secretGroups?.map((g) => (
+                                        <div key={g.group}>
+                                            <div className="font-mono text-[11px] font-semibold text-text-secondary">{g.group}</div>
+                                            {(groupKeys[g.group] ?? []).map((key) => {
+                                                const ref = `${g.group}/${key}`;
+                                                const checked = (
+                                                    selectedRef.inline
+                                                        ? (selectedRef.inline.secret_refs ?? [])
+                                                        : (selectedRef.overrides?.secret_refs ?? [])
+                                                ).includes(ref);
+                                                return (
+                                                    <label key={ref} className="ml-2 flex cursor-pointer items-center gap-2 text-xs text-text-primary">
+                                                        <input
+                                                            type="checkbox"
+                                                            className="accent-signal"
+                                                            checked={checked}
+                                                            onChange={() => toggleSecretRef(ref)}
+                                                        />
+                                                        <span className="font-mono">{key}</span>
+                                                    </label>
+                                                );
+                                            })}
+                                            {(groupKeys[g.group] ?? []).length === 0 && <p className="ml-2 text-[11px] text-text-secondary">No keys.</p>}
+                                        </div>
+                                    ))}
+                                    {secretGroups && secretGroups.length === 0 && <p className="text-xs text-text-secondary">No secret groups yet.</p>}
+                                </div>
+                            </div>
+
+                            <div className="border-b border-border pb-4">
+                                <label className="mb-1 block text-xs uppercase text-text-secondary">On failure</label>
+                                <select
+                                    className={inputClass}
+                                    value={selectedRef.on_failure}
+                                    onChange={(e) =>
+                                        updateRef(selectedIdxInWf, {
+                                            on_failure: e.target.value as WorkflowStepRef["on_failure"],
+                                        })
+                                    }
+                                >
+                                    <option value="stop">Stop workflow</option>
+                                    <option value="continue">Continue</option>
+                                    <option value="retry">Retry</option>
+                                </select>
+                                {selectedRef.on_failure === "retry" && (
+                                    <div className="mt-2">
+                                        <label className="mb-1 block text-xs uppercase text-text-secondary">Max retries</label>
+                                        <input
+                                            type="number"
+                                            min={1}
+                                            className={inputClass}
+                                            value={selectedRef.max_retries}
+                                            onChange={(e) => updateRef(selectedIdxInWf, { max_retries: parseInt(e.target.value || "0", 10) })}
+                                        />
+                                    </div>
+                                )}
+                            </div>
+
+                            <Button variant="danger" size="sm" onClick={() => removeStep(selectedIdxInWf)}>
+                                Remove from workflow
+                            </Button>
+                        </div>
+                    )}
+                </aside>
+            </div>
+
+            <EditWorkflowModal open={editWorkflowOpen} workflow={wf} onSaved={(w) => setWf(w)} onClose={() => setEditWorkflowOpen(false)} />
+            <EditStepModal
+                key={editingStep?.step_id ?? "new"}
+                open={editStepOpen}
+                step={editingStep}
+                onClose={() => {
+                    setEditStepOpen(false);
+                    queryClient.invalidateQueries({ queryKey: ["steps"] });
+                }}
+            />
+        </>
+    );
+}
+
+function LibraryCard({ step, onAdd, onEdit }: { step: WorkflowStep; onAdd: () => void; onEdit: () => void }) {
+    return (
+        <div
+            draggable
+            onDragStart={(e) => {
+                e.dataTransfer.setData("text/plain", JSON.stringify({ kind: "lib", stepId: step.step_id }));
+            }}
+            onClick={onAdd}
+            className="group relative mb-2 cursor-grab rounded-lg border border-border bg-surface-2 p-2 text-left hover:border-signal/50"
+        >
+            <div className="mb-1 flex items-center gap-2">
+                <span className="text-text-secondary">⠿</span>
+                <ShellBadge interpreter={step.interpreter} />
+                {step.source === "default" && <DefaultBadge />}
+                <span className="text-sm font-medium text-text-primary">{step.name}</span>
+                <a
+                    href={api.exportStepUrl(step.step_id)}
+                    download
+                    onClick={(e) => e.stopPropagation()}
+                    className="ml-auto hidden text-text-secondary hover:text-text-primary group-hover:block"
+                    title="Export step"
+                >
+                    ⬇
+                </a>
+                <button
+                    onClick={(e) => {
+                        e.stopPropagation();
+                        onEdit();
+                    }}
+                    className="hidden text-text-secondary hover:text-text-primary group-hover:block"
+                    title="Edit step"
+                >
+                    ✎
+                </button>
+            </div>
+            {step.description && <p className="text-xs text-text-secondary">{step.description}</p>}
+        </div>
+    );
+}

web/app/workflows/[id]/runs/[runId]/page.tsx

@@ -0,0 +1,442 @@
+"use client";
+
+import { useParams } from "next/navigation";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { api, ServerRun, StepRun, WorkflowRun } from "@/lib/api";
+import { Button } from "@/components/ui";
+
+// ---- status vocabulary ----------------------------------------------------
+
+type CellKind = "done" | "fail" | "run" | "wait" | "skip" | "warn";
+
+function cellKind(status: string): CellKind {
+    switch (status) {
+        case "success":
+            return "done";
+        case "failed":
+            return "fail";
+        case "running":
+            return "run";
+        case "skipped":
+            return "skip";
+        case "cancelled":
+            return "warn";
+        default:
+            return "wait"; // queued / pending / missing
+    }
+}
+
+const cellGlyph: Record<CellKind, string> = {
+    done: "✓",
+    fail: "✕",
+    run: "●",
+    wait: "○",
+    skip: "–",
+    warn: "!",
+};
+
+const cellClass: Record<CellKind, string> = {
+    done: "bg-success/15 text-success",
+    fail: "bg-danger/15 text-danger",
+    run: "bg-accent/15 text-accent",
+    wait: "text-border",
+    skip: "text-text-secondary",
+    warn: "bg-warning/15 text-warning",
+};
+
+// ---- run-level status pill ------------------------------------------------
+
+type PillKind = "running" | "success" | "failed" | "neutral";
+
+function pillKind(status: string): PillKind {
+    if (status === "running") return "running";
+    if (status === "success") return "success";
+    if (status === "failed" || status === "cancelled") return "failed";
+    return "neutral";
+}
+
+const pillClass: Record<PillKind, string> = {
+    running: "text-accent border-accent/40 bg-accent/10",
+    success: "text-success border-success/35 bg-success/10",
+    failed: "text-danger border-danger/35 bg-danger/10",
+    neutral: "text-text-secondary border-border bg-surface-2",
+};
+
+const pillLed: Record<PillKind, string> = {
+    running: "bg-accent led-pulse",
+    success: "bg-success",
+    failed: "bg-danger",
+    neutral: "bg-text-secondary",
+};
+
+function StatusPill({ status, small }: { status: string; small?: boolean }) {
+    const kind = pillKind(status);
+    return (
+        <span
+            className={`inline-flex items-center gap-2 rounded-full border font-mono font-semibold uppercase tracking-wide ${
+                small ? "px-2 py-0.5 text-[10px]" : "px-2.5 py-1 text-xs"
+            } ${pillClass[kind]}`}
+        >
+            <span className={`h-1.5 w-1.5 rounded-full ${pillLed[kind]}`} />
+            {status}
+        </span>
+    );
+}
+
+// ---- time helpers ---------------------------------------------------------
+
+function fmtDuration(ms: number): string {
+    if (ms < 0) ms = 0;
+    const s = Math.floor(ms / 1000);
+    if (s < 60) return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    if (m < 60) return `${m}m ${rem}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+
+function stepDuration(st: StepRun, running: boolean, now: number): string {
+    if (!st.started_at) return st.status === "queued" ? "queued" : "";
+    const start = new Date(st.started_at).getTime();
+    const end = st.finished_at ? new Date(st.finished_at).getTime() : running ? now : start;
+    return fmtDuration(end - start);
+}
+
+// ---- live log terminal ----------------------------------------------------
+
+function LogTerminal({ runId, server }: { runId: string; server: ServerRun }) {
+    const [text, setText] = useState("");
+    const preRef = useRef<HTMLDivElement>(null);
+    const running = server.status === "running";
+    const serverId = server.server_id;
+
+    useEffect(() => {
+        setText("");
+        if (running) {
+            const es = new EventSource(api.serverRunLogStreamUrl(runId, serverId), {
+                withCredentials: true,
+            });
+            es.onmessage = (e) => setText((t) => t + e.data + "\n");
+            es.addEventListener("done", () => es.close());
+            es.onerror = () => es.close();
+            return () => es.close();
+        }
+        api.getServerRunLog(runId, serverId)
+            .then(setText)
+            .catch(() => setText(""));
+    }, [running, runId, serverId]);
+
+    useEffect(() => {
+        preRef.current?.scrollTo(0, preRef.current.scrollHeight);
+    }, [text]);
+
+    const activeStep = server.steps.find((s) => s.status === "running") ?? [...server.steps].reverse().find((s) => s.started_at);
+
+    return (
+        <div className="overflow-hidden rounded-xl border border-border bg-[#0a0b10]">
+            <div className="flex items-center justify-between gap-2 border-b border-border bg-surface px-4 py-3">
+                <span className="truncate font-mono text-[13px] font-semibold text-text-primary">
+                    {activeStep ? activeStep.name : "Output"} <span className="font-normal text-text-secondary">{server.hostname}</span>
+                </span>
+                {running && (
+                    <span className="inline-flex items-center gap-1.5 font-mono text-[10.5px] uppercase tracking-wide text-accent">
+                        <span className="h-1.5 w-1.5 rounded-full bg-accent led-pulse" />
+                        Streaming
+                    </span>
+                )}
+            </div>
+            <div ref={preRef} className="max-h-[340px] overflow-auto whitespace-pre-wrap px-4 py-3.5 font-mono text-[12.5px] leading-relaxed text-text-secondary">
+                {text ? <LogLines text={text} /> : running ? "Waiting for output…" : "No output."}
+                {running && text && <span className="ml-0.5 inline-block h-3.5 w-[7px] translate-y-[2px] bg-accent caret-blink align-baseline" />}
+            </div>
+        </div>
+    );
+}
+
+// LogLines renders the raw server-run log, parsing each line's leading UTC
+// timestamp ([2026-07-20T12:04:02.000Z]) and rendering it in the viewer's local
+// timezone. Event markers (===== …) are highlighted so the run's shape scans.
+const TS_RE = /^\[(\d{4}-\d{2}-\d{2}T[\d:.]+Z)\]\s?(.*)$/;
+
+function LogLines({ text }: { text: string }) {
+    const lines = text.replace(/\n$/, "").split("\n");
+    return (
+        <>
+            {lines.map((line, i) => {
+                const m = TS_RE.exec(line);
+                if (!m) {
+                    return (
+                        <span key={i} className="block">
+                            {line || " "}
+                        </span>
+                    );
+                }
+                const local = new Date(m[1]).toLocaleTimeString([], { hour12: false });
+                const body = m[2];
+                const isMarker = body.startsWith("=====");
+                return (
+                    <span key={i} className="block">
+                        <span className="select-none text-[#565b74]" title={m[1]}>
+                            {local}{" "}
+                        </span>
+                        <span className={isMarker ? "font-semibold text-accent" : ""}>{body || " "}</span>
+                    </span>
+                );
+            })}
+        </>
+    );
+}
+
+// ---- step list ------------------------------------------------------------
+
+function StepList({ server, now }: { server: ServerRun; now: number }) {
+    const running = server.status === "running";
+    return (
+        <div className="overflow-hidden rounded-xl border border-border bg-surface">
+            <div className="flex items-center justify-between gap-2 border-b border-border px-4 py-3">
+                <span className="font-mono text-[13px] font-semibold text-text-primary">
+                    Steps <span className="font-normal text-text-secondary">{server.steps.length}</span>
+                </span>
+                <StatusPill status={server.status} small />
+            </div>
+            <div className="flex flex-col gap-0.5 p-1.5">
+                {server.steps.map((st) => {
+                    const kind = cellKind(st.status);
+                    return (
+                        <div
+                            key={st.order}
+                            className={`grid grid-cols-[20px_1fr_auto] items-center gap-2.5 rounded-lg px-3 py-2.5 text-[13px] hover:bg-surface-2 ${st.status === "running" ? "bg-accent/[0.06]" : ""}`}
+                        >
+                            <span className="text-right font-mono text-[11px] text-text-secondary">{String(st.order + 1).padStart(2, "0")}</span>
+                            <span className="flex items-center gap-2 font-medium text-text-primary">
+                                <span className={`font-mono ${cellClass[kind].replace(/bg-\S+/, "")}`}>{cellGlyph[kind]}</span>
+                                {st.name}
+                            </span>
+                            <span className="text-right font-mono text-[10.5px] text-text-secondary">
+                                {st.status === "failed" && <span className="text-danger">exit {st.exit_code} · </span>}
+                                {st.attempts > 1 ? `${st.attempts} tries` : "1 try"}
+                                {stepDuration(st, running, now) ? ` · ${stepDuration(st, running, now)}` : ""}
+                            </span>
+                        </div>
+                    );
+                })}
+                {server.steps.length === 0 && <p className="px-3 py-2 text-xs text-text-secondary">No steps yet.</p>}
+            </div>
+        </div>
+    );
+}
+
+// ---- execution matrix (signature) -----------------------------------------
+
+interface Column {
+    order: number;
+    name: string;
+}
+
+function buildColumns(run: WorkflowRun): Column[] {
+    const byOrder = new Map<number, string>();
+    for (const sr of run.server_runs) {
+        for (const st of sr.steps) {
+            if (!byOrder.has(st.order)) byOrder.set(st.order, st.name);
+        }
+    }
+    return [...byOrder.entries()].map(([order, name]) => ({ order, name })).sort((a, b) => a.order - b.order);
+}
+
+function ExecutionMatrix({ run, columns, selected, onSelect }: { run: WorkflowRun; columns: Column[]; selected: string; onSelect: (serverId: string) => void }) {
+    return (
+        <div className="overflow-x-auto rounded-xl border border-border bg-surface">
+            <table className="w-full border-collapse font-mono text-[12.5px]">
+                <thead>
+                    <tr>
+                        <th className="border-b border-border px-4 py-3 text-left align-bottom text-xs font-semibold uppercase tracking-wider text-text-primary">Server</th>
+                        {columns.map((c) => (
+                            <th key={c.order} className="whitespace-nowrap border-b border-border px-3.5 py-3 align-bottom text-[11px] font-medium text-text-secondary">
+                                <span className="block text-[10px] text-border">{String(c.order + 1).padStart(2, "0")}</span>
+                                {c.name}
+                            </th>
+                        ))}
+                    </tr>
+                </thead>
+                <tbody>
+                    {run.server_runs.map((sr) => {
+                        const byOrder = new Map(sr.steps.map((s) => [s.order, s]));
+                        const isSel = sr.server_id === selected;
+                        return (
+                            <tr key={sr.server_id} onClick={() => onSelect(sr.server_id)} className={`cursor-pointer ${isSel ? "bg-accent/5" : "hover:bg-white/[0.02]"}`}>
+                                <th className="min-w-[240px] border-b border-r border-border px-4 py-3 text-left font-medium text-text-primary">
+                                    <div className="flex items-center gap-3">
+                                        <span className="flex-1 whitespace-nowrap">{sr.hostname}</span>
+                                        <StatusPill status={sr.status} small />
+                                    </div>
+                                </th>
+                                {columns.map((c) => {
+                                    const st = byOrder.get(c.order);
+                                    const kind = st ? cellKind(st.status) : "wait";
+                                    return (
+                                        <td key={c.order} className="relative border-b border-r border-border last:border-r-0">
+                                            <span className="flex h-[54px] items-center justify-center">
+                                                <span className={`relative flex h-[26px] w-[26px] items-center justify-center rounded-md ${cellClass[kind]}`}>
+                                                    {kind === "run" && <span className="absolute inset-0 rounded-md border border-accent/50 cell-ring" />}
+                                                    {cellGlyph[kind]}
+                                                </span>
+                                            </span>
+                                        </td>
+                                    );
+                                })}
+                            </tr>
+                        );
+                    })}
+                </tbody>
+            </table>
+        </div>
+    );
+}
+
+// ---- page -----------------------------------------------------------------
+
+function SectionLabel({ children }: { children: React.ReactNode }) {
+    return (
+        <div className="mb-3 mt-8 flex items-center gap-2.5 font-mono text-[11px] uppercase tracking-widest text-text-secondary">
+            {children}
+            <span className="h-px flex-1 bg-border" />
+        </div>
+    );
+}
+
+export default function RunDetail() {
+    const { runId } = useParams<{ runId: string }>();
+    const queryClient = useQueryClient();
+    const [selected, setSelected] = useState<string | null>(null);
+    const [now, setNow] = useState(() => Date.now());
+
+    const { data: run, isLoading } = useQuery({
+        queryKey: ["run", runId],
+        queryFn: () => api.getRun(runId),
+        refetchInterval: (query) => (query.state.data?.status === "running" ? 2000 : false),
+    });
+
+    const running = run?.status === "running";
+
+    // tick the elapsed clock while running
+    useEffect(() => {
+        if (!running) return;
+        const t = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(t);
+    }, [running]);
+
+    const columns = useMemo(() => (run ? buildColumns(run) : []), [run]);
+
+    // default selection: first running server, else first server
+    const selectedServer = useMemo(() => {
+        if (!run || run.server_runs.length === 0) return null;
+        if (selected) {
+            const match = run.server_runs.find((s) => s.server_id === selected);
+            if (match) return match;
+        }
+        return run.server_runs.find((s) => s.status === "running") ?? run.server_runs[0];
+    }, [run, selected]);
+
+    const cancel = async () => {
+        await api.cancelRun(runId);
+        queryClient.invalidateQueries({ queryKey: ["run", runId] });
+    };
+
+    if (isLoading || !run) {
+        return <div className="p-8 text-text-secondary">Loading…</div>;
+    }
+
+    const totalSteps = run.server_runs.reduce((n, s) => n + s.steps.length, 0);
+    const doneSteps = run.server_runs.reduce((n, s) => n + s.steps.filter((st) => st.status === "success").length, 0);
+    const succeeded = run.server_runs.filter((s) => s.status === "success").length;
+    const failed = run.server_runs.filter((s) => s.status === "failed" || s.status === "cancelled").length;
+
+    const startMs = run.started_at ? new Date(run.started_at).getTime() : now;
+    const endMs = run.finished_at ? new Date(run.finished_at).getTime() : now;
+    const elapsed = fmtDuration(endMs - startMs);
+    const ago = fmtDuration(now - startMs);
+
+    return (
+        <div className="mx-auto max-w-[1180px] p-8 pb-16">
+            {/* identity bar */}
+            <div className="flex flex-wrap items-start justify-between gap-6">
+                <div>
+                    <div className="mb-2 font-mono text-xs uppercase tracking-wide text-text-secondary">Workflows / {run.name} / Runs</div>
+                    <h1 className="text-[28px] font-semibold tracking-tight text-text-primary">{run.name}</h1>
+                    <div className="mt-2.5 flex flex-wrap items-center gap-x-4 gap-y-1 font-mono text-[12.5px] text-text-secondary">
+                        <span>
+                            run <b className="font-medium text-text-primary">{run.run_id.slice(0, 8)}</b>
+                        </span>
+                        <span className="h-[3px] w-[3px] rounded-full bg-border" />
+                        <span>
+                            triggered by <b className="font-medium text-text-primary">{run.triggered_by || "—"}</b>
+                        </span>
+                        <span className="h-[3px] w-[3px] rounded-full bg-border" />
+                        <span>
+                            started <b className="font-medium text-text-primary">{ago}</b> ago
+                        </span>
+                        <span className="h-[3px] w-[3px] rounded-full bg-border" />
+                        <span>
+                            elapsed <b className="font-medium text-text-primary">{elapsed}</b>
+                        </span>
+                    </div>
+                </div>
+                <div className="flex items-center gap-3.5">
+                    <StatusPill status={run.status} />
+                    {running && (
+                        <Button variant="danger" onClick={cancel}>
+                            Cancel run
+                        </Button>
+                    )}
+                </div>
+            </div>
+
+            {/* summary strip */}
+            <div className="mt-6 grid grid-cols-2 gap-px overflow-hidden rounded-xl border border-border bg-border sm:grid-cols-4">
+                <div className="bg-surface px-[18px] py-4">
+                    <div className="font-mono text-[10.5px] uppercase tracking-wider text-text-secondary">Servers</div>
+                    <div className="mt-1 font-mono text-[22px] font-semibold tabular-nums text-text-primary">{run.server_runs.length}</div>
+                </div>
+                <div className="bg-surface px-[18px] py-4">
+                    <div className="font-mono text-[10.5px] uppercase tracking-wider text-text-secondary">Succeeded</div>
+                    <div className="mt-1 font-mono text-[22px] font-semibold tabular-nums text-success">
+                        {succeeded}
+                        <small className="text-sm font-medium text-text-secondary"> / {run.server_runs.length}</small>
+                    </div>
+                </div>
+                <div className="bg-surface px-[18px] py-4">
+                    <div className="font-mono text-[10.5px] uppercase tracking-wider text-text-secondary">Failed</div>
+                    <div className={`mt-1 font-mono text-[22px] font-semibold tabular-nums ${failed > 0 ? "text-danger" : "text-text-primary"}`}>{failed}</div>
+                </div>
+                <div className="bg-surface px-[18px] py-4">
+                    <div className="font-mono text-[10.5px] uppercase tracking-wider text-text-secondary">Steps done</div>
+                    <div className="mt-1 font-mono text-[22px] font-semibold tabular-nums text-text-primary">
+                        {doneSteps}
+                        <small className="text-sm font-medium text-text-secondary"> / {totalSteps}</small>
+                    </div>
+                </div>
+            </div>
+
+            {run.server_runs.length === 0 ? (
+                <p className="mt-8 text-text-secondary">No servers targeted by this run.</p>
+            ) : (
+                <>
+                    <SectionLabel>Execution matrix</SectionLabel>
+                    <ExecutionMatrix run={run} columns={columns} selected={selectedServer?.server_id ?? ""} onSelect={setSelected} />
+
+                    {selectedServer && (
+                        <>
+                            <SectionLabel>{selectedServer.hostname}&nbsp;·&nbsp;steps &amp; live output</SectionLabel>
+                            <div className="grid grid-cols-1 items-start gap-4 md:grid-cols-[320px_1fr]">
+                                <StepList server={selectedServer} now={now} />
+                                <LogTerminal runId={run.run_id} server={selectedServer} />
+                            </div>
+                        </>
+                    )}
+                </>
+            )}
+        </div>
+    );
+}

web/app/workflows/[id]/runs/page.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import Link from "next/link";
+import { useParams } from "next/navigation";
+import { useQuery } from "@tanstack/react-query";
+import { api, WorkflowRun } from "@/lib/api";
+import { Card, Table, Thead, Tbody, Tr, Th, Td, Badge } from "@/components/ui";
+
+type BadgeVariant = "success" | "warning" | "danger" | "neutral" | "accent";
+
+const statusVariant: Record<string, BadgeVariant> = {
+  success: "success",
+  failed: "danger",
+  running: "warning",
+  cancelled: "neutral",
+  queued: "neutral",
+};
+
+export default function WorkflowRunsPage() {
+  const { id } = useParams<{ id: string }>();
+  const { data: wf } = useQuery({ queryKey: ["workflow", id], queryFn: () => api.getWorkflow(id) });
+  const { data: runs, isLoading, error } = useQuery({ queryKey: ["runs", id], queryFn: () => api.listRuns(id) });
+
+  return (
+    <div className="p-8">
+      <div className="mb-6">
+        <Link href={`/workflows/${id}`} className="text-sm text-text-secondary hover:text-text-primary">
+          ← Back to builder
+        </Link>
+        <h1 className="mt-2 text-2xl font-bold text-text-primary">Runs · {wf?.name ?? ""}</h1>
+      </div>
+
+      <Card padding={false}>
+        {isLoading ? (
+          <div className="flex items-center justify-center py-20">
+            <div className="h-8 w-8 animate-spin rounded-full border-2 border-border border-t-accent" />
+          </div>
+        ) : error ? (
+          <div className="py-20 text-center text-danger">Failed to load runs. Is the backend running?</div>
+        ) : runs && runs.length > 0 ? (
+          <Table>
+            <Thead>
+              <Tr>
+                <Th>Run</Th>
+                <Th>Status</Th>
+                <Th>Started</Th>
+                <Th>By</Th>
+                <Th>Servers</Th>
+              </Tr>
+            </Thead>
+            <Tbody>
+              {runs.map((r: WorkflowRun) => (
+                <Tr key={r.run_id}>
+                  <Td>
+                    <Link
+                      href={`/workflows/${id}/runs/${r.run_id}`}
+                      className="font-mono text-text-primary hover:text-signal"
+                    >
+                      {r.run_id.slice(0, 8)}
+                    </Link>
+                  </Td>
+                  <Td>
+                    <Badge variant={statusVariant[r.status] ?? "neutral"}>{r.status}</Badge>
+                  </Td>
+                  <Td className="text-text-secondary">{new Date(r.started_at).toLocaleString()}</Td>
+                  <Td className="text-text-secondary">{r.triggered_by}</Td>
+                  <Td className="text-text-secondary">{r.server_runs.length}</Td>
+                </Tr>
+              ))}
+            </Tbody>
+          </Table>
+        ) : (
+          <div className="py-16 text-center text-text-secondary">No runs yet.</div>
+        )}
+      </Card>
+    </div>
+  );
+}

web/app/workflows/page.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { api, Workflow } from "@/lib/api";
+import { Button, Card } from "@/components/ui";
+import { Table, Thead, Tbody, Tr, Th, Td } from "@/components/ui";
+
+export default function WorkflowsPage() {
+  const qc = useQueryClient();
+  const router = useRouter();
+  const [error, setError] = useState<string | null>(null);
+
+  const { data: workflows, isLoading, error: loadError } = useQuery({
+    queryKey: ["workflows"],
+    queryFn: api.listWorkflows,
+  });
+
+  const { mutate: create, isPending } = useMutation({
+    mutationFn: () => api.createWorkflow({ name: "Untitled workflow", target_server_ids: [], steps: [] }),
+    onSuccess: (workflow) => {
+      qc.invalidateQueries({ queryKey: ["workflows"] });
+      router.push(`/workflows/${workflow.workflow_id}`);
+    },
+    onError: (err) => setError((err as Error).message),
+  });
+
+  return (
+    <div className="p-8">
+      <div className="mb-6 flex items-center justify-between">
+        <div>
+          <h1 className="text-2xl font-bold text-text-primary">Workflows</h1>
+          <p className="mt-1 text-sm text-text-secondary">
+            {workflows?.length ?? 0} workflow{workflows?.length !== 1 ? "s" : ""} · run reusable steps across servers
+          </p>
+        </div>
+        <Button variant="primary" loading={isPending} onClick={() => create()}>
+          <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M12 4.5v15m7.5-7.5h-15" />
+          </svg>
+          New Workflow
+        </Button>
+      </div>
+
+      {error && (
+        <div className="mb-4 rounded-lg border border-danger/30 bg-danger/10 px-3 py-2 text-sm text-danger">
+          {error}
+        </div>
+      )}
+
+      <Card padding={false}>
+        {isLoading ? (
+          <div className="flex items-center justify-center py-20">
+            <div className="h-8 w-8 animate-spin rounded-full border-2 border-border border-t-accent" />
+          </div>
+        ) : loadError ? (
+          <div className="py-20 text-center text-danger">Failed to load workflows. Is the backend running?</div>
+        ) : workflows && workflows.length > 0 ? (
+          <Table>
+            <Thead>
+              <Tr>
+                <Th>Name</Th>
+                <Th>Targets</Th>
+                <Th>Steps</Th>
+                <Th />
+              </Tr>
+            </Thead>
+            <Tbody>
+              {workflows.map((w: Workflow) => (
+                <Tr key={w.workflow_id}>
+                  <Td>
+                    <span className="font-medium text-text-primary">{w.name}</span>
+                  </Td>
+                  <Td>
+                    <span className="text-text-secondary">
+                      {w.target_server_ids.length} server{w.target_server_ids.length !== 1 ? "s" : ""}
+                    </span>
+                  </Td>
+                  <Td>
+                    <span className="text-text-secondary">{w.steps.length}</span>
+                  </Td>
+                  <Td>
+                    <div className="flex items-center justify-end gap-2">
+                      <Link href={`/workflows/${w.workflow_id}/runs`}>
+                        <Button variant="ghost" size="sm">Runs</Button>
+                      </Link>
+                      <Link href={`/workflows/${w.workflow_id}`}>
+                        <Button variant="ghost" size="sm">Open →</Button>
+                      </Link>
+                    </div>
+                  </Td>
+                </Tr>
+              ))}
+            </Tbody>
+          </Table>
+        ) : (
+          <div className="py-20 text-center">
+            <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-surface-2">
+              <svg className="h-6 w-6 text-text-secondary" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+              </svg>
+            </div>
+            <p className="text-text-secondary">No workflows yet.</p>
+            <Button variant="primary" size="sm" className="mt-4" loading={isPending} onClick={() => create()}>
+              Create your first workflow
+            </Button>
+          </div>
+        )}
+      </Card>
+    </div>
+  );
+}

web/components/Sidebar.tsx

@@ -35,6 +35,14 @@ function SecretIcon() {
   );
 }
 
+function WorkflowIcon() {
+  return (
+    <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+      <path strokeLinecap="round" strokeLinejoin="round" d="M9 3.75H6.912a2.25 2.25 0 00-2.15 1.588L2.35 13.177a2.25 2.25 0 00-.1.661V18a2.25 2.25 0 002.25 2.25h15A2.25 2.25 0 0021.75 18v-4.162c0-.224-.034-.447-.1-.661L19.24 5.338a2.25 2.25 0 00-2.15-1.588H15M2.25 13.5h3.86a2.25 2.25 0 012.012 1.244l.256.512a2.25 2.25 0 002.012 1.244h3.22a2.25 2.25 0 002.012-1.244l.256-.512a2.25 2.25 0 012.012-1.244h3.86M12 3v8.25m0 0l-3-3m3 3l3-3" />
+    </svg>
+  );
+}
+
 function AuditIcon() {
   return (
     <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
@@ -56,6 +64,7 @@ const navItems: NavItem[] = [
   { href: "/servers", label: "Servers", icon: <ServerIcon /> },
   { href: "/keys", label: "SSH Keys", icon: <KeyIcon /> },
   { href: "/secrets", label: "Secrets", icon: <SecretIcon /> },
+  { href: "/workflows", label: "Workflows", icon: <WorkflowIcon /> },
   { href: "/audit", label: "Audit Log", icon: <AuditIcon /> },
   { href: "/settings", label: "Settings", icon: <SettingsIcon /> },
 ];

web/components/ui/Modal.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useEffect } from "react";
+
+export function Modal({
+  open,
+  title,
+  onClose,
+  children,
+  wide,
+}: {
+  open: boolean;
+  title: string;
+  onClose: () => void;
+  children: React.ReactNode;
+  wide?: boolean;
+}) {
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      <div className="absolute inset-0 bg-black/60" onClick={onClose} />
+      <div
+        className={`relative z-10 w-full ${wide ? "max-w-2xl" : "max-w-md"} max-h-[90vh] overflow-auto rounded-xl border border-border bg-surface shadow-2xl`}
+        role="dialog"
+        aria-modal="true"
+      >
+        <div className="flex items-center justify-between border-b border-border px-5 py-3">
+          <h2 className="text-sm font-bold text-text-primary">{title}</h2>
+          <button onClick={onClose} className="text-text-secondary hover:text-text-primary" aria-label="Close">
+            ✕
+          </button>
+        </div>
+        <div className="p-5">{children}</div>
+      </div>
+    </div>
+  );
+}

web/components/ui/index.ts

@@ -2,3 +2,4 @@ export { Button } from "./Button";
 export { Badge } from "./Badge";
 export { Card, CardHeader, CardTitle } from "./Card";
 export { Table, Thead, Tbody, Tr, Th, Td } from "./Table";
+export { Modal } from "./Modal";

web/components/workflows/EditStepModal.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import { useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { api, WorkflowStep, InputParam } from "@/lib/api";
+import { Button, Modal } from "@/components/ui";
+
+const inputClass =
+  "w-full rounded-lg border border-border bg-surface-2 px-3 py-2 text-sm text-text-primary placeholder-text-secondary/50 focus:border-signal focus:outline-none focus:ring-1 focus:ring-signal";
+
+export function EditStepModal({ open, step, onClose }: { open: boolean; step: WorkflowStep | null; onClose: () => void }) {
+  const qc = useQueryClient();
+  const [name, setName] = useState(step?.name ?? "");
+  const [interpreter, setInterpreter] = useState<"bash" | "powershell">(step?.interpreter ?? "bash");
+  const [script, setScript] = useState(step?.script ?? "");
+  const [inputs, setInputs] = useState<InputParam[]>(step?.declared_inputs ?? []);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // NOTE: because state is seeded from props, render the modal conditionally
+  // (parent mounts it only when opening) OR key it by step_id so it re-seeds.
+
+  const save = async () => {
+    setBusy(true); setError(null);
+    try {
+      const payload: Partial<WorkflowStep> = {
+        name: name.trim(), description: step?.description ?? "", interpreter, script,
+        declared_inputs: inputs.filter((i) => i.name.trim() !== ""),
+        secret_refs: step?.secret_refs ?? [],
+      };
+      if (step) await api.updateStep(step.step_id, payload);
+      else await api.createStep(payload);
+      qc.invalidateQueries({ queryKey: ["steps"] });
+      onClose();
+    } catch (e) { setError((e as Error).message); } finally { setBusy(false); }
+  };
+
+  const del = async () => {
+    if (!step || !window.confirm("Delete this step? It will be removed from every workflow that uses it.")) return;
+    setBusy(true); setError(null);
+    try {
+      await api.deleteStep(step.step_id);
+      qc.invalidateQueries({ queryKey: ["steps"] });
+      qc.invalidateQueries({ queryKey: ["workflow"] });
+      onClose();
+    } catch (e) { setError((e as Error).message); } finally { setBusy(false); }
+  };
+
+  return (
+    <Modal open={open} onClose={onClose} title={step ? "Edit base step" : "New step"} wide>
+      <div className="space-y-4">
+        {error && <div className="rounded border border-danger/30 bg-danger/10 px-3 py-2 text-sm text-danger">{error}</div>}
+        <p className="text-xs text-text-secondary">Reusable steps are shared across all workflows. Editing here changes it everywhere.</p>
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Name</label>
+          <input className={inputClass} value={name} onChange={(e) => setName(e.target.value)} />
+        </div>
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Interpreter</label>
+          <select className={inputClass} value={interpreter} onChange={(e) => setInterpreter(e.target.value as "bash" | "powershell")}>
+            <option value="bash">bash</option>
+            <option value="powershell">powershell</option>
+          </select>
+        </div>
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Script</label>
+          <textarea className={`${inputClass} h-40 font-mono text-xs`} value={script} onChange={(e) => setScript(e.target.value)} />
+          <p className="mt-1 text-xs text-text-secondary">Write <code className="text-signal">KEY=value</code> to <code className="text-signal">$WORKFLOW_ENV</code> to expose it to later steps.</p>
+        </div>
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Outputs</label>
+          <div className="mb-1 flex flex-wrap gap-1">
+            {(step?.declared_outputs ?? []).length === 0 && (
+              <p className="text-xs text-text-secondary">No declared outputs.</p>
+            )}
+            {(step?.declared_outputs ?? []).map((o) => (
+              <span key={o} className="flex items-center gap-1 rounded bg-signal px-2 py-0.5 font-mono text-[11px] text-signal-ink">
+                {o}
+              </span>
+            ))}
+          </div>
+          <p className="text-xs text-text-secondary">Outputs are detected automatically from lines writing to $WORKFLOW_ENV.</p>
+        </div>
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Inputs</label>
+          <div className="space-y-2">
+            {inputs.map((inp, i) => (
+              <div key={i} className="flex gap-2">
+                <input className={inputClass} placeholder="name" value={inp.name} onChange={(e) => setInputs(inputs.map((x, j) => j === i ? { ...x, name: e.target.value } : x))} />
+                <input className={inputClass} placeholder="default" value={inp.default} onChange={(e) => setInputs(inputs.map((x, j) => j === i ? { ...x, default: e.target.value } : x))} />
+                <input className={inputClass} placeholder="description" value={inp.description} onChange={(e) => setInputs(inputs.map((x, j) => j === i ? { ...x, description: e.target.value } : x))} />
+                <Button variant="ghost" size="sm" onClick={() => setInputs(inputs.filter((_, j) => j !== i))}>✕</Button>
+              </div>
+            ))}
+          </div>
+          <Button variant="ghost" size="sm" className="mt-2" onClick={() => setInputs([...inputs, { name: "", default: "", description: "" }])}>Add input</Button>
+        </div>
+        <div className="flex items-center justify-between pt-2">
+          {step ? <Button variant="danger" onClick={del} loading={busy}>Delete step</Button> : <span />}
+          <div className="flex gap-2">
+            <Button variant="ghost" onClick={onClose}>Cancel</Button>
+            <Button variant="primary" onClick={save} loading={busy} disabled={!name.trim()}>Save</Button>
+          </div>
+        </div>
+      </div>
+    </Modal>
+  );
+}

web/components/workflows/EditWorkflowModal.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useQuery } from "@tanstack/react-query";
+import { api, Workflow } from "@/lib/api";
+import { Button, Modal } from "@/components/ui";
+
+const inputClass =
+  "w-full rounded-lg border border-border bg-surface-2 px-3 py-2 text-sm text-text-primary focus:border-signal focus:outline-none focus:ring-1 focus:ring-signal";
+
+export function EditWorkflowModal({ open, workflow, onSaved, onClose }: { open: boolean; workflow: Workflow; onSaved: (w: Workflow) => void; onClose: () => void }) {
+  const router = useRouter();
+  const [name, setName] = useState(workflow.name);
+  const [targets, setTargets] = useState<string[]>(workflow.target_server_ids);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const { data: servers } = useQuery({ queryKey: ["servers"], queryFn: api.listServers });
+
+  useEffect(() => {
+    if (open) {
+      setName(workflow.name);
+      setTargets(workflow.target_server_ids);
+    }
+  }, [open, workflow]);
+
+  const toggle = (id: string) => setTargets((t) => (t.includes(id) ? t.filter((x) => x !== id) : [...t, id]));
+
+  const save = async () => {
+    setBusy(true); setError(null);
+    try {
+      const updated = await api.updateWorkflow(workflow.workflow_id, { ...workflow, name, target_server_ids: targets });
+      onSaved(updated); onClose();
+    } catch (e) { setError((e as Error).message); } finally { setBusy(false); }
+  };
+
+  const del = async () => {
+    if (!window.confirm("Delete this workflow? This cannot be undone.")) return;
+    setBusy(true); setError(null);
+    try { await api.deleteWorkflow(workflow.workflow_id); router.push("/workflows"); }
+    catch (e) { setError((e as Error).message); setBusy(false); }
+  };
+
+  return (
+    <Modal open={open} onClose={onClose} title="Edit workflow">
+      <div className="space-y-4">
+        {error && <div className="rounded border border-danger/30 bg-danger/10 px-3 py-2 text-sm text-danger">{error}</div>}
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Name</label>
+          <input className={inputClass} value={name} onChange={(e) => setName(e.target.value)} />
+        </div>
+        <div>
+          <label className="mb-1 block text-xs uppercase text-text-secondary">Target servers</label>
+          <div className="flex flex-wrap gap-2">
+            {servers?.map((s) => {
+              const on = targets.includes(s.server_id);
+              return (
+                <label key={s.server_id} className={`flex cursor-pointer items-center gap-2 rounded-lg border px-2 py-1 text-sm ${on ? "border-signal bg-signal/10 text-text-primary" : "border-border text-text-secondary"}`}>
+                  <input type="checkbox" className="accent-signal" checked={on} onChange={() => toggle(s.server_id)} />
+                  {s.hostname}
+                </label>
+              );
+            })}
+            {servers && servers.length === 0 && <p className="text-xs text-text-secondary">No servers registered.</p>}
+          </div>
+        </div>
+        <div className="flex items-center justify-between pt-2">
+          <Button variant="danger" onClick={del} loading={busy}>Delete workflow</Button>
+          <div className="flex gap-2">
+            <Button variant="ghost" onClick={onClose}>Cancel</Button>
+            <Button variant="primary" onClick={save} loading={busy} disabled={!name.trim()}>Save</Button>
+          </div>
+        </div>
+      </div>
+    </Modal>
+  );
+}

web/lib/api.ts

@@ -95,6 +95,7 @@ export interface Settings {
   alerts: AlertSettings;
   email: EmailSettings;
   secrets: SecretsSettings;
+  workflow_log_retention_days?: number | null;
 }
 
 export interface SecretGroupSummary {
@@ -113,6 +114,7 @@ export interface NewServerResponse {
   server_id: string;
   pre_reg_token: string;
   install_command: string;
+  install_command_ps: string;
 }
 
 export interface GenerateKeyOptions {
@@ -131,6 +133,75 @@ export interface ServerWithKeys extends Server {
   keys: (Assignment & { key: Key })[];
 }
 
+export interface InputParam {
+  name: string;
+  default: string;
+  description: string;
+}
+
+export interface WorkflowStep {
+  step_id: string;
+  name: string;
+  description: string;
+  interpreter: "bash" | "powershell";
+  script: string;
+  declared_outputs: string[];
+  declared_inputs: InputParam[];
+  secret_refs: string[];
+  source?: "user" | "default";
+  slug?: string;
+}
+
+export interface WorkflowStepRef {
+  step_id?: string;
+  inline?: WorkflowStep;
+  order: number;
+  on_failure: "stop" | "continue" | "retry";
+  max_retries: number;
+  overrides?: { script?: string; secret_refs?: string[] };
+  inputs?: Record<string, string>;
+}
+
+export interface Workflow {
+  workflow_id: string;
+  name: string;
+  target_server_ids: string[];
+  steps: WorkflowStepRef[];
+}
+
+export interface StepRun {
+  order: number;
+  name: string;
+  status: string;
+  attempts: number;
+  exit_code: number;
+  log_offset: number;
+  output_env: Record<string, string>;
+  started_at?: string;
+  finished_at?: string;
+}
+
+export interface ServerRun {
+  server_id: string;
+  hostname: string;
+  status: string;
+  run_env: Record<string, string>;
+  steps: StepRun[];
+  started_at?: string;
+  finished_at?: string;
+}
+
+export interface WorkflowRun {
+  run_id: string;
+  workflow_id: string;
+  name: string;
+  status: string;
+  triggered_by: string;
+  started_at: string;
+  finished_at?: string;
+  server_runs: ServerRun[];
+}
+
 class ApiError extends Error {
   constructor(
     public status: number,
@@ -188,7 +259,10 @@ export const api = {
     });
   },
 
-  getUpdateCommand(): string {
+  getUpdateCommand(osInfo?: string): string {
+    if (osInfo && osInfo.toLowerCase().includes("windows")) {
+      return `irm "${window.location.origin}/update.ps1" | iex`;
+    }
     return `curl -fsSL "${window.location.origin}/update" | bash`;
   },
 
@@ -219,7 +293,11 @@ export const api = {
     return request<Settings>("/settings");
   },
 
-  saveSettings(settings: { alerts: AlertSettings; email: EmailSettings }): Promise<{ saved: boolean }> {
+  saveSettings(settings: {
+    alerts: AlertSettings;
+    email: EmailSettings;
+    workflow_log_retention_days?: number | null;
+  }): Promise<{ saved: boolean }> {
     return request<{ saved: boolean }>("/settings", {
       method: "PUT",
       body: JSON.stringify(settings),
@@ -320,4 +398,109 @@ export const api = {
       body: JSON.stringify(body),
     });
   },
+
+  // Steps
+  listSteps(): Promise<WorkflowStep[]> {
+    return request<WorkflowStep[]>("/steps");
+  },
+
+  createStep(s: Partial<WorkflowStep>): Promise<WorkflowStep> {
+    return request<WorkflowStep>("/steps", {
+      method: "POST",
+      body: JSON.stringify(s),
+    });
+  },
+
+  updateStep(stepId: string, s: Partial<WorkflowStep>): Promise<WorkflowStep> {
+    return request<WorkflowStep>(`/steps/${stepId}`, {
+      method: "PUT",
+      body: JSON.stringify(s),
+    });
+  },
+
+  deleteStep(stepId: string): Promise<void> {
+    return request<void>(`/steps/${stepId}`, { method: "DELETE" });
+  },
+
+  exportStepUrl(stepId: string): string {
+    return `/api/steps/${stepId}/export`;
+  },
+
+  importStep(doc: unknown): Promise<WorkflowStep> {
+    return request<WorkflowStep>("/steps/import", {
+      method: "POST",
+      body: JSON.stringify(doc),
+    });
+  },
+
+  parseStep(doc: unknown): Promise<WorkflowStep> {
+    return request<WorkflowStep>("/steps/parse", {
+      method: "POST",
+      body: JSON.stringify(doc),
+    });
+  },
+
+  seedDefaults(): Promise<{ created: number; updated: number }> {
+    return request<{ created: number; updated: number }>("/steps/seed-defaults", {
+      method: "POST",
+    });
+  },
+
+  // Workflows
+  listWorkflows(): Promise<Workflow[]> {
+    return request<Workflow[]>("/workflows");
+  },
+
+  getWorkflow(workflowId: string): Promise<Workflow> {
+    return request<Workflow>(`/workflows/${workflowId}`);
+  },
+
+  createWorkflow(w: Partial<Workflow>): Promise<Workflow> {
+    return request<Workflow>("/workflows", {
+      method: "POST",
+      body: JSON.stringify(w),
+    });
+  },
+
+  updateWorkflow(workflowId: string, w: Partial<Workflow>): Promise<Workflow> {
+    return request<Workflow>(`/workflows/${workflowId}`, {
+      method: "PUT",
+      body: JSON.stringify(w),
+    });
+  },
+
+  deleteWorkflow(workflowId: string): Promise<void> {
+    return request<void>(`/workflows/${workflowId}`, { method: "DELETE" });
+  },
+
+  runWorkflow(workflowId: string): Promise<{ run_id: string }> {
+    return request<{ run_id: string }>(`/workflows/${workflowId}/run`, {
+      method: "POST",
+    });
+  },
+
+  listRuns(workflowId: string): Promise<WorkflowRun[]> {
+    return request<WorkflowRun[]>(`/workflows/${workflowId}/runs`);
+  },
+
+  // Runs
+  getRun(runId: string): Promise<WorkflowRun> {
+    return request<WorkflowRun>(`/runs/${runId}`);
+  },
+
+  cancelRun(runId: string): Promise<void> {
+    return request<void>(`/runs/${runId}/cancel`, { method: "POST" });
+  },
+
+  async getServerRunLog(runId: string, serverId: string): Promise<string> {
+    const res = await fetch(`/api/runs/${runId}/servers/${serverId}/logs`, {
+      credentials: "include",
+    });
+    if (!res.ok) throw new Error("no logs");
+    return res.text();
+  },
+
+  serverRunLogStreamUrl(runId: string, serverId: string): string {
+    return `/api/runs/${runId}/servers/${serverId}/logs/stream`;
+  },
 };

web/lib/guacConsole.ts

@@ -2,26 +2,70 @@
 // The library attaches a global `Guacamole` object when loaded.
 declare const Guacamole: any;
 
-export function openConsole(container: HTMLElement, wsUrl: string): { disconnect: () => void } {
+export function openConsole(
+  container: HTMLElement,
+  wsUrl: string,
+  connectData = ""
+): { disconnect: () => void; setScale: (scale: number) => void; resize: (width: number, height: number) => void } {
+  // Guacamole's WebSocketTunnel builds the socket URL as `wsUrl + "?" + data`,
+  // so wsUrl must NOT already contain a query string — pass params via connectData.
   const tunnel = new Guacamole.WebSocketTunnel(wsUrl);
   const client = new Guacamole.Client(tunnel);
 
   container.innerHTML = "";
   container.appendChild(client.getDisplay().getElement());
+  // Make the console focusable so keyboard capture is scoped to it (see below).
+  container.tabIndex = 0;
 
-  client.connect("");
+  client.connect(connectData);
 
-  // Wire keyboard + mouse.
-  const mouse = new Guacamole.Mouse(client.getDisplay().getElement());
-  mouse.onmousedown = mouse.onmouseup = mouse.onmousemove = (state: any) =>
-    client.sendMouseState(state);
-  const keyboard = new Guacamole.Keyboard(document);
+  const display = client.getDisplay();
+  let scale = 1;
+
+  // Wire keyboard + mouse. The display element is rendered at `scale` of the
+  // remote's native resolution, but Guacamole.Mouse reports coordinates in
+  // element (on-screen) pixels. Divide by scale to map back to remote
+  // coordinates, otherwise the cursor is offset.
+  const mouse = new Guacamole.Mouse(display.getElement());
+  mouse.onmousedown = mouse.onmouseup = mouse.onmousemove = (state: any) => {
+    const s = new Guacamole.Mouse.State(
+      state.x / scale,
+      state.y / scale,
+      state.left,
+      state.middle,
+      state.right,
+      state.up,
+      state.down
+    );
+    client.sendMouseState(s);
+  };
+  // Scope keyboard capture to the container rather than `document`, so it only
+  // grabs keys while the console is focused and stops entirely once the element
+  // is removed (navigating away / disconnect). Attaching to `document` leaks the
+  // capture and swallows keystrokes in unrelated inputs.
+  const keyboard = new Guacamole.Keyboard(container);
   keyboard.onkeydown = (k: number) => client.sendKeyEvent(1, k);
   keyboard.onkeyup = (k: number) => client.sendKeyEvent(0, k);
+  // Guacamole.Mouse consumes the native mousedown, so clicking the console never
+  // moves DOM focus back to it. Refocus explicitly so keyboard capture resumes.
+  const refocus = () => container.focus();
+  container.addEventListener("mousedown", refocus);
+  container.focus();
 
   return {
     disconnect() {
+      container.removeEventListener("mousedown", refocus);
+      keyboard.onkeydown = null;
+      keyboard.onkeyup = null;
+      if (typeof keyboard.reset === "function") keyboard.reset();
       client.disconnect();
     },
+    setScale(s: number) {
+      scale = s;
+      display.scale(s);
+    },
+    resize(width: number, height: number) {
+      client.sendSize(width, height);
+    },
   };
 }

web/next.config.ts

@@ -18,10 +18,18 @@ const nextConfig: NextConfig = {
                 source: "/install",
                 destination: `${apiUrl}/install`,
             },
+            {
+                source: "/install.ps1",
+                destination: `${apiUrl}/install.ps1`,
+            },
             {
                 source: "/update",
                 destination: `${apiUrl}/update`,
             },
+            {
+                source: "/update.ps1",
+                destination: `${apiUrl}/update.ps1`,
+            },
         ];
     },
 };

web/tailwind.config.ts

@@ -21,6 +21,10 @@ const config: Config = {
         warning: "#f59e0b",
         danger: "#ef4444",
         "danger-hover": "#dc2626",
+        bash: "#3fb950",
+        pwsh: "#5b9bff",
+        signal: "#f5a524",
+        "signal-ink": "#241800",
       },
     },
   },