# docs/ — Wegweiser (HiveGrid-Technik-Referenz)

`docs/` ist **technische Plattform-Referenz** plus HiveGrid-spezifische Entscheidungs-/Bau-Dokumente.

> **Du willst PLANEN/steuern?** → Plane für Status und Dependencies, `.planning/ticket-docs/<ID>.md` für Scope und DoD.
> **Du willst BAUEN?** → Ticket-Doc + `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`.
> **Du willst wissen, warum?** → `docs/ARCHITECTURE-DECISIONS.md`.

**Stand:** 2026-08-02 · Infra-Realität: **Hetzner + Coolify + Cloudflare**.

## HiveGrid-spezifisch (wichtig, gepflegt)
| Datei/Ordner | Inhalt |
|---|---|
| **ARCHITECTURE-DECISIONS.md** | kompaktes Register der AD-IDs, Gründe und Status; operative Regeln stehen in `AGENTS.md` |
| **INTEGRATION-CONTRACTS.md** | Modul-Integrationsvertrag (Sidebar/Routes/Search/Notifications/Entitlement-Gate) |
| **UAT.md** | stabile Golden-Journey-Landkarte; Details und DoD bleiben in den Ticket-Docs |
| **MID-STREAM-CHANGES.md** | Rollback-Playbook für ticket-getriebene Änderungen |

## Plattform-Referenz (Boilerplate — Nachschlagen, selten Startpunkt)
deployment.md · staging-live-uat.md · worker.md · database.md / db-*.md · mail*.md · env-vars.md / env-access-inventory.md · plugins.md · api.md · observability.md · security.md + **security/** · **architecture/** · troubleshooting.md · configuration.md · local-dev.md · quickstart.md · roles-matrix.md · data-retention.md

## Betriebs-/Spezial-Ordner
- **ops/** = operative Runbooks (Queues, PgBouncer, Backups, CDN, Lago-Staging/Production-Prep, Billing-Meter)
- **operations/** = Setup/Admin-Guides (Authentik-SSO, Plugin-Lifecycle) — *Namens-Doppel mit ops/, Konsolidierung wäre ein Aufräum-Kandidat*
- **observability/** = Monitoring (Sentry/Logging/Metrics)
- **deploy/** (Service-Runbooks, z.B. Meilisearch) · **deployments/** (Referenz-Deploy boiler-saas-ctrl) · **agent-playbooks/** · **contributing/** · **testing/** · **plugins/** · **ui-inventory/** · **compliance/** · **storage/** · **auth/** · **verification/**

## Historisch — NICHT Startpunkt
- **archive/** · **reports/** — abgeschlossene Artefakte.
- Die früheren Boilerplate-Abgleichs- und Milestone-Archive wurden im Bespoke-Cleanup entfernt. Aktive
  Quellen sind `AGENTS.md`, die Ticket-Docs, `.planning/ENTITY-MODEL.md` und
  `.planning/REQUIREMENTS.md`; das AD-Register erklärt Entscheidungen, dupliziert aber keine Regeln.