feat: define and document repository structure version 1

[weatherhog]

What does this PR do?

Declares the layout this repository prescribes as structure version 1, and adds a
Structure Version
section to docs/repo_structure.md defining what does and does not warrant a bump.

Also ships a .gitops-metadata.yaml at the repository root so that forks start pinned at version 1.

Why

The structure had no version. A fork carried no marker of which generation of the layout it was
built from, so there was no way to tell it had fallen behind — and no way to enumerate what would
need updating. This repository has exactly one tag (v0.1.0, September 2022), zero published
releases, and every structural change since sits in a single ## Unreleased CHANGELOG section.

Companion PR

Pairs with giantswarm/kubectl-gs#2081, which teaches kubectl gs gitops to record the
version in the repositories it generates and adds kubectl gs gitops check to report drift.
Neither PR breaks without the other, but the docs here describe a command that only exists once
the kubectl-gs side is released — the new section says so explicitly.

Why layers: [] in the shipped file

The trees under management-clusters/ and bases/ here are examples, not generated layers.
Listing them would create an inventory that rots every time an example is added. A fork records
its real layers with kubectl gs gitops check --adopt. Staleness is harmless either way: check
compares versions, never completeness.

What is being committed to

Shipping structureVersion: 1 obliges someone to bump it when the layout changes, and to say what
changed. Nothing enforces the lockstep between the number here and StructureVersion in
kubectl-gs/internal/gitops/metadata/types.go — it is a convention, documented in both repos. If
reviewers want that enforced by CI rather than by discipline, say so and I will add it.

What this does not do

This is the detection half of giantswarm/giantswarm#23540. Migration and upgrade tooling is
untouched — the part described in
March 2025 as an
open product feature. The issue stays open.

What is needed from the reviewers

1. Agreement that version 1 is the right starting point, i.e. that today's main is the baseline.
2. A sanity check on the bump criteria in the new section.
3. Whether a root-level .gitops-metadata.yaml in every fork is acceptable.

Verification

The new root file is invisible to every PR check: tools/test-all-ff filters find output by
api.*\.fluxcd\.io and this file does not match; tests/ats/conftest.py only applies
management-clusters/<dir>/<dir>.yaml; the only top-level Flux Kustomization has
path: ./management-clusters/MC_NAME. yamllint passes and no added markdown line exceeds
MD013's 120 characters.

Related: giantswarm/giantswarm#23540

[github-actions]

Semantic YAML source diff — key reordering without value changes is ignored.

Output

@@ .gitops-metadata.yaml @@
(Added — see file diff in PR for content)

Suppress with /no_diffs_printing on its own line in the PR body or as a comment.

[github-actions]

Validation output log

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

yamllint: OK
kubeconform: OK

[github-actions]

Rendered manifest diff output log

No diff detected