T-0.3 ServiceDefinition schema + renderer contract + examples (R-GITOPS-02)

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

catalog/README.md

@@ -1,3 +1,37 @@
-# catalog
+# catalog — ServiceDefinition entries (the onboarding surface)
 
-_Placeholder — populated in Phase 0. See ../home-network-k3s (read-only spec)._
+One YAML file per service. Each file is a **ServiceDefinition** conforming to
+[`../schemas/servicedefinition.schema.json`](../schemas/servicedefinition.schema.json). Adding or
+editing a service here is the *only* onboarding step — the platform renders compute, storage, network
+policy, egress, TLS, DNS, monitoring, and update policy from it (see
+[`../schemas/renderer-contract.md`](../schemas/renderer-contract.md)). Serves **R-GITOPS-02**.
+
+**Source of truth for the initial catalog:** spec
+[`docs/13-service-catalog.md`](../../home-network-k3s/docs/13-service-catalog.md) (14-service table +
+SSO/egress/dependency intent).
+
+## Current examples (Phase 0)
+| File | docs/13 row | exposure | egress | auth | Notes |
+|---|---|---|---|---|---|
+| `pihole.yaml` | 6 | internal | internet | forward-auth | admin UI behind oauth2-proxy; config on Longhorn (DR-critical); also platform DNS |
+| `keycloak.yaml` | 0 | public | internet | native | the IdP itself (own admin login + MFA); PostgreSQL on Longhorn; DR-critical |
+
+The remaining catalog services (plex, sonarr, radarr, jackett, seerr, nextcloud, minecraft, unifi,
+semaphore, kasm, gitea, qbittorrent) are onboarded in later phases; they follow the same schema and
+inherit every guarantee automatically.
+
+## Authoring rules
+- Only `name` and `source` are mandatory; every other field defaults to docs/13's default posture
+  (`kind: container`, `exposure: internal`, `egress: internet`, `auth.mode: forward-auth`, stable
+  auto-update, DNS-only default-deny). Set a field only to override the default.
+- Any exposed UI must have an `auth` block: `forward-auth` (default) or `oidc`, each with a non-empty
+  `auth.groups`; `native`/`none` are documented exceptions only.
+- Irreplaceable state (`class: longhorn` configs/DBs) must set `backup.policy` to an off-cluster
+  schedule — never `reacquirable` (R-STATE-03). Only bulk media may be `reacquirable`.
+
+## Validate before commit — single command, no cluster (R-TEST-02)
+```bash
+check-jsonschema --schemafile schemas/servicedefinition.schema.json catalog/*.yaml
+```
+See [`../schemas/README.md`](../schemas/README.md) for install/pinning and a pure-Python fallback.
+This is the L0/L1 schema gate (spec `docs/14`); CI (`.gitea/`) runs it on every change.