Merge pull request #26 from podverse/chore/k8s-alignment

chore: update environment variables and documentation

Author: mitchdowney

.cursor/skills/argocd-gitops-push/SKILL.md

@@ -9,33 +9,36 @@ description: When adding or changing files under infra/k8s/ or sync targets for
 
 When adding or changing files under:
 
-- `infra/k8s/` (local, base, or app-of-apps manifests and referenced resources),
-- Or any path that is part of an Argo CD Application source (e.g. `infra/k8s/local/apps`, `infra/k8s/local/stack`, `infra/k8s/base/stack`, source under base, and files referenced by those via Kustomize),
-- Or **canonical linear migration SQL** under `infra/k8s/base/ops/source/database/linear-migrations/{app,management}/` (versioned chain applied by the linear migration runner),
-- Or **ops** manifests under `infra/k8s/base/ops/` (Kustomize bundles: migration CronJob SQL, scripts mounted into jobs, and related `kustomization.yaml` entries that must stay in sync with on-disk files).
+- **`infra/k8s/base/`** – reusable Kustomize bases per component (referenced by alpha overlays and/or your GitOps repo),
+- **`infra/k8s/alpha/`** – in-repo alpha app-of-apps and child overlays,
+- **`infra/k8s/argocd/`** – optional project manifests committed here,
+- Any path that is part of an **Argo CD Application** source in **your GitOps repository** (paths vary by installation),
+- **Canonical linear migration SQL** under `infra/k8s/base/ops/source/database/linear-migrations/{app,management}/`,
+- **Ops** manifests under `infra/k8s/base/ops/` (migration CronJobs, mounted scripts, `kustomization.yaml` entries).
 
 ## What Argo CD syncs
 
-- The local app points at repo path `infra/k8s/local/apps` (see `infra/k8s/local-application.yaml`), which references `infra/k8s/local/stack` and the base stack.
-- The alpha app-of-apps root points at repo path `infra/k8s/alpha/apps` (see `infra/k8s/alpha-application.yaml`), which references `infra/k8s/alpha/<component>/` overlays.
-- Only the **remote** Git repo at the configured revision (e.g. `develop`) is used; the agent does not push. The user must push for Argo CD to see changes.
+- **Alpha:** Root **`infra/k8s/alpha-application.yaml`** (when applied) points at **`infra/k8s/alpha/apps`**, which references **`infra/k8s/alpha/<component>/`** overlays.
+- **Remote environments:** Application CRs usually live in your **GitOps repo** and reference paths/branches you configure (see [docs/development/k8s/REMOTE-K8S-GITOPS.md](../../../docs/development/k8s/REMOTE-K8S-GITOPS.md)).
+- Only the **remote** Git revision Argo CD tracks is authoritative; the agent does not push.
 
 ## When a push is required
 
-Any change to files under those paths (or to canonical sources that get copied into them) means the cluster will not reflect the change until the user pushes to the branch Argo CD tracks.
+Any change to synced paths (or canonical sources copied into them) is invisible to the cluster until those commits are on the branch Argo CD watches (**often `develop` / `main` on the GitOps repo**).
 
 ## Response requirement
 
-When your file-modifying work touches any of these paths, add a short **Push to Git** note in the response (e.g. before or after the verification block):
+When file-modifying work touches **`infra/k8s/`** or migration SQL under **`infra/k8s/base/ops/`**, add a short **Push to Git** note:
 
-**Push to Git:** This change affects Argo CD–synced manifests. Push to the branch Argo CD tracks (e.g. `develop`) for the cluster to sync.
+**Push to Git:** This change affects Argo CD–synced manifests. Push to the branch Argo CD tracks so the cluster can sync.
 
 ## Version updates (GitOps)
 
-- **Manifest changes** (image tags, env, resources, new deployments): Updating the manifest is the change; push is required for Argo CD (covered by the response reminder above).
-- **npm/package versions:** Follow the existing AGENTS.md Dependencies section; no separate version rule for GitOps.
+- **Manifest changes** (image tags, env, resources): push so Argo CD picks them up.
+- **npm/package versions:** Follow AGENTS.md Dependencies; no separate GitOps-only rule.
 
 ## See also
 
-- [infra/k8s/INFRA-K8S.md](infra/k8s/INFRA-K8S.md) – k8s layout and local app-of-apps.
-- [docs/development/k8s/K3D-ARGOCD-LOCAL.md](docs/development/k8s/K3D-ARGOCD-LOCAL.md) – Local k3d + Argo CD setup.
+- [infra/k8s/INFRA-K8S.md](../../../infra/k8s/INFRA-K8S.md) – layout and consumption.
+- [docs/development/k8s/REMOTE-K8S-GITOPS.md](../../../docs/development/k8s/REMOTE-K8S-GITOPS.md) – remote cluster workflow.
+- [docs/development/k8s/K3D-ARGOCD-LOCAL.md](../../../docs/development/k8s/K3D-ARGOCD-LOCAL.md) – stub (local k3d removed).

.cursor/skills/linear-db-migrations/SKILL.md

@@ -9,25 +9,25 @@ version: 1.0.0
 ## When to use
 
 - Adding or changing files under `infra/k8s/base/db/source/`, `infra/k8s/base/ops/`, or `scripts/database/`.
-- Wiring DB credentials in Compose, k3d, or K8s manifests, or in env templates/examples.
+- Wiring DB credentials in Compose, Kubernetes manifests, or env templates/examples.
 
 ## Single source of truth
 
 - **Canonical forward-only SQL:** `infra/k8s/base/ops/source/database/linear-migrations/app/` and `infra/k8s/base/ops/source/database/linear-migrations/management/` (ordered `0001_*.sql`, ...).
-- **Bootstrap init (`docker-entrypoint-initdb.d`):** `infra/k8s/base/db/source/bootstrap/` — shell steps **`0001`** / **`0002`**, generated **`0003_linear_baseline.sql.gz`** and **`0004_seed_linear_migration_history.sql`**, then **`0006_management_grants.sh`**.
+- **Bootstrap init (`docker-entrypoint-initdb.d`):** `infra/k8s/base/db/source/bootstrap/` — shell steps **`0001`** / **`0002`**, then **`0003_apply_linear_baselines.sh`** with generated **`0003a_app_linear_baseline.sql.gz`** / **`0003b_management_linear_baseline.sql.gz`**.
 - **Generated bootstrap artifacts:**
-  - `infra/k8s/base/db/source/bootstrap/0003_linear_baseline.sql.gz`
-  - `infra/k8s/base/db/source/bootstrap/0004_seed_linear_migration_history.sql`
+  - `infra/k8s/base/db/source/bootstrap/0003a_app_linear_baseline.sql.gz`
+  - `infra/k8s/base/db/source/bootstrap/0003b_management_linear_baseline.sql.gz`
   - Generated by scripts under `scripts/database/`; do not hand-edit.
 
 ## Runner and validation
 
 - Apply migrations: `bash scripts/database/run-linear-migrations.sh --database app|management` (always pass `--database`; there is no default).
-- K8s wrapper: `bash scripts/database/run-linear-migrations-k8s.sh` (same requirement).
+- **Credentials:** **app** migrations use `DB_APP_MIGRATOR_USER`, `DB_APP_MIGRATOR_PASSWORD`, `DB_APP_NAME`, `DB_HOST`, and `DB_PORT`. **Management** migrations use `DB_MANAGEMENT_MIGRATOR_USER`, `DB_MANAGEMENT_MIGRATOR_PASSWORD`, `DB_MANAGEMENT_NAME`, `DB_HOST`, and `DB_PORT`. Optional: `infra/config/local/db.env` when keys are unset before sourcing.
+- K8s wrapper: `bash scripts/database/run-linear-migrations-k8s.sh` (`--database` required); validates the same keys from Secrets.
 - Validate: `bash scripts/database/validate-linear-migrations.sh` (and `--check-db` to compare on-disk checksums to `linear_migration_history` when a DB is available).
 - Regenerate baseline artifacts:
   - `bash scripts/database/generate-linear-baseline.sh`
-  - `bash scripts/database/generate-linear-migration-history-seed.sh`
 - Verify generated artifacts are committed and up to date:
   - `bash scripts/database/verify-linear-baseline.sh`
 - The migration runner **creates** the `linear_migration_history` table if missing; do not rely on a dedicated SQL file for that.
@@ -39,13 +39,13 @@ version: 1.0.0
 
 ## Environment keys (admin vs image)
 
-- **Authoritative in secrets and generated env:** `DB_APP_ADMIN_USER` / `DB_APP_ADMIN_PASSWORD`, `DB_MANAGEMENT_ADMIN_USER` / `DB_MANAGEMENT_ADMIN_PASSWORD`, plus read-only and read-write keys and `DB_APP_NAME` / `DB_MANAGEMENT_NAME` (see `infra/config/env-templates/db.env.example` and local `infra/config/local/db.env` after `scripts/local-env/setup.sh`).
-- The **postgres** container image still reads `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` at runtime—**map** those from the `DB_*_ADMIN_*` and `DB_APP_NAME` keys in Compose or Deployment `env`, not the reverse.
+- **Authoritative in secrets and generated env:** owner keys (`DB_APP_OWNER_*`, `DB_MANAGEMENT_OWNER_*`) for bootstrap, migrator keys (`DB_APP_MIGRATOR_*`, `DB_MANAGEMENT_MIGRATOR_*`) for linear migrations, plus read-write and read keys and `DB_APP_NAME` / `DB_MANAGEMENT_NAME` (see `infra/config/env-templates/db.env.example` and local `infra/config/local/db.env` after `scripts/local-env/setup.sh`).
+- The **postgres** container image still reads `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` at runtime—**map** those from `DB_APP_OWNER_USER` / `DB_APP_OWNER_PASSWORD` and `DB_APP_NAME` in Compose or Deployment `env`, not the reverse.
 
 ## Cross-repo invariants
 
 - Canonical forward-only trees under `infra/k8s/base/ops/source/database/linear-migrations/`.
-- Generated bootstrap baseline artifacts `0003` and `0004` are machine-derived and committed.
+- Generated bootstrap baseline artifacts `0003a` and `0003b` are machine-derived and committed.
 - Same npm script naming model in root `package.json` (`db:migrate:linear:*`, `db:validate:linear`, etc.). Product-specific naming differences are expected.
 
 ## Documentation

.cursor/skills/local-docker-env-alignment/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: local-docker-env-alignment
+description: When adding or changing preconditions, cleanup steps, or env usage for local Docker Compose, keep behavior aligned with shared infra/config/local/*.env and documented teardown flows.
+---
+
+# Local Docker Compose env alignment
+
+## When to use
+
+When you:
+
+- Add or change **`make`** targets that touch **`infra/config/local/*.env`** or local containers (`metaboost_local_*`),
+- Add guards to **`local_env_clean`** / **`local_clean`**, or
+- Document local env setup / teardown.
+
+Metaboost does **not** ship an in-repo local Kubernetes (k3d) path; cluster validation is **remote GitOps**.
+
+## Do
+
+- Keep **`local_env_clean`** blocked while **Docker Compose** Metaboost local containers are running (`make local_down` first).
+- Keep **`local_clean`** as full teardown: **`local_down`**, **`local_down_volumes`**, **`test_clean`** (and any other documented test/E2E containers).
+- Document that **`make local_env_setup`** and Compose share **`infra/config/local/*.env`** where applicable.
+
+## Don't
+
+- Reference k3d or `make local_k3d_*` (removed).
+
+## Reference targets
+
+- **`local_env_clean`**: Aborts if `metaboost_local_*` containers are running.
+- **`local_clean`**: Docker + volumes + test stack teardown.

.cursor/skills/local-docker-k3d-alignment/SKILL.md

@@ -12,8 +12,9 @@ version: 1.0.0
 ## Runtime config (sidecar)
 
 - The Next.js app can load runtime config from a sidecar server when `RUNTIME_CONFIG_URL` is set.
-- Sidecar runs on a separate port (e.g. 3001) and serves GET `/runtime-config` with env-derived JSON.
+- Sidecar runs on a separate port (e.g. 4001) and serves GET `/runtime-config` with env-derived JSON.
 - `instrumentation.ts` runs once at server start and fetches config; it is stored in a global/store and used in layout and components.
+- Root layout only calls the sidecar when `RUNTIME_CONFIG_URL` is set; on failure it falls back to `getRuntimeConfig()` (`process.env` in dev). Kubernetes bases put `RUNTIME_CONFIG_URL` in `infra/k8s/base/web/source/web.env` (ConfigMap `metaboost-web-config`), not only as a Deployment literal.
 
 ## Structure
 
@@ -26,3 +27,4 @@ version: 1.0.0
 - `npm run dev` – Next.js dev server
 - `npm run dev:sidecar` – Run sidecar (after building it)
 - From root: `npm run dev:web-sidecar` – Build sidecar then run web with sidecar
+- `npm run validate-env -w @metaboost/web` (and `-w @metaboost/management-web`) – optional pre-build check that `RUNTIME_CONFIG_URL` is a valid http(s) URL (loads `.env.local` / `.env` like Podverse `validate-env`).