diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5649ed1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,30 @@
+# AGENTS
+
+## Repo Snapshot (verified)
+- This is a .NET 8 solution with 4 projects: API (`src/presentation/DigitalData.TaskFlow.API`), Application, Domain, Infrastructure.
+- `Program.cs` only wires DI + Swagger + `MapControllers`; there are currently no controller classes, so no HTTP endpoints are exposed yet.
+- There is no test project in the repository right now.
+
+## High-value Commands
+- Restore/build whole solution from repo root:
+  - `dotnet restore DigitalData.TaskFlow.sln`
+  - `dotnet build DigitalData.TaskFlow.sln`
+- Run API project:
+  - `dotnet run --project src/presentation/DigitalData.TaskFlow.API/DigitalData.TaskFlow.API.csproj`
+- Focused build for one layer:
+  - `dotnet build src/core/DigitalData.TaskFlow.Application/DigitalData.TaskFlow.Application.csproj`
+
+## Architecture That Matters During Edits
+- Dependency direction is strict: `API -> Application -> Domain`; `Infrastructure` depends on `Application` + `Domain` and is injected by API.
+- Application layer uses MediatR + FluentValidation pipeline behavior (`ValidationBehavior<,>`) + AutoMapper profile (`ApplicationMappingProfile`).
+- Response contract is centralized in Domain `ApiEnvelope<T>` + `MetaEntry`; use `ApiEnvelopeFactory` for consistent `meta.code/message` mapping.
+- Infrastructure registers `TaskFlowDbContext` and repository interfaces in `DependencyInjection.cs`; missing `ConnectionStrings:TaskFlowDb` throws at startup.
+- DB row-shape models (for procedures/views) live in Infrastructure (`Persistence/Models`), not in Domain.
+
+## Current Implementation Gaps (easy to miss)
+- `DocumentRepository` and `WorkflowRepository.CloseAsync` are still baseline/stub implementations returning placeholder data.
+- `WorkflowListingReadModel` column mapping is based on read-only DB metadata and observed SP result sets; final shape must be re-verified from DB metadata (`sp_describe_first_result_set` or equivalent) before production hardening.
+- `Swagger:EnabledInProduction` exists in config model but is not used in `Program.cs` yet.
+
+## Config/Security Gotcha
+- `src/presentation/DigitalData.TaskFlow.API/appsettings.json` currently contains a concrete SQL connection string and a MediatR license key; treat this file as sensitive and avoid propagating those values in docs, logs, or commits.
diff --git a/src/infrastructure/DigitalData.TaskFlow.Infrastructure/README.md b/src/infrastructure/DigitalData.TaskFlow.Infrastructure/README.md
index 42c8c94..4af281c 100644
--- a/src/infrastructure/DigitalData.TaskFlow.Infrastructure/README.md
+++ b/src/infrastructure/DigitalData.TaskFlow.Infrastructure/README.md
@@ -26,6 +26,15 @@ Die Infrastructure-Schicht setzt die in Application definierten Abstraktionen ko
 - `Persistence/Models/`
   - Keyless Modelle fuer Procedure-Ergebnisse.
 
+## Wichtiger Hinweis zu DB-Spaltennamen
+
+- Spaltennamen in `Persistence/Models` (z. B. `WorkflowListingReadModel`) basieren aktuell auf:
+  - read-only Abfragen auf `sys.columns` (u. a. `TBCUST_F19_LISTING_RESULT`),
+  - beobachteten Result-Sets von `PRCUST_F19_GET_LISTING_DATA` im `table`-Modus.
+- Vor produktiven Aenderungen muss das finale SP-Resultset read-only verifiziert werden, idealerweise mit
+  `sp_describe_first_result_set` oder einer gleichwertigen Metadata-Pruefung.
+- Domain-Modelle bleiben davon getrennt: DB-Feldnamen werden nur in Infrastructure gemappt, nicht in Domain.
+
 ## Architektur-Regeln
 
 - Keine Controller- oder HTTP-Logik.