simpler check and deps messages

rig/docs/notes/env.md

@@ -0,0 +1,74 @@
+# ctrl/.env.example, ctrl/env.d/*.env.example
+
+## ctrl/.env.example: header
+
+Machine-local config. Copy to ctrl/.env (gitignored) and edit. The cluster SHAPE is an optional profile in ctrl/env.d/ — see the *.env.example there. The architecture MODEL lives in arch/<name>.json — not in .env either.
+
+## ctrl/.env.example: CLUSTER
+
+The kubectl context becomes kind-<CLUSTER>. LEAVE THIS UNSET unless you need a name that differs from the directory — it defaults to this folder's name, which is what makes the folder copyable: copy it, rename it, and you get a separate environment with no edits.
+
+## ctrl/.env.example: host ports
+
+LEAVE UNSET — they derive from the directory name so several environments coexist without negotiating (see ctrl/ports.sh). `make check` shows this environment's block; `bash ctrl/ports.sh persist` writes it into ctrl/.env so it stops being derived and becomes fixed. Set a value only to override.
+
+## ctrl/.env.example: MANIFESTS_DIR
+
+Where the application manifests live. The real ones are expected to be versioned separately from this installer — they change on a different cadence, by different people. Repoint this at their repo and rig stops owning them:
+
+    MANIFESTS_DIR=../platform-manifests/overlays/dev
+
+## ctrl/.env.example: DEPS_SOURCE
+
+Where the installer fetches the pinned binaries from.
+
+- `upstream` — GitHub releases / dl.k8s.io (needs internet)
+- `artifactory` — a generic repo; what a locked-down client usually allows
+- `baked` — already inside the installer image; no network at all
+
+## ctrl/.env.example: registry secrets
+
+The registry mode comes from the profile (REGISTRY_MODE). REGISTRY_REMOTE_URL, REGISTRY_USER and REGISTRY_PASSWORD are the secrets it needs, required for mirror/remote.
+
+## ctrl/.env.example: REGISTRY_CA_FILE
+
+Corporate root CA, if Artifactory is fronted by an internal CA (it usually is). Trust has to reach THREE places and nothing does it for you: the host docker daemon, every kind node's containerd, and any in-cluster client. registry.sh handles the first two; check.sh reports when it's configured but not trusted. Symptom when missing: `x509: certificate signed by unknown authority`.
+
+## env.d/*.env.example: profiles in general
+
+EXAMPLE PROFILES. rig needs none of these: with no profile it runs on its built-in defaults (lib/config.sh). To use one, copy it to <name>.env in ctrl/env.d/ and name it — PROFILE=<name> in ctrl/.env, or on the command line. It then overlays the defaults; anything it does not set, they still supply.
+
+## env.d/client.env.example
+
+client — images through a pull-through cache of the corporate registry, with TLS and metrics addons. More nodes or port mappings: edit k8s/kind-config.yaml.tpl.
+
+### Real ports (80/443)
+
+Ports derive from the directory name by default (see ctrl/ports.sh), so several environments run side by side.
+
+Opt in to the real ports only when this is the ONLY environment and nothing else owns :80. They fail to bind otherwise, and docker reports it as an opaque "failed to bind host port 0.0.0.0:80/tcp: address already in use" halfway through cluster creation. `make check` checks before you spend the time. Uncommenting also means only one environment can exist at a time.
+
+## env.d/data.env.example
+
+data — databases and a scheduler for an environment that needs them: postgres, redis and airflow, each an upstream image run unmodified.
+
+Everything lands in the `data` namespace (DATA_NAMESPACE to move it), so `make cluster reset` on the app namespace leaves the databases alone.
+
+Costs roughly 2-3 GB with airflow, under 1 without. Airflow's first boot runs the whole metadata migration, so expect a few minutes before it is ready.
+
+### Postgres password
+
+The password is not in the profile: postgres.sh generates one on first install and keeps it across re-runs, so re-running the addon never rotates the credential out from under whatever is already connected.
+
+### Reaching the databases
+
+Ports derive from the directory name by default — see ctrl/ports.sh. Reach the databases with port-forward rather than binding more host ports:
+
+    kubectl -n data port-forward svc/postgres 5432:5432
+    kubectl -n data port-forward svc/airflow 8080:8080
+
+## env.d/offline.env.example
+
+offline — air-gapped. Everything comes from a local registry that was loaded ahead of time; nothing reaches the internet. Pair with the deps-full image (DEPS_SOURCE=baked) so the toolchain install is offline too.
+
+The heavier addons are left out to keep first boot viable.