@minicor/mcp-server 3.9.1 → 4.1.0

package/README.md

@@ -1,12 +1,12 @@
 # Minicor MCP Server
 
-Build, deploy, and debug VM-based browser and desktop automations from **Cursor** or **Claude Code**. The AI agent connects to your Windows VM, writes Python automation scripts, tests them through the Minicor executor, and deploys production-ready workflows — with skills accumulated from every build.
+Build, deploy, and debug VM-based browser and desktop automations from **Cursor** or **Claude Code**. The AI agent connects to your Windows VM, writes Python automation scripts, tests them through the Minicor executor, and deploys production-ready workflows - with skills accumulated from every build.
 
 ## Quick Start
 
 ### 1. Install
 
-**Cursor** — add to `~/.cursor/mcp.json`:
+**Cursor** - add to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -19,7 +19,7 @@ Build, deploy, and debug VM-based browser and desktop automations from **Cursor*
 }
 ```
 
-**Claude Code** — no global install needed (npx always runs the latest):
+**Claude Code** - no global install needed (npx always runs the latest):
 
 ```bash
 claude mcp add minicor -- npx -y @minicor/mcp-server
@@ -39,46 +39,49 @@ npx -y -p @minicor/mcp-server minicor-mcp-setup --cli
 
 > The package ships multiple commands. Always use `npx -p @minicor/mcp-server <command>` to run a specific one (`minicor-mcp-setup`, `minicor-bootstrap`, …). Running `npx @minicor/mcp-server` alone only starts the MCP server and ignores trailing arguments.
 
-### Focused Builder MCP (optional)
+### Hosted MCP (cloud, no install)
 
-The package also includes `minicor-builder-mcp`, a focused server for workflow creation, Dev Mode drafts and execution controls, configuration stores, VM discovery, and Jobs. It shares the normal Minicor login and backend-owned draft state with the full server.
+The same server also runs hosted at `https://mcp.minicor.com/mcp` (Streamable HTTP). Sign-in is your Minicor email/password through an OAuth flow - no API keys, no local tokens. The tool set matches the local server except for the tools that read and write your local disk (workspace clones, sessions, sync); those require the local install above.
 
-To add it alongside the normal Cursor MCP during setup:
+**Claude (web / Desktop / mobile):**
+
+1. Go to **Settings > Connectors > Add custom connector**.
+2. Paste `https://mcp.minicor.com/mcp` and save. OAuth is auto-discovered - no client ID or secret.
+3. Claude opens the Minicor sign-in page. Enter your email, password, and region (US/Canada). Done - the connector acts as your account.
+
+**Claude Code:**
 
 ```bash
-npx -y -p @minicor/mcp-server minicor-mcp-setup --with-builder
+claude mcp add --transport http minicor-cloud https://mcp.minicor.com/mcp
 ```
 
-Or configure it directly:
+Then run `/mcp` inside Claude Code to trigger the OAuth sign-in.
+
+**Cursor** - add a URL-based entry to `~/.cursor/mcp.json` (Cursor prompts for the OAuth sign-in on first use):
 
 ```json
 {
   "mcpServers": {
-    "minicor-builder": {
-      "command": "npx",
-      "args": ["-y", "-p", "@minicor/mcp-server", "minicor-builder-mcp"]
+    "minicor-cloud": {
+      "url": "https://mcp.minicor.com/mcp"
     }
   }
 }
 ```
 
-For Claude Code:
+Access tokens expire within an hour and refresh automatically for up to 30 days; after that you sign in again. To self-host the same endpoint (or restrict sign-in to your email domain), see [docs/HOSTED.md](docs/HOSTED.md).
 
-```bash
-claude mcp add minicor-builder -- npx -y -p @minicor/mcp-server minicor-builder-mcp
-```
-
-Use the builder server while editing, testing, and publishing drafts, then switch back to `minicor` for the full tool surface. The builder uses standard MCP tools by default; code mode remains opt-in through `EXPERIMENTAL_USE_CODE_MODE=1`.
+> Older installs may have a separate `minicor-builder` entry in their MCP config. That server was folded into `minicor`; re-running `minicor-mcp-setup` removes the stale entry.
 
 ### 3. Bootstrap Workspace (optional)
 
 After cloning a workspace, generate harness-specific config files:
 
 ```bash
-# For Claude Code — creates CLAUDE.md + .claude/settings.local.json
+# For Claude Code - creates CLAUDE.md + .claude/settings.local.json
 npx -y -p @minicor/mcp-server minicor-bootstrap claude-code --dir ./my-workspace
 
-# For Cursor — creates .cursor/rules/workspace.mdc
+# For Cursor - creates .cursor/rules/workspace.mdc
 npx -y -p @minicor/mcp-server minicor-bootstrap cursor --dir ./my-workspace
 
 # All harnesses at once
@@ -93,13 +96,12 @@ npx -y -p @minicor/mcp-server minicor-bootstrap all --dir ./my-workspace
 
 Remove the MCP server entry from your editor first:
 
-**Cursor** — edit `~/.cursor/mcp.json` and remove `mcpServers.minicor`, `mcpServers.minicor-builder`, and any legacy `mcpServers.laminar` entry.
+**Cursor** - edit `~/.cursor/mcp.json` and remove `mcpServers.minicor`, plus any legacy `mcpServers.laminar` or `mcpServers.minicor-builder` entry.
 
-**Claude Code** — remove the registered server:
+**Claude Code** - remove the registered server:
 
 ```bash
 claude mcp remove minicor
-claude mcp remove minicor-builder
 ```
 
 If the command is unavailable, remove the `minicor` MCP server entry from your Claude Code MCP config.
@@ -199,7 +201,7 @@ Sessions are synced to `[Workspace:Session]` issues on the platform, so agents o
 
 ## The RPA Lifecycle
 
-This is the complete flow from zero to production automation. The agent handles each phase using MCP tools and skills.
+This is the complete flow from zero to production automation. The agent handles each phase using MCP tools and skills. Workflows are built and tested inside a **Job** (see [Jobs](#jobs-rpa-orchestration) below): the job's test cases are written before the workflow exists and are the definition of done for the whole build.
 
 ### Phase 1: Workspace Setup
 
@@ -207,11 +209,11 @@ This is the complete flow from zero to production automation. The agent handles
 "Create a workspace for Acme Corp and set up a VM"
 ```
 
-- `create_workspace` / `list_workspaces` / `get_workspace` — create or find a workspace
-- `vm_list` — discover available VMs
-- `deploy_vm` — provision a new Windows VM if needed
-- `install_mds_on_vm` / `start_mds_on_vm` — install the Minicor Desktop Service
-- `vm_connect` — connect to the VM via Cloudflare tunnel
+- `create_workspace` / `list_workspaces` / `get_workspace` - create or find a workspace
+- `vm_list` - discover available VMs
+- `deploy_vm` - provision a new Windows VM if needed
+- `install_mds_on_vm` / `start_mds_on_vm` - install the Minicor Desktop Service
+- `vm_connect` - connect to the VM via Cloudflare tunnel
 
 ### Phase 2: Clone Workspace
 
@@ -219,18 +221,18 @@ This is the complete flow from zero to production automation. The agent handles
 "Clone workspace 257 to my local folder"
 ```
 
-- `clone_workspace` — pulls everything to a local folder:
-  - `minicor.json` — workspace manifest
-  - `workflows/` — all workflow steps as files (git-native)
-  - `.minicor/skills/general/` — bundled RPA skills
-  - `.minicor/skills/workspace/` — workspace-specific learned skills
-  - `.minicor/issues/` — agent-persisted context from previous runs
-  - `.minicor/skill-index.json` — compact skill summary
-  - `.minicor/workspace.json` — workspace metadata
+- `clone_workspace` - pulls everything to a local folder:
+  - `minicor.json` - workspace manifest
+  - `workflows/` - all workflow steps as files (git-native)
+  - `.minicor/skills/general/` - bundled RPA skills
+  - `.minicor/skills/workspace/` - workspace-specific learned skills
+  - `.minicor/issues/` - agent-persisted context from previous runs
+  - `.minicor/skill-index.json` - compact skill summary
+  - `.minicor/workspace.json` - workspace metadata
 
 The folder is git-ready. Push to GitHub for version control, diffs, and CI/CD.
 
-### Phase 3: Scope & Research
+### Phase 3: Scope & Define the Green-Gate
 
 ```
 "I want to automate patient lookup in Centricity"
@@ -239,37 +241,45 @@ The folder is git-ready. Push to GitHub for version control, diffs, and CI/CD.
 The agent:
 
 - Takes screenshots, inspects UI elements, identifies the app framework
-- Loads relevant skills: `get_skill("cdp-browser-automation")` or `get_skill("desktop-uiautomation")`
+- Loads relevant skills: `get_skill("job-build-loop")`, then `get_skill("cdp-browser-automation")` or `get_skill("desktop-uiautomation")`
 - Checks `list_skills()` for customer-specific skills (e.g., "centricity-quirks")
 - Studies existing workflows via `get_workflow_overview`
 - Determines strategy: CDP browser, desktop uiautomation, or hybrid
+- **Writes the test cases before building.** `register_job` (a thin job whose workflow step will call the new workflow) plus `teach_job` or `add_test_case` with a real input and assertions. These cases start red; the rest of the lifecycle exists to turn them green.
 
 ### Phase 4: Build (Iterative)
 
 For each automation step:
 
-1. **Observe** — `vm_screenshot` + `vm_inspect_ui` to map the UI
-2. **Write** — Python script using patterns from loaded skills
-3. **Prototype** — `vm_execute_script` to test on the VM directly
-4. **Save** — `create_rpa_flow` to persist as a Minicor workflow step
-5. **Test through Minicor** — `execute_workflow_async` with `start_from_step`/`end_at_step` to verify the step works through the real executor (config variables, data passing, JS wrapper)
+1. **Observe** - `vm_screenshot` + `vm_inspect_ui` to map the UI
+2. **Write** - Python script using patterns from loaded skills
+3. **Prototype** - `vm_execute_script` to test on the VM directly
+4. **Save** - `create_rpa_flow` to persist as a Minicor workflow step
+5. **Test through Minicor** - `execute_workflow_async` with `start_from_step`/`end_at_step` to verify the step works through the real executor (config variables, data passing, JS wrapper)
 
-The testing step is critical — `vm_execute_script` doesn't resolve `{{config.*}}` variables or `data.input` interpolation. The agent loads `get_skill("rpa-testing-workflow")` for exact tool call sequences.
+The testing step is critical - `vm_execute_script` doesn't resolve `{{config.*}}` variables or `data.input` interpolation. The agent loads `get_skill("rpa-testing-workflow")` for exact tool call sequences.
 
-### Phase 5: Test End-to-End
+### Phase 5: Test End-to-End, Then Green-Gate the Job
 
 After all steps pass individually:
 
-- `execute_workflow_async` with real inputs + `configurationId` — full workflow, no step isolation
+- `execute_workflow_async` with real inputs + `configurationId` - full workflow, no step isolation
 - Poll `get_execution_status` + `vm_screenshot` to monitor
 - `diagnose_execution` on failure, fix with `update_flow`, re-run
-- Workflow is NOT done until it passes end-to-end through the Minicor executor
+- The workflow is not done until it passes end-to-end through the Minicor executor
+
+Then close the loop at the job level:
+
+- Point the job's workflow step at the finished `workflowId` (`update_job variant=draft`). If the workflow was edited in Dev Mode, `dev_mode_publish` first - jobs execute published workflows, not Dev Mode branches.
+- `run_tests variant=draft` - the test cases from Phase 3 are the pass/fail verdict for the build
+- On a red case, `resolve_job_state` / `inspect_job_execution` locate the failing step; replay just that slice with `run_job` (`fromStepId` + `seedExecutionId`) or drop back into the workflow, fix, re-run
+- When the suite is green, `publish_job` puts it live at `/m/:slug/:path`
 
 ### Phase 6: Production Hardening
 
 For production workflows (not POCs):
 
-- Load `get_skill("state-verification")` — add `expectedPreState`/`expectedPostState` to each step
+- Load `get_skill("state-verification")` - add `expectedPreState`/`expectedPostState` to each step
 - Run the workflow twice to verify idempotency
 - `create_agent` with `mode: "monitor"` + `watchWorkflowId` for failure monitoring
 - `create_agent` with `mode: "scheduled"` + cron for recurring runs
@@ -279,50 +289,77 @@ For production workflows (not POCs):
 
 After a successful build:
 
-- `generate_skill` — gathers workflow code, execution history, and agent issues
+- `generate_skill` - gathers workflow code, execution history, and agent issues
 - The agent analyzes patterns and calls `save_skill` to persist them
 - Skills are stored per-workspace and available to future builds
 - Customer-specific quirks become reusable knowledge
 
 ## Jobs (RPA orchestration)
 
-A **Job** is a middleware route whose behavior is a structured `definition` (a step graph) instead of freeform handler code. Jobs sit **above** workflows: a job step either calls an entire Minicor workflow (`kind: "workflow"`, by `workflowId`) or runs a code block (`kind: "code"`). The job never touches a workflow's internal steps — a workflow is an opaque callable with an input and an output. A job is the **macro zoom** (what ran, status, replays); a workflow → step is the **microscope**. This is the layer that turns one or more workflows into a versioned, testable, observable API endpoint.
+A **Job** is a middleware route whose behavior is a structured `definition` (a step graph) instead of freeform handler code. Jobs sit **above** workflows: a job step either calls an entire Minicor workflow (`kind: "workflow"`, by `workflowId`) or runs a code block (`kind: "code"`). The job never touches a workflow's internal steps - a workflow is an opaque callable with an input and an output. A job is the **macro zoom** (what ran, status, replays); a workflow → step is the **microscope**. This is the layer that turns one or more workflows into a versioned, testable, observable API endpoint.
 
 ### The job tools
 
 | Tool | What it does |
 | --- | --- |
-| `list_middlewares` | List the routers (middlewares) in a workspace — jobs attach to one of these. |
+| `resolve_job_state` | The first call to make when picking up a job. Returns the job's state (draft vs published, test cases, latest test run, recent executions, active build) plus `nextActions` - the concrete next tool calls. A red test run is drilled automatically: failing case → failing step → its `workflowId` (a `dev_mode_load` hint) → a seeded `fromStepId` replay command. |
+| `list_middlewares` | List the routers (middlewares) in a workspace - jobs attach to one of these. |
 | `register_middleware` | Create a router jobs attach to. `autoConfigure` (default true) populates the router's `workspaceApiKey` from the workspace's first key; or pass `workspaceApiKey` explicitly. |
-| `register_job` | Create a job — a route backed by a structured `definition` (step graph). |
+| `register_job` | Create a job - a route backed by a structured `definition` (step graph). |
 | `update_job` | Update a job's `definition`, path, method, or description. `variant: "draft"` writes the draft definition (the teach/build working copy); `variant: "published"` (default) edits the live definition and snapshots a new route version. |
 | `get_job` | Get a job (route) incl. its `definition` (and `draftDefinition` when one exists); omit `routeId` to list all routes on the router. |
-| `run_job` | Run a job once with an input, poll to completion, return the full `JobExecution` (per-step Minicor deep-links). `variant: "draft"` runs the draft definition instead of the published one. |
+| `run_job` | Run a job once with an input, poll to completion, return the full `JobExecution` (per-step Minicor deep-links). `variant: "draft"` runs the draft definition. For step-range debugging, `fromStepId` / `toStepId` (both inclusive) run a slice of the step graph, and `seedExecutionId` hydrates `ctx` from a prior execution so mid-graph starts still resolve earlier steps' values. `waitForResult: false` returns the `jobExecutionId` immediately for runs you want to stop or monitor. |
+| `stop_job_execution` | Stop a queued/running execution. This is a cooperative cancel (there is no pause): a queued run cancels immediately; a running one stops at the runner's next checkpoint (between steps, between `forEach` items, or while waiting on a workflow). A workflow already running on the VM is not killed - it finishes on its own; the job just stops waiting. Idempotent for already-cancelled runs. |
+| `list_job_executions` | List a job's executions (paginated summaries, newest first). Filter by `status` (`queued`/`running`/`succeeded`/`partial`/`failed`/`cancelled`) and/or `trigger` (`test` = suite runs; `api,mcp,cron` = live traffic). Use to find a prior run to seed a range run from, a running execution to stop, or the latest failure to inspect. |
+| `get_job_execution` | Fetch one past execution's full trace: status, input, output, `ctx`, per-step results. |
+| `inspect_job_execution` | Deep-drill an execution end to end: job → steps → (workflow steps) the underlying workflow execution's internal flow-runs, with RPA failure analysis on failures. |
 | `teach_job` | Teach a job by example: an `input` + a natural-language `prompt` (+ optional `expect` output or refusal, and `artifacts` like Loom links or SOP text). Upserts an idempotent judge-graded test case, folds it into the job's active build run, and, when a draft definition exists, runs the draft now and returns its output + judge verdict. |
 | `publish_job` | Promote a job's draft definition to published: snapshots a route version, copies draft to published, stamps `publishedAt`. Live traffic serves the new definition immediately. Run `run_tests` with `variant: "draft"` first. |
 | `get_build_status` | Get a job's build runs (the teach loop's cycles): status `queued`/`running`/`green`/`failed`/`needs_input`, folded-in test cases, builder summary, open questions. Pass `buildId` for one run; omit to list recent runs. |
 | `answer_build_question` | Answer a `needs_input` question on a build run (credentials choice, ambiguity, 2FA policy). When no open questions remain the build re-queues automatically. |
+| `cancel_build` | Stop a queued/running autonomous build run. The build flips to `failed` with a "stopped by user" summary; the job's draft definition is left as-is. Use it to take the loop over manually. |
 | `update_build_run` | Builder-facing: update a build run's lifecycle (`running` when you start, `green`/`failed` with a summary when done, `needs_input` with questions when blocked). |
 | `add_test_case` | Attach a test case to a job: named `input` + assertions (the green-gate). Assertions are `expr` (sandbox boolean) or `judge` (an LLM grades the execution against a natural-language `intent`). |
+| `update_test_case` | Update an existing test case: tighten assertions as behavior firms up, or set `enabled: false` to disable a case without deleting its history. |
 | `run_tests` | Run a job's test suite (or a subset), poll to completion, return the report (`green`, totals, per-case). `variant: "draft"` runs against the draft definition. |
 | `get_test_report` | Fetch a test run report by id (totals + per-case results, each linking to its job execution). |
-| `list_workspace_api_keys` | List a workspace's API keys (id, apiKey, name) — to find a key for the two tools below. |
+| `list_workspace_api_keys` | List a workspace's API keys (id, apiKey, name) - to find a key for the two tools below. |
 | `set_middleware_api_key` | Set a router's `workspaceApiKey` after the fact, then re-read to confirm it stuck. |
 
-### The recommended build loop — test-driven → job → workflow
+### The build loop - test-case-first, macroscope → microscope
 
-You work **backwards from the job's test cases**. The job's test suite is the macro green-gate; individual workflows are the micro RPA underneath.
+You work **backwards from the job's test cases**. The job's test suite is the macro green-gate; individual workflows are the micro RPA underneath. This mirrors the platform's Jobs UI (Overview = macroscope, Build = microscope). The full playbook ships as the `job-build-loop` skill - load it with `get_skill("job-build-loop")`.
 
 ```
-1. CONTRACT FIRST  — define the JOB's input/output and its test cases (the macro green-gate)
-                     via register_job + add_test_case. Cases start RED.
-2. BUILD WORKFLOWS — build/curate the Minicor workflow(s) each step will call (the micro RPA).
-3. WIRE THE STEPS  — wire workflows as `kind: "workflow"` steps with `input` mappings,
-                     plus `when` / `forEach` / `cache` / `onError` as needed.
-4. RUN TESTS       — run_tests until green: true. (run_job to inspect a single execution.)
+1. GREEN-GATE FIRST - teach_job (input + intent) or add_test_case (input + assertions).
+                      A job with no test cases has no definition of correct. Cases start RED.
+2. BUILD THE DRAFT  - register_job / update_job variant=draft. Job steps call PUBLISHED
+                      Minicor workflows (by workflowId) or run code blocks.
+3. RUN THE GATE     - run_tests variant=draft. Green -> publish_job. Red -> step 4.
+4. LOCATE (macro)   - resolve_job_state tells you where you are and what to do next;
+                      get_test_report + inspect_job_execution drill a failing case down to
+                      the failing job step and its workflow's internal flow-runs.
+5. FIX AT THE RIGHT LEVEL:
+   5a. Job-level    - update_job variant=draft, then replay JUST the failing slice:
+                      run_job variant=draft fromStepId=<failing step>
+                      seedExecutionId=<failed execution>  (seeds ctx so mid-graph starts
+                      resolve earlier steps' values).
+   5b. Workflow-level (microscope) - the failing step's workflowId -> dev_mode_load,
+                      fix/run the branch's flow steps with dev_mode_run,
+                      dev_mode_publish - jobs execute PUBLISHED workflows.
+6. PUBLISH          - when run_tests variant=draft is green, publish_job promotes the draft;
+                      runtime traffic at /m/:slug serves it immediately.
 ```
 
-A job step supports `saveAs`, `when` (conditional skip), `forEach` (fan-out), `onError` (`abort`/`skip`/`continue`/`{goto}` — `goto` currently treated as abort), `retry`, and `cache` (a login/smart-launch gate). Use `resource.lockKey` to serialize execution per desktop/VM. To migrate an existing NestJS customer middleware onto this layer, use the `nestjs-middleware-to-job` prompt or skill.
+A job step supports `saveAs`, `when` (conditional skip), `forEach` (fan-out), `onError` (`abort`/`skip`/`continue`/`{goto}` - `goto` currently treated as abort), `retry`, and `cache` (a login/smart-launch gate). Use `resource.lockKey` to serialize execution per desktop/VM. To migrate an existing NestJS customer middleware onto this layer, use the `nestjs-middleware-to-job` prompt or skill.
+
+### Execution control - stop, ranges, and traffic lenses
+
+- **Stopping:** there is no pause/resume. `stop_job_execution` is a cooperative cancel: a queued run cancels immediately; a running one stops at the runner's next checkpoint (between steps, between `forEach` items, or while waiting on a workflow). A workflow already running on a VM is not killed - it finishes on its own; the job just stops waiting and starts no new steps.
+- **Long or risky runs:** `run_job` with `waitForResult: false` returns the `jobExecutionId` immediately - poll it with `get_job_execution`, stop it with `stop_job_execution`.
+- **Step-range replays:** `run_job` with `fromStepId` / `toStepId` runs only a slice of the step graph (both inclusive, by step id). For any mid-graph start, pass `seedExecutionId` - it hydrates `ctx` from that prior execution so steps you aren't re-running still have their `ctx.*` values. The job's `output` block only runs when the range covers the last step.
+- **Finding runs:** `list_job_executions` returns paginated summaries with `status` and `trigger` filters - `trigger: "test"` isolates suite runs, `trigger: "api,mcp,cron"` isolates live traffic (the same split as the platform's Development/Production lenses).
+- **Autonomous builds:** watch with `get_build_status`, unblock with `answer_build_question`, take over with `cancel_build`. Don't edit the draft while a build is running - coordinate or cancel first.
 
 ### Teach-by-example: draft vs published
 
@@ -351,7 +388,7 @@ The `definition` you pass to `register_job` (see `register_job`'s `definition` p
 
 ```ts
 {
-  region: "us" | "ca",                       // region awareness — also auto-detected from workspace
+  region: "us" | "ca",                       // region awareness - also auto-detected from workspace
   resource?: { configStoreId?, lockKey? },    // configStoreId = which VM/desktop; lockKey serializes runs
   inputSchema:  JSONSchema,
   outputSchema: JSONSchema,
@@ -363,7 +400,7 @@ The `definition` you pass to `register_job` (see `register_job`'s `definition` p
 }
 ```
 
-**`ctx` is the data through-line** between steps — each step's `saveAs` key is what the next step reads:
+**`ctx` is the data through-line** between steps - each step's `saveAs` key is what the next step reads:
 
 - `ctx` starts as `{ input: <the job input> }`.
 - Each step's result is stored at `ctx.<saveAs>` (when `saveAs` is set), so later steps / `when` / `forEach` / `output` can read it.
@@ -374,7 +411,7 @@ Assertions (`add_test_case`) are either `expr` (TS booleans over `{ input, outpu
 
 ### Region & API key
 
-Jobs are **region-aware** (`us` / `ca`) — pass `region` or let it be auto-detected from the workspace. Running a job requires the router's `workspaceApiKey` to be set so a job's workflow steps can call the Laminar API: it's populated by `register_middleware`'s `autoConfigure` (default), or set later with `set_middleware_api_key` (find a key via `list_workspace_api_keys`). `register_middleware` / `set_middleware_api_key` report `workspaceApiKeyConfigured` so you can confirm it stuck.
+Jobs are **region-aware** (`us` / `ca`) - pass `region` or let it be auto-detected from the workspace. Running a job requires the router's `workspaceApiKey` to be set so a job's workflow steps can call the Laminar API: it's populated by `register_middleware`'s `autoConfigure` (default), or set later with `set_middleware_api_key` (find a key via `list_workspace_api_keys`). `register_middleware` / `set_middleware_api_key` report `workspaceApiKeyConfigured` so you can confirm it stuck.
 
 ## Skills System
 
@@ -383,6 +420,7 @@ Skills are reusable RPA patterns that accumulate as you build automations. The M
 
 | Skill                        | Purpose                                                                           |
 | ---------------------------- | --------------------------------------------------------------------------------- |
+| `job-build-loop`             | **Mandatory for job work.** The test-case-first build/debug loop: green-gate first, macroscope (job) → microscope (workflow steps), seeded range replays, stop semantics, publish gates |
 | `rpa-testing-workflow`       | **Mandatory.** Exact tool call sequences for testing through the Minicor executor |
 | `cdp-browser-automation`     | CDP starter template, React-safe setters, parallel execution                      |
 | `desktop-uiautomation`       | Framework selection, element selectors, wait/retry patterns                       |
@@ -407,18 +445,18 @@ Skills are automatically persisted through the Minicor platform API. When authen
 
 Skill tiers:
 
-- **Global** — general RPA knowledge (read-only, bundled with the MCP)
-- **Per-workspace** — learned from agent sessions, persisted across runs
-- **Customer-specific** — app quirks, environment patterns
+- **Global** - general RPA knowledge (read-only, bundled with the MCP)
+- **Per-workspace** - learned from agent sessions, persisted across runs
+- **Customer-specific** - app quirks, environment patterns
 
 Without authentication, skills fall back to the bundled `.md` files in the package.
 
 ## What You Can Automate
 
-- **Web portals** — Chrome via CDP. React/Angular SPAs, anti-bot sites, payor portals, EHR web apps.
-- **Desktop applications** — Windows apps via uiautomation, pywinauto, pyautogui. EMR clients, billing software, legacy systems.
-- **APIs** — Direct HTTP when the agent discovers usable endpoints behind a portal.
-- **Hybrid workflows** — Mix browser, desktop, and API steps in one workflow.
+- **Web portals** - Chrome via CDP. React/Angular SPAs, anti-bot sites, payor portals, EHR web apps.
+- **Desktop applications** - Windows apps via uiautomation, pywinauto, pyautogui. EMR clients, billing software, legacy systems.
+- **APIs** - Direct HTTP when the agent discovers usable endpoints behind a portal.
+- **Hybrid workflows** - Mix browser, desktop, and API steps in one workflow.
 
 ## VM Setup
 
@@ -430,7 +468,7 @@ The easiest path is to let the agent handle everything:
 
 The agent runs: `deploy_vm` → `install_mds_on_vm` → `start_mds_on_vm` → `vm_connect`
 
-Once the VM is provisioned, a secure tunnel is automatically created. The agent connects via the tunnel URL and is ready to build automations. Chrome instances for browser automation are managed automatically by the MDS — no manual setup needed.
+Once the VM is provisioned, a secure tunnel is automatically created. The agent connects via the tunnel URL and is ready to build automations. Chrome instances for browser automation are managed automatically by the MDS - no manual setup needed.
 
 For manual setup, use `get_lds_setup_guide` for step-by-step instructions.
 
@@ -487,25 +525,32 @@ For manual setup, use `get_lds_setup_guide` for step-by-step instructions.
 
 | Tool                  | What it does                                                                                  |
 | --------------------- | -------------------------------------------------------------------------------------------- |
-| `list_middlewares`    | List the routers (middlewares) in a workspace — jobs attach to one of these                   |
+| `resolve_job_state`   | "Where am I in the build loop?" - job state + `nextActions` (the concrete next tool calls)    |
+| `list_middlewares`    | List the routers (middlewares) in a workspace - jobs attach to one of these                   |
 | `register_middleware` | Create a router (middleware) jobs attach to; `autoConfigure` populates its workspace API key  |
-| `register_job`        | Create a job — a middleware route backed by a structured `definition` (step graph)            |
+| `register_job`        | Create a job - a middleware route backed by a structured `definition` (step graph)            |
 | `update_job`          | Update a job's `definition`, path, method, or description; `variant: "draft"` writes the draft |
 | `get_job`             | Get a job (route) incl. its `definition`; omit `routeId` to list all routes on the router     |
-| `run_job`             | Run a job once with an input, poll to completion; `variant: "draft"` runs the draft definition |
+| `run_job`             | Run a job once, poll to completion; `variant: "draft"` runs the draft. Step-range replays via `fromStepId`/`toStepId` + `seedExecutionId`; `waitForResult: false` returns the execution id immediately |
+| `stop_job_execution`  | Cooperative cancel of a queued/running execution (no pause; VM workflows finish on their own) |
+| `list_job_executions` | Paginated execution summaries with `status`/`trigger` filters (test vs live traffic)          |
+| `get_job_execution`   | Fetch one execution's full trace (status, input, output, `ctx`, per-step results)             |
+| `inspect_job_execution` | Deep-drill: job → steps → workflow execution's internal flow-runs, with RPA failure analysis |
 | `teach_job`           | Teach by example: upsert a judge-graded test case from input + prompt; runs the draft if one exists |
 | `publish_job`         | Promote a job's draft definition to published (snapshots a version); live traffic serves it   |
 | `get_build_status`    | Get a job's build runs: status, folded-in test cases, builder summary, open questions         |
 | `answer_build_question` | Answer a `needs_input` question on a build run; the build re-queues when none remain        |
+| `cancel_build`        | Stop a queued/running autonomous build run (flips to `failed`; the draft is left as-is)       |
 | `update_build_run`    | Builder-facing: set a build run's status (`running`/`green`/`failed`/`needs_input`) + summary |
 | `add_test_case`       | Attach a test case to a job: named `input` + `expr` or `judge` assertions (the green-gate)    |
+| `update_test_case`    | Update a test case (tighten assertions, or `enabled: false` to disable without deleting)      |
 | `run_tests`           | Run a job's test suite, poll to completion, return the report; `variant: "draft"` tests the draft |
 | `get_test_report`     | Fetch a test run report by id (totals + per-case results, each linking to its job execution)  |
-| `list_workspace_api_keys` | List a workspace's API keys (id, apiKey, name) — find one for the two tools below          |
+| `list_workspace_api_keys` | List a workspace's API keys (id, apiKey, name) - find one for the two tools below          |
 | `set_middleware_api_key`  | Set a router's `workspaceApiKey` (then re-reads to confirm it stuck)                        |
 
 
-See the **Jobs (RPA orchestration)** section above for the build loop and job/ctx shape. `batch_test_rpa` can also persist each passing input as a real job test case — set `persistAsTestCases` with `routeId` + `middlewareId` + `workspaceId`.
+See the **Jobs (RPA orchestration)** section above for the build loop and job/ctx shape. `batch_test_rpa` can also persist each passing input as a real job test case - set `persistAsTestCases` with `routeId` + `middlewareId` + `workspaceId`.
 
 ### 2FA / OTP
 
@@ -541,7 +586,7 @@ Workflows that encounter 2FA prompts use these tools to auto-resolve OTP challen
 | `update_config_property` / `remove_config_property` | Manage individual properties                        |
 
 
-Scripts reference credentials as `{{config.propertyKey}}` — resolved at runtime by the workflow engine.
+Scripts reference credentials as `{{config.propertyKey}}` - resolved at runtime by the workflow engine.
 
 ### Issues
 
@@ -557,9 +602,9 @@ Scripts reference credentials as `{{config.propertyKey}}` — resolved at runtim
 
 Agents use Issues to persist context across runs with the `[Agent:<name>]` title convention:
 
-- `[Agent:my-bot] Rules` — learned behaviors (e.g., "login page takes 15s to load")
-- `[Agent:my-bot] Context` — persistent state (URLs, credential rotation dates)
-- `[Agent:my-bot] Session 2026-04-09` — run summaries
+- `[Agent:my-bot] Rules` - learned behaviors (e.g., "login page takes 15s to load")
+- `[Agent:my-bot] Context` - persistent state (URLs, credential rotation dates)
+- `[Agent:my-bot] Session 2026-04-09` - run summaries
 
 ### Agents
 
@@ -622,9 +667,9 @@ Agents are autonomous runners that execute tasks on VMs using MCP tools. After b
 
 The `build-rpa-workflow` prompt accepts a `mode` parameter:
 
-- `**poc**` — Quick prototype. Streamlined testing, no state verification or monitoring.
-- `**production**` — Full hardening. State verification, idempotency testing, monitoring agent, context persistence.
-- **Omitted** — The agent asks the user which mode to use.
+- `**poc**` - Quick prototype. Streamlined testing, no state verification or monitoring.
+- `**production**` - Full hardening. State verification, idempotency testing, monitoring agent, context persistence.
+- **Omitted** - The agent asks the user which mode to use.
 
 ## Environment Variables
 
@@ -664,23 +709,23 @@ npm test
 
 ```
 src/
-  index.ts              — CLI MCP entry (stdio transport, token management, disconnect hooks)
-  lib.ts                — Embeddable server factory (in-process, no side effects)
-  bootstrap.ts          — CLI to generate harness configs (CLAUDE.md, .cursor/rules, etc.)
-  config.ts             — User config (~/.minicor/config.json) — workspacesRoot, etc.
-  state.ts              — Shared mutable state (VM connections, active session tracking)
-  skills.ts             — Skill loader, parser, index builder
+  index.ts              - CLI MCP entry (stdio transport, token management, disconnect hooks)
+  lib.ts                - Embeddable server factory (in-process, no side effects)
+  bootstrap.ts          - CLI to generate harness configs (CLAUDE.md, .cursor/rules, etc.)
+  config.ts             - User config (~/.minicor/config.json) - workspacesRoot, etc.
+  state.ts              - Shared mutable state (VM connections, active session tracking)
+  skills.ts             - Skill loader, parser, index builder
   tools/
-    session.ts          — session_start, session_checkpoint, session_end, auto-checkpoint
-    skills.ts           — list_skills, get_skill, save_skill, generate_skill
-    sync-tools.ts       — clone_workspace, init_project, pull/push, set_workspaces_root
-    vm.ts, vm-rpa.ts    — VM and RPA tools
-    core.ts             — Workflows, flows, executions
+    session.ts          - session_start, session_checkpoint, session_end, auto-checkpoint
+    skills.ts           - list_skills, get_skill, save_skill, generate_skill
+    sync-tools.ts       - clone_workspace, init_project, pull/push, set_workspaces_root
+    vm.ts, vm-rpa.ts    - VM and RPA tools
+    core.ts             - Workflows, flows, executions
     ...
   prompts/
-    workspace-session.ts — Workspace session guide prompt
-    build-rpa.ts        — Guided RPA building (POC/production modes)
+    workspace-session.ts - Workspace session guide prompt
+    build-rpa.ts        - Guided RPA building (POC/production modes)
     ...
 skills/
-  general/              — Bundled skill files (shipped with npm package)
+  general/              - Bundled skill files (shipped with npm package)
 ```