feat(local): add Cluster and Environment GitOps workflow

README.md

@@ -81,21 +81,71 @@ hops validate --help
 hops xr --help
 ```
 
-## Local workbench (happy path)
+## Local workbench definition
 
-Multi-workspace local GitOps on the laptop control plane:
+Keep the Kubernetes-shaped local workbench definitions together under
+`.gitops/local/`. The Cluster owns the local control plane and shared
+`.gitops/local/cluster/` manifests. The reusable Environment names the deploys
+that make up the current checkout's environment.
+
+```yaml
+apiVersion: hops.local/v1alpha1
+kind: Cluster
+metadata:
+  name: project-dev
+spec:
+  clusterProvider: kind
+  dockerProvider: dory
+  mountRoot: ../..
+  manifests:
+    path: .gitops/local/cluster
+```
+
+```yaml
+apiVersion: hops.local/v1alpha1
+kind: Environment
+metadata:
+  name: local
+spec:
+  clusterRef:
+    name: project-dev
+  root: .
+  values:
+    local: true
+    preview: false
+  deploys:
+    - path: apps/gateway
+```
+
+From that project root:
 
 ```bash
-# shared control-plane tree (terminal 1)
-hops local gitops cluster ./gitops/cluster \
-  --cluster-provider kind --docker-provider dory --cluster-name hops
+hops local up
+hops local gitops cluster ./.gitops/local/cluster
+hops local gitops environment ./.gitops/local/environment.yaml --name main
+```
+
+From another checkout of the same project:
 
-# per-workspace tree (terminal 2)
-hops local gitops worktree ./gitops/envs/local --name alice \
-  --cluster-provider kind --docker-provider dory --cluster-name hops
+```bash
+hops local gitops environment ./.gitops/local/environment.yaml --name feature-auth
 ```
 
-Use `--name` for concurrent worktrees (`<name>` namespaces). Full guide: [skills/claude/references/local-workbench.md](skills/claude/references/local-workbench.md).
+`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/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.
+
+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`
+during migration.
 
 ## Command Areas
 
@@ -291,7 +341,7 @@ export DOCKER_HOST=unix://$HOME/.dory/dory.sock
 ```bash
 hops local start --cluster-provider dory --docker-provider dory
 hops local start --cluster-provider dory --docker-provider dory --dory-name mine
-hops local gitops worktree ./gitops/envs/local --name alice
+hops local gitops environment ./.gitops/local/environment.yaml --name alice
 
 kubectl get nodes          # context hops-dory
 docker info                # context hops-dory

skills/claude/SKILL.md

@@ -17,7 +17,7 @@ control planes, configuration packages, providers, secrets, and live infrastruct
 
 | Command area | Purpose |
 |-------------|---------|
-| `hops local` | Local CP (dory/colima/kind), gitops cluster/worktree, workbench |
+| `hops local` | Local CP (dory/colima/kind), gitops Cluster/Environment, workbench |
 | `hops config` | Install Configuration packages (published **or** source + gitops) |
 | `hops provider` | Install/patch Providers (published **or** source + SemVer-safe tags + gitops) |
 | `hops secrets` | SOPS encrypt/decrypt, sync to AWS Secrets Manager or GitHub |
@@ -31,7 +31,7 @@ For detailed reference on each area, see the bundled references:
 
 - **[Local source packages & providers](references/local-source-packages.md)** — **read this** when developing configs/providers on a laptop CP
 - [Config install modes and gitops](references/config-install.md)
-- [Local workbench (gitops cluster / worktree)](references/local-workbench.md)
+- [Local workbench (gitops Cluster / Environment)](references/local-workbench.md)
 - [Local control plane setup](references/local-setup.md)
 - [XR observe → adopt → manage workflow](references/xr-workflow.md)
 - [Secrets management](references/secrets.md)
@@ -55,7 +55,7 @@ hops config install --repo hops-ops/auth-stack --version v1.6.0 \
   --gitops ./gitops/cluster --local
 
 hops local gitops cluster ./gitops/cluster          # watches by default; --once for CI
-hops local gitops worktree ./gitops/envs/local --name dogfood
+hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
 ```
 
 - **`--gitops`** materializes pins under the cluster tree (not one-shot-only kubectl)

skills/claude/references/local-source-packages.md

@@ -140,7 +140,7 @@ Day-to-day:
 
 ```bash
 hops local gitops cluster ./gitops/cluster          # watches by default
-hops local gitops worktree ./gitops/envs/local --name dogfood
+hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
 ```
 
 ## Do / don’t
@@ -161,5 +161,5 @@ hops local gitops worktree ./gitops/envs/local --name dogfood
 ## See also
 
 - [config-install.md](./config-install.md) — flags and mode details  
-- [local-workbench.md](./local-workbench.md) — cluster vs worktree gitops  
+- [local-workbench.md](./local-workbench.md) — Cluster vs Environment gitops
 - [local-setup.md](./local-setup.md) — `hops local start` bootstrap  

skills/claude/references/local-workbench.md

@@ -15,8 +15,8 @@ tree copy). You do not need to learn volume types.
 
 ```bash
 # Dory app running (engine healthy). Product Dory Kubernetes is optional.
-hops local start --cluster-provider kind --docker-provider dory \
-  --cluster-name hops --gitops ./gitops/cluster
+hops local up
+hops local gitops cluster ./.gitops/local/cluster
 ```
 
 Context is typically `kind-hops`. Confirm mounts:
@@ -36,18 +36,17 @@ 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 start --cluster-provider dory --docker-provider dory \
-  --gitops ./gitops/cluster
+hops local up --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/cluster
+hops local gitops cluster ./.gitops/local/cluster
 
-# Per-worktree apps (Application YAMLs → namespace = --name) — watches by default
-hops local gitops worktree ./gitops/envs/local --name dogfood
+# One Environment per checkout (namespace = --name) — watches by default
+hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
 
 # Stop either watcher with Ctrl+C.
 ```
@@ -60,10 +59,10 @@ Use a distinct name per worktree so namespaces and URLs stay isolated:
 
 ```bash
 # Terminal A
-hops local gitops worktree ./gitops/envs/local --name alice
+hops local gitops environment ./.gitops/local/environment.yaml --name alice
 
 # Terminal B
-hops local gitops worktree ./gitops/envs/local --name bob
+hops local gitops environment ./.gitops/local/environment.yaml --name bob
 
 ```
 
@@ -74,24 +73,25 @@ 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 start --cluster-provider kind --docker-provider dory \
-  --cluster-name hops --gitops ./gitops/cluster
-hops local gitops cluster ./gitops/cluster
-hops local gitops worktree ./gitops/envs/local --name dogfood
+hops local up
+hops local gitops cluster ./.gitops/local/cluster
+hops local gitops environment ./.gitops/local/environment.yaml --name dogfood
 ```
 
-Charts live under `api/.gitops/deploy` and `ui/.gitops/deploy`. You can also render them without hops:
+Editable charts live under `api/.gitops/local` and `ui/.gitops/local`;
+`.gitops/deploy` is reserved for independent cloud charts. You can render the
+local charts without Hops:
 
 ```bash
-helm template api ./api/.gitops/deploy --set local=true --set appRuntime=cluster-dev
-helm template ui ./ui/.gitops/deploy --set local=true --set appRuntime=cluster-dev
+helm template api ./api/.gitops/local
+helm template ui ./ui/.gitops/local
 ```
 
 ### Agent rules (do not skip)
 
-Dogfood apps run as **`appRuntime: cluster-dev`** in namespace `= --name` with
-source delivery into the pods. The site you must fix is **that** stack — not a
-host `make run` you invent.
+Dogfood apps run from their **`.gitops/local` charts** in namespace `= --name`
+with source delivery into the pods. The site you must fix is **that** stack —
+not a host `make run` you invent.
 
 **When the dogfood site is broken:**
 
@@ -134,11 +134,11 @@ host `make run` you invent.
 ```text
 gitops/
   cluster/          # shared CP (one per machine) — hops local gitops cluster
-  envs/local/       # app Applications — hops local gitops worktree
+  .gitops/local/environment.yaml # reusable Environment definition
 ```
 
 - **cluster** — not per-worktree; packages + platform XRs on the local CP
-- **worktree** — env Application YAMLs into namespace `= --name`
+- **environment** — promoted local applications into namespace `= --name`
 
 ## Developing configs & providers on this CP
 

src/commands/local/aws.rs

@@ -56,7 +56,7 @@ pub struct AwsArgs {
     pub refresh: bool,
 
     /// Write non-secret Provider / DeploymentRuntimeConfig / ProviderConfig YAML
-    /// under this directory (e.g. `./gitops/cluster`). Credential Secrets are
+    /// under this directory (e.g. `./.gitops/local/cluster`). Credential Secrets are
     /// **not** written — still applied live only.
     #[arg(long)]
     pub gitops: Option<PathBuf>,