# AGENTS.md

This file is the execution guide for `ocdp-workload-manifests`.

## Working Boundary

- Treat this project as a plain app manifests repository.
- Do not store OCDP WorkloadTemplate records here; they belong in `ocdp-server`
  PostgreSQL.
- Do not store user WorkloadClaim instances here; they belong in target-cluster
  CRs created through `ocdp-server`.
- Keep reusable Kubernetes resources under `apps/*/base`.
- Keep optional Kustomize components under `apps/*/components`.
- Keep Helm post-render presets under `packages/*/presets/*`.
- Keep per-deployment runtime values out of this repository. They belong in
  temporary source files or runtime specs generated by `ocdp-server`.
- Use `tests/kustomize/*` only for generic validation overlays, never for real
  user instances.
- Do not commit real passwords, tokens, customer hostnames, private NFS paths, or
  private registry credentials.

## Runtime Rules

- Do not add a global catalog index unless the server explicitly needs one later.
- `ocdp-server` WorkloadTemplate records may reference Helm charts plus
  `source.preset.repositoryUrl/ref/path`.
- Runtime source generation may render Helm, create Secret, ConfigMap, and patch
  files, then run Kustomize.
- Bases should stay template-free YAML.
- App bases should keep Services internally reachable; expose apps from
  WorkloadClaim top-level intent such as `exposure=internal` or
  `exposure=external`, rendered by the agent/template path.
  Components such as `service-nodeport`, `service-loadbalancer`, or `ingress`
  are implementation building blocks, not the user-facing contract.
- Environment overlays are platform/admin choices for cluster- or site-level
  differences such as StorageClass, IngressClass, GPU runtime, registry prefix,
  pull secrets, node selectors, tolerations, and site labels.
- NodePort numbers should be assigned per claim by Kubernetes, not hard-coded in
  reusable app bases or components.

## Validation

- Run `make validate` after changing workload bases, components, or test
  overlays.
- If a change intentionally affects generated resource names, check references
  such as Secret refs, PVC claim names, Service backends, and ConfigMap mounts.