switch plan command to semantic planner

README.md

@@ -275,23 +275,26 @@ The spec is a smaller surface than the Kubernetes API on purpose, so step 2 adds
 fields you did not write. You can read the result before anything is applied:
 
 ```sh
-deployah plan <environment> --raw --yaml
+deployah plan <environment>
 ```
 
-`deployah plan` renders the chart and compares it with the release on your
-cluster, so it needs cluster access. `--raw` prints raw Kubernetes field paths
-instead of the compact Deployah vocabulary, and `--yaml` shows changed fields
-as YAML blocks. For the resolved hostname, TLS mode, context, and runtime
-environment without a cluster, use `deployah resolve <environment>`
-(`--output json` for machine-readable output).
+`deployah plan` renders the chart and compares it with the previous release
+baseline selected by Helm, so it needs cluster access. Human output shows
+resource changes as YAML, hook tasks, and a Chart CRDs section for Helm's
+chart-CRD lifecycle. For an existing release it also compares that baseline
+with live cluster state (drift). Secret values stay hidden unless you pass
+`--show-secrets`, which reveals them in human output and in JSON. Use
+`-o json` for machine-readable output. For the resolved hostname, TLS mode,
+context, and runtime environment without a cluster, use
+`deployah resolve <environment>` (`--output json` for machine-readable output).
 
 For how Deployah compares to similar tools (DevSpace, Werf, Score, Epinio,
 Kubero), see [docs/comparison.md](docs/comparison.md).
 
 ## What Deployah decides for you
 
 These are the defaults step 2 fills in. Most are overridable.
-`deployah plan --raw` shows the rendered resources; `deployah resolve` shows
+`deployah plan` shows the rendered resources; `deployah resolve` shows
 hostname, TLS, and resolved runtime environment.
 
 | Decision | Default | Set it with |
@@ -423,7 +426,7 @@ These work with every command:
 | `deployah validate <environment>` | Also load the platform file and check the resolved configuration for that environment. |
 | `deployah resolve <environment>` | Preview the fully resolved hostname, TLS mode, context, and runtime environment, offline. Prints FileValues and ExplicitValues; do not treat the output as secret-safe CI output. Use `--output json` for machine-readable output. |
 | `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>` | Inspect changes for an environment, without applying anything. It needs cluster access. Extra manifests from `.deployah/manifests/` appear in the diff; CRD files from `.deployah/crds/` are listed with Helm's install-only lifecycle, not applied. Use `--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 plan <environment>` | Inspect changes for an environment, without applying anything. It needs cluster access. It compares the chart with the previous release baseline selected by Helm. Extra manifests from `.deployah/manifests/` appear as resource changes. CRD files from `.deployah/crds/` appear in a Chart CRDs section with Helm's lifecycle, not as resource changes. For an existing release, drift against live cluster state is included. `--detailed-exitcode` exits 2 when the plan has effects and 0 when it does not (drift alone exits 0). `--show-secrets` reveals Secret values in human or JSON output. `-o json` writes JSON for CI. |
 | `deployah deploy <environment>` | Deploy your project. Deployah validates the spec, runs deploy guards, then always runs a Helm install for a new release or a Helm upgrade for an existing one. Use `--skip-crds` to skip installing [chart CRDs](docs/custom-manifests-and-crds.md#helm-crd-lifecycle) on a fresh Helm install (a CRD added after that first install is not installed by a later deploy), `--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. |

docs/cli/deployah_plan.md

@@ -4,7 +4,7 @@ Inspect changes for an environment
 
 ### Synopsis
 
-Render the chart for an environment and compare it with the last successful Helm release. With --drift, also compare the rendered manifests with live cluster state. Plan is read-only and never applies anything.
+Render the chart for an environment and compare it with the previous release baseline selected by Helm. For an existing release, also compare that baseline with live cluster state. Plan is read-only and never applies anything.
 
 ```text
 deployah plan <environment> [flags]
@@ -13,12 +13,9 @@ deployah plan <environment> [flags]
 ### Options
 
 ```text
-      --detailed-exitcode   Exit 2 when the plan has pending changes, 0 when it does not, 1 on error (for CI)
-      --drift               Detect drift between the rendered manifests and the live cluster state
-      --output string       Output format (default "text")
-      --raw                 Show raw Kubernetes field paths instead of the compact Deployah vocabulary
-      --show-secrets        Reveal masked secret values in text output (requires an interactive terminal; refused with --output json)
-      --yaml                Show changed fields as YAML blocks instead of a single line
+      --detailed-exitcode   Exit 2 when the plan has effects (resource changes, tasks that change or run, chart CRDs Helm will process), 0 when it has none, 1 on error; drift alone exits 0
+  -o, --output string       Output format: human or json (default "human")
+      --show-secrets        Reveal Kubernetes Secret data and stringData values in the selected output format (human or json); values are redacted by default
 ```
 
 ### Options inherited from parent commands

docs/custom-manifests-and-crds.md

@@ -138,12 +138,15 @@ later.
 
 ## Plan vs deploy
 
-- `deployah plan` includes extra manifests in the rendered diff. It does
-  not apply CRDs. Chart CRDs appear as lifecycle entries with `kind` and
-  `metadata.name`. On a fresh install the plan shows each CRD document
-  Helm will process. It does not claim Kubernetes will create versus
-  apply the object. On upgrade, CRDs are listed as present in the chart
-  but not processed.
+- `deployah plan` includes extra manifests as resource changes. It does
+  not apply CRDs. Chart CRDs appear in their own "Chart CRDs" section,
+  and in JSON under `chartCRDs`, with lifecycle `process` on a fresh
+  install or `upgrade` when Helm will not process them. The section does
+  not use resource actions (`+`, `~`, `-`). A chart CRD that Helm will
+  process counts as a pending effect for `--detailed-exitcode`. On a
+  fresh install the plan shows each CRD document Helm will process. It
+  does not claim Kubernetes will create versus apply the object. On
+  upgrade, CRDs are listed as present in the chart but not processed.
 - `deployah deploy` copies those CRD files into the generated chart, then
   runs Helm. On a fresh install Helm processes `crds/` before ordinary
   resources. On upgrade Helm leaves chart CRDs alone, including CRDs added

docs/tasks.md

@@ -166,7 +166,7 @@ count and cannot exceed 100000 (the Kubernetes Indexed Job limit).
 On a first install, `preDeploy` runs **before** Deployments and Services.
 Anything the task talks to (Postgres, RabbitMQ, another API) must already
 be reachable: another release, a managed service, or a job you ran first.
-`deployah plan` prints this reminder on a fresh install.
+`deployah plan` lists `preDeploy` tasks under Tasks. It does not check whether their dependencies are reachable.
 
 ## Logs
 

docs/troubleshooting.md

@@ -45,8 +45,9 @@ Hook timeout defaults to `5m` and must be less than the `--timeout` used for
 that deploy (default `10m`). Increase `--timeout` so it stays above every hook
 timeout. A spec may set a hook timeout longer than the default `10m`; deploy
 then needs a matching `--timeout`. Deployah does not raise the flag for you.
-Serial hooks can add up to more than `--timeout`; plan shows each hook timeout
-so you can see the budget.
+Serial hooks can add up to more than `--timeout`. Plan shows a new or changed
+hook Job, including its `activeDeadlineSeconds`. It does not list every hook
+timeout.
 
 **A task did not run on deploy.**
 

internal/cmd/deploy/deploy_test.go

@@ -92,6 +92,10 @@ func (s *stubHelmClient) RenderManifests(context.Context, *spec.ResolvedSpec, po
 	return s.renderResult, cleanup, nil
 }
 
+func (s *stubHelmClient) RenderManifestsWithPrep(context.Context, *spec.ResolvedSpec, postrenderer.PostRenderer, []extras.RawFile) (*render.RenderResult, helm.ReleasePrep, func(), error) {
+	panic("unexpected RenderManifestsWithPrep call")
+}
+
 func (s *stubHelmClient) DeleteRelease(context.Context, string, string, bool) error {
 	panic("unexpected DeleteRelease call")
 }

internal/cmd/plan/doc.go

@@ -14,12 +14,6 @@
 
 // Package plan implements the deployah plan command.
 //
-// It renders the chart for an environment and diffs it against the last
-// successful release using [deployah.dev/deployah/internal/plan] as the diff
-// engine. --detailed-exitcode returns
-// [deployah.dev/deployah/internal/plan.ErrChangesPresent] on pending
-// changes, so callers can tell "no changes" from "changes pending" from
-// "error"; see [deployah.dev/deployah/internal/cmd.Execute].
-//
-// Register the command with [Register] on a [nabat.dev/nabat.App] instance.
+// [Register] adds the command to a [nabat.dev/nabat.App]. It writes a
+// semantic plan for the environment and does not apply anything.
 package plan