# CLAUDE.md

## Project Overview

This repository contains "Wild Cloud".

Wild Cloud helps administrators set up and manage a Kubernetes cluster with nodes running Talos linux. It also contains a directory of application (in `apps/`) that can be deployed on clusters.

The scripts in this repository ($WC_ROOT) are intended to be sourced and executed from within a Wild Cloud project directory ($WC_HOME).

Again, this repository ($WC_ROOT) contains the Wild Cloud scripts and applications. The actual Wild Cloud project directory ($WC_HOME), which contains your specific configuration files, is separate.

## Info about Wild Cloud

- @docs/agent-context/wildcloud/README.md
- @docs/agent-context/wildcloud/overview.md
- @docs/agent-context/wildcloud/project-architecture.md
- @docs/agent-context/wildcloud/bin-scripts.md
- @docs/agent-context/wildcloud/configuration-system.md
- @docs/agent-context/wildcloud/setup-process.md
- @docs/agent-context/wildcloud/apps-system.md

## Info about Talos

- @docs/agent-context/talos-v1.11/README.md
- @docs/agent-context/talos-v1.11/architecture-and-components.md
- @docs/agent-context/talos-v1.11/cli-essentials.md
- @docs/agent-context/talos-v1.11/cluster-operations.md
- @docs/agent-context/talos-v1.11/discovery-and-networking.md
- @docs/agent-context/talos-v1.11/etcd-management.md
- @docs/agent-context/talos-v1.11/bare-metal-administration.md
- @docs/agent-context/talos-v1.11/troubleshooting-guide.md

## Code Guidelines

- Wild Cloud projects use infrastructure-as-code principles.
- Scripts that interact with a Wild Cloud project must manage state and infrastructure idempotently and check for existing state.
- Timeouts should be avoided in favor of proper readiness and liveness probes, for example:
  - Use `kubectl wait` to ensure resources are ready before proceeding with dependent operations.
  - Use `kubectl rollout status` to ensure deployments are successfully rolled out before proceeding.
  - Use `kubectl get` with appropriate selectors to check the status of resources.
- All code should be simple and easy to understand.
  - Avoid unnecessary complexity.
  - Avoid unnecessary dependencies.
  - Avoid unnecessary features.
  - Avoid unnecessary abstractions.
  - Avoid unnecessary comments.
  - Avoid unnecessary configuration options.
- Avoid Helm. Use Kustomize.

### Scripts

- Use @scripts/common.sh for common functions and patterns, especially if they will clean up the code.
- Don't define functions in a script that are only used once. Just inline the code.