# Documentation Index — `devops-infra-argo-config`

> Navigation guide for agents and humans working in this repository.

---

## Layout

```text
devops-infra-argo-config/
├── CLAUDE.md                              ← Agent entry point (read first)
├── index.md                               ← This file
├── repository.yaml                        ← Ownership metadata (automation-owned, do not hand-edit)
│
├── docs/
│   ├── global/
│   │   ├── SANCTITY_RULES.md              ← Non-negotiable rules R1–R12
│   │   ├── AGENT_BOUNDARIES.md            ← Layer 1-T map, blast radii, what agents may/may not touch
│   │   ├── escalation-matrix.md           ← When to page a human and who to contact
│   │   └── coding-guidelines/
│   │       ├── infra-argo.md              ← Combined YAML authoring conventions (values files + appSpec)
│   │       ├── argocd.md                  ← ArgoCD Application manifest conventions (incubator files)
│   │       └── helm.md                    ← Helm values file conventions (clusterSpec, teamSpec, appSpec)
│   │
│   ├── platform/
│   │   ├── procedures/
│   │   │   ├── add-tool-to-cluster.md     ← Add, update, or remove an appSpec entry
│   │   │   ├── add-new-cluster.md         ← Onboard a new cluster (incubator + values files)
│   │   │   ├── upgrade-chart-version.md   ← Change chartDir for one or many clusters
│   │   │   ├── deboard-tool-from-cluster.md ← Safely remove a tool from a cluster
│   │   │   └── fleet-wide-tool-rollout.md ← Add a tool to multiple clusters in one PR
│   │   │
│   │   ├── runbooks/
│   │   │   ├── argocd-sync-failure.md     ← Sync failure decision tree
│   │   │   ├── render-failure.md          ← Helm render errors (ComparisonError)
│   │   │   ├── values-drift.md            ← Detect and fix inconsistencies across cluster values files
│   │   │   └── deployment-stuck.md        ← Pod pending/crashloop after sync
│   │   │
│   │   └── schemas/
│   │       ├── values-file-schema.md      ← Annotated appSpec schema — every field explained
│   │       └── incubator-values-schema.md ← Incubator Application YAML field reference
│   │
│   └── golden-prs.md                      ← Golden PRs for benchmark suite (generated)
│
├── skills/
│   └── infra/
│       ├── add-tool.md                    ← Agent skill: add tool to cluster
│       ├── upgrade-chart-version.md       ← Agent skill: bump chartDir version
│       ├── fleet-wide-rollout.md          ← Agent skill: roll out a tool across many clusters
│       └── onboard-cluster.md             ← Agent skill: onboard a new cluster
│
├── wiki/
│   ├── entities/
│   │   └── DevOps Infra ArgoCD Config.md  ← Wiki entity page
│   └── analyses/
│       ├── ADR-I1-generic-chart-per-cluster.md  ← ADR: why one generic Helm chart
│       └── ADR-I2-incubator-pattern.md          ← ADR: why the incubator + App-of-Apps pattern
│
├── generic-argo-apps-chart/               ← Helm chart: renders child Applications from appSpec
├── incubator/<env>/                       ← Parent ArgoCD Application per cluster
├── values/<env>/                          ← appSpec lists defining which tools deploy per cluster
├── projects/                              ← ArgoCD AppProject definitions (sre, sec)
├── external-name-service-incubator/       ← Cross-cluster DNS routing Application manifests
├── external-name-service-template/        ← Helm chart for ExternalName services
└── external-name-service-values/          ← MCS topology values per zone
```

---

## Quick navigation

### For agents

1. Read [CLAUDE.md](CLAUDE.md) — repo role, naming conventions, forbidden actions, validation commands.
2. Read [docs/global/AGENT_BOUNDARIES.md](docs/global/AGENT_BOUNDARIES.md) — what you may and may not touch.
3. Read [docs/global/SANCTITY_RULES.md](docs/global/SANCTITY_RULES.md) — non-negotiable rules.

### For human PR reviewers

1. Skim [docs/global/coding-guidelines/infra-argo.md](docs/global/coding-guidelines/infra-argo.md) — YAML conventions.
2. Check [docs/platform/schemas/values-file-schema.md](docs/platform/schemas/values-file-schema.md) — appSpec field reference.

### By task

| I want to... | Read this |
| ------------ | --------- |
| Add a tool to a cluster | [docs/platform/procedures/add-tool-to-cluster.md](docs/platform/procedures/add-tool-to-cluster.md) |
| Upgrade a chart version | [docs/platform/procedures/upgrade-chart-version.md](docs/platform/procedures/upgrade-chart-version.md) |
| Deboard a tool from a cluster | [docs/platform/procedures/deboard-tool-from-cluster.md](docs/platform/procedures/deboard-tool-from-cluster.md) |
| Roll out a tool across all clusters | [docs/platform/procedures/fleet-wide-tool-rollout.md](docs/platform/procedures/fleet-wide-tool-rollout.md) |
| Onboard a new cluster | [docs/platform/procedures/add-new-cluster.md](docs/platform/procedures/add-new-cluster.md) |
| Debug a sync failure | [docs/platform/runbooks/argocd-sync-failure.md](docs/platform/runbooks/argocd-sync-failure.md) |
| Debug a Helm render error | [docs/platform/runbooks/render-failure.md](docs/platform/runbooks/render-failure.md) |
| Find inconsistencies across clusters | [docs/platform/runbooks/values-drift.md](docs/platform/runbooks/values-drift.md) |
| Debug a stuck deployment | [docs/platform/runbooks/deployment-stuck.md](docs/platform/runbooks/deployment-stuck.md) |
| Understand when to escalate | [docs/global/escalation-matrix.md](docs/global/escalation-matrix.md) |
| Understand why we use one generic chart | [wiki/analyses/ADR-I1-generic-chart-per-cluster.md](wiki/analyses/ADR-I1-generic-chart-per-cluster.md) |
| Understand the incubator pattern | [wiki/analyses/ADR-I2-incubator-pattern.md](wiki/analyses/ADR-I2-incubator-pattern.md) |
| See repo ownership and relationships | [wiki/entities/DevOps Infra ArgoCD Config.md](wiki/entities/DevOps%20Infra%20ArgoCD%20Config.md) |