Scripts

Every helper in the repo, with a 1-line "what" + a "when you'd use it". All paths are relative to the repo root.

Tracked scripts (scripts/)

Script	What it does	When you'd use it
scripts/apps.yaml	Single source of truth for ~20 tracked upstream apps — current versions, download URLs, skip rules.	Read when you want to know "what version of X are we on?". Edit when adding a new app to the auto-update workflow.
scripts/check-updates.py	Queries upstream (Helm repos, GitHub releases) for new versions of everything in apps.yaml and prints what's outdated.	Weekly routine — python3 scripts/check-updates.py tells you what needs bumping.
scripts/do-updates.py	Applies all safe updates (patch bumps, matching skip rules), patches files, commits. Supports --dry-run, --no-commit, specific app names.	After check-updates.py: python3 scripts/do-updates.py --dry-run to preview, then python3 scripts/do-updates.py to apply.
scripts/generate-client-docs.py	Walks manifests_v1/app-constructs/ecommercen-clients/** and generates docs/tenants/*.md + a sidebar JSON.	Before committing changes to any client's manifests — otherwise CI fails with a drift warning. Also runs automatically as part of npm run build in docs-gen/.
scripts/bw-unlock.sh	Unlocks the Bitwarden CLI non-interactively using credentials from a gitignored file. Exports BW_SESSION.	Source it before running anything that reaches into Bitwarden (e.g., ./tf.sh, the autoscaler secret builder).

Untracked operational scripts (untracked/scripts/)

These are in git but their outputs or sensitive config aren't.

Script	What it does	When you'd use it
untracked/scripts/argo.sh	Drop-in replacement for argocd — port-forwards to the in-cluster argocd-server Service, auto-authenticates with the admin secret, cleans up on exit. See the GitOps concepts page for context on why this wrapper exists.	Daily use — it's the zero-friction version of argocd. Use raw argocd only if you've set up argocd login manually and CF Access is OK with your browser session.
untracked/scripts/mariadb-exec.sh	Drops you into a mysql shell against the wecare MariaDB.	When you need to inspect or run SQL against wecare's production database. Read-mostly — write with a review.
untracked/scripts/manifest-counter.sh	Counts K8s resources by kind across the repo.	"How many Ingresses do we have?" sanity checks.
untracked/scripts/find_large_resources.sh	Flags resources that might hit K8s annotation-size limits (CRDs with huge last-applied annotations, etc).	When ArgoCD sync fails with "Too long" or similar.

Secret sealing (untracked/secrets/)

Script	What it does	When you'd use it
untracked/secrets/seal.sh	Loops over registered plaintext YAMLs, runs kubeseal on each, outputs sealed-*.yaml.	After creating or rotating a plaintext secret in untracked/secrets/.
untracked/secrets/build-autoscaler-config.sh	Assembles the cluster-autoscaler config Secret from Bitwarden values (RKE2 join token, node groups, cloud credentials).	When onboarding a new node pool or rotating autoscaler credentials. Requires Bitwarden unlocked.

Terraform (terraform/)

Script	What it does	When you'd use it
terraform/tf.sh	Wrapper around terraform — unlocks Bitwarden, exports Hetzner API token + RKE2 join token, then forwards to terraform. Saves plans under terraform/plans/.	Any terraform operation: ./tf.sh plan -out=plans/<name>.tfplan, ./tf.sh apply plans/<name>.tfplan.
terraform/import.sh	Imports existing Hetzner resources into terraform state.	Rare — when we've created a resource manually and want terraform to manage it going forward.

Toolbox (toolbox/)

Script	What it does	When you'd use it
toolbox/build.sh	Builds the ecommercen/ecnv4-toolbox Docker image with kubectl, kustomize, helm, kubeseal, terraform, etc.	When we bump K8s version and need a matching client; also runs ecnv4-toolbox:latest.

Documentation

Script	What it does	When you'd use it
docs-gen/npm run dev	Local VitePress dev server for this manual. Auto-reloads on markdown change.	Writing docs, previewing before commit.
docs-gen/npm run build	Full production build — runs the client-docs generator, VitePress, Pagefind indexing.	Rarely needed locally; CI runs this on every push.
docs-gen/npm run generate	Just the scripts/generate-client-docs.py step.	Before committing a client-manifest change that changes the topology.

Recommended before changing anything

1. Read CLAUDE.md at the repo root — highest-density guide.
2. Delegate to the right Claude agent — see Agents.
3. Never commit plaintext — all secrets flow through seal.sh.
4. git diff before every push. Small commits, clean messages.

Further reading

• Tracked apps — what apps.yaml holds
• Ansible playbooks (legacy) — node-level operations, superseded by Terraform + kured in most cases
• Rules & guardrails — safety conventions