docs: add a documentation index and fix dangling references

DESIGN_GUIDELINES.md

@@ -12,7 +12,7 @@ This document defines Mila’s **UI system** to ensure **UX consistency**, **acc
 - standard page skeletons (index/detail/form)
 - microcopy conventions (German “du” tone)
 
-> Engineering practices (LiveView load budget, testing, security, etc.) are defined in `docs/CODE_GUIDELINES.md`.  
+> Engineering practices (LiveView load budget, testing, security, etc.) are defined in `CODE_GUIDELINES.md`.  
 > This document focuses on **visual + UX** consistency and references engineering rules where needed.
 
 ---

docs/README.md

@@ -0,0 +1,46 @@
+# Documentation index
+
+Project documentation for Mila (Mitgliederverwaltung). Each area below lists a coarse entry point first, then the deeper references. For engineering conventions see the repo-root `CODE_GUIDELINES.md`; for UI conventions see `DESIGN_GUIDELINES.md`.
+
+## Roles & permissions
+- [roles-and-permissions-overview.md](roles-and-permissions-overview.md) — coarse entry: the RBAC concept, evaluated approaches, permission sets and scopes.
+- [roles-and-permissions-architecture.md](roles-and-permissions-architecture.md) — deep reference: per-resource policies, permission matrix, page-permission plug, authorization bootstrap patterns.
+- [roles-and-permissions-implementation-plan.md](roles-and-permissions-implementation-plan.md) — historical record of how the MVP was built.
+- [policy-bypass-vs-haspermission.md](policy-bypass-vs-haspermission.md) — the two-tier Ash pattern (bypass + `expr()` for reads, `HasPermission` for writes).
+- [page-permission-route-coverage.md](page-permission-route-coverage.md) — route → permission-set access matrix and the page-permission plug behaviour.
+
+## Membership & fees
+- [membership-fee-overview.md](membership-fee-overview.md) — coarse entry: terminology (DE↔EN), worked cycle examples, UI mockups.
+- [membership-fee-architecture.md](membership-fee-architecture.md) — deep reference: design decisions, data model, cycle generation, atomicity.
+- [vereinfacht-api.md](vereinfacht-api.md) — the Vereinfacht finance-contact sync integration.
+
+## Members: import, onboarding, custom fields
+- [csv-member-import-v1.md](csv-member-import-v1.md) — CSV member import: column mapping, validation, error handling, templates.
+- [onboarding-join-concept.md](onboarding-join-concept.md) — public join flow (double opt-in, JoinRequest), plus unimplemented approval/invite/OIDC design.
+- [custom-fields-search-performance.md](custom-fields-search-performance.md) — performance of custom-field values in the member search vector.
+
+## Groups
+- [groups-architecture.md](groups-architecture.md) — groups design, hierarchy extension path, search integration, A11y notes.
+
+## Database
+- [database-schema-readme.md](database-schema-readme.md) — schema overview: tables, relationships, indexes, full-text & fuzzy search.
+- [database_schema.dbml](database_schema.dbml) — machine-readable DBML schema (for dbdiagram.io / dbdocs.io).
+
+## Accounts, OIDC & email
+- [admin-bootstrap-and-oidc-role-sync.md](admin-bootstrap-and-oidc-role-sync.md) — production admin bootstrap and OIDC group → Admin role sync (ENV contract).
+- [oidc-account-linking.md](oidc-account-linking.md) — secure account linking between password and OIDC accounts.
+- [email-sync.md](email-sync.md) — email synchronization rules between linked User and Member.
+- [email-validation.md](email-validation.md) — the dual `:html_input` + `:pow` email-validation strategy.
+- [email-layout-mockup.md](email-layout-mockup.md) — shared transactional-email layout structure.
+- [smtp-configuration-concept.md](smtp-configuration-concept.md) — SMTP config precedence, TLS handling, operational caveats.
+
+## UI & components
+- [settings-authentication-mockup.txt](settings-authentication-mockup.txt) — Settings → Authentication section layout.
+- [daisyui-drawer-pattern.md](daisyui-drawer-pattern.md) — the project's sidebar drawer pattern (implemented in `lib/mv_web/components/layouts/sidebar.ex`).
+- [badge-wcag-phase1-analysis.md](badge-wcag-phase1-analysis.md) — `<.badge>` component API and WCAG contrast design notes.
+- [pdf-generation-imprintor.md](pdf-generation-imprintor.md) — PDF generation via Imprintor + Typst templates (decision vs. Chromium).
+
+## Project history & planning
+- [development-progress-log.md](development-progress-log.md) — coarse implementation history, architecture decisions, migration index, gotchas.
+- [feature-roadmap.md](feature-roadmap.md) — per-area status matrix and the open/missing backlog.
+- [test-performance-optimization.md](test-performance-optimization.md) — test-suite speed-up: seeds-test coverage mapping and the `@tag :slow` model.

test/seeds_test.exs

@@ -17,7 +17,7 @@ defmodule Mv.SeedsTest do
   - Detailed role configuration tests → covered by `authorization/*_test.exs`
   - Permission set validation → covered by `authorization/permission_sets_test.exs`
 
-  See `docs/test-optimization-seeds.md` for detailed rationale and coverage mapping.
+  See `docs/test-performance-optimization.md` for detailed rationale and coverage mapping.
   """
 
   use Mv.DataCase, async: false