# docs/ — Wegweiser (Technik- & Boilerplate-Referenz)

`docs/` ist überwiegend **technische Plattform-Referenz** (geerbt aus der @toolctrl-Boilerplate) plus einige HiveGrid-spezifische Entscheidungs-/Bau-Dokumente.

> **Du willst PLANEN/steuern?** → nicht hier, sondern **`.planning/`** (Live-Planung: PROJECT, ROADMAP, STATE, REQUIREMENTS, ENTITY-MODEL).
> **Du willst BAUEN?** → `docs/milestones/` (die PLAN.md je Milestone) + `docs/ARCHITECTURE-DECISIONS.md` + `docs/INTEGRATION-CONTRACTS.md`.

**Stand:** 2026-06-15 · Infra-Realität: **Hetzner + Coolify + Cloudflare** (Scaleway/Fly sind raus — historische Erwähnungen in alten Sets sind nur Historie).

## HiveGrid-spezifisch (wichtig, gepflegt)
| Datei/Ordner | Inhalt |
|---|---|
| **ARCHITECTURE-DECISIONS.md** | verbindliche ADRs AD-1…AD-20 (inkl. Projekt-zentrisches Modell) |
| **INTEGRATION-CONTRACTS.md** | Modul-Integrationsvertrag (Sidebar/Routes/Search/Notifications/Entitlement-Gate) |
| **milestones/** | 176 Milestone-PLANs — **aktiv** von `.planning/PHASE-SOURCES.md` referenziert |
| **boilerplate-mapping/** + **boilerplate-inventory/** | Reuse-Abgleich gegen die Boilerplate (Quelle für Scope-Schnitte) |
| **feature-inventory.md** + **feature-decisions/** + **feature-manifests/** | Feature-Klassifikation. ⚠ `feature-manifests/*.json` werden **zur Laufzeit/von Tests geladen** — nicht anfassen |
| **TC-PLANNING-BRIEFING.md** · **MID-STREAM-CHANGES.md** · **PROGRESS-TRACKER.md** | Agent-Briefing · Rollback-Playbook · Live-Fortschritts-Tracker |

## Plattform-Referenz (Boilerplate — Nachschlagen, selten Startpunkt)
deployment*.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 · upgrade(s).md · versioning.md · configuration.md · local-dev.md · quickstart.md · production-checklist.md / release-checklist.md · roles-matrix.md · data-retention.md

## Betriebs-/Spezial-Ordner
- **ops/** = operative Runbooks (Queues, PgBouncer, Backups, CDN, Stripe-Meter)
- **operations/** = Setup/Admin-Guides (Authentik-SSO, Plugin-Lifecycle, Capacitor) — *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
- **improvement-plan/** — **gehört der Boilerplate (upstream), nicht HiveGrid.** Es ist der Tech-Debt-/Reifungs-Plan der @toolctrl-Boilerplate (Phasen 01–11), kommt per Downstream-Merge mit und wird **upstream weiter gepflegt**. Die ~100 Code-Kommentare „siehe docs/improvement-plan/…" sind ebenfalls Boilerplate-Code. **Nicht verschieben/löschen** — das würde bei jedem `git merge upstream` kollidieren (AD-10). Status laut Boilerplate selbst (CURRENT-STATUS.md): überwiegend **historisch** (PROGRESS.md/VERIFICATION.md = reconciled), nur OPERATOR-CHECKLIST.md + BLOCKERS.md noch live. Für HiveGrid: **kein Planungs-Input** — unsere Quelle ist `.planning/` + `milestones/`.
- **archive/** · **releases/** · **reports/** — abgeschlossene Artefakte.