Update docs

Author: daniel-thom

docs/src/explanation/architecture.md

@@ -7,7 +7,7 @@ coordination, while clients create workflows and job runners execute tasks on co
 
 **Key Components:**
 
-- **Server**: REST API service that manages workflow state via a SQLite database
+- **Server**: HTTP API service that manages workflow state via a SQLite database
 - **Client**: CLI tool and library for creating and managing workflows
 - **Job Runner**: Worker process that pulls ready jobs, executes them, and reports results
 - **Database**: Central SQLite database that stores all workflow state and coordinates distributed
@@ -18,7 +18,7 @@ coordination, while clients create workflows and job runners execute tasks on co
 ```mermaid
 graph TB
     subgraph Server["Torc Server"]
-        API["REST API (Tokio 1-thread)<br/>/workflows /jobs /files<br/>/user_data /results"]
+        API["HTTP API (Tokio 1-thread)<br/>/workflows /jobs /files<br/>/user_data /results"]
         DB["SQLite Database (WAL)<br/>• Workflow state<br/>• Job dependencies<br/>• Resource tracking<br/>• Execution results"]
         API --> DB
     end
@@ -27,7 +27,7 @@ graph TB
     Runner1["Job Runner 1<br/>(compute-01)<br/>• Poll for jobs<br/>• Execute tasks<br/>• Report results"]
     RunnerN["Job Runner N<br/>(compute-nn)<br/>• Poll for jobs<br/>• Execute tasks<br/>• Report results"]
 
-    Client -.HTTP/REST.-> API
-    Runner1 -.HTTP/REST.-> API
-    RunnerN -.HTTP/REST.-> API
+    Client -.HTTP.-> API
+    Runner1 -.HTTP.-> API
+    RunnerN -.HTTP.-> API
 ```

docs/src/explanation/design/interfaces.md

@@ -46,7 +46,7 @@ graph TD
     end
 
     subgraph "Server"
-        HTTP["HTTP REST API<br/>(torc-server)"]
+        HTTP["HTTP API<br/>(torc-server)"]
         DB[(SQLite Database)]
     end
 

docs/src/explanation/job-states.md

@@ -32,6 +32,5 @@ stateDiagram-v2
 - **running** (4) - Currently executing
 - **completed** (5) - Finished successfully (exit code 0)
 - **failed** (6) - Finished with error (exit code != 0)
-- **canceled** (7) - Explicitly canceled by user or system
-- **terminated** (8) - Explicitly terminated by system, such as for checkpointing before wall-time
-  timeout
+- **canceled** (7) - Explicitly canceled by user or torc. Never executed.
+- **terminated** (8) - Explicitly terminated by system, such as at wall-time timeout

docs/src/getting-started.md

@@ -10,51 +10,82 @@ coordination, while clients create workflows and job runners execute tasks on co
 
 Choose the interface that fits your workflow:
 
-- **Dashboard** — Web UI ([torc-dash](./how-to/dashboard.md)) for visual monitoring
+- **CLI** — Primary interface which provides access to all torc functionality
+- **Dashboard** — Web UI ([torc-dash](./how-to/dashboard.md)) for visual configuration and
+  monitoring
+- **TUI** — Terminal User Interface (`torc tui`) for visual monitoring in a terminal
 - **AI Assistants** — Use [Claude Code](https://claude.ai/code) or GitHub Copilot to manage
   workflows through natural language. _"Create a workflow with 10 parallel jobs"_ or _"Why did job 5
   fail?"_
-- **TUI** — Terminal User Interface (`torc tui`) for visual monitoring in a terminal
-- **CLI** — The `torc` command for scripting and automation
 - **Spec Files** — YAML, KDL, or JSON5 files for version-controlled workflow definitions
 - **Python/Julia APIs** — Libraries for programmatic workflow generation
 
-All interfaces work with the same server—mix and match as needed.
+All interfaces work with the same server — mix and match as needed.
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Torc Server                              │
-│                   (REST API + SQLite DB)                        │
-└─────────────────────────────────────────────────────────────────┘
-        ▲              ▲              ▲              ▲
-        │              │              │              │
-   ┌────┴────┐   ┌─────┴─────┐   ┌────┴────┐   ┌─────┴─────┐
-   │   CLI   │   │ Dashboard │   │   AI    │   │  Python   │
-   │  torc   │   │ torc-dash │   │Assistant│   │   API     │
-   └─────────┘   └───────────┘   └─────────┘   └───────────┘
+```mermaid
+flowchart TB
+    subgraph ai["AI Integration"]
+        AI_CLIENTS["AI Clients<br/>(Claude Code, Copilot)"]
+        MCP["torc-mcp-server"]
+        AI_CLIENTS -->|"MCP"| MCP
+    end
+
+    subgraph clients["Client Applications"]
+        TUI["torc tui"]
+        DASH["torc-dash<br/>(web UI)"]
+        PY["Python Client"]
+        JL["Julia Client"]
+    end
+
+    CLI["torc CLI"]
+
+    subgraph server["Server"]
+        HTTP["HTTP API<br/>(torc-server)"]
+        DB[(SQLite)]
+        HTTP --> DB
+    end
+
+    subgraph workers["Workers (local, remote, or HPC)"]
+        LOCAL["Local Runner"]
+        SLURM["Slurm Runner"]
+    end
+
+    TUI -->|"executes"| CLI
+    DASH -->|"executes"| CLI
+    MCP -->|"executes"| CLI
+
+    CLI -->|"HTTP"| HTTP
+    TUI -->|"HTTP"| HTTP
+    DASH -->|"HTTP"| HTTP
+    MCP -->|"HTTP"| HTTP
+    PY -->|"HTTP"| HTTP
+    JL -->|"HTTP"| HTTP
+
+    LOCAL -->|"HTTP"| HTTP
+    SLURM -->|"HTTP"| HTTP
 ```
 
 **Key components:**
 
-- **Server** — REST API service managing workflow state via SQLite
+- **Server** — HTTP API service managing workflow state via SQLite
 - **Job Runners** — Worker processes that execute jobs on compute resources
 - **Clients** — CLI, dashboard, AI assistants, or API libraries
 
 ## Features
 
-- **AI-Assisted Management** — Create, debug, and manage workflows through conversation
 - **Declarative Workflow Specifications** — Define workflows in YAML, JSON5, JSON, or KDL
-- **Automatic Dependency Resolution** — Dependencies inferred from file and data relationships
 - **Job Parameterization** — Create parameter sweeps and grid searches with simple syntax
+- **Automatic Dependency Resolution** — Dependencies inferred from file and data relationships
 - **Distributed Execution** — Run jobs across multiple compute nodes with resource tracking
 - **Slurm Integration** — Native support for HPC cluster job submission
 - **Automatic Failure Recovery** — Detect OOM/timeout failures and retry with adjusted resources
 - **Workflow Resumption** — Restart workflows after failures without losing progress
 - **Change Detection** — Automatically detect input changes and re-run affected jobs
-- **Resource Management** — Track CPU, memory, and GPU usage across all jobs
+- **Resource Management** — Track CPU and memory across all jobs
 - **RESTful API** — Complete OpenAPI-specified REST API for integration
+- **AI-Assisted Management** — Create, debug, and manage workflows through conversation
 
 ## Next: Quick Start
 

docs/src/how-to/ai-assistants.md

@@ -5,7 +5,7 @@ Complete guide for configuring AI assistants (Claude Code, GitHub Copilot) to wo
 ## Overview
 
 Torc provides an MCP (Model Context Protocol) server that enables AI assistants to interact with
-workflows. The `torc-mcp-server` binary acts as a bridge between AI assistants and the Torc REST
+workflows. The `torc-mcp-server` binary acts as a bridge between AI assistants and the Torc HTTP
 API.
 
 ## Available Tools
@@ -219,7 +219,7 @@ Torc uses the Model Context Protocol (MCP), an open standard for connecting AI a
 external tools. The `torc-mcp-server` binary:
 
 1. **Receives tool calls** from the AI assistant via stdio
-2. **Translates them** to Torc REST API calls
+2. **Translates them** to Torc HTTP API calls
 3. **Returns results** in a format the assistant can understand
 
 The server is stateless—it simply proxies requests to your running Torc server. All workflow state

docs/src/how-to/slurm.md

@@ -293,7 +293,7 @@ torc slurm schedule-nodes -n 5 $WORKFLOW_ID
 ### Check Slurm Job Status
 
 ```bash
-squeue -u $USER
+squeue --me
 ```
 
 ### View Torc Worker Logs

docs/src/installation.md

@@ -14,6 +14,45 @@ xattr -cr /path/to/torc*
 
 Alternatively, you can right-click each binary and select "Open" to add a security exception.
 
+## Site-Specific Installations
+
+Some HPC facilities maintain pre-installed Torc binaries and shared servers. Check if your site is
+listed below.
+
+### NREL Kestrel
+
+**Pre-installed binaries** are available at:
+
+```
+/scratch/dthom/torc/
+├── 0.8.0/
+├── ...
+└── latest -> 0.8.0  (symlink to current version)
+```
+
+> **Recommended**: Use the `latest` directory. Torc maintains backwards compatibility, so you'll
+> automatically receive updates and bug fixes without changing your configuration.
+
+Add to your PATH:
+
+```bash
+export PATH="/scratch/dthom/torc/latest:$PATH"
+```
+
+Or add to your `~/.bashrc` for persistence:
+
+```bash
+echo 'export PATH="/scratch/dthom/torc/latest:$PATH"' >> ~/.bashrc
+```
+
+**Shared server**: A `torc-server` instance runs on a dedicated VM within the Kestrel environment.
+Contact Daniel Thom for access credentials and the server URL. Once you have access:
+
+```bash
+export TORC_API_URL="http://<server-address>/torc-service/v1"
+export TORC_PASSWORD="<your-password>"
+```
+
 ## Building from Source
 
 ### Prerequisites
@@ -67,8 +106,10 @@ cargo build --release -p torc-dash
 cargo build --release -p torc-slurm-job-runner
 ```
 
-Binaries will be in `target/release/`. We recommend adding this directory to your system path so
-that you can run all binaries without specifying the full path.
+Binaries will be in `target/release/`.
+
+**Required**: Add this directory to your system path or copy the binaries to a directory already in
+your path (e.g., `~/.local/bin/`).
 
 ## Python Client
 
@@ -81,7 +122,7 @@ The Python client provides programmatic workflow management for Python users.
 ### Installation
 
 ```bash
-pip install "torc @ git+https://github.com/NREL/torc.git#subdirectory=python_client"
+pip install torc-client
 ```
 
 The `pytorc` command will be available after installation.

docs/src/introduction.md

@@ -8,7 +8,8 @@ dependencies, mixed resource requirements, and multiple stages.
 
 - **Declarative Workflow Definitions** — Define workflows in YAML, JSON, JSON5, or KDL
 - **Automatic Dependency Resolution** — Dependencies inferred from file and data relationships
-- **Distributed Execution** — Run jobs across local machines and HPC clusters
+- **Distributed Execution** — Run jobs across local machines, HPC clusters, and networked compute
+  nodes
 - **Resource Management** — Track CPU and memory usage across all jobs
 - **Automatic Failure Recovery** — Detect OOM/timeout failures and retry with adjusted resources
 - **Fault Tolerance** — Resume workflows after failures without losing progress

docs/src/quick-start-hpc.md

@@ -105,7 +105,7 @@ torc tui
 Check Slurm queue:
 
 ```console
-squeue -u $USER
+squeue --me
 ```
 
 ## View Results

docs/src/quick-start-local.md

@@ -38,7 +38,7 @@ jobs:
     command: echo "Hello again from torc!"
 ```
 
-> **Note:** Torc also accepts `.json5` and `.kdl` workflow specifications. See
+> **Note:** Torc also accepts `.json`, `.json5` and `.kdl` workflow specifications. See
 > [Workflow Specification Formats](./reference/workflow-formats.md) for details.
 
 ## Run the Workflow