fix broken doc links

README.md

@@ -72,9 +72,9 @@ docker compose -f docker-compose.prod.yml up --build -d
 
 Details stehen in:
 
-- `/docs/docker-lokal.md`
+- `/docs/howto-docker-lokal.md`
-- `/docs/docker-produktiv.md`
+- `/docs/howto-docker-produktiv.md`
-- `/docs/docker-betrieb.md` (Übersicht)
+- `/docs/explanation-docker-betrieb.md` (Übersicht)
 
 ## Seed-Daten
 
@@ -216,12 +216,12 @@ docker compose exec php composer cs:fix
 ## Dokumentation
 
 - `/docs/index.md` Dokumentationsstart mit chronologischem Lernpfad und Referenzbereichen
-- `/docs/00-systemueberblick.md` Einstieg in Produktbild und Kernprinzipien
+- `/docs/tutorial-02-systemueberblick.md` Einstieg in Produktbild und Kernprinzipien
-- `/docs/01-setup-und-erster-login.md` lokales Setup und erster Smoke-Test
+- `/docs/tutorial-03-setup-und-erster-login.md` lokales Setup und erster Smoke-Test
-- `/docs/02-domain-glossar.md` zentrale Begriffe fuer Tenant/Role/Scope
+- `/docs/reference-domain-glossar.md` zentrale Begriffe fuer Tenant/Role/Scope
-- `/docs/03-architektur-request-flow.md` Request-Flow und Schichtmodell
+- `/docs/tutorial-04-architektur-request-flow.md` Request-Flow und Schichtmodell
-- `/docs/06-security-tenant-scope.md` Security-Grundlagen vor Feature-Arbeit
+- `/docs/tutorial-07-security-tenant-scope.md` Security-Grundlagen vor Feature-Arbeit
-- `/docs/07-api-erweitern.md` verbindlicher API-Aenderungsablauf inkl. OpenAPI
+- `/docs/tutorial-08-api-erweitern.md` verbindlicher API-Aenderungsablauf inkl. OpenAPI
 
 ## Troubleshooting
 

agent-system/README.md

@@ -12,3 +12,4 @@ Structure:
 References:
 - Planner standard: `tools/codex-skills/starterkit-planner/SKILL.md`
 - Guardrails: `tools/codex-skills/core-guardrails/SKILL.md`
+- Docs/Skills audit policy: `agent-system/checks/docs-skills-audit-policy.md`

agent-system/checks/docs-skills-audit-policy.md

@@ -0,0 +1,27 @@
+# Docs/Skills Audit Policy
+
+Letzte Aktualisierung: 2026-03-09
+
+## Ziel
+
+Einheitliche Einstufung und Ablage von Findings fuer Docs-/Skills-Audits.
+
+## Severity-Klassen
+
+- `P0`: Kritischer Produktions- oder Sicherheitsimpact.
+- `P1`: Hoher Architektur-/Compliance-Impact, kurzfristig zu beheben.
+- `P2`: Mittlerer Impact, kein unmittelbarer Betriebsblocker.
+- `P3`: Niedriger Impact, redaktionell oder kosmetisch.
+
+## Persistenzregeln
+
+- `P0` und `P1` muessen als eigener Run unter `agent-system/runs/` dokumentiert werden.
+- Naming fuer diese Runs: `DOCS-SKILLS-AUDIT-00x` (fortlaufend).
+- `P2` und `P3` werden kompakt im laufenden Audit-Protokoll gesammelt und spaeter gebuendelt umgesetzt.
+
+## Mindestinhalt pro grossem Finding-Run (`P0`/`P1`)
+
+- Finding-ID, Severity, betroffene Dateien.
+- Reproduzierbare Evidenz (Befehl/Output oder Dateiverweis).
+- Geplante Mitigation inkl. Guard-/Gate-Bezug.
+- Abschlussstatus (`open`, `resolved`, `accepted-risk`).

bin/codex-skills-sync.sh

@@ -50,6 +50,8 @@ target_dir="${codex_home_dir}/skills"
 managed_skills=(
   "core-guardrails"
   "starterkit-planner"
+  "starterkit-grid-standards"
+  "starterkit-php-style-ci"
 )
 
 for skill in "${managed_skills[@]}"; do
@@ -70,7 +72,7 @@ check_skill() {
   fi
 
   local diff
-  diff="$(rsync -rcn --delete --itemize-changes "${src}/" "${dst}/" || true)"
+  diff="$(diff -qr "${src}" "${dst}" || true)"
   if [[ -n "${diff}" ]]; then
     echo "[DRIFT] ${skill} differs:"
     echo "${diff}" | sed 's/^/  /'

docs/howto-erste-aenderung.md

@@ -1,6 +1,6 @@
 # Leitfaden für die erste Änderung
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
 ## Ziel
 
@@ -37,7 +37,7 @@ Ein neuer Entwickler soll den ersten Change strukturiert und reproduzierbar umse
 2. Permission- und Tenant-Scope-Prüfungen beibehalten
 3. Optional Service/Repository ergänzen, Instanziierung über `app(...)`/Factory-Standards
 4. `docs/openapi.yaml` aktualisieren
-5. `docs/api.md` mit Beispiel aktualisieren
+5. `/docs/reference-api.md` mit Beispiel aktualisieren
 6. Bei neuen Berechtigungen: `PermissionService` + `init.sql` synchron halten, für Bestandsumgebungen idempotentes SQL-Update in `db/updates/*.sql` bereitstellen
 
 ### Done-Kriterien

docs/howto-lokale-entwicklung.md

@@ -1,6 +1,6 @@
 # Lokale Entwicklung
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
 ## Ziel
 
@@ -55,8 +55,8 @@ Bei JS-Änderungen zusätzlich Browser-Smoke mit DevTools-Console (keine JS-Erro
 ## API-spezifisch
 
 - `docs/openapi.yaml` aktualisieren
-- bei Bedarf `docs/api.md` ergänzen
+- bei Bedarf `/docs/reference-api.md` ergänzen
-- bei Security-Änderungen `docs/sicherheitsmodell.md` aktualisieren
+- bei Security-Änderungen `/docs/explanation-sicherheitsmodell.md` aktualisieren
 
 ## Vertiefung
 

docs/index.md

@@ -1,6 +1,6 @@
 # Dokumentation
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
 Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: Tutorials zum Lernen, How-to Guides zum Nachschlagen von Aufgaben, Explanation zum Verstehen und Reference zum Nachschlagen von Fakten.
 
@@ -93,6 +93,8 @@ Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert:
   - Definition of Done vor Merge.
 - `/docs/reference-codex-prompts.md`
   - Standard-Prompts fuer Skill-basierte Planung und Implementierung.
+- `/docs/reference-extension-readiness.md`
+  - Verbindliche Vorbedingungen fuer spaetere Module ohne Hook-/Lifecycle-Festlegung.
 - `/docs/reference-agents-overview.md`
   - Einstieg in das Rollenmodell und die Artefakte.
 - `/docs/reference-agents-roles.md`

docs/reference-agents-overview.md

@@ -1,6 +1,6 @@
 # Agent Workflow Overview
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
 This project uses a multi-role workflow for issue and feature delivery.
 
@@ -24,6 +24,6 @@ Source of truth:
 - quality gates: `agent-system/checks/quality-gates.json`
 
 Entry points:
-- roles: `docs/agents/roles.md`
+- roles: `/docs/reference-agents-roles.md`
-- workflow: `docs/agents/flow.md`
+- workflow: `/docs/reference-agents-flow.md`
 - schemas and prompts: `agent-system/`

docs/reference-codex-prompts.md

@@ -1,6 +1,6 @@
 # Codex Prompt-Standards
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
 ## Ziel
 
@@ -63,3 +63,4 @@ Regel:
 1. Keine impliziten Extension-Standards erfinden.
 2. Erweiterungen explizit als Out-of-Scope kennzeichnen.
 3. Nur dokumentieren, was bereits verbindlich im Repo festgelegt ist.
+4. Vor Implementierungsstart die Vorbedingungen aus `/docs/reference-extension-readiness.md` prüfen.

docs/reference-extension-readiness.md

@@ -0,0 +1,41 @@
+# Extension-Readiness (ohne Architektur-Festlegung)
+
+Letzte Aktualisierung: 2026-03-09
+
+## Ziel
+
+Verbindliche Vorbedingungen fuer spaetere eigenstaendige Module festhalten, ohne jetzt eine konkrete Extension-Mechanik (Hooks/Lifecycle/Loader) zu standardisieren.
+
+## Readiness-Checkliste vor neuem Modul
+
+1. **Modulgrenzen klarziehen**
+   - Betroffene Schichten benoennen (`pages -> Service -> Repository`).
+   - Keine SQL-/Business-Logik in Templates oder `pages/*.phtml`.
+2. **Contracts definieren**
+   - Oeffentliche API-/UI-Contracts dokumentieren (Inputs, Outputs, Fehlerfaelle).
+   - Bei API-Aenderungen `docs/openapi.yaml` im selben Merge pflegen.
+3. **Security + Scope absichern**
+   - AuthZ/RBAC serverseitig pruefen.
+   - Tenant-Scope serverseitig pruefen.
+   - POST-Mutationen mit CSRF absichern.
+4. **Testbarkeit und Gates**
+   - Architektur- und Domain-Tests fuer neue Logik ergaenzen.
+   - Relevante Quality Gates (`QG-*`) im Merge reporten.
+5. **Daten- und Betriebsfaehigkeit**
+   - Schema-/Datenaenderungen fuer Bestandsinstallationen idempotent in `db/updates/*.sql`.
+   - Logs/Audit ohne unredacted PII/Secrets.
+
+## Bewusst Out of Scope in diesem Stand
+
+- Kein standardisierter Extension-Loader.
+- Kein Hook-/Plugin-Lifecycle.
+- Keine verbindlichen Modul-Ablageorte ausserhalb bestehender Schichten.
+
+## Entscheidungslog fuer spaetere Standardisierung
+
+Wenn die Extension-Mechanik spaeter konkretisiert wird, muss die Entscheidung mindestens diese Punkte mitliefern:
+
+1. Aktivierung/Deaktivierung und Reihenfolge von Modulen.
+2. Versionierung und Migrationsstrategie pro Modul.
+3. Sicherheits- und Tenant-Isolation pro Erweiterung.
+4. Test- und Rollback-Strategie fuer Modul-Deployments.

docs/reference-konventionen.md

@@ -1,6 +1,6 @@
 # Konventionen (kurz und verbindlich)
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
 ## 1) Code
 
@@ -44,7 +44,7 @@ Letzte Aktualisierung: 2026-03-06
 
 - Templates nur für Rendering.
 - UI-Texte über `t('...')`.
-- Strukturregeln in `docs/frontend-css.md` und `docs/frontend-javascript.md`.
+- Strukturregeln in `/docs/reference-frontend-css.md` und `/docs/reference-frontend-javascript.md`.
 
 ## 6) Mindestchecks vor Merge
 

docs/reference-lib-standards.md

@@ -1,8 +1,8 @@
 # lib-Standards
 
-Letzte Aktualisierung: 2026-03-06
+Letzte Aktualisierung: 2026-03-09
 
-Praktische Regeln nur für `lib/**`. Ergänzt `docs/architektur.md`.
+Praktische Regeln nur für `lib/**`. Ergänzt `/docs/explanation-architektur.md`.
 
 ## 1) Repository-Regeln
 

tests/Architecture/CodexSkillsContractTest.php

@@ -63,5 +63,41 @@ class CodexSkillsContractTest extends TestCase
         $this->assertStringContainsString('--check', $script);
         $this->assertStringContainsString('--apply', $script);
         $this->assertStringContainsString('mode="check"', $script);
+        $this->assertStringContainsString('"core-guardrails"', $script);
+        $this->assertStringContainsString('"starterkit-planner"', $script);
+        $this->assertStringContainsString('"starterkit-grid-standards"', $script);
+        $this->assertStringContainsString('"starterkit-php-style-ci"', $script);
+    }
+
+    public function testDocumentationLinksResolveInReadmeDocsAndSourceMap(): void
+    {
+        $files = [
+            'README.md',
+            'tools/codex-skills/core-guardrails/references/source-map.md',
+        ];
+
+        $docFiles = glob($this->projectRootPath() . '/docs/*.md');
+        $this->assertNotFalse($docFiles, 'Failed to enumerate docs/*.md files.');
+        foreach ($docFiles as $fullPath) {
+            $files[] = 'docs/' . basename($fullPath);
+        }
+
+        foreach ($files as $file) {
+            $content = $this->readProjectFile($file);
+            preg_match_all('/(?<![A-Za-z0-9_])\\/?docs\\/[a-z0-9_\\/-]+\\.md\\b/', $content, $matches);
+            foreach (array_unique($matches[0]) as $link) {
+                $normalized = ltrim($link, '/');
+                $absolute = $this->projectRootPath() . '/' . $normalized;
+                $this->assertFileExists($absolute, sprintf('Broken docs link "%s" in %s', $link, $file));
+            }
+        }
+    }
+
+    public function testDocsSkillsAuditPolicyExists(): void
+    {
+        $policy = $this->readProjectFile('agent-system/checks/docs-skills-audit-policy.md');
+        $this->assertStringContainsString('P0', $policy);
+        $this->assertStringContainsString('P1', $policy);
+        $this->assertStringContainsString('DOCS-SKILLS-AUDIT-00x', $policy);
     }
 }

tools/codex-skills/core-guardrails/references/source-map.md

@@ -2,24 +2,24 @@
 
 ## Kernregeln
 
-- Architektur- und Schichtgrenzen: `/docs/architektur.md`
+- Architektur- und Schichtgrenzen: `/docs/explanation-architektur.md`
-- `lib/**`-Regeln und Instanziierung: `/docs/lib-standards.md`
+- `lib/**`-Regeln und Instanziierung: `/docs/reference-lib-standards.md`
-- Kurzkonventionen: `/docs/konventionen.md`
+- Kurzkonventionen: `/docs/reference-konventionen.md`
-- Request/Input/Validation: `/docs/request-input-validation.md`
+- Request/Input/Validation: `/docs/howto-request-input-validation.md`
 
 ## UI-/Frontend-Contracts
 
-- JavaScript-Standards und Wrapper: `/docs/frontend-javascript.md`
+- JavaScript-Standards und Wrapper: `/docs/reference-frontend-javascript.md`
-- CSS-Standards und Scope-Regeln: `/docs/frontend-css.md`
+- CSS-Standards und Scope-Regeln: `/docs/reference-frontend-css.md`
-- DoD-Checks: `/docs/entwickler-checkliste.md`
+- DoD-Checks: `/docs/reference-entwickler-checkliste.md`
-- Rollen-Workflow (Planner/Executor/Reviewer/Finalizer): `/docs/agents/overview.md`
+- Rollen-Workflow (Planner/Executor/Reviewer/Finalizer): `/docs/reference-agents-overview.md`
 
 ## Security / RBAC
 
-- RBAC-Erweiterungen: `/docs/rbac-permissions-playbook.md`
+- RBAC-Erweiterungen: `/docs/howto-rbac-permissions-playbook.md`
-- Sicherheitsmodell: `/docs/sicherheitsmodell.md`
+- Sicherheitsmodell: `/docs/explanation-sicherheitsmodell.md`
 
 ## Betrieb und Qualitaetschecks
 
-- Entwickler-Checkliste: `/docs/entwickler-checkliste.md`
+- Entwickler-Checkliste: `/docs/reference-entwickler-checkliste.md`
-- Architektur-Request-Flow: `/docs/03-architektur-request-flow.md`
+- Architektur-Request-Flow: `/docs/tutorial-04-architektur-request-flow.md`