feat(workflow): background container services + with: step vocabulary

Container steps now take a single GitHub-Actions-style `with:` params block
selected by `action:` (steps only; container components are unchanged). All
action parameters live under `with:`; only provider/container/runtime_auto_start
stay top-level.

Adds background container services: a `container` step with `background: true`
starts a long-running service detached and the workflow continues. Readiness
reuses the existing container `healthcheck:` via `container.WaitHealthy`
(implicit gate + explicit `wait`/`wait-all`); `cancel` tears it down via
`container.Down`; anything still running is auto-torn-down at workflow end.

- pkg/background: generic Runner/Handle/Registry seam (shell/atmos runner later)
- pkg/workflow: container runner (Up/WaitHealthy/Down) + Start/Wait/WaitAll/Cancel
- pkg/runner/step: wait/wait-all/cancel action-step handlers
- pkg/schema: with:/background:/for: polymorphic decode + background validation
- hooks: decode step `with:` via yaml.v3 so WorkflowStep.UnmarshalYAML fires
- docs + blog + roadmap + JSON schemas + runnable examples/background-steps

PRD: docs/prd/parallel-workflow-steps.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: osterman

docs/prd/parallel-workflow-steps.md

@@ -41,7 +41,7 @@ Plus **per-step output modes** for controlling how command output is displayed.
 1. **Full Gum CLI Parity**: We implement the most useful subset, not every Gum option
 2. **External Process Execution**: Step types are native Go, not shelling out to `gum`
 3. **Custom Themes per Step**: Steps use the global Atmos theme, not per-step theming
-4. **Parallel Step Execution**: Steps execute sequentially (existing behavior)
+4. **Parallel Step Execution**: Out of scope for *this* PRD. Concurrent execution shipped separately via the `parallel`/`matrix` control steps — see [`parallel-workflow-steps.md`](./parallel-workflow-steps.md).
 5. **Conditional Logic**: No if/else branching in workflows (use shell for this)
 
 ## Proposed Configuration

docs/prd/workflow-step-types.md

@@ -0,0 +1,52 @@
+# Background container services
+
+This example shows how to start a long-running container service in the background,
+run work against it, and tear it down — all from a workflow.
+
+A container step with `background: true` starts detached and the workflow continues
+to the next step. Atmos reuses the existing container lifecycle to supervise it:
+
+- **Readiness** reuses the container `healthcheck:` (under `with:`). When a health
+  check is configured, Atmos blocks until the service is **healthy** before the next
+  step (the implicit readiness gate). An explicit `{type: wait, for: [name]}` (or
+  `{type: wait-all}`) does the same on demand.
+- **Teardown** is an explicit `{type: cancel, for: [name]}` step (stop + remove).
+  Anything still running when the workflow ends is **auto-torn-down** — a service
+  never exits on its own, so it is never "waited to exit".
+
+> Requires a container runtime (Docker or Podman).
+
+## Run it
+
+```shell
+cd examples/background-steps
+
+# Start nginx in the background, wait until healthy, use it, then cancel it.
+atmos workflow service -f background
+
+# Start redis + nginx in the background, wait-all, then tear both down.
+atmos workflow fanout -f background
+```
+
+## How it maps to the syntax
+
+```yaml
+- name: cache
+  type: container
+  action: run
+  background: true          # start detached, keep going
+  with:                     # all container params live under `with:`
+    image: nginx:alpine
+    healthcheck:            # the readiness gate (reuses the container health check)
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost/ || exit 1"]
+      interval: 2s
+      retries: 10
+- name: use-service
+  type: shell
+  command: ...              # runs only after `cache` is healthy
+- type: cancel
+  for: cache                # graceful teardown
+```
+
+See the [`parallel`](../parallel-steps) example for the complementary *structured*
+concurrency (`parallel`/`matrix`) control steps.

examples/background-steps/README.md

@@ -0,0 +1,7 @@
+base_path: "./"
+
+workflows:
+  base_path: "workflows"
+
+logs:
+  level: Info

examples/background-steps/atmos.yaml

@@ -0,0 +1,71 @@
+workflows:
+  # Start a long-running container service in the background, run work against it,
+  # then tear it down. Readiness reuses the container `healthcheck:` — Atmos blocks
+  # until the service is healthy before the next step runs.
+  service:
+    description: Start a background service, use it, then cancel it.
+    steps:
+      - name: cache
+        type: container
+        action: run
+        background: true
+        with:
+          # A tiny long-running service with a health check. nginx:alpine ships
+          # busybox `wget`, so the check probes the web root.
+          image: nginx:alpine
+          ports:
+            - { host: 8080, container: 80 }
+          healthcheck:
+            test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost/ || exit 1"]
+            interval: 2s
+            timeout: 2s
+            retries: 10
+            start_period: 2s
+
+      # Implicit readiness gate: because `cache` has a health check, this step does
+      # not run until the service reports healthy.
+      - name: use-service
+        type: shell
+        command: 'echo "service is healthy; doing work against http://localhost:8080"'
+
+      # Graceful teardown (stop + remove). Omit this and Atmos auto-tears-down the
+      # service when the workflow ends — a service is never "waited to exit".
+      - type: cancel
+        for: cache
+
+  # Start several background services and gate on all of them with `wait-all`.
+  fanout:
+    description: Start two services in the background, wait for all, then tear down.
+    steps:
+      - name: redis
+        type: container
+        action: run
+        background: true
+        with:
+          image: redis:7-alpine
+          ports: [{ host: 6379, container: 6379 }]
+          healthcheck:
+            test: ["CMD", "redis-cli", "ping"]
+            interval: 2s
+            retries: 10
+
+      - name: web
+        type: container
+        action: run
+        background: true
+        with:
+          image: nginx:alpine
+          ports: [{ host: 8081, container: 80 }]
+          healthcheck:
+            test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost/ || exit 1"]
+            interval: 2s
+            retries: 10
+
+      - type: wait-all
+
+      - name: smoke
+        type: shell
+        command: 'echo "redis and web are both healthy"'
+
+      - type: cancel
+        for: [redis, web]

examples/background-steps/workflows/background.yaml

@@ -52,7 +52,7 @@ commands:
           - name: hello
             type: container
             action: run
-            run:
+            with:
               image: alpine:latest
               command: echo "hello from a custom command container"
 
@@ -62,7 +62,7 @@ commands:
           - name: build
             type: container
             action: build
-            build:
+            with:
               context: .
               dockerfile: Dockerfile
               tags:
@@ -73,13 +73,13 @@ commands:
           - name: inspect
             type: container
             action: inspect
-            inspect:
+            with:
               image: "{{ .steps.build.outputs.image }}"
 
           - name: run
             type: container
             action: run
-            run:
+            with:
               image: "{{ .steps.build.outputs.image }}"
               command: |
                 /usr/local/bin/example
@@ -91,7 +91,7 @@ commands:
           - name: build
             type: container
             action: build
-            build:
+            with:
               context: .
               dockerfile: Dockerfile
               tags:
@@ -102,7 +102,7 @@ commands:
           - name: push
             type: container
             action: push
-            push:
+            with:
               image: "{{ .steps.build.outputs.image }}"
               tags:
                 - localhost:5000/atmos-container-step:local
@@ -113,27 +113,29 @@ commands:
           - name: run
             type: container
             action: run
-            run:
+            with:
               image: "{{ .steps.push.outputs.image }}"
               command: |
                 /usr/local/bin/example
                 uname -a
 
       - name: flat-run
-        description: Run using the backward-compatible flat run shorthand
+        description: Run a single command using the with params block
         steps:
           - name: hello
             type: container
-            image: alpine:latest
-            command: echo "hello from flat run shorthand"
+            action: run
+            with:
+              image: alpine:latest
+              command: echo "hello from with params"
 
       - name: workspace
         description: Show the mounted workspace from a container
         steps:
           - name: workspace
             type: container
             action: run
-            run:
+            with:
               image: alpine:latest
               command: |
                 uname -a
@@ -148,6 +150,6 @@ commands:
             env:
               EXAMPLE_MESSAGE: "hello from env"
             action: run
-            run:
+            with:
               image: alpine:latest
               command: echo "$EXAMPLE_MESSAGE"

examples/container-step/atmos.yaml

@@ -42,7 +42,7 @@ workflows:
       - name: hello
         type: container
         action: run
-        run:
+        with:
           image: alpine:latest
           command: echo "hello from a workflow container"
 
@@ -52,7 +52,7 @@ workflows:
       - name: build
         type: container
         action: build
-        build:
+        with:
           context: .
           dockerfile: Dockerfile
           tags:
@@ -63,7 +63,7 @@ workflows:
       - name: run
         type: container
         action: run
-        run:
+        with:
           image: "{{ .steps.build.outputs.image }}"
           command: |
             /usr/local/bin/example
@@ -75,8 +75,8 @@ workflows:
       - name: build
         type: container
         action: build
-        build:
-          provider: docker
+        provider: docker
+        with:
           engine: buildx
           tags:
             - atmos-container-step:bake
@@ -92,7 +92,7 @@ workflows:
       - name: run
         type: container
         action: run
-        run:
+        with:
           image: "{{ .steps.build.outputs.image }}"
           command: /usr/local/bin/example
 
@@ -102,7 +102,7 @@ workflows:
       - name: build
         type: container
         action: build
-        build:
+        with:
           context: .
           dockerfile: Dockerfile
           tags:
@@ -113,7 +113,7 @@ workflows:
       - name: push
         type: container
         action: push
-        push:
+        with:
           image: "{{ .steps.build.outputs.image }}"
           tags:
             - localhost:5000/atmos-container-step:local
@@ -124,7 +124,7 @@ workflows:
       - name: run
         type: container
         action: run
-        run:
+        with:
           image: "{{ .steps.push.outputs.image }}"
           command: |
             /usr/local/bin/example
@@ -141,7 +141,7 @@ workflows:
         type: container
         action: build
         identity: dev-admin
-        build:
+        with:
           context: .
           dockerfile: Dockerfile
           tags:
@@ -153,7 +153,7 @@ workflows:
         type: container
         action: push
         identity: dev-admin
-        push:
+        with:
           image: "{{ .steps.build.outputs.image }}"
         outputs:
           image: "{{ .metadata.image }}"
@@ -165,7 +165,7 @@ workflows:
       - name: workspace
         type: container
         action: run
-        run:
+        with:
           image: alpine:latest
           command: |
             uname -a
@@ -184,7 +184,7 @@ workflows:
         env:
           STEP_MESSAGE: "hello from step env"
         action: run
-        run:
+        with:
           image: alpine:latest
           command: |
             echo "$WORKFLOW_MESSAGE"
@@ -196,7 +196,7 @@ workflows:
       - name: check
         type: container
         action: run
-        run:
+        with:
           image: alpine:latest
           command: |
             echo "simulated check failed" >&2
@@ -210,6 +210,6 @@ workflows:
         tty: true
         interactive: true
         action: run
-        run:
+        with:
           image: alpine:latest
           command: /bin/sh