feat: add Backstage-compatible docs/ directory with TechDocs

[patrick-hermann-sva]

Summary

Create a docs/ directory compatible with Backstage TechDocs to consolidate all component documentation into a single, navigable site. Currently, documentation is scattered across 20+ individual README.md files in each component directory.

Structure

docs/
├── index.md                    # Overview, purpose, repo structure
├── getting-started/
│   ├── prerequisites.md        # Required tools (flux, kubectl, helm, task, dagger, sops, age)
│   └── quick-start.md          # Minimal steps to deploy a first app
├── bootstrap/
│   ├── overview.md             # Bootstrap approaches comparison
│   ├── flux-operator.md        # Flux Operator + FluxInstance CR (preferred)
│   ├── flux-cli.md             # flux bootstrap github method
│   ├── blueprints.md           # Dagger kubernetes-deployment module (full lifecycle)
│   └── sops-secrets.md         # SOPS/Age encryption setup for Flux decryption
├── apps/
│   ├── index.md                # App catalog overview, all apps listed
│   ├── argo-cd.md
│   ├── claim-machinery-api.md
│   ├── clusterbook.md
│   ├── flux-web.md
│   ├── headlamp.md
│   ├── homepage.md
│   ├── homerun-base-stack.md
│   ├── homerun-iot-stack.md
│   ├── keycloak.md
│   ├── minio.md
│   ├── openldap.md
│   ├── uptime-kuma.md
│   ├── vault.md
│   └── vcluster.md
├── infra/
│   ├── index.md                # Infra catalog overview
│   ├── cert-manager.md
│   ├── cilium.md
│   ├── ingress-nginx.md
│   ├── metallb.md
│   ├── nfs-csi.md
│   ├── openebs.md
│   ├── prometheus.md
│   └── vault.md
├── cicd/
│   ├── index.md
│   ├── crossplane.md
│   └── tekton.md
└── development/
    ├── adding-components.md    # How to create a new app/infra component
    ├── conventions.md          # Variable naming, API versions, patterns
    └── releasing.md            # Semantic-release workflow, commit convention
mkdocs.yml                      # MkDocs config (required by Backstage TechDocs)
catalog-info.yaml               # Backstage entity descriptor (optional)

Per-Component Doc Template

Each app/infra/cicd page should follow a consistent structure (migrated from existing READMEs):

# <Component Name>

<One-line description>

## Prerequisites

- Required secrets (with `kubectl apply` examples)
- Required ConfigMaps or external dependencies

## Deployment

### GitRepository

\`\`\`yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: flux-apps
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    tag: <version>
  url: https://github.com/stuttgart-things/flux.git
\`\`\`

### Kustomization

\`\`\`yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: <app>
  namespace: flux-system
spec:
  ...
  path: ./<category>/<app>
  postBuild:
    substitute:
      VAR: value
\`\`\`

## Variables

| Variable | Default | Description |
|---|---|---|

## Notes

<Component-specific notes, PromQL queries, etc.>

Bootstrap Section: Blueprints Repo Integration

The bootstrap/blueprints.md page should document the Dagger kubernetes-deployment module from stuttgart-things/blueprints which provides a full Flux bootstrap lifecycle via FluxBootstrap:

Phases:
0. ValidateAgeKeyPair — fail fast on key mismatch

1. FluxRenderConfig — render FluxInstance via KCL module
2. FluxEncryptSecrets — encrypt with SOPS/Age
3. FluxCommitConfig — push to Git
4. FluxDeployOperator — install operator via Helmfile
5. FluxApplyConfig — apply FluxInstance CR
6. FluxApplySecrets — apply secrets to cluster
7. FluxVerifySecrets — confirm secrets exist
8. FluxWaitForReconciliation — wait for Flux controllers

Key examples to document:

# Full bootstrap
dagger call -m kubernetes-deployment flux-bootstrap \
  --kube-config file:///path/to/kubeconfig \
  --deploy-operator=true --commit-to-git=true \
  --repository org/repo --destination-path "clusters/env/cluster" \
  --render-secrets=true --apply-secrets=true --apply-config=true \
  --encrypt-secrets=true --wait-for-reconciliation=true ...

# Render + encrypt + commit only (no cluster deploy)
dagger call -m kubernetes-deployment flux-bootstrap \
  --deploy-operator=false --wait-for-reconciliation=false \
  --render-secrets --encrypt-secrets --commit-to-git ...

# Deploy operator only
dagger call -m kubernetes-deployment flux-bootstrap \
  --deploy-operator=true --apply-secrets=false \
  --commit-to-git=false --wait-for-reconciliation=false ...

Backstage Integration

mkdocs.yml (root level)

site_name: stuttgart-things/flux
site_description: Flux CD GitOps Kustomizations
plugins:
  - techdocs-core
nav:
  - Home: index.md
  - Getting Started:
      - Prerequisites: getting-started/prerequisites.md
      - Quick Start: getting-started/quick-start.md
  - Bootstrap:
      - Overview: bootstrap/overview.md
      - Flux Operator: bootstrap/flux-operator.md
      - Flux CLI: bootstrap/flux-cli.md
      - Blueprints (Dagger): bootstrap/blueprints.md
      - SOPS Secrets: bootstrap/sops-secrets.md
  - Apps:
      - Overview: apps/index.md
      - ...per app
  - Infrastructure:
      - Overview: infra/index.md
      - ...per component
  - CI/CD:
      - Overview: cicd/index.md
      - ...per component
  - Development:
      - Adding Components: development/adding-components.md
      - Conventions: development/conventions.md
      - Releasing: development/releasing.md

catalog-info.yaml (root level, optional)

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: flux
  description: Flux CD GitOps kustomizations for infrastructure and applications
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: library
  lifecycle: production
  owner: sthings-team

Acceptance Criteria

• mkdocs.yml at repo root with TechDocs plugin
• docs/ directory with all pages from structure above
• All existing README content migrated into the per-component docs
• Bootstrap section covers all 3 approaches (Flux Operator, Flux CLI, Blueprints/Dagger)
• Variables table in each component doc (from task get-variables output)
• catalog-info.yaml for Backstage entity registration
• Existing per-component README.md files can optionally remain as symlinks or short pointers to docs/