add tasks for run-to-completion work

.dockerignore

@@ -1,6 +1,5 @@
 .git
 .github
-.cursor
 .direnv
 .envrc
 .env*

.golangci.yaml

@@ -355,3 +355,8 @@ issues:
 run:
   # Timeout for total work
   timeout: 5m
+  # Without these, every //go:build e2e and //go:build integration file is
+  # invisible to the linter, so the e2e and scenario suites go unchecked.
+  build-tags:
+    - e2e
+    - integration

README.md

@@ -88,18 +88,16 @@ For how Deployah compares to DevSpace, Werf, Score, Epinio, and Kubero, see
 
 Know these before you invest time:
 
-- **`env` is not applied yet.** The `env` field on a component passes schema
-  validation but does not reach the running container. Put runtime values in
-  your image or your app's own config for now. See
+- **`env` is not applied to Deployments yet.** The `env` field on a component
+  passes schema validation but does not reach the running container. Task
+  `env` is inlined onto Jobs. See
   [Two kinds of variables](docs/configuration.md#two-kinds-of-variables).
-- **`role: job` is not deployable yet.** It exists in the schema; only
-  `service` and `worker` deploy today.
 - **Deployah does not build images.** Give it an image that already exists in a
   registry your cluster can pull from.
 - **Stateful with persistence needs Kubernetes 1.32 or newer.** Deployah checks
   the API version and fails fast on older clusters. Identity-only stateful
   components have no such floor.
-- **The schemas are alpha.** App manifests are at `v1-alpha.4` and platform
+- **The schemas are alpha.** App manifests are at `v1-alpha.5` and platform
   files at `platform/v1-alpha.3`; expect breaking changes between releases.
 
 ## Contents
@@ -193,7 +191,7 @@ Save this as `deployah.yaml` in an empty folder. It runs the public `nginx`
 image, so you do not need to build anything.
 
 ```yaml
-apiVersion: v1-alpha.4
+apiVersion: v1-alpha.5
 project: my-first-app
 components:
   web:
@@ -335,15 +333,16 @@ A few words you will see often.
 - **Role.** What a component is for:
   - `service`: it serves traffic and can be exposed (the default).
   - `worker`: a long-running background task, not exposed.
-  - `job`: a one-off task that runs and then stops.
+- **Task.** Run-to-completion work (`preDeploy`, `postDeploy`, or `manual`).
+  See [Tasks](docs/tasks.md).
 - **Kind.** The component's `kind` field: `stateless` (the default, easy to
   scale) or `stateful` (StatefulSet with stable identity; optional per-pod
   volumes). This field has nothing to do with Kind, the tool that runs the
   optional local cluster. See
   [Stateful workloads](docs/workloads.md#stateful-workloads) and
   [Storage classes](docs/platform.md#storage-classes).
-- **Workload matrix.** `role` and `kind` combine independently. `job` is in
-  the schema but not deployable yet.
+- **Workload matrix.** `role` and `kind` combine independently. Run-to-completion
+  work is `tasks:`, not a component role.
 
   | Capability          | service+stateless | service+stateful | worker+stateless | worker+stateful |
   |---------------------|:-----------------:|:----------------:|:----------------:|:---------------:|
@@ -396,6 +395,7 @@ The README covers the shape of the tool. The details live in `docs/`:
 | [Spec reference](docs/spec-reference.md) | Every `deployah.yaml` field, value rules, resource presets, and full examples. |
 | [Platform file](docs/platform.md) | Contexts, domains, TLS modes, storage classes, and profiles. |
 | [Workloads](docs/workloads.md) | Stateful components and volumes, workers, health checks, metrics. |
+| [Tasks](docs/tasks.md) | Migrations, smoke checks, `deployah run`, and fanout. |
 | [Configuration](docs/configuration.md) | Environment selection, variables, `.env` files, precedence rules. |
 | [Networking](docs/networking.md) | Reaching your app, and how the local cluster resolves hostnames. |
 | [Custom manifests and CRDs](docs/custom-manifests-and-crds.md) | Ship plain Kubernetes YAML alongside the release. |
@@ -437,6 +437,7 @@ These work with every command:
 | `deployah resolve --environments` | List every environment from both files: where it is registered, its context (or the kubeconfig fallback), domains, and overrides. |
 | `deployah plan <environment>` | Preview what a deploy would change, without applying anything. Extra manifests from `.deployah/manifests/` appear in the diff; pending CRDs are reported but not applied. Use `--offline` to render with no cluster access, `--raw` for raw Kubernetes field paths instead of the compact Deployah vocabulary, `--yaml` to show changed fields as YAML blocks, `--drift` to also compare against live cluster state, `--detailed-exitcode` to exit 2 when changes are pending, or `--output json` for CI. |
 | `deployah deploy <environment>` | Deploy your project. Shows the plan and asks for confirmation before applying; use `-y`/`--yes` to skip the prompt, `--reapply` to upgrade even with no changes, `--crds` for [CRD install policy](docs/custom-manifests-and-crds.md#crd-policy) (`create` or `create-replace`), `--explain` to print the resolution report first, `--force-hostname-change` to bypass the hostname guard, or `--resize-volumes` to grow [persistence](docs/workloads.md#growing-volumes) sizes. |
+| `deployah run <task> <environment>` | Run a spec task as a one-off Job. Wait is the default; `--detach` returns after create. `--count` / `--parallelism` override fanout for that run. |
 | `deployah status <project>` | Show the status of a deployed project. Use `--detailed` for pod details, `-e` for an environment. |
 | `deployah logs <project>` | Stream logs. Filter with `--component`, `-e`, `--container`, `--since`, `--tail`. Use `--no-follow` for a one-off read. |
 | `deployah shell <project>` | Open a shell in a running container. Choose with `--component` and `--container`. |
@@ -456,9 +457,9 @@ These work with every command:
 
 Deployah validates your spec and platform file with JSON Schema.
 
-- **Manifest schema version:** v1-alpha.4
-- **Manifest schema:** `internal/spec/schema/v1-alpha.4/manifest.json`
-- **Manifest environments schema:** `internal/spec/schema/v1-alpha.4/environments.json`
+- **Manifest schema version:** v1-alpha.5
+- **Manifest schema:** `internal/spec/schema/v1-alpha.5/manifest.json`
+- **Manifest environments schema:** `internal/spec/schema/v1-alpha.5/environments.json`
 - **Platform schema version:** platform/v1-alpha.3
 - **Platform schema:** `internal/spec/schema/platform/v1-alpha.3/platform.json`
 

docs/cli/deployah.md

@@ -20,7 +20,7 @@ deployah [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO
@@ -33,6 +33,7 @@ deployah [flags]
 * [deployah logs](deployah_logs.md)  - View logs for a deployed project
 * [deployah plan](deployah_plan.md)  - Preview the changes a deploy would make
 * [deployah resolve](deployah_resolve.md)  - Show the fully resolved configuration for an environment
+* [deployah run](deployah_run.md)  - Run a spec task as a one-off Job
 * [deployah shell](deployah_shell.md)  - Connect to a shell in a container
 * [deployah status](deployah_status.md)  - Display the status of a project
 * [deployah validate](deployah_validate.md)  - Validate a Deployah spec

docs/cli/deployah_cluster.md

@@ -21,7 +21,7 @@ deployah cluster [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_cluster_down.md

@@ -26,7 +26,7 @@ deployah cluster down [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_cluster_kubeconfig.md

@@ -26,7 +26,7 @@ deployah cluster kubeconfig [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_cluster_status.md

@@ -26,7 +26,7 @@ deployah cluster status [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_cluster_up.md

@@ -34,7 +34,7 @@ deployah cluster up [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_delete.md

@@ -4,7 +4,7 @@ Delete a deployed project in an environment
 
 ### Synopsis
 
-Delete (uninstall) a deployed project in an environment from the Kubernetes cluster.
+Delete (uninstall) a deployed project in an environment from the Kubernetes cluster. Also deletes leftover Jobs labeled for the project and environment, including CLI runs. --dry-run lists those Jobs even when the Helm release is already gone.
 
 ```text
 deployah delete <project> <environment> [flags]
@@ -18,7 +18,7 @@ deployah delete <project> <environment> [flags]
   -o, --output string            Output format for dry-run preview (default "tree")
       --show-resources           Show detailed resources that would be deleted (implies --dry-run)
       --wait                     Wait until all Kubernetes resources are fully deleted before returning (uses stable legacy polling; suitable for CI)
-  -y, --yes                      Skip confirmation prompt and continue even if the release is not found
+  -y, --yes                      Skip confirmation prompt
 ```
 
 ### Options inherited from parent commands
@@ -31,7 +31,7 @@ deployah delete <project> <environment> [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_deploy.md

@@ -31,7 +31,7 @@ deployah deploy <environment> [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_init.md

@@ -32,7 +32,7 @@ deployah init [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_list.md

@@ -28,7 +28,7 @@ deployah list [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_logs.md

@@ -37,7 +37,7 @@ deployah logs <project> [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_plan.md

@@ -32,7 +32,7 @@ deployah plan <environment> [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_resolve.md

@@ -38,7 +38,7 @@ deployah resolve [environment] [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_run.md

@@ -0,0 +1,37 @@
+## deployah run
+
+Run a spec task as a one-off Job
+
+### Synopsis
+
+Create a Kubernetes Job for a task from the spec. Works for preDeploy, postDeploy, and manual tasks. Runs only the named task; tasks listed in its after field are not run. Waits for completion unless --detach is set.
+
+```text
+deployah run <task> <environment> [flags]
+```
+
+### Options
+
+```text
+      --count int         Override fanout count for this run
+      --detach            Return after creating the Job without waiting for completion
+      --parallelism int   Override how many copies may run at once
+  -y, --yes               Run without an interactive confirmation prompt
+```
+
+### Options inherited from parent commands
+
+```text
+      --context string         Kubernetes context to use (overrides the current context and any environment 'context' field)
+  -d, --debug                  Enable debug mode (verbose logging and keep temporary files)
+  -h, --help                   show help for this command
+  -k, --kubeconfig string      Path to the kubeconfig file to use (defaults to standard kubeconfig resolution)
+  -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
+      --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
+  -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
+```
+
+### SEE ALSO
+
+* [deployah](deployah.md)  - Deployah turns a spec into a running release on Kubernetes (Spec-to-Release)

docs/cli/deployah_shell.md

@@ -31,7 +31,7 @@ deployah shell <project> [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO

docs/cli/deployah_status.md

@@ -28,7 +28,7 @@ deployah status <project> [flags]
   -n, --namespace string       Kubernetes namespace to use for Deployah operations (defaults to current context namespace)
       --platform-file string   Path to the platform config file (overrides DEPLOYAH_PLATFORM_FILE and the default same-directory lookup)
   -s, --spec string            Path to the Deployah spec file (YAML or JSON) (default "deployah.yaml")
-  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete) (default 10m0s)
+  -t, --timeout duration       Timeout for Deployah operations (install/upgrade, list, status, logs, delete, run) (default 10m0s)
 ```
 
 ### SEE ALSO