fix(local)!: align GitOps lifecycle and runtime resilience

README.md

@@ -120,8 +120,7 @@ spec:
 From that project root:
 
 ```bash
-hops local up
-hops local gitops cluster ./.gitops/local/cluster
+hops local gitops cluster ./.gitops/local/cluster.yaml
 hops local gitops environment ./.gitops/local/environment.yaml --name main
 ```
 
@@ -131,17 +130,27 @@ From another checkout of the same project:
 hops local gitops environment ./.gitops/local/environment.yaml --name feature-auth
 ```
 
-`up` validates the Cluster before starting or reusing it. `gitops cluster`
-watches shared `.gitops/local/cluster` manifests. `environment` validates the
-Environment against that Cluster, renders each deploy's `.gitops/promote`
-chart, applies the resulting local Applications to the runtime namespace, and
-watches `.gitops/local/environment.yaml` plus the referenced
-`.gitops/promote` and `.gitops/local` charts. Each application's
+`gitops cluster` validates the Cluster, starts or resumes it, bootstraps the
+local control plane, and watches the declared shared manifests.
+`environment` validates the Environment against that Cluster, turns each
+deploy's `.gitops/local` chart (or explicit `deploys[].chart`) into a local
+Application, applies it to the runtime namespace, and watches
+`.gitops/local/environment.yaml` plus those chart roots. Each application's
 `.gitops/local` chart owns its editable local workload; `.gitops/deploy` is a
 separate cloud workload chart selected by promotion outside local mode.
 The runtime name, namespace, checkout path, and Cluster binding are local state;
 they are not committed to the Cluster definition.
 
+Use the same commands for teardown:
+
+```bash
+hops local gitops environment --name feature-auth --down
+hops local gitops cluster ./.gitops/local/cluster.yaml --down
+```
+
+Deleting a watched Environment definition also purges and unregisters its
+runtime Environment.
+
 An existing kind Cluster with a different exact `mountRoot` fails with an
 explicit reset/recreate instruction and is never silently deleted. A legacy
 directory of pre-rendered Application YAMLs is still accepted by `environment`

bootstrap/registry/registry.yaml

@@ -55,13 +55,20 @@ spec:
               scheme: HTTPS
             initialDelaySeconds: 2
             periodSeconds: 5
+            # A laptop resuming several local control planes can briefly take
+            # seconds to service TLS. Do not turn CPU contention into a
+            # destructive registry restart loop.
+            timeoutSeconds: 15
+            failureThreshold: 6
           livenessProbe:
             httpGet:
               path: /v2/
               port: 5000
               scheme: HTTPS
             initialDelaySeconds: 5
             periodSeconds: 10
+            timeoutSeconds: 15
+            failureThreshold: 6
       volumes:
         - name: registry-data
           persistentVolumeClaim:

skills/claude/references/local-setup.md

@@ -3,18 +3,17 @@
 ## Quick Start
 
 ```bash
-# 1. Start local k8s + Crossplane + providers + registry
-#    (provider selection is user-local: ~/.hops/local/providers.json)
-hops local start --cluster-provider kind --docker-provider dory --cluster-name hops
+# 1. Start/resume the declared cluster and watch shared GitOps manifests
+hops local gitops cluster ./.gitops/local/cluster.yaml
 
-# 2. Install platform packages into the CP *and* pin them in cluster gitops
+# 2. Add or update platform packages in .gitops/local/cluster when needed
 hops config install --repo hops-ops/psql-stack --version v0.9.1 \
-  --gitops ./gitops/cluster --local
+  --gitops ./.gitops/local/cluster --local
 hops config install --repo hops-ops/auth-stack --version v1.6.0 \
-  --gitops ./gitops/cluster --local
+  --gitops ./.gitops/local/cluster --local
 
-# 3. Watch/apply cluster gitops (packages + XRs). Or pass --gitops on start.
-hops local gitops cluster ./gitops/cluster
+# 3. Register this checkout as an Environment
+hops local gitops environment ./.gitops/local/environment.yaml --name main
 
 # 4. Optional cloud provider auth (writes live Secrets; use --gitops for non-secret YAML)
 hops local aws --profile hops
@@ -31,7 +30,13 @@ to `default` (scaffolded by `config install --gitops --local`). See
 ### `hops local install`
 Installs Colima via Homebrew.
 
-### `hops local start`
+### `hops local gitops cluster <cluster.yaml>`
+
+This is the normal lifecycle command. It validates the Kubernetes-shaped
+Cluster definition, invokes the local start/bootstrap pipeline, and applies +
+watches the definition's `spec.manifests.path`.
+
+The underlying `hops local start` command:
 - Starts the chosen backend (colima / kind / dory)
 - Installs **pinned** Crossplane Helm chart (`CROSSPLANE_CHART_VERSION` in `start.rs`)
 - Applies bootstrap Providers (pinned tags in `bootstrap/providers/`):
@@ -40,13 +45,9 @@ Installs Colima via Homebrew.
 - Applies ProviderConfigs named `default`, local registry, DRCs
 - Configures node trust for the in-cluster registry
 
-With **`--gitops PATH`** (e.g. `./gitops/cluster`):
-1. Writes the same helm/k8s bootstrap into the tree (`providers/`, `providerconfigs/`, `runtime/`)
-2. Runs `hops local gitops cluster PATH` (apply + watch) so day-to-day CP state is gitops-owned
-
 ```bash
-hops local start --cluster-provider kind --docker-provider dory \
-  --cluster-name hops --gitops ./gitops/cluster
+hops local gitops cluster ./.gitops/local/cluster.yaml
+hops local gitops cluster ./.gitops/local/cluster.yaml --down
 ```
 
 **Version bumps:** Renovate owns these pins (`cli/renovate.json` customManagers →
@@ -62,8 +63,11 @@ hops provider install --path /path/to/provider-helm --gitops ./gitops/cluster
 
 See [local-source-packages.md](./local-source-packages.md).
 
-### `hops local stop` / `hops local destroy` / `hops local uninstall`
-Stop, delete, or uninstall Colima respectively.
+### Cluster teardown
+
+`hops local gitops cluster <cluster.yaml> --down` stops the declared Cluster
+while preserving its data. `hops local destroy` remains the explicit,
+destructive cluster deletion command; `hops local uninstall` removes tooling.
 
 ### `hops local aws --profile <PROFILE>`
 

skills/claude/references/local-workbench.md

@@ -15,8 +15,7 @@ tree copy). You do not need to learn volume types.
 
 ```bash
 # Dory app running (engine healthy). Product Dory Kubernetes is optional.
-hops local up
-hops local gitops cluster ./.gitops/local/cluster
+hops local gitops cluster ./.gitops/local/cluster.yaml
 ```
 
 Context is typically `kind-hops`. Confirm mounts:
@@ -36,14 +35,15 @@ Stock Dory k8s (`--cluster-provider dory --docker-provider dory`) is fine for pl
 **cannot** hostPath-mount Mac paths into the node; delivery falls back to sync.
 
 ```bash
-hops local up --cluster-provider dory --docker-provider dory
+hops local gitops cluster ./.gitops/local/cluster.yaml \
+  --cluster-provider dory --docker-provider dory
 ```
 
 ## Daily loop
 
 ```bash
-# Shared CP watch (if start did not use --gitops, or after Ctrl+C)
-hops local gitops cluster ./.gitops/local/cluster
+# Start/resume the Cluster and watch its shared control-plane manifests
+hops local gitops cluster ./.gitops/local/cluster.yaml
 
 # One Environment per checkout (namespace = --name) — watches by default
 hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
@@ -52,6 +52,9 @@ hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
 ```
 
 Watch is the default for both gitops commands. Use `--once` for a single reconcile (CI/scripts).
+Use `environment --name <name> --down` to purge one Environment and
+`cluster <cluster.yaml> --down` to stop the control plane while preserving its
+named node volume.
 
 ## Concurrent worktrees
 
@@ -73,8 +76,7 @@ Each name maps to namespace `<name>`.
 ```bash
 cd distributed/tests/e2e-ui
 # Prefer kind-on-Dory for hostPath HMR (see One-time prerequisite)
-hops local up
-hops local gitops cluster ./.gitops/local/cluster
+hops local gitops cluster ./.gitops/local/cluster.yaml
 hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
 ```