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	CLI primitive over kubeseal. One file at a time: seal.sh seal <path> (namespace-scoped) or seal.sh cluster-seal <path> (cluster-wide). Output goes to sealed-<path>.	When you know exactly which file + scope you want.
untracked/secrets/seal-all.sh	Bulk orchestrator over seal.sh. Walks the tree, reads each plaintext's sealedsecrets.bitnami.com/cluster-wide annotation to pick scope, silently skips plaintexts you don't have locally.	Re-sealing everything after a controller-key rotation; day-to-day bulk work.
untracked/secrets/set-secret-field.sh	Interactive single-field mutator — prompts for a new value (silent, off argv), base64s it, replaces one data.* field in a plaintext Secret YAML.	Rotating a single password inside an existing plaintext without exposing it in shell history.
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.
untracked/secrets/*.local.sh	Gitignored by convention. Personal wrapper scripts — write your own flow on top of seal.sh if the shared orchestrator doesn't fit your habits. Ignored so contributors don't have to agree on one orchestrator.	When you want custom automation without touching shared tooling.

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 / seal-all.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