diff --git a/.gitignore b/.gitignore
index dd574cd..a52faa8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 .cursor/
 .github/copilot-instructions.md
 AGENTS.md
+.ai
diff --git a/docs/ai-context.md b/docs/ai-context.md
new file mode 100644
index 0000000..9a0969b
--- /dev/null
+++ b/docs/ai-context.md
@@ -0,0 +1,51 @@
+# AI Context: Gitea Actions CI -kirjasto
+
+**Updated**: 2026-06-08
+
+## Project Overview
+Gitea Actions reusable workflow -kirjasto mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessien orkestrointiin. Korvaa `ci-jenkins-library`:n Gitea-natiivilla toteutuksella. Mikropalvelut käyttävät kirjastoa `uses:`-direktiivillä ja konfiguroivat itsensä `ci-flow-values.yaml`:lla.
+
+## Architecture
+- 4 reusable workflow'ta: `ci-feature.yml`, `ci-master.yml`, `deploy.yml`, `test.yml`
+- 4 jaettua bash-skriptiä (`scripts/`): `report-status.sh`, `dispatch-workflow.sh`, `push-reports.sh`, `tag-commit.sh`
+- Raportit MinIO:ssa (S3 + static web), OIDC-autentikointi Traefikin kautta
+- Cross-repo commit traceability Gitea REST API:n kautta
+- `report-service/`-moduuli samassa repossa: raporttiskriptit, retention CronJob, index.html-generointi
+- Normatiivinen arkkitehtuuri: `docs/architecture.md`, perustelut `docs/design-rationale.md`
+
+## Repository Structure
+| Path | Purpose |
+|---|---|
+| `.gitea/workflows/` | Reusable workflow -tiedostot (`ci-feature.yml`, `ci-master.yml`, `deploy.yml`, `test.yml`) |
+| `scripts/` | Jaetut bash-skriptit |
+| `report-service/` | Raporttipalvelun koodi (retention, indeksigenerointi) |
+| `docs/` | Arkkitehtuuri-, vaatimus- ja konfiguraatiodokumentaatio |
+
+## Key Technical Decisions
+- **Vain Gitea.** Ei multi-platform-tukea (GitLab, BitBucket, GitHub)
+- **Ei omaa runtimea.** Reusable workflowt, ei Docker custom actioneita (ellei pakko)
+- **Konfiguraatio repoon.** `ci-flow-values.yaml` projektin juuressa, infra-asetukset Gitea org secrets/variables
+- **Vaiheittainen test flow.** Ei rinnakkaista suoritusta — deterministinen, debuggattava
+- **Raportit MinIO:ssa.** Gitea artifact-järjestelmä ei tue HTML-selailtavuutta
+- **Docker-rekisterit:** MVP:ssä vain Gitea Packages. Factory/adapter-pattern valmiina Artifactorylle/Nexukselle
+- **MVP-scope:** `doNotDowngrade` ei mukana, vain Gitea Packages docker-rekisterinä
+
+## Tech Stack
+- **Runtime:** Bash 4.0+, curl 7.0+, jq 1.6+, git 2.30+, MinIO client (`mc`)
+- **Alusta:** Gitea Actions 1.21+, Gitea act runner 0.2+
+- **Integraatiot:** Gitea REST API (`/api/v1/`), MinIO S3 API, SonarQube REST API
+- **Tuetut build-ekosysteemit:** Java/Maven, Java/Gradle, Node.js/npm
+- **Tuetut testikehykset:** Cucumber, JUnit, JaCoCo, Maven Site, custom HTML
+
+## Common Commands
+- Workflow-triggerit: `push` branchiin tai `workflow_dispatch`
+- Skriptien kutsuminen tapahtuu workflow-stepeistä, ei paikallisesti
+- `ci-flow-values.yaml` validointi: skeema `docs/config-model.md`:ssa
+
+## What NOT to Do
+- Älä lisää tukea muille Git-alustoille (GitLab, BitBucket, GitHub)
+- Älä lisää Docker custom actioneita ilman pakottavaa syytä
+- Älä siirrä konfiguraatiota pois reposita (`ci-flow-values.yaml`)
+- Älä lisää rinnakkaista test flow -suoritusta
+- Älä lisää ulkoista orkestraattoria — Gitea REST API riittää
+- Älä käytä `repository_dispatch`-webhookia test flow -ketjutukseen