Remove Logs & Artifacts page

This reverts commit 4affeae616af7d7f2510af4b724517f317388eb2.

.claude/CLAUDE.md

@@ -0,0 +1,74 @@
+# Technical Documentation Guidelines
+
+You are an expert technical writer with deep expertise in creating clear, concise, and well-structured documentation. Your goal is to produce documentation that flows naturally while maintaining technical accuracy.
+
+## Core Principles
+
+### 1. Conciseness and Clarity
+- Use clear, direct language
+- Eliminate unnecessary words and redundancy
+- Make every sentence count
+- Prefer active voice over passive voice
+- Use short paragraphs (3-5 sentences maximum)
+
+### 2. Structure and Organization
+- Start with the most important information
+- Use logical hierarchies with consistent heading levels
+- Group related concepts together
+- Provide clear navigation through table of contents when appropriate
+- Use lists for sequential steps or related items
+
+### 3. Flow and Readability
+- Ensure smooth transitions between sections
+- Connect ideas logically
+- Build complexity gradually
+- Use examples to illustrate concepts
+- Maintain consistent terminology throughout
+
+### 4. Technical Accuracy
+- Be precise with technical terms
+- Include relevant code examples that are tested and functional
+- Document edge cases and limitations
+- Provide accurate command syntax and parameters
+- Link to related documentation when appropriate
+
+## Documentation Structure
+
+### Standard Document Layout
+1. **Title** - Clear, descriptive heading
+2. **Overview** - Brief introduction (2-3 sentences)
+3. **Prerequisites** - What the reader needs to know or have
+4. **Main Content** - Organized in logical sections
+5. **Examples** - Practical, real-world use cases
+6. **Troubleshooting** - Common issues and solutions (when applicable)
+7. **Related Resources** - Links to additional documentation
+
+### Code Examples
+- Provide complete, runnable examples
+- Include comments for complex logic
+- Show expected output
+- Use consistent formatting and syntax highlighting
+
+### Commands and APIs
+- Show full syntax with all parameters
+- Indicate required vs optional parameters
+- Provide parameter descriptions
+- Include return values or output format
+
+## Writing Style
+
+- **Be direct**: "Configure the database" not "You should configure the database"
+- **Be specific**: "Set timeout to 30 seconds" not "Set an appropriate timeout"
+- **Be consistent**: Use the same terms for the same concepts
+- **Be complete**: Don't assume implicit knowledge; explain as needed
+
+## When Uncertain
+
+**If you don't know something or need clarification:**
+- Ask specific questions
+- Request examples or use cases
+- Clarify technical details or edge cases
+- Verify terminology and naming conventions
+- Confirm target audience and their expected knowledge level
+
+Your expertise is in writing excellent documentation. Use your judgment to create documentation that serves the reader's needs effectively. When in doubt, ask rather than guess.

.envrc.example

@@ -0,0 +1 @@
+use flake

.github/workflows/test.yml

@@ -1,8 +1,8 @@
 name: Hugo Site Tests
 
 on:
-  push:
+#   push:
-    branches: [ main ]
+#     branches: [ main ]
   pull_request:
     branches: [ main ]
 

.gitignore

@@ -35,3 +35,7 @@ Thumbs.db
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+### direnv ###
+.direnv
+.envrc

README.md

@@ -4,20 +4,60 @@ Documentation for the edgeDeveloperFramework (eDF) project and the resulting Edg
 
 ## Quick Start
 
+### Development Environment
+
+Install and enter [Devbox](https://www.jetify.com/devbox):
 ```bash
-# Install dependencies
+curl -fsSL https://get.jetify.com/devbox | bash
-task deps
+devbox shell
-
-# Start local development server
-task serve
-
-# Run tests
-task test
-
-# Build production site
-task build
 ```
 
+Devbox installs Hugo, Node.js, Go, and all required tools. First-time setup requires sudo for the Nix daemon (one-time only).
+
+To avoid entering the shell, run commands directly:
+```bash
+devbox run task serve
+```
+
+### Local Development
+
+```bash
+task deps:install    # Install dependencies
+task serve          # Start dev server at http://localhost:1313 (hot-reloading)
+task test:quick     # Run tests
+task build          # Build production site
+```
+
+## Architecture Diagrams (LikeC4)
+
+[LikeC4](https://likec4.dev/) generates interactive architecture diagrams from text-based [C4 models](https://c4model.com/). Create or edit diagrams:
+
+```bash
+cd resources/edp-likec4     # Platform architecture
+npm install                 # First time only
+npm start                   # Preview at http://localhost:5173
+```
+
+Edit `.c4` files to define systems and views. Generate web components for Hugo:
+```bash
+task likec4:generate
+```
+
+Embed in Markdown pages:
+```markdown
+{{</* likec4-view view="overview" project="architecture" */>}}
+```
+
+See [LikeC4 documentation](https://likec4.dev/) for detailed syntax and [README-likec4.md](doc/README-likec4.md) for project-specific details.
+
+## Deployment
+
+Deployment is automatic via ArgoCD. Push to `main` triggers CI/CD build and deployment within 5-10 minutes.
+
+**Infrastructure Configuration:**
+- ArgoCD is configured within [stacks-instances](https://edp.buildth.ing/DevFW-CICD/stacks-instances/src/branch/main/otc/edp.buildth.ing/registry/docs.yaml)
+- Documentation stack definition: [./argocd-stack/](https://edp.buildth.ing/DevFW-CICD/website-and-documentation/src/branch/main/argocd-stack)
+
 ## Documentation
 
 * [Developer Guide](doc/README-developer.md)

Taskfile.yml

@@ -43,7 +43,7 @@ tasks:
       - deps:ensure-npm
       - build:generate-info
     cmds:
-      - "{{.HUGO_CMD}} server"
+      - "{{.HUGO_CMD}} server --noHTTPCache"
 
   clean:
     desc: Clean build artifacts
@@ -166,14 +166,14 @@ tasks:
     generates:
       - node_modules/.package-lock.json
     cmds:
-      - "{{.NPM_CMD}} install"
+      - "{{.NPM_CMD}} ci"
     status:
       - test -d node_modules
 
   deps:install:
     desc: Install all dependencies
     cmds:
-      - "{{.NPM_CMD}} install"
+      - "{{.NPM_CMD}} ci"
       - "{{.HUGO_CMD}} mod get -u"
       - "{{.HUGO_CMD}} mod tidy"
 

argocd-stack/docs.yaml

@@ -0,0 +1,28 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: docs
+  namespace: argocd
+  labels:
+    env: prod
+spec:
+  project: default
+  syncPolicy:
+    automated:
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+      - ServerSideApply=true
+  destination:
+    name: in-cluster
+    namespace: docs
+  syncOptions:
+    - CreateNamespace=true
+  sources:
+    - repoURL: https://edp.buildth.ing/DevFW-CICD/website-and-documentation
+      targetRevision: HEAD
+      path: argocd-stack/helm
+      helm:
+        parameters:
+        - name: image.tag
+          value: $ARGOCD_APP_REVISION_SHORT

argocd-stack/helm/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

argocd-stack/helm/Chart.yaml

@@ -0,0 +1,24 @@
+apiVersion: v2
+name: helm
+description: Deploy documentation to edp.buildth.ing
+
+# A chart can be either an 'application' or a 'library' chart.
+#
+# Application charts are a collection of templates that can be packaged into versioned archives
+# to be deployed.
+#
+# Library charts provide useful utilities or functions for the chart developer. They're included as
+# a dependency of application charts to inject those utilities and functions into the rendering
+# pipeline. Library charts do not define any templates and therefore cannot be deployed.
+type: application
+
+# This is the chart version. This version number should be incremented each time you make changes
+# to the chart and its templates, including the app version.
+# Versions are expected to follow Semantic Versioning (https://semver.org/)
+version: 0.1.0
+
+# This is the version number of the application being deployed. This version number should be
+# incremented each time you make changes to the application. Versions are not expected to
+# follow Semantic Versioning. They should reflect the version the application is using.
+# It is recommended to use it with quotes.
+appVersion: "1.16.0"

argocd-stack/helm/templates/deploy.yaml

@@ -0,0 +1,62 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: docs
+  name: docs
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: docs
+  strategy: {}
+  template:
+    metadata:
+      labels:
+        app: docs
+    spec:
+      containers:
+        - image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          name: docs
+          ports:
+            - name: http
+              containerPort: 80
+              protocol: TCP
+          resources: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: docs
+spec:
+  selector:
+    app: docs
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 80
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: docs
+  annotations:
+    cert-manager.io/cluster-issuer: main
+    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
+spec:
+  ingressClassName: nginx
+  rules:
+    - host: docs.edp.buildth.ing
+      http:
+        paths:
+          - backend:
+              service:
+                name: docs
+                port:
+                  number: 80
+            path: /
+            pathType: Prefix
+  tls:
+    - hosts:
+        - docs.edp.buildth.ing
+      secretName: docs-edp-buildth-ing-tls

argocd-stack/helm/values.yaml

@@ -0,0 +1,4 @@
+
+image:
+  repository: edp.buildth.ing/devfw-cicd/website-and-documentation
+  tag: "UNKNOWN_TAG"

content/en/_index.md

@@ -16,22 +16,22 @@ Built on open standards and battle-tested technologies.
 
 {{% blocks/section color="dark" type="row" %}}
 
-{{% blocks/feature icon="fa-solid fa-diagram-project" title="Architecture Documentation" url="/docs/architecture/" %}}
+{{% blocks/feature icon="fa-solid fa-diagram-project" title="Edge Developer Platform (EDP)" url="/docs/edp/" %}}
-Explore the platform's architecture with interactive C4 diagrams. Understand the system design, components, and deployment topology.
+Understand EDP as the developer platform hub (Forgejo, CI/CD, deployment, operations) and how it connects inner loop and outer loop workflows.
 
-**Dive into the architecture →**
+**Dive into EDP docs →**
 {{% /blocks/feature %}}
 
-{{% blocks/feature icon="fa-solid fa-book-open" title="Technical Writer Guide" url="/docs/documentation/" %}}
+{{% blocks/feature icon="fa-solid fa-cloud" title="EdgeConnect Cloud" url="/docs/edgeconnect/" %}}
-Learn how to contribute to this documentation. Write content, test locally, and understand the CI/CD pipeline.
+Learn what EdgeConnect is, how it is consumed via stable entry points (CLI, SDK, Terraform), and how EDP integrates with it as a deployment target.
 
-**Start documenting →**
+**Explore EdgeConnect →**
 {{% /blocks/feature %}}
 
-{{% blocks/feature icon="fa-solid fa-archive" title="Legacy Documentation (v1)" url="/docs/v1/" %}}
+{{% blocks/feature icon="fa-solid fa-scale-balanced" title="Governance" url="/docs/governance/" %}}
-Access the previous version of our documentation including historical project information and early architecture decisions.
+Read the project history, decision context, and audit-oriented traceability to primary sources and repository artifacts.
 
-**Browse v1 docs →**
+**Go to Governance →**
 {{% /blocks/feature %}}
 
 {{% /blocks/section %}}
@@ -76,11 +76,11 @@ Access the previous version of our documentation including historical project in
 
 ## Get Started
 
-Whether you're a **platform engineer**, **application developer**, or **technicalWriter**, we have resources for you:
+Whether you're a **platform engineer**, **application developer**, or **auditor**, we have resources for you:
 
-* 📖 Read the [Documentation](/docs/) to understand the platform
+* 📖 Start at [Documentation](/docs/)
-* 🏗️ Explore [Platform Components](/docs/components/) and their usage
+* 🧭 Read [Edge Developer Platform (EDP)](/docs/edp/)
-* ✍️ Learn [How to Document](/docs/DOCUMENTATION-GUIDE/) and contribute
+* ☁️ Read [EdgeConnect Cloud](/docs/edgeconnect/)
-* 🔍 Browse [Legacy Documentation](/docs-old/) for historical context
+* 🧾 Read [Governance](/docs/governance/)
 
 {{% /blocks/section %}}

content/en/blog/20250401_review.md

@@ -1,84 +0,0 @@
-# Review
-
-1) 09h35 Marco
-business plan
-issue: value of software, depreciation
-FTE: around 100 overall, 3 full teams of developers
-tax discussion
-
-10h04 Discussions
-
-2) 10h10 Julius
-
-3) 10h27 Sebastiano - DevDay bis 10h40
-
-schriften bei votes größer - fragen sollten lesbar sein!
-
-devops is dead .... claim
-
-
-4) Stephan bis 10h55
-
-5) christopher 10h58
-
-6) robert 11:11
-* app
-* devops-pipelines
-* edp in osc deployed
-
-7) michal has nothing to show
-
-8) evgenii wants to finish -- 11:30
-
-9) patrick 11:32
-
-
-====
-
-projekt management meeting
-
-workshops, externe teams
-
-customer episodes
-
-wem was wo prinzipien
-|
-Rollen, Personas
-
-weiter die perspektive des nutzers bekommen, inneres verlangen eines developers, mein anspruch an das EDP
-(bekommen wir das hin, möchte ic damit arbeiten)
-
-level 2 erklimmen
-
-workshops halten
-
-senioren bekommen
-
-
-level1: source code structure, artefakte builden, revision control, branching model, e.g. pull requesting, tests der software, local debugging
-level2: automatisierung des artefakte-builds, versionsmgmt, milestones, tickets, issues, compliances an security
-level3: deployment auf stages, feedback pipeline verhalten
-level4: feedback app-verhalten (logs, metrics, alerts) + development loop
-level5: 3rd level support in production
-
-level1: coding
-source code structure, artefakte builden, revision control, branching model, e.g. pull requesting, tests der software, local debugging
-
-level2: reaching the outdside world with output
-automatisierung des artefakte-builds, versionsmgmt, milestones, tickets, issues, compliances an security
-
-level3: run the app anywhere
-deployment auf stages, feedback pipeline verhalten
-
-level4: monitoring the app
-feedback app-verhalten (logs, metrics, alerts) + development loop
-
-level5: support
-3rd level support in production (or any outer stage)
-
-
-sprint 4
-leveraging säule
-eigene app säule
-chore säule
-

content/en/blog/20251027_important_links.md

@@ -1,6 +0,0 @@
----
-title: important links
-weight: 20
----
-
-* Gardener login to Edge and orca cluster: IPCEICIS-6222

content/en/blog/240823-archsession.md

@@ -1,40 +0,0 @@
----
-title: Architecture session
-weight: 20
----
-
-
-## Platform Generics
-
-* https://tag-app-delivery.cncf.io/whitepapers/platforms/#capabilities-of-platforms
-
-* https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/
-
-* https://humanitec.com/blog/wtf-internal-developer-platform-vs-internal-developer-portal-vs-paas
-
-## reference architecture + Portfolio
-
-* https://platformengineering.org/blog/create-your-own-platform-engineering-reference-architectures
-
-* https://humanitec.com/reference-architectures
-
-* https://www.youtube.com/watch?v=AimSwK8Mw-U
-
-
-## Platform Portfolio
-
-### Viktor Farcic
-
-* https://technologyconversations.com/
-
-* https://technologyconversations.com/2024/01/08/the-best-devops-tools-platforms-and-services-in-2024/
-
-
-### Internal devloper platform
-
-* https://internaldeveloperplatform.org/core-components/
-
-### Workflow / CI/CD
-
-* https://cnoe.io/blog/optimizing-data-quality-in-dev-portals
-

content/en/docs/Autonomous UAT Agent/_index.md

@@ -0,0 +1,12 @@
+---
+title: "Autonomous UAT Agent"
+linkTitle: "Autonomous UAT Agent"
+weight: 10
+description: >
+  General documentation for D66 and the Autonomous UAT Agent
+---
+
+This section contains the core documentation for D66, focusing on how the Autonomous UAT Agent works and how to run it.
+
+“Autonomous UAT Agent” is the current working title of the application; **UAT** stands for **User Acceptance Testing** (i.e., end-to-end testing from a user’s perspective).
+

content/en/docs/Autonomous UAT Agent/agent-workflow-diagram.md

@@ -0,0 +1,106 @@
+---
+title: "Agent Workflow Diagram"
+linkTitle: "UAT Agent Workflow Diagram"
+weight: 5
+description: >
+  Visual workflow of a typical Agent S (Autonomous UAT Agent) run (gui_agent_cli.py) across Ministral, Holo, and VNC
+---
+This page provides a **visual sketch** of the typical workflow (example: `gui_agent_cli.py`).
+
+## Workflow (fallback without Mermaid)
+
+If Mermaid rendering is not available or fails in your build, this section shows the same workflow as plain text.
+
+```text
+Operator/Prompt
+  -> gui_agent_cli.py
+     -> (1) Planning request  -> Ministral vLLM (thinking)
+     <-     Next action intent
+     -> (2) Screenshot capture -> VNC Desktop / Firefox
+     <-     PNG screenshot
+     -> (3) Grounding request  -> Holo vLLM (vision)
+     <-     Coordinates + element metadata
+     -> (4) Execute action     -> VNC Desktop / Firefox
+     -> Artifacts saved        -> results/ (logs, screenshots, JSON)
+```
+
+| Step | From | To | What | Output |
+|---:|---|---|---|---|
+| 0 | Operator | gui_agent_cli.py | Provide goal / prompt | Goal text |
+| 1 | gui_agent_cli.py | Ministral vLLM | Plan next step (text) | Next action intent |
+| 2 | gui_agent_cli.py | VNC Desktop | Capture screenshot | PNG screenshot |
+| 3 | gui_agent_cli.py | Holo vLLM | Ground UI element(s) | Coordinates + element metadata |
+| 4 | gui_agent_cli.py | VNC Desktop | Execute click/type/scroll | UI state change |
+| 5 | gui_agent_cli.py | results/ | Persist evidence | Logs + screenshots + JSON |
+
+## High-level data flow
+
+```mermaid
+flowchart LR
+  %% Left-to-right overview of one typical agent loop
+
+  user[Operator / Prompt] --> cli[Agent S script<br/>gui_agent_cli.py]
+
+  subgraph OTC[OTC (Open Telekom Cloud)]
+    subgraph MIN_HOST[ecs_ministral_L4]
+      MIN[(Ministral 3 8B<br/>Thinking / Planning)]
+    end
+
+    subgraph HOLO_HOST[ecs_holo_A40]
+      HOLO[(Holo 1.5-7B<br/>Vision / Grounding)]
+    end
+
+    subgraph TARGET[GUI test target]
+      VNC[VNC / Desktop]
+      FF[Firefox]
+      VNC --> FF
+    end
+  end
+
+  cli -->|1. plan step<br/>vLLM_THINKING_ENDPOINT| MIN
+  MIN -->|next action<br/>click / type / wait| cli
+
+  cli -->|2. capture screenshot| VNC
+  VNC -->|screenshot (PNG)| cli
+
+  cli -->|3. grounding request<br/>vLLM_VISION_ENDPOINT| HOLO
+  HOLO -->|coordinates + UI element info| cli
+
+  cli -->|4. execute action<br/>mouse / keyboard| VNC
+
+  cli -->|logs + screenshots| artifacts[(Artifacts<br/>logs, screenshots, JSON comms)]
+```
+
+## Sequence (one loop)
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as Operator
+  participant CLI as gui_agent_cli.py
+  participant MIN as Ministral vLLM (ecs_ministral_L4)
+  participant VNC as VNC Desktop (Firefox)
+  participant HOLO as Holo vLLM (ecs_holo_A40)
+
+  U->>CLI: Provide goal / prompt
+
+  loop Step loop (until done)
+    CLI->>MIN: Plan next step (text-only reasoning)
+    MIN-->>CLI: Next action (intent)
+
+    CLI->>VNC: Capture screenshot
+    VNC-->>CLI: Screenshot (image)
+
+    CLI->>HOLO: Ground UI element(s) in screenshot
+    HOLO-->>CLI: Coordinates + element metadata
+
+    CLI->>VNC: Execute click/type/scroll
+  end
+
+  CLI-->>U: Result summary + saved artifacts
+```
+
+## Notes
+
+- The **thinking** and **grounding** models are separate on purpose: it improves coordinate reliability and makes failures easier to debug.
+- The agent loop typically produces artifacts (logs + screenshots) which are later copied into D66 evidence bundles.

content/en/docs/Autonomous UAT Agent/model-stack.md

@@ -0,0 +1,80 @@
+---
+title: "Model Stack"
+linkTitle: "Model Stack"
+weight: 4
+description: >
+  Thinking vs grounding model split for D66 (current state and target state)
+---
+
+For a visual overview of how the models interact with the VNC-based GUI automation loop, see: [Workflow Diagram](./agent-workflow-diagram.md)
+
+## Requirement
+
+The Autonomous UAT Agent must use **open-source models from European companies**. This has been a project requirement form the very beginnning of this project.
+
+## Target setup
+
+- **Thinking / planning:** Ministral
+- **Grounding / coordinates:** Holo 1.5
+
+The Agent S framework runs an iterative loop: it uses a reasoning model to decide *what to do next* (plan the next action) and a grounding model to translate UI intent into *pixel-accurate coordinates* on the current screenshot. This split is essential for reliable GUI automation because planning and “where exactly to click” are different problems and benefit from different model capabilities.
+
+## Why split models?
+
+- Reasoning models optimize planning and textual decision making
+- Vision/grounding models optimize stable coordinate output
+- Separation reduces “coordinate hallucinations” and makes debugging easier
+
+## Current state in repo
+
+- Some scripts and docs still reference historical **Claude** and **Pixtral** experiments.
+- **Pixtral is not suitable for pixel-level grounding in this use case**: in our evaluations it did not provide the consistency and coordinate stability required for reliable UI automation.
+- In an early prototyping phase, **Anthropic Claude Sonnet** was useful due to strong instruction-following and reasoning quality; however it does not meet the D66 constraints (open-source + European provider), so it could not be used for the D66 target solution.
+
+## Current configuration (D66)
+
+### Thinking model: Ministral 3 8B (Instruct)
+
+- HuggingFace model card: https://huggingface.co/mistralai/Ministral-3-8B-Instruct-2512
+- Runs on **OTC (Open Telekom Cloud) ECS**: `ecs_ministral_L4` (public IP: `164.30.28.242`)
+  - Flavor: GPU-accelerated | 16 vCPUs | 64 GiB | `pi5e.4xlarge.4`
+  - GPU: 1 × NVIDIA Tesla L4 (24 GiB)
+  - Image: `Standard_Ubuntu_24.04_amd64_bios_GPU_GitLab_3074` (Public image)
+- Deployment: vLLM OpenAI-compatible endpoint (chat completions)
+  - Endpoint env var: `vLLM_THINKING_ENDPOINT`
+  - Current server (deployment reference): `http://164.30.28.242:8001/v1`
+
+**Operational note:** vLLM is configured to **auto-start on server boot** (OTC ECS restart) via `systemd`.
+
+**Key serving settings (vLLM):**
+
+- `--gpu-memory-utilization 0.90`
+- `--max-model-len 32768`
+- `--host 0.0.0.0`
+- `--port 8001`
+
+**Key client settings (Autonomous UAT Agent scripts):**
+
+- `model`: `/home/ubuntu/ministral-vllm/models/ministral-3-8b`
+- `temperature`: `0.0`
+
+### Grounding model: Holo 1.5-7B
+
+- HuggingFace model card: https://huggingface.co/holo-1.5-7b
+- Runs on **OTC (Open Telekom Cloud) ECS**: `ecs_holo_A40` (public IP: `164.30.22.166`)
+  - Flavor: GPU-accelerated | 48 vCPUs | 384 GiB | `g7.12xlarge.8`
+  - GPU: 1 × NVIDIA A40 (48 GiB)
+  - Image: `Standard_Ubuntu_24.04_amd64_bios_GPU_GitLab_3074` (Public image)
+- Deployment: vLLM OpenAI-compatible endpoint (multimodal grounding)
+  - Endpoint env var: `vLLM_VISION_ENDPOINT`
+  - Current server (deployment reference): `http://164.30.22.166:8000/v1`
+
+**Key client settings (grounding / coordinate space):**
+
+- `model`: `holo-1.5-7b`
+- Native coordinate space: `3840×2160` (4K)
+- Client grounding dimensions:
+  - `grounding_width`: `3840`
+  - `grounding_height`: `2160`
+
+

content/en/docs/Autonomous UAT Agent/results/_index.md

@@ -0,0 +1,13 @@
+---
+title: "Results & Findings"
+linkTitle: "Results"
+weight: 20
+description: >
+  Results, findings, and evidence artifacts for D66
+---
+This section contains the outputs that support D66 claims: findings summaries and pointers to logs, screenshots, and run artifacts.
+
+## Pages
+
+- [PoC Validation](./poc-validation.md)
+- [Golden Run (Telekom Header Navigation)](./golden-run-telekom-header-nav/)

content/en/docs/Autonomous UAT Agent/results/golden-run-telekom-header-nav/index.md

@@ -0,0 +1,114 @@
+---
+title: "Golden Run: Telekom Header Navigation"
+linkTitle: "Golden Run (Telekom)"
+weight: 3
+description: >
+  Evidence pack (screenshots + logs) for the golden run on www.telekom.de header navigation
+---
+
+This page is the evidence pack for the **Autonomous UAT Agent** golden run on **www.telekom.de**.
+
+## Run intent
+
+- Goal: Test interactive elements in the header navigation for functional weaknesses
+- Output: Click-marked screenshots + per-run log (and optionally model communication JSON)
+
+## How the run was executed (ECS)
+
+Command (as used in the runbook):
+
+```bash
+python staging_scripts/gui_agent_cli.py \
+  --prompt "Role: You are a UI/UX testing agent specializing in functional correctness.
+Goal: Test all interactive elements in the header navigation on www.telekom.de for functional weaknesses.
+Tasks:
+1. Navigate to the website
+2. Identify and test interactive elements (buttons, links, forms, menus)
+3. Check for broken flows, defective links, non-functioning elements
+4. Document issues found
+Report Format:
+Return findings in the 'issues' field as a list of objects:
+- element: Name/description of the element
+- location: Where on the page
+- problem: What doesn't work
+- recommendation: How to fix it
+If no problems found, return an empty array: []" \
+  --max-steps 15
+```
+
+## Artifacts
+
+## Screenshot gallery
+
+### Thumbnail grid (recommended for many screenshots)
+
+Click any thumbnail to open the full image.
+
+<div style="display:grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 12px; align-items:start;">
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_001.png"><img src="screenshots/uat_agent_step_001.png" alt="UAT agent step 001" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 001</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_002.png"><img src="screenshots/uat_agent_step_002.png" alt="UAT agent step 002" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 002</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_003.png"><img src="screenshots/uat_agent_step_003.png" alt="UAT agent step 003" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 003</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_004.png"><img src="screenshots/uat_agent_step_004.png" alt="UAT agent step 004" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 004</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_005.png"><img src="screenshots/uat_agent_step_005.png" alt="UAT agent step 005" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 005</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_006.png"><img src="screenshots/uat_agent_step_006.png" alt="UAT agent step 006" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 006</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_007.png"><img src="screenshots/uat_agent_step_007.png" alt="UAT agent step 007" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 007</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_008.png"><img src="screenshots/uat_agent_step_008.png" alt="UAT agent step 008" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 008</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_010.png"><img src="screenshots/uat_agent_step_010.png" alt="UAT agent step 010" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 010</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_011.png"><img src="screenshots/uat_agent_step_011.png" alt="UAT agent step 011" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 011</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_012.png"><img src="screenshots/uat_agent_step_012.png" alt="UAT agent step 012" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 012</figcaption>
+  </figure>
+  <figure style="margin:0;">
+    <a href="screenshots/uat_agent_step_013.png"><img src="screenshots/uat_agent_step_013.png" alt="UAT agent step 013" style="width:100%; height:auto; border:1px solid #ddd; border-radius:6px;" /></a>
+    <figcaption style="text-align:center; font-size:0.9em;">Step 013</figcaption>
+  </figure>
+</div>
+
+<details>
+  <summary>Full-size images (stacked)</summary>
+
+  {{< figure src="screenshots/uat_agent_step_001.png" caption="Step 001" >}}
+  {{< figure src="screenshots/uat_agent_step_002.png" caption="Step 002" >}}
+  {{< figure src="screenshots/uat_agent_step_003.png" caption="Step 003" >}}
+  {{< figure src="screenshots/uat_agent_step_004.png" caption="Step 004" >}}
+  {{< figure src="screenshots/uat_agent_step_005.png" caption="Step 005" >}}
+  {{< figure src="screenshots/uat_agent_step_006.png" caption="Step 006" >}}
+  {{< figure src="screenshots/uat_agent_step_007.png" caption="Step 007" >}}
+  {{< figure src="screenshots/uat_agent_step_008.png" caption="Step 008" >}}
+  {{< figure src="screenshots/uat_agent_step_010.png" caption="Step 010" >}}
+  {{< figure src="screenshots/uat_agent_step_011.png" caption="Step 011" >}}
+  {{< figure src="screenshots/uat_agent_step_012.png" caption="Step 012" >}}
+  {{< figure src="screenshots/uat_agent_step_013.png" caption="Step 013" >}}
+
+</details>

content/en/docs/Autonomous UAT Agent/results/poc-validation.md

@@ -0,0 +1,26 @@
+---
+title: "PoC Validation"
+linkTitle: "PoC Validation"
+weight: 1
+description: >
+  What was validated and where to find the evidence
+---
+## What was validated
+
+- Autonomous GUI interaction via the Autonomous UAT Agent (Agent S3-based scripts)
+- Generation of UX findings and recommendations
+- Production of reproducible artifacts (screenshots, logs)
+
+## Where to find evidence in this repo
+
+- Run logs and calibration logs: `logs/`
+- Story evidence and investigation notes:
+  - `docs/story-025-001-context.md`
+  - `docs/story-026-001-context.md`
+  - `docs/story-023-003-coordinate-space-detection.md`
+
+## How to reproduce a run
+
+1. Choose a script in `Backend/IPCEI-UX-Agent-S3/staging_scripts/`
+2. Set target URL (if supported) via `AS2_TARGET_URL`
+3. Run and capture artifacts (see `docs/D66/documentation/outputs-and-artifacts.md`)

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/1- Funktionale Korrektheit von UI-Elementen/1 - Ergebnisse Agent S2.md

@@ -0,0 +1,37 @@
+---
+title: "Use Case 1 – Ergebnisse Agent S2"
+linkTitle: "UC1 – Agent S2"
+weight: 10
+draft: true
+description: >
+  Roh-Ergebnisse (PoC Validation) für Use Case 1 – Agent S2
+---
+
+## Kontext
+
+- Use Case: **Funktionale Korrektheit von UI-Elementen**
+- Zielsystem: **leipzig.de** (Fahrrad-Seite; siehe PoC-Kontext)
+- Prompt: siehe [1 - Prompt.md](./1%20-%20Prompt.md)
+
+## Executive Summary
+
+- **Ergebnis (positiv):** Es wurden **keine Broken Flows oder Sackgassen** identifiziert.
+- **Ergebnis (Auffälligkeit):** Ein zentrales UI-Element (Sprachauswahl) war für den Agenten **schwer auffindbar**, was auf potenzielle Usability-/Findability-Probleme hindeutet.
+
+## Findings (tabellarisch)
+
+| Element | Fundstelle | Reaktion sichtbar ≤ 500 ms | Sackgasse/Broken Flow | Problem-Beschreibung | Empfehlung |
+|---|---|---:|---:|---|---|
+| Sprache-Dropdown | Kopfbereich (oben rechts) | Nicht bewertet | Nein | Schwierigkeiten beim Lokalisieren der Sprach-Funktion; mehrfaches Scrollen und Fehlklicks (Browser-Menü statt Website-Element) deuten auf unklare Positionierung bzw. geringe Auffindbarkeit hin. | Sprachauswahl prominenter platzieren und visuell stärker auszeichnen (z. B. Flaggen-Icons, höherer Kontrast, größere Schrift). |
+
+## Positive Ergebnisse
+
+- ✅ Keine Broken Flows oder Sackgassen gefunden
+
+## Empfehlungen (konkret)
+
+1. Sprachauswahl mit internationalen Flaggen-Icons ergänzen (visuelle Erkennbarkeit)
+2. Kontrast und Schriftgröße des Sprachelements erhöhen
+3. Position in der Header-Zone prüfen und ggf. prominenter platzieren
+4. Kurztest mit internationalen Nutzern durchführen (Findability)
+5. Hover-/Fokus-Effekte verbessern, um Interaktivität eindeutiger zu signalisieren

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/1- Funktionale Korrektheit von UI-Elementen/1 - Ergebnisse Anthropic Computer Use.md

@@ -0,0 +1,49 @@
+---
+title: "Use Case 1 – Ergebnisse Anthropic Computer Use"
+linkTitle: "UC1 – Anthropic"
+weight: 20
+draft: true
+description: >
+  Roh-Ergebnisse (PoC Validation) für Use Case 1 – Anthropic Computer Use
+---
+
+## Kontext
+
+- Use Case: **Funktionale Korrektheit von UI-Elementen**
+- Zielsystem: **leipzig.de**
+- Prompt: siehe [1 - Prompt.md](./1%20-%20Prompt.md)
+
+## Executive Summary
+
+- **Funktionalität:** Alle getesteten Elemente wurden als **technisch funktionsfähig** bewertet.
+- **Hauptbefund:** Mehrere Interaktionen zeigen **verzögerte Antwortzeiten** (Reaktion nicht innerhalb von 500 ms; teils > 3 Sekunden Ladezeit).
+- **Flow-Qualität:** **Keine Broken Flows oder Sackgassen** identifiziert.
+
+Hinweis: Gemessene Ladezeiten können je nach Netzwerk, Serverlast und Client variieren; der Befund zeigt jedoch, dass Performance aus UX-Sicht ein zentraler Hebel ist.
+
+## Findings (tabellarisch)
+
+| Element | Fundstelle | Reaktion sichtbar ≤ 500 ms | Sackgasse/Broken Flow | Problem-Beschreibung | Empfehlung |
+|---|---|---:|---:|---|---|
+| Kontakt-Link (Top-Navigation) | https://www.leipzig.de/kontakt | Nein | Nein | Ladezeit über 3 Sekunden (verzögerte Antwortzeit). | Performance optimieren; Caching verbessern. |
+| RSS-Feeds Link (Top-Navigation) | https://www.leipzig.de/rss-feeds | Nein | Nein | Ladezeit über 3 Sekunden (verzögerte Antwortzeit). | Performance optimieren; Caching verbessern. |
+| Mediathek Link (Top-Navigation) | https://www.leipzig.de/servicenavigation/mediathek | Nein | Nein | Ladezeit über 3 Sekunden (verzögerte Antwortzeit). | Performance optimieren; Caching verbessern. |
+| Suchfunktion | Startseite (Suchfeld / Suchergebnisse) | Nein | Nein | Suchergebnisse laden über 3 Sekunden (verzögerte Antwortzeit). | Suchindex-Performance optimieren; Suchalgorithmus beschleunigen. |
+| Bürgerservice und Verwaltung (Hauptnavigation) | https://www.leipzig.de/buergerservice-und-verwaltung | Nein | Nein | Ladezeit über 3 Sekunden (verzögerte Antwortzeit). | Performance optimieren; Caching verbessern. |
+
+## Positive Ergebnisse
+
+- ✅ Alle getesteten Elemente funktionieren technisch korrekt
+- ✅ Keine Broken Flows oder Sackgassen gefunden
+- ✅ Vollständige Navigation und Breadcrumb-System
+- ✅ Funktionierende Mehrsprachigkeit
+- ✅ Korrekte URL-Struktur und Verlinkung
+- ✅ Responsive Elemente mit visueller Rückmeldung
+
+## Hauptempfehlung (Performance)
+
+1. Server-Response-Zeit optimieren
+2. Caching-Strategien verbessern
+3. Asset-Komprimierung implementieren
+4. CDN-Einsatz prüfen
+5. Datenbank-/Query-Optimierung

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/1- Funktionale Korrektheit von UI-Elementen/1 - Experteneinschätzung zum Vergleich der Agent Frameworks.md

@@ -0,0 +1,22 @@
+---
+title: "Use Case 1 – Experteneinschätzung (Agent Frameworks)"
+linkTitle: "UC1 – Experteneinschätzung"
+weight: 30
+draft: true
+description: >
+  Vergleich Agent S2 vs. Anthropic Computer Use (UC1)
+---
+
+Im direkten Vergleich zeigt Anthropic Computer Use eine stärkere Ausrichtung auf die technische Dimension der UI-Prüfung, insbesondere in Bezug auf Ladezeiten. Solche Aspekte sind aus UX-Sicht zwar relevant, lassen sich aber nur eingeschränkt bewerten – etwa wenn Ladezeiten subjektiv als störend empfunden werden oder Links ins Leere führen.
+
+  
+
+**Anthropic Computer Use**
+
+ ![(Info)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/information.svg)identifiziert Unterschiede bei Ladezeiten (z. B. Kontakt, RSS-Feeds vs. Mein Stadtteil). Diese sind jedoch noch im akzeptablen Bereich und kaum auffällig. Ich hätte sogar behauptet noch deutlich unter 3 Sekunden.
+
+✅ In der Mediathek sind die Ladezeiten dagegen spürbar verlängert, was tatsächlich einen UX-relevanten Warnhinweis darstellt.
+
+**Agent S2**
+
+![(Info)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/information.svg) liefert Ergebnisse, die stärker auf Usability und Barrierefreiheit (Sprach-Dropdown) abzielen. Diese Perspektive ist weniger technisch, aber für die praktische UX-Bewertung ebenso zentral. Hätte ich aber eher unter dem zweiten Prompt (Visuelle Qualität & Konsistenz bzw. UX Health Check) vermutet.

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/1- Funktionale Korrektheit von UI-Elementen/1 - Prompt.md

@@ -0,0 +1,55 @@
+---
+title: "Use Case 1 – Prompt"
+linkTitle: "UC1 – Prompt"
+weight: 5
+draft: true
+description: >
+   Prompt für Use Case 1 (funktionale Korrektheit von UI-Elementen)
+---
+
+Rolle:  
+Du bist ein technischer Usability- und QA-Tester mit Fokus auf funktionale Korrektheit von Websites. Du prüfst systematisch interaktive UI-Elemente und Sub-Element auf ihre technische Funktionalität, Reaktionsverhalten und mögliche Broken Flows.
+
+Ziel:  
+Untersuche alle interaktiven Elemente auf der Website [Website-URL] auf funktionale Schwächen oder Sackgassen. Erkenne Broken Flows, defekte Verlinkungen, Buttons ohne Funktion und fehlende Rückmeldungen. Dein Ziel ist es, jede Interaktion aus Nutzersicht lückenlos testbar und reaktionsschnell zu machen.
+
+---
+
+Prüfkriterien für jedes UI-Element und Sub-Element (Button, Link, CTA, Menüpunkt etc.):
+
+1. Technische Funktionsfähigkeit
+   - Ist das Element technisch klickbar?
+   - Führt der Klick zu einer gültigen Zieladresse oder Aktion?
+   - Wird ein neues Fenster geöffnet (wenn ja: sinnvoll?)?
+
+2. Keine Sackgassen (Dead Ends)
+   - Führt die Interaktion zu einem „404“, „Fehler“-Screen, einer leeren Seite oder ohne sichtbaren nächsten Schritt?
+   - Gibt es einen Rückweg oder eine Navigation zurück?
+   - Bleibt man ohne Erklärung stecken?
+
+3. Reaktionszeit
+   - Findet innerhalb von max. 500 ms eine sichtbare Reaktion statt?  
+     (z. B. Ladeanimation, Seitenwechsel, visuelle Rückmeldung)
+   - Bleibt der Klick „tot“ oder reagiert verzögert?
+
+4. Visuelle Rückmeldung
+   - Gibt es einen Hover-/Fokus-/Aktiv-Zustand?
+   - Wird der Nutzer über den Status der Aktion informiert (z. B. „wird geladen“, „erfolgreich gesendet“)?
+
+5. Broken Flow Detection
+   - Gibt es aufeinanderfolgende Interaktionen, die nicht korrekt abgeschlossen werden können?  
+     (z. B. "Jetzt kaufen" → leere Warenkorbseite)
+   - Gibt es Flows, bei denen Nutzer:innen nicht weiterkommen oder Informationen fehlen?
+   - Werden Ladefehler, modale Blockaden oder Fehlermeldungen korrekt gehandhabt?
+
+---
+
+Ausgabeformat für jedes getestete UI-Element und Sub-Element, das Probleme aufweist:
+
+- Element: [Bezeichnung oder Sichtbarkeit des Buttons/Links]
+- Fundstelle: [URL oder Seitensektion]
+- Reaktion sichtbar in 500 ms: [Ja/Nein]
+- Sackgasse oder Broken Flow: [Ja/Nein]
+- Problem-Beschreibung: [z. B. "Link führt ins Leere", "kein Feedback nach Klick"]
+- Empfehlung: [z. B. „Verlinkung prüfen“, „Lade-Feedback integrieren“, „Rückweg ermöglichen“]
+

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Ergebnisse Agent S2.md

@@ -0,0 +1,124 @@
+---
+title: "Use Case 2 – Ergebnisse Agent S2"
+linkTitle: "UC2 – Agent S2"
+weight: 10
+draft: true
+description: >
+  Roh-Ergebnisse (PoC Validation) für Use Case 2 – Agent S2
+---
+
+## GESAMTBEWERTUNG & KATEGORIEN
+
+### 1. NAVIGATIONSSTRUKTUR & ORIENTIERUNG
+
+**Bewertung: 3/5 (Erhebliche Mängel bei externen Verlinkungen)**
+
+  ✅ Positive Aspekte:
+
+- Keine positiven Aspekte dokumentiert
+
+  
+
+🔴 Identifizierte Probleme:
+
+**Status:** Kritisches Problem
+
+**Fundstelle:** Twitter/X Website ([x.com](http://x.com/))  
+
+**Begründung:** Nutzer werden nach Klick auf Social Media Button auf externe Plattform weitergeleitet und können durch Login-Prompts und Cookie-Banner nicht zur ursprünglichen Website zurückkehren. Back-Button funktioniert nicht.  
+
+**Empfehlung**: Social Media Sharing in neuem Tab/Fenster öffnen oder JavaScript-basierte Sharing-Lösung implementieren  
+
+**Verbesserungspotenzial**: Hoch – Verhindert kompletten Nutzungsabbruch
+
+### 2. BARRIEREFREIHEIT (WCAG 2.1 AA)
+
+**Bewertung:** 5/5 (Keine Probleme identifiziert)
+
+✅ Positive Aspekte:
+
+- Keine positiven Aspekte dokumentiert
+
+🔴 Identifizierte Probleme:
+
+- Keine Probleme in dieser Kategorie identifiziert
+
+### 3. INTERAKTIVE ELEMENTE & USABILITY
+
+Bewertung: 3/5 (Kritische Funktionsstörungen)
+
+✅ Positive Aspekte:
+
+- Keine positiven Aspekte dokumentiert
+
+🔴 Identifizierte Probleme:
+
+**Status:** Kritisches Problem  
+
+**Fundstelle:** Stadt Leipzig Website - Bürgerservice Sektion  
+
+**Begründung:** Automatisierte Tests blockieren komplett, Agent führt keine Aktionen mehr aus und zeigt wiederholt Fehlermeldungen. Testprozess funktionsunfähig.  
+
+**Empfehlung:** Test-Automatisierung überarbeiten - Fallback-Mechanismen für blockierte Aktionen implementieren  
+
+**Verbesserungspotenzial:** Hoch – Verhindert vollständige Funktionalitätsprüfung
+
+### 4. UI-KONSISTENZ & DESIGNSYSTEM
+
+Bewertung: 5/5 (Keine Probleme identifiziert)
+
+  ✅ Positive Aspekte:
+
+- Keine positiven Aspekte dokumentiert
+
+  🔴 Identifizierte Probleme:
+
+- Keine Probleme in dieser Kategorie identifiziert
+
+### 5. MOBILE NUTZUNG & RESPONSIVE DESIGN
+
+Bewertung: 5/5 (Keine Probleme identifiziert)
+
+✅ Positive Aspekte:
+
+- Keine positiven Aspekte dokumentiert
+
+🔴 Identifizierte Probleme:
+
+- Keine Probleme in dieser Kategorie identifiziert
+
+### 6. PERFORMANCE & LADEZEIT
+
+Bewertung: 5/5 (Keine Probleme identifiziert)
+
+✅ Positive Aspekte:**
+
+- Keine positiven Aspekte dokumentiert
+
+🔴 Identifizierte Probleme:
+
+- Keine Probleme in dieser Kategorie identifiziert
+
+## PRIORISIERTE HANDLUNGSEMPFEHLUNGEN
+
+### 🚨 KRITISCH (Sofort umsetzen):
+
+- Social Media Links in neuem Tab öffnen - verhindert Nutzungsabbruch
+
+- Test-Automatisierung mit Fallback-Mechanismen ausstatten - ermöglicht vollständige Qualitätsprüfung
+
+### 🔥 HOCH (Nächste 4 Wochen):
+
+- Keine Probleme dieser Prioritätsstufe identifiziert
+
+### 🟠 MITTEL (Nächste 8 Wochen):
+
+- Keine Probleme dieser Prioritätsstufe identifiziert
+
+### 🟢 **NIEDRIG (Kontinuierlich):**
+
+- Keine Probleme dieser Prioritätsstufe identifiziert
+
+## FAZIT
+
+**Gesamtnote: 4/5** - Die Website zeigt grundsätzlich solide UX-Performance, wird jedoch durch zwei kritische Navigationsprobleme erheblich beeinträchtigt. Die Haupthebel liegen in der Behebung der externen Verlinkungsproblematik und der Stabilisierung der Test-Infrastruktur. Nach Lösung dieser kritischen Punkte ist eine deutliche Verbesserung der Nutzererfahrung zu erwarten.

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Ergebnisse Anthropic Computer Use.md

@@ -0,0 +1,209 @@
+---
+title: "Use Case 2 – Ergebnisse Anthropic Computer Use"
+linkTitle: "UC2 – Anthropic"
+weight: 20
+draft: true
+description: >
+  Roh-Ergebnisse (PoC Validation) für Use Case 2 – Anthropic Computer Use
+---
+
+## GESAMTBEWERTUNG & KATEGORIEN
+
+### 1. NAVIGATIONSSTRUKTUR & ORIENTIERUNG
+
+**Bewertung: 4/5 (Gut)**
+
+✅ **Positive Aspekte:**
+
+- Klares Logo als Home-Anker vorhanden
+- Konsistente Hauptnavigation mit 5 logischen Kategorien
+- Gute Breadcrumb-Navigation
+- Sekundäre Navigation mit Service-Links
+- Funktionierendes responsive Hamburger-Menü
+- Skip-Links für Barrierefreiheit ("Zur Hauptnavigation springen", "Zur Suche springen", "Zum Inhalt springen")
+
+🔴 **Identifizierte Probleme:**
+
+**Status:** Problem  
+**Fundstelle:** Top-Navigation, Sprach-Dropdown  
+**Begründung:** Das Sprach-Dropdown ist zwar funktional, aber könnte für internationale Nutzer klarer beschriftet sein  
+**Empfehlung:** Icon mit "Language/Sprache" Label ergänzen  
+**Verbesserungspotenzial:** Niedrig - einfache Beschriftungsänderung
+
+---
+
+  
+
+### 2. BARRIEREFREIHEIT (WCAG 2.1 AA)
+
+**Bewertung: 4/5 (Gut)**
+
+✅ **Positive Aspekte:**
+
+- Ausgezeichnete Skip-Link-Implementierung
+- Funktionale Tastaturnavigation
+- Logische Tab-Reihenfolge
+- Mehrsprachigkeit verfügbar
+- Schriftgrößen sind ausreichend (≥16px)
+
+🔴 **Identifizierte Probleme:**
+
+**Status:** Problem  
+**Fundstelle:** Farbkontraste bei Links und Buttons  
+**Begründung:** Einige blaue Links könnten bessere Kontraste zum Hintergrund haben  
+**Empfehlung:** Farbkontraste auf mindestens 4.5:1 prüfen und anpassen  
+**Verbesserungspotenzial:** Mittel - Design-Anpassungen erforderlich
+
+**Status:** Problem  
+**Fundstelle:** Alt-Texte bei Bildern nicht überprüfbar  
+**Begründung:** Ohne Screenreader-Test nicht vollständig bewertbar  
+**Empfehlung:** Vollständige Alt-Text-Audit durchführen  
+**Verbesserungspotenzial:** Hoch - Barrierefreiheit kritisch
+
+---
+
+  
+
+### 3. INTERAKTIVE ELEMENTE & USABILITY
+
+**Bewertung: 3/5 (Befriedigend)**
+
+✅ **Positive Aspekte:**
+
+- Suchfunktion vorhanden und funktional
+- Hover-States bei Buttons erkennbar
+- Links sind als solche erkennbar
+
+🔴 **Identifizierte Probleme:**
+
+**Status:** Problem  
+**Fundstelle:** Suchfeld und Suchbutton  
+**Begründung:** Suchbutton könnte prägnanter beschriftet sein ("Suchen" statt nur Icon)  
+**Empfehlung:** Button-Beschriftung optimieren, Placeholder-Text im Suchfeld verbessern  
+**Verbesserungspotenzial:** Niedrig - einfache Textanpassungen
+
+**Status:** Problem  
+**Fundstelle:** Touch-Targets auf mobilen Geräten  
+**Begründung:** Einige Navigationselemente könnten für Touch-Bedienung zu klein sein  
+**Empfehlung:** Touch-Targets auf mindestens 44x44px vergrößern  
+**Verbesserungspotenzial:** Mittel - CSS-Anpassungen erforderlich
+
+---
+
+  
+
+### 4. UI-KONSISTENZ & DESIGNSYSTEM
+
+**Bewertung: 4/5 (Gut)**
+
+✅ **Positive Aspekte:**
+
+- Konsistente Farbverwendung (Blau für Stadt Leipzig)
+- Einheitliche Schriftarten
+- Konsistente Button-Styles
+- Klare visuelle Hierarchie
+
+🔴 **Identifizierte Probleme:**
+
+**Status:** Problem  
+**Fundstelle:** Verschiedene Button-Stile  
+**Begründung:** Primäre und sekundäre Buttons nicht immer klar unterscheidbar  
+**Empfehlung:** Klares Button-Hierarchie-System etablieren  
+**Verbesserungspotenzial:** Mittel - Designsystem-Überarbeitung
+
+---
+
+  
+
+### 5. MOBILE NUTZUNG & RESPONSIVE DESIGN
+
+**Bewertung: 4/5 (Gut)**
+
+✅ **Positive Aspekte:**
+
+- Vollständig responsive Design
+- Funktionierendes Hamburger-Menü
+- Gute mobile Navigation
+- Kein horizontales Scrollen
+
+🔴 **Identifizierte Probleme:**
+
+**Status:** Problem  
+**Fundstelle:** Mobile Schriftgrößen  
+**Begründung:** Einige Texte könnten auf sehr kleinen Bildschirmen zu klein sein  
+**Empfehlung:** Minimum 18px für mobile Fließtexte  
+**Verbesserungspotenzial:** Niedrig - CSS-Anpassungen
+
+**Status:** Problem  
+**Fundstelle:** Touch-Target-Größen  
+**Begründung:** Navigationslinks könnten größere Touch-Bereiche haben  
+**Empfehlung:** Padding vergrößern für bessere Touch-Erfahrung  
+**Verbesserungspotenzial:** Niedrig - CSS-Padding-Anpassungen
+
+---
+
+  
+
+### 6. PERFORMANCE & LADEZEIT
+
+**Bewertung: 2/5 (Großer Handlungsbedarf)**
+
+🔴 **Kritische Probleme:**
+
+**Status:** Problem  
+**Fundstelle:** Allgemeine Seitenladezeiten  
+**Begründung:** Mehrere Bereiche laden über 3 Sekunden (RSS-Feeds, Kontakt, Mediathek, Suche)  
+**Empfehlung:** Server-Performance optimieren, Caching implementieren, Asset-Komprimierung  
+**Verbesserungspotenzial:** HOCH - Kritisch für User Experience
+
+**Status:** Problem  
+**Fundstelle:** Bildoptimierung  
+**Begründung:** Große Bilder ohne Lazy Loading oder Komprimierung  
+**Empfehlung:** WebP-Format implementieren, Lazy Loading, responsive Images  
+**Verbesserungspotenzial:** HOCH - Große Performance-Verbesserung möglich
+
+---
+
+  
+
+## PRIORISIERTE HANDLUNGSEMPFEHLUNGEN
+
+### 🔥 KRITISCH (Sofort umsetzen):
+
+1. **Performance-Optimierung** - Server-Response-Zeit unter 2 Sekunden
+2. **Bildkomprimierung** - WebP-Format und Lazy Loading implementieren
+3. **Barrierefreiheit-Audit** - Alt-Texte und Farbkontraste vollständig prüfen
+
+  
+
+### ⚡ HOCH (Nächste 4 Wochen):
+
+1. **Touch-Target-Optimierung** - Alle interaktiven Elemente ≥44px
+2. **Button-Hierarchie** - Klares Designsystem für Buttons etablieren
+3. **Mobile Schriftgrößen** - Minimum 18px für Fließtext
+
+  
+
+### 📈 MITTEL (Nächste 8 Wochen):
+
+1. **Suchfunktion verbessern** - Bessere Labels und Autocomplete
+2. **Sprachauswahl optimieren** - Klarere Beschriftung
+3. **Fokus-Indikatoren** - Deutlichere Keyboard-Navigation
+
+  
+
+### ✨ NIEDRIG (Kontinuierliche Verbesserung):
+
+1. **Content-Optimierung** - Klarere CTAs und Labels
+2. **Micro-Interactions** - Subtile Hover-Effekte verbessern
+3. **Error-Handling** - Kontextsensitive Fehlermeldungen
+
+---
+
+  
+
+## FAZIT
+
+[Leipzig.de](http://leipzig.de/) ist eine **solide, gut strukturierte Website** mit guter Navigation und Barrierefreiheit. Der **größte Handlungsbedarf liegt bei der Performance** - hier ist eine umfassende Optimierung erforderlich. Die mobile Erfahrung ist grundsätzlich gut, könnte aber durch größere Touch-Targets verbessert werden. Das Design ist konsistent und professionell, benötigt aber ein klareres Button-Hierarchie-System.
+
+**Gesamtnote: 3.5/5** - Gut mit deutlichem Verbesserungspotenzial

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Experteneinschätzung zum Vergleich der Agent Frameworks.md

@@ -0,0 +1,113 @@
+---
+title: "Use Case 2 – Experteneinschätzung (Agent Frameworks)"
+linkTitle: "UC2 – Experteneinschätzung"
+weight: 30
+draft: true
+description: >
+  Vergleich Agent S2 vs. Anthropic Computer Use (UC2)
+---
+
+### 1. NAVIGATIONSSTRUKTUR & ORIENTIERUNG
+
+**Anthropic Computer Use**
+
+✅  greift den wichtigen Hinweis zum Sprach-Dropdown auf, was aus UX-Sicht eine entscheidende Komponente für Zugänglichkeit und Orientierung darstellt.
+
+**Agent S2**
+
+🔴 Erwähnt an dieser Stelle nicht das Problem beim Sprach-Dropdown (wie z. B. beim ersten Test zur funktionalen Korrektheit von UI-Elementen)
+
+✅ hebt dagegen den separaten Tab für Social-Media-Funktionen hervor. Ein relevanter Aspekt der Informationsarchitektur, der bei Anthropic Computer Use fehlt.
+
+  
+
+### 2. BARRIEREFREIHEIT (WCAG 2.1 AA)
+
+Hier schneiden beide KI Agenten verhältnismäßig unbefriedigend ab.
+
+**Anthropic Computer Use**
+
+🔴 Weist darauf hin, dass alle Schriftgrößen ausreichend groß sind. das ist nicht korrekt. Die Texte in der Meta-Nav oder Breadcrumb sind deutlich kleiner (ca. 14px). Zudem ist der Farbkontrast an diesen Stellen zu gering.
+
+🔴 Probleme im Bereich Farbkontrast werden zwar als Empfehlung erwähnt, müssen aber manuell nochmal nachgeprüft werden.
+
+🔴 Alt-Texte bei Bildern können nicht geprüft werden, sind aber für die Barrierefreiheit relevant.
+
+**Agent S2** 
+
+🔴 Erwähnt auch nicht das Problem mit den zu geringen Schriftgrößen bzw. zu geringem Kontrast.
+
+🔴 Probleme im Bereich Farbkontrast werden nicht erkannt, obwohl vorhanden z. B. bei hellgrauem Text in der Meta-Nav, Breadcrumb oder Text auf grauem Hintergrund (z. B. AKTUELLE THEMEN)
+
+### 3. INTERAKTIVE ELEMENTE & USABILITY
+
+**Anthropic Computer Use**
+
+**🔴** Suchbutton ist beschriftet bezieht sich die Aussage, dass es lediglich ein Icon ohne Label gibt auf kleine Viewports?
+
+**🔴** Fehlende Status wie Hover-Effekte bei z. B. Icon inkl. Label (z. B. Seite in Leichter Sprache lesen, Vorlesen), Icon-Buttons (z. B. Drucken, Mail) werden nicht erwähnt.
+
+![(Haken)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/check.svg) Gute Empfehlung: Button-Beschriftung optimieren, Placeholder-Text im Suchfeld verbessern
+
+![(Haken)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/check.svg) Gute Empfehlung: Touch-Targets auf mindestens 44x44px vergrößern → Werden Problemstellen ebenfalls nochmals benannt oder mit konkreter Fundstelle (URL/Position) bereitgestellt, damit man diese nicht manuell suchen muss?
+
+**Agent S2** 
+
+**🔴** Was bedeutet das?
+
+### 4. UI-KONSISTENZ & DESIGNSYSTEM
+
+**Anthropic Computer Use**
+
+**🔴** Widersprüchliche Aussage:
+
+- Positiv Aspekte: Konsistente Button-Styles
+- Identifizierte Probleme: Verschiedene Button-Stile
+
+![(Haken)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/check.svg) Problem ist auf jeden Fall korrekt erkannt und die Empfehlung passt ebenfalls. Jedoch wird hier dann auch wieder manueller Support benötigt, um eine klare Button-Hierarchie zu etablieren.
+
+**Agent S2** 
+
+**🔴** Probleme werden nicht erkannt
+
+  
+
+### 5. MOBILE NUTZUNG & RESPONSIVE DESIGN
+
+**Anthropic Computer Use**
+
+ **![(Haken)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/check.svg)**Gute Hinweise und Empfehlungen, hilfreich wären Angaben, wo genau nachgebessert werden muss und welche Abstände eingefügt werden müssen.
+
+**Agent S2** 
+
+**🔴** Probleme werden nicht erkannt
+
+  
+
+### 6. PERFORMANCE & LADEZEIT
+
+**Anthropic Computer Use**
+
+ **![(Haken)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/check.svg)**Gute Hinweise und Empfehlungen, hilfreich wären Angaben, wo genau nachgebessert werden muss und welche Abstände eingefügt werden müssen.
+
+**Agent S2** 
+
+**🔴** Probleme werden nicht erkannt
+
+  
+
+## PRIORISIERTE HANDLUNGSEMPFEHLUNGEN
+
+**Anthropic Computer Use**
+
+**![(Haken)](https://confluence.telekom-mms.com/s/-x470jc/9111/1hjr1ir/_/images/icons/emoticons/check.svg)**Gute Handlungsempfehlung und Priorisierung, hilfreich wären Angaben, wo genau nachgebessert muss
+
+**Agent S2** 
+
+**🔴** Die meisten Handlungsbedarfe werden nicht erkannt und benannt
+
+## FAZIT
+
+- Auffällig ist, dass Agent S2 tendenziell Probleme betont, ohne positive Aspekte hervorzuheben, während Anthropic Computer Use vereinzelt auch neutrale bis positive Befunde anspricht.
+- Im Gegensatz zu Anthropic, findet Agent S2 einen Großteil der Probleme überhaupt nicht.
+- Im Bereich Barrierefreiheit schneiden beide KI Agents eher unbefriedigend ab

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Prompt.md

@@ -0,0 +1,74 @@
+---
+title: "Use Case 2 – Prompt"
+linkTitle: "UC2 – Prompt"
+weight: 5
+draft: true
+description: >
+  Prompt für Use Case 2 (Visuelle Qualität & Konsistenz / UX Health Check)
+---
+
+Rolle:  
+Du bist ein erfahrener UX- und UI-Experte mit Spezialisierung auf heuristische Evaluation, visuelle Konsistenz und digitale Barrierefreiheit (WCAG 2.1 AA).
+
+Aufgabe:  
+Führe einen vollständigen UX Health Check für die Website mit folgender URL durch:[Website-URL]
+
+Ziel:
+Analysiere sowohl inhaltliche UX-Aspekte als auch visuelle und technische UI-Kriterien. Die Analyse soll strukturiert, verständlich und umsetzungsorientiert sein – ideal für Stakeholder in Produkt, Design und Entwicklung. Nutze die folgenden Prüfkriterien und liefere die Auswertung als strukturierte Liste mit Empfehlungen.
+
+---
+
+Prüfkriterien: 
+
+1. Navigationsstruktur & Orientierung
+- Ist die Navigation intuitiv, konsistent und jederzeit erreichbar?
+- Ist die Informationsarchitektur logisch gegliedert?
+- Gibt es eine klar erkennbare Startseite oder einen „Home“-Anker?
+- Werden Navigationspunkte auf Mobilgeräten verständlich dargestellt (z. B. Burger-Menü mit klarer Beschriftung)?
+
+2. Barrierefreiheit (Accessibility – WCAG 2.1 AA)
+- Farbkontrast: Sind Kontraste ausreichend? (Empfohlen: mind. 4.5:1 für Text, 3:1 für große Texte)
+- Schriftgröße:
+  - Mindestgröße für Fließtext: 16 px (ca. 1rem) auf Desktop
+  - Auf Mobilgeräten: mind. 16 px, idealerweise 18 px
+  - Große Texte (z. B. Überschriften): ab 20–24 px
+- Bedienbarkeit: Funktionieren alle interaktiven Elemente mit Tastatur (Tab-Fokus, Enter)?
+- Alternativtexte: Sind Bilder und Icons korrekt mit Alt-Texten oder Aria-Labels ausgezeichnet?
+- Fokus-Indikatoren: Sind sie deutlich sichtbar (z. B. Outline oder Kontrastwechsel)?
+
+3. Interaktive Elemente & Usability
+- Sind Buttons und Links visuell als solche erkennbar (Form, Farbe, Hover-Zustand)?
+- Sind Labels sprechend und handlungsorientiert (z. B. "Jetzt absenden" statt "OK")?
+- Gibt es kontextsensitive Fehlermeldungen, die Ursachen und Lösungen benennen?
+- Wird bei Formularen z. B. Autocomplete unterstützt?
+
+4. UI-Konsistenz & Designsystem
+- Werden UI-Komponenten (z. B. Buttons, Input-Felder) konsistent verwendet?
+- Gibt es klare Regeln für Farben, Abstände, Schriftarten und Größen?
+- Gibt es widersprüchliche visuelle Muster (z. B. zwei verschiedene Button-Styles für dieselbe Aktion)?
+- Werden Komponenten aus einem einheitlichen Designsystem eingesetzt?
+
+5. Mobile Nutzung & Responsive Design
+- Ist die Website vollständig responsive?
+- Gibt es Layoutverschiebungen oder horizontales Scrollen?
+- Touch-Ziele:
+  - Sind alle klick-/tippbaren Elemente mind. 44 x 44 px groß? (gemäß Apple HIG und WCAG)
+  - Haben Elemente ausreichend Abstand zueinander, um Fehleingaben zu vermeiden?
+- Werden Schriftgrößen und Abstände auf kleinen Viewports gut angepasst (keine Zoompflicht)?
+
+6. Performance & Ladezeit
+- Liegt die Ladezeit der Seite unter 3 Sekunden (First Contentful Paint)?
+- Gibt es Performance-Probleme durch unoptimierte Bilder, Fonts oder JavaScript?
+- Wird Lazy Loading für nicht sichtbare Inhalte verwendet?
+
+---
+
+Ausgabeformat pro Hauptkategorie, die Probleme aufzeigt:
+- Vergib für jede Hauptkategorie eine Bewertung auf einer Skala von 1–5 (1 = großer Handlungsbedarf, 5 = sehr gut)  
+
+Ausgabeformat pro Fundstelle, die Probleme aufzeigt:
+- Status: [Problem]  
+- Fundstelle: [URL/Position, Beschreibung z. B. Kontrastprobleme, kleine Klickflächen, zu kleine Schriftgrößen]  
+- Begründung: Warum ist das ein Problem?  
+- Empfehlung: Was sollte verbessert werden?
+- Verbesserungspotenzial: Liste konkrete Verbesserungen nach Priorität (Impact x Aufwand)

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Ergebnisse Agent S2.md

@@ -0,0 +1,33 @@
+---
+title: "Use Case 3 – Ergebnisse Agent S2"
+linkTitle: "UC3 – Agent S2"
+weight: 10
+draft: true
+description: >
+  Roh-Ergebnisse (PoC Validation) für Use Case 3 – Agent S2
+---
+
+## **HAUPTAUFGABE**
+
+Anmeldung für den Newsletter auf [leipzig.de](http://leipzig.de/) mit einer vorgegebenen E-Mail-Adresse durchführen.
+
+### **GEFUNDENE PROBLEME**
+
+Keine Probleme gefunden.
+
+### **POSITIVE ERGEBNISSE**
+
+✅ Alle getesteten Elemente funktionieren technisch korrekt  
+✅ Keine Broken Flows oder Sackgassen gefunden
+
+### **HAUPT-EMPFEHLUNG**
+
+Kontinuierliche Qualitätssicherung: Da bei der aktuellen Prüfung keine technischen Probleme identifiziert wurden, sollte der Fokus auf der Aufrechterhaltung der bestehenden Qualität liegen.
+
+### **Empfohlene Maßnahmen**
+
+1. Regelmäßige automatisierte Tests für Newsletter-Anmeldeprozess implementieren  
+2. Performance-Monitoring für kritische User-Flows einrichten  
+3. Monatliche manuelle Usability-Tests durchführen  
+4. Responsive Design auf verschiedenen Endgeräten kontinuierlich prüfen  
+5. Barrierefreiheit gemäß WCAG-Standards regelmäßig validieren

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Ergebnisse Anthropic Computer Use.md

@@ -0,0 +1,47 @@
+---
+title: "Use Case 3 – Ergebnisse Anthropic Computer Use"
+linkTitle: "UC3 – Anthropic"
+weight: 20
+draft: true
+description: >
+  Roh-Ergebnisse (PoC Validation) für Use Case 3 – Anthropic Computer Use
+---
+
+## **Zusammenfassung der Hauptprobleme:**
+
+**Positive Aspekte:**
+
+- ✅ **Newsletter-Button gut auffindbar:** Der blaue Button "Stadt Leipzig Newsletter abonnieren" war deutlich sichtbar auf der Startseite
+- ✅ **Klare Formulierung:** Button-Text und Überschriften sind verständlich
+- ✅ **Transparenter Datenschutz:** DSGVO-Hinweise und CleverReach werden explizit erwähnt
+- ✅ **Double-Opt-In erklärt:** Das Verfahren mit Bestätigungslink wird vorab erklärt
+- ✅ **Gute Fehlerbehandlung:** Klare, verständliche Fehlermeldungen bei ungültigen E-Mail-Adressen
+- ✅ **Responsive Design:** Seite funktioniert gut im Browser
+
+**Usability-Probleme:**
+
+- ❌ **Newsletter-Link nicht in der Hauptnavigation:** Nutzer müssen scrollen, um ihn zu finden
+- ❌ **Keine Suchfunktion für Newsletter:** Bei der Suche nach "Newsletter" wäre es hilfreich, wenn dieser direkt gefunden würde
+- ❌ **Fehlende Alternative E-Mail-Validierung:** Das System hätte vor der Weiterleitung zu CleverReach eine Frontend-Validierung durchführen können
+- ❌ **Kein direkter Link zurück:** Nach dem Fehler muss der Nutzer den Browser-Zurück-Button verwenden
+
+---
+
+  
+
+## **Verbesserungsvorschläge:**
+
+1. **Newsletter in der Hauptnavigation:** Einen "Newsletter" Link in der oberen Navigation hinzufügen, eventuell unter "Social Media" oder als eigenen Menüpunkt
+    
+2. **Frontend-E-Mail-Validierung:** Eine JavaScript-Validierung implementieren, die offensichtlich ungültige E-Mail-Adressen (wie [test@example.com](mailto:test@example.com)) bereits vor der Übermittlung abfängt
+    
+3. **Such-Integration:** Den Newsletter in die Suchfunktion der Website integrieren, so dass bei der Suche nach "Newsletter" direkt die Anmeldeseite gefunden wird
+    
+4. **Zurück-Button auf Fehlerseite:** Auf der CleverReach-Fehlerseite einen "Zurück zur Anmeldung" Button hinzufügen
+    
+5. **Newsletter-Teaser prominenter platzieren:** Den Newsletter-Button eventuell auch im Header oder Footer der Website dauerhaft sichtbar machen
+    
+6. **Mobile Optimierung prüfen:** Testen, wie gut der Button und das Formular auf mobilen Geräten funktionieren (Mindestgröße 44x44px)
+    
+
+**Gesamtbewertung:** Der Newsletter-Anmeldeprozess funktioniert grundsätzlich gut und ist benutzerfreundlich. Die wichtigsten Usability-Prinzipien werden befolgt, auch wenn es Raum für kleinere Verbesserungen gibt.

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Experteneinschätzung zum Vergleich der Agent Frameworks.md

@@ -0,0 +1,12 @@
+---
+title: "Use Case 3 – Experteneinschätzung (Agent Frameworks)"
+linkTitle: "UC3 – Experteneinschätzung"
+weight: 30
+draft: true
+description: >
+  Vergleich Agent S2 vs. Anthropic Computer Use (Task-based UX-Analyse)
+---
+- Beide KI Agenten erledigen die Aufgabe.
+- Während Agent S2 eher technische Empfehlungen zur Optimierung gibt, fokussiert sich Anthropic Computer Use auf Usability Optimierungen.
+- Tatsächlich muss man erstmal scrollen, um den Button für das Newsletter Abo zu finden. Annahme, dass hier reale Nutzer bereits etwas mit der Suche beschäftigt wären.
+- Anthropic Computer Use gibt hier gute Hinweise bzgl. der Usability-Probleme und mögliche Verbesserungsvorschläge, um die Usability zu optimieren.

content/en/docs/Autonomous UAT Agent/results/poc-validation/POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Prompt.md

@@ -0,0 +1,61 @@
+---
+title: "Use Case 3 – Prompt"
+linkTitle: "UC3 – Prompt"
+weight: 5
+draft: true
+description: >
+  Prompt für Use Case 3 (Task-based UX-Analyse)
+---
+
+Rolle:  
+Du bist ein realitätsnaher, kritischer Testnutzer mit Grundverständnis für digitale Produkte – aber ohne Expertenwissen. Deine Aufgabe ist es, eine konkrete Aufgabe auf einer Website durchzuführen, so wie es echte Nutzer:innen tun würden. Du berichtest über jeden deiner Schritte, Gedanken und Reaktionen – und identifizierst dabei Usability-Probleme und Verbesserungspotenziale.
+
+Ziel:  
+Simuliere einen realistischen Usability-Test auf [Website-URL]. Du erhältst eine typische Nutzeraufgabe und beschreibst Schritt für Schritt, wie du die Aufgaben durchführst, was du dabei wahrnimmst, wo du stockst und wie du dich zurechtfindest.
+
+Vorgehen:  
+- Handle so, wie ein:e durchschnittliche:r Nutzer:in in dieser Situation handeln würde.  
+- Beschreibe deine Gedanken laut („Think-Aloud“).  
+- Analysiere nicht als Experte, sondern schildere deine Nutzerwahrnehmung.  
+- Gib am Ende eine Zusammenfassung der größten Usability-Probleme und deiner Verbesserungsvorschläge.
+
+Beachte:
+- Nutze visuelle Beschreibungen, wenn du UI-Elemente siehst (z. B. „grauer Button unten rechts“).
+- Achte besonders auf klassische Usability-Prinzipien nach Jakob Nielsen:
+  - Verständliche Navigation
+  - Erwartungskonforme Formulierungen
+  - Sichtbarkeit von Interaktionen & Zuständen
+  - Fehlerprävention und Fehlermeldungen
+  - Mobiloptimierung und Touchgrößen (mind. 44x44px)
+  - Lesbarkeit von Text (mind. 16 px, bevorzugt 18 px auf Mobilgeräten)
+
+---
+
+Aufgabe (bitte anpassen):
+„Finde auf der Seite <Website-URL> heraus, wie man sich für den Newsletter anmeldet und melde dich an.“
+
+---
+
+Ausgabeformat:
+
+Aufgabe:
+[Hier steht die konkrete Aufgabe]
+
+Schritt-für-Schritt-Vorgehen:
+1. Was ich tun will: (Ziel oder Teilaufgabe)     
+2. Was ich tue: (interaktiver Schritt auf der Seite)  
+3. Was ich erwarte: (Systemreaktion oder Information)  
+4. Was passiert: (tatsächliche Reaktion/Anzeige)   
+5. Was mir auffällt: (positive oder negative Beobachtungen)   
+6. Was mich irritiert oder verwirrt: ...
+7. Wie ich weitermache / ob ich zurückgehe / abbreche: ...
+(für jeden weiteren Schritt wiederholen)
+
+Am Ende:
+Zusammenfassung der Hauptprobleme:
+- [Usability-Probleme entlang des Flows]
+- [z. B. Filteroption war schwer zu finden, Tarifvergleich nicht möglich, keine klare Preistransparenz]
+
+Verbesserungsvorschläge:
+- [z. B. Tarifvergleich als eigene Seite anlegen]
+- [Button-Beschriftung präzisieren („Jetzt bestellen“ → „Tarif wählen und bestellen“)]

content/en/docs/Autonomous UAT Agent/results/poc-validation/_index.md

@@ -0,0 +1,61 @@
+---
+title: "PoC Validation"
+linkTitle: "PoC Validation"
+weight: 1
+description: >
+  What was validated in the PoC and where to find the evidence
+---
+This page summarizes what was validated in the Proof of Concept (PoC) for the **Autonomous UAT Agent** and where to find supporting evidence.
+
+## Scope and objective
+
+The PoC aimed to demonstrate that an agent can:
+
+- Interact with real web UIs autonomously (VNC-based GUI automation)
+- Produce actionable UI/UX findings and recommendations
+- Generate reproducible artifacts (logs, structured reports) suitable for review and auditing
+
+## Validated use cases
+
+The PoC covered three concrete use cases:
+
+1. **Functional correctness of UI elements**
+   - Validate that interactive elements (e.g., links, buttons, menus, forms) behave as expected.
+   - Identify broken interactions, dead ends, inconsistent states, and regressions.
+
+2. **Visual quality & consistency (UX Health Check)**
+   - Assess visual consistency and basic UX hygiene (e.g., typography, spacing, alignment, contrast, component consistency).
+   - Highlight issues that impact perceived quality, accessibility, and brand consistency.
+
+3. **Task-based UX analysis**
+   - Execute representative user journeys end-to-end (task flows).
+   - Document friction points, unnecessary steps, unclear labels, missing feedback, and other usability barriers.
+
+## Where to find evidence in this documentation repo
+
+- **Evidence pack example (recommended reference):**
+  - Golden run (Telekom header navigation): [Golden Run: Telekom Header Navigation](../golden-run-telekom-header-nav/)
+
+- **Artifact locations and guidance:**
+  - See: Golden Run evidence pack and run outputs in `results/`
+
+- **Model configuration context (current vs legacy):**
+  - See: [Model Stack](../../model-stack/)
+
+## Legacy PoC runs (Anthropic / Claude Sonnet 4.5)
+
+During early prototyping, we executed a small number of runs using the **Anthropic API** with **Claude Sonnet 4.5** as the combined *vision* and *thinking* model.
+
+In the legacy results, we compare two different agent approaches:
+
+- **Anthropic Computer Use Agent**
+- **Agent S2** (using the **Anthropic API** with **Claude Sonnet 4.5** for both **thinking** and **grounding/vision**)
+
+These runs are included here as **legacy PoC evidence** to illustrate what an end-to-end workflow can look like: a scripted run that drives a real UI and produces a report of UI/UX improvement opportunities.
+
+Note: The D66 target solution uses a different model stack to meet the project constraints (open-source models from European companies). For background, see [Model Stack](../../model-stack/).
+
+- [Run 1 – Functional Correctness](run-1-functional-correctness/)
+- [Run 2 – Visual Quality & Consistency (UX Health Check)](run-2-ux-health-check/)
+- [Run 3 – Task-based UX Analysis](run-3-task-based-ux-analysis/)
+

content/en/docs/Autonomous UAT Agent/results/poc-validation/run-1-functional-correctness/index.md

@@ -0,0 +1,216 @@
+---
+title: "Run 1: Functional Correctness (Legacy PoC)"
+linkTitle: "Run 1 – Functional Correctness"
+weight: 10
+description: >
+  Legacy PoC run executed with the Anthropic API and Claude Sonnet 4.5 to validate functional UI correctness checks
+---
+## Purpose
+
+This run demonstrates how an autonomous agent can systematically validate the **functional correctness** of UI elements (e.g., links, buttons, menus, dialogs, forms) and produce a structured result set.
+
+## Model and execution context
+
+- Execution period: early prototyping / PoC phase (legacy)
+- Model provider: Anthropic API
+- Model used: Claude Sonnet 4.5
+- Role in this run: combined *vision* (screen understanding) and *thinking* (planning and reasoning)
+
+Comparison note: The legacy PoC compares **two agent approaches**—the **Anthropic Computer Use Agent** and **Agent S2**—both executed via the **Anthropic API** using **Claude Sonnet 4.5** for **thinking** and **vision/grounding**.
+
+Note: The current D66 target stack differs due to project constraints. See [Model Stack](../../../model-stack/).
+
+## What the agent checks
+
+Typical checks in a functional correctness run include:
+
+- Clickability and responsiveness of interactive elements
+- Correct navigation targets (no dead links / broken routes)
+- Correct component behavior (e.g., menus open/close, dialogs dismiss)
+- Input validation and form submission feedback
+- Error states and recovery (e.g., back navigation, cancellations)
+
+## Expected outputs (evidence)
+
+A functional correctness run is expected to produce:
+
+- A step-by-step action trace in the report (actions + observations)
+- A run log with timestamps and actions
+- A structured issue list (e.g., JSON or markdown) with:
+  - element
+  - location / context
+  - observed problem
+  - severity / impact
+  - recommendation
+
+## Legacy artifacts
+
+This page is the intended location to attach the **original legacy artifacts** from the Anthropic/Claude run (logs and the generated report).
+
+If the artifacts are available outside this documentation repository (e.g., in the agent runtime repository), link them here and/or copy the evidence pack into this page bundle folder.
+
+## Results (Use Case 1) – Agent S2 vs Anthropic Computer Use
+
+This section summarizes the **most important findings** from two legacy PoC runs for Use Case 1:
+
+- Agent S2
+- Anthropic Computer Use (Anthropic API, Claude Sonnet 4.5)
+
+The original source documents (German) are stored in the repository under the PoC Validation Confluence export folder.
+
+### Source documents (German, original)
+
+- Prompt: [../POC Validation Confluence docs/1- Funktionale Korrektheit  von UI-Elementen/1 - Prompt.md](../POC%20Validation%20Confluence%20docs/1-%20Funktionale%20Korrektheit%20%20von%20UI-Elementen/1%20-%20Prompt.md)
+- Results – Agent S2: [../POC Validation Confluence docs/1- Funktionale Korrektheit  von UI-Elementen/1 - Ergebnisse Agent S2.md](../POC%20Validation%20Confluence%20docs/1-%20Funktionale%20Korrektheit%20%20von%20UI-Elementen/1%20-%20Ergebnisse%20Agent%20S2.md)
+- Results – Anthropic Computer Use: [../POC Validation Confluence docs/1- Funktionale Korrektheit  von UI-Elementen/1 - Ergebnisse Anthropic Computer Use.md](../POC%20Validation%20Confluence%20docs/1-%20Funktionale%20Korrektheit%20%20von%20UI-Elementen/1%20-%20Ergebnisse%20Anthropic%20Computer%20Use.md)
+- Expert assessment: [../POC Validation Confluence docs/1- Funktionale Korrektheit  von UI-Elementen/1 - Experteneinschätzung zum Vergleich der Agent Frameworks.md](../POC%20Validation%20Confluence%20docs/1-%20Funktionale%20Korrektheit%20%20von%20UI-Elementen/1%20-%20Experteneinsch%C3%A4tzung%20zum%20Vergleich%20der%20Agent%20Frameworks.md)
+
+<details>
+  <summary><strong>Prompt used (translated, collapsed)</strong></summary>
+
+  Disclaimer: The PoC runs were executed using a **German** prompt. For documentation purposes, the prompt is **translated into English** below.
+
+  ```text
+  Role:
+  You are a technical usability and QA tester with a focus on the functional correctness of websites. You systematically verify interactive UI elements and sub-elements for technical functionality, responsiveness, and potential broken flows.
+
+  Goal:
+  Inspect all interactive elements on the website [Website-URL] for functional weaknesses or dead ends. Detect broken flows, defective links, buttons without a function, and missing feedback. Your goal is to ensure each interaction is fully testable from a user perspective and provides timely feedback.
+
+  ---
+
+  Evaluation criteria for each UI element and sub-element (button, link, CTA, menu item, etc.):
+
+  1. Technical functionality
+     - Is the element technically clickable?
+     - Does the click lead to a valid target URL or action?
+     - Does it open a new window (and if so: is it appropriate)?
+
+  2. No dead ends
+     - Does the interaction lead to a "404", error screen, empty page, or a state with no visible next step?
+     - Is there a way back or navigation to return?
+     - Can the user get stuck without explanation?
+
+  3. Response time
+     - Is there visible feedback within max. 500 ms?
+       (e.g., loading indicator, page change, visual response)
+     - Does the click appear "dead" or respond with noticeable delay?
+
+  4. Visual feedback
+     - Are there hover/focus/active states?
+     - Is the user informed about the status of the action (e.g., "loading", "successfully submitted")?
+
+  5. Broken flow detection
+     - Are there consecutive interactions that cannot be completed successfully?
+       (e.g., "Buy now" → empty cart page)
+     - Are there flows where users cannot proceed or required information is missing?
+     - Are load failures, modal blockers, or error messages handled correctly?
+
+  ---
+
+  Output format for each tested element and sub-element with issues:
+
+  - Element: [Label or visible name of button/link]
+  - Location: [URL or page section]
+  - Visible reaction within 500 ms: [Yes/No]
+  - Dead end or broken flow: [Yes/No]
+  - Problem description: [e.g., "link leads nowhere", "no feedback after click"]
+  - Recommendation: [e.g., "verify link target", "add loading feedback", "provide a way back"]
+  ```
+
+</details>
+
+### Executive comparison
+
+| Dimension | Agent S2 | Anthropic Computer Use |
+|---|---|---|
+| Broken flows / dead ends | None reported | None reported |
+| Main issue type | Findability / discoverability | Performance / response time |
+| Functional correctness (tested elements) | No functional defects reported | Tested elements considered technically functional |
+| Most actionable recommendation | Improve discoverability of language switcher | Systematic performance optimization (server, caching, assets, CDN, DB) |
+
+### Findings (details)
+
+The sections below contain a consolidated view of the **most important findings** for each agent, written in English for this documentation.
+
+<details>
+  <summary><strong>Results – Agent S2 (collapsed)</strong></summary>
+
+  ### Executive summary
+
+  - **Positive:** No broken flows or dead ends were identified.
+  - **Main observation:** A key UI element (language selection) was hard to discover, indicating a potential findability/usability issue.
+
+  ### Findings (table)
+
+  | Element | Location | Visible reaction ≤ 500 ms | Dead end / broken flow | Observation | Recommendation |
+  |---|---|---:|---:|---|---|
+  | Language dropdown | Header (top right) | Not assessed | No | Difficulty locating the language function; repeated scrolling and mis-clicks (browser menu instead of website element) suggest unclear placement or low discoverability. | Make the language selector more prominent and visually distinct (e.g., flag icons, higher contrast, larger text). |
+
+  ### Positive results
+
+  - ✅ No broken flows or dead ends identified
+
+  ### Recommendations
+
+  1. Add international flag icons to improve recognition
+  2. Increase contrast and font size for the language control
+  3. Review header placement and move to a more prominent position if needed
+  4. Run quick usability checks with international users (findability)
+  5. Improve hover/focus states to make interactivity more explicit
+
+</details>
+
+<details>
+  <summary><strong>Results – Anthropic Computer Use (collapsed)</strong></summary>
+
+  ### Executive summary
+
+  - **Functional correctness:** Tested elements were considered technically functional.
+  - **Main finding:** Multiple interactions show delayed response times (no visible reaction within 500 ms; reported load times above 3 seconds).
+  - **Flow quality:** No broken flows or dead ends were identified.
+
+  Note: Measured load times can vary by network, server load, and client conditions. The results still highlight performance as a relevant UX lever.
+
+  ### Findings (table)
+
+  | Element | Location | Visible reaction ≤ 500 ms | Dead end / broken flow | Observation | Recommendation |
+  |---|---|---:|---:|---|---|
+  | Contact link (top navigation) | https://www.leipzig.de/kontakt | No | No | Load time reported above 3 seconds (delayed response). | Implement performance optimization; improve caching. |
+  | RSS feeds link (top navigation) | https://www.leipzig.de/rss-feeds | No | No | Load time reported above 3 seconds (delayed response). | Implement performance optimization; improve caching. |
+  | Media library link (top navigation) | https://www.leipzig.de/servicenavigation/mediathek | No | No | Load time reported above 3 seconds (delayed response). | Implement performance optimization; improve caching. |
+  | Search | Homepage search field / results | No | No | Search results reported above 3 seconds (delayed response). | Optimize search performance (indexing and query execution). |
+  | Citizen services & administration (main navigation) | https://www.leipzig.de/buergerservice-und-verwaltung | No | No | Load time reported above 3 seconds (delayed response). | Implement performance optimization; improve caching. |
+
+  ### Positive results
+
+  - ✅ All tested elements functioned correctly
+  - ✅ No broken flows or dead ends identified
+  - ✅ Complete navigation and breadcrumb system
+  - ✅ Working multilingual support
+  - ✅ Correct URL structure and linking
+  - ✅ Responsive elements with visible feedback
+
+  ### Main recommendation (performance)
+
+  1. Optimize server response time
+  2. Improve caching strategy
+  3. Implement asset compression
+  4. Evaluate CDN usage
+  5. Optimize database queries
+
+</details>
+
+<details>
+  <summary><strong>Expert assessment (collapsed)</strong></summary>
+
+  The expert assessment below compares the practical value of the two result sets from a UX/UI perspective.
+
+  - **Anthropic Computer Use:** Stronger focus on technical UI checks, especially load times. From a UX perspective this is relevant, but interpretation can be limited unless delays are clearly noticeable or cause user frustration.
+  - **Load-time differences:** Differences were reported (e.g., Contact, RSS feeds vs. “Mein Stadtteil”), but considered mostly within an acceptable range and not very noticeable.
+  - **Notable exception:** In the Media Library (“Mediathek”), load times were perceived as clearly longer, which is a UX-relevant warning signal.
+  - **Agent S2:** Produced findings that lean more towards usability and accessibility aspects (language dropdown discoverability). This view is less purely technical but equally important for practical UX evaluation.
+  - **Classification note:** The expert would have expected the language dropdown topic more under the *Visual Quality & Consistency (UX Health Check)* prompt.
+
+</details>
+

content/en/docs/Autonomous UAT Agent/results/poc-validation/run-2-ux-health-check/index.md

@@ -0,0 +1,232 @@
+---
+title: "Run 2: Visual Quality & Consistency (UX Health Check) (Legacy PoC)"
+linkTitle: "Run 2 – UX Health Check"
+weight: 20
+description: >
+  Legacy PoC run executed with the Anthropic API and Claude Sonnet 4.5 to assess visual quality and UX consistency
+---
+## Purpose
+
+This run demonstrates how an autonomous agent can perform a lightweight **UX health check** focused on visual quality and consistency, and turn observations into actionable recommendations.
+
+## Model and execution context
+
+- Execution period: early prototyping / PoC phase (legacy)
+- Model provider: Anthropic API
+- Model used: Claude Sonnet 4.5
+- Role in this run: combined *vision* (screen understanding) and *thinking* (analysis and recommendation)
+
+Comparison note: The legacy PoC compares **two agent approaches**—the **Anthropic Computer Use Agent** and **Agent S2**—both executed via the **Anthropic API** using **Claude Sonnet 4.5** for **thinking** and **vision/grounding**.
+
+Note: The current D66 target stack differs due to project constraints. See [Model Stack](../../../model-stack/).
+
+## What the agent looks for
+
+Common categories for a UX health check include:
+
+- Consistency of typography (sizes, weights, line heights)
+- Layout alignment and spacing rhythm
+- Color usage and contrast (including accessibility risks)
+- Component consistency (buttons, form fields, cards, navigation)
+- Visual hierarchy and clarity of call-to-action placement
+- UI state consistency (hover, focus, active, disabled)
+
+## Expected outputs (evidence)
+
+A UX health check run is expected to produce:
+
+- A structured report documenting UI states and inconsistencies (with precise locations)
+- A structured checklist or issue list with:
+  - observed issue
+  - affected component/page area
+  - user impact
+  - recommended remediation
+  - optional severity rating
+
+## Legacy artifacts
+
+This page is the intended location to attach the **original legacy artifacts** from the Anthropic/Claude run (logs and the generated report).
+
+If the artifacts are stored elsewhere, link them here and/or copy them into this page bundle folder.
+
+## Results (Use Case 2) – Agent S2 vs Anthropic Computer Use
+
+This section summarizes the **most important findings** from two legacy PoC runs for Use Case 2:
+
+- Agent S2
+- Anthropic Computer Use (Anthropic API, Claude Sonnet 4.5)
+
+The original source documents (German) are stored in the repository under the PoC Validation Confluence export folder.
+
+### Source documents (German, original)
+
+- Prompt: [../POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Prompt.md](../POC%20Validation%20Confluence%20docs/2%20-%20Visuelle%20Qualit%C3%A4t%20%26%20Konsistenz%20(UX%20Health%20Check)/2%20-%20Prompt.md)
+- Results – Agent S2: [../POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Ergebnisse Agent S2.md](../POC%20Validation%20Confluence%20docs/2%20-%20Visuelle%20Qualit%C3%A4t%20%26%20Konsistenz%20(UX%20Health%20Check)/2%20-%20Ergebnisse%20Agent%20S2.md)
+- Results – Anthropic Computer Use: [../POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Ergebnisse Anthropic Computer Use.md](../POC%20Validation%20Confluence%20docs/2%20-%20Visuelle%20Qualit%C3%A4t%20%26%20Konsistenz%20(UX%20Health%20Check)/2%20-%20Ergebnisse%20Anthropic%20Computer%20Use.md)
+- Expert assessment: [../POC Validation Confluence docs/2 - Visuelle Qualität & Konsistenz (UX Health Check)/2 - Experteneinschätzung zum Vergleich der Agent Frameworks.md](../POC%20Validation%20Confluence%20docs/2%20-%20Visuelle%20Qualit%C3%A4t%20%26%20Konsistenz%20(UX%20Health%20Check)/2%20-%20Experteneinsch%C3%A4tzung%20zum%20Vergleich%20der%20Agent%20Frameworks.md)
+
+<details>
+  <summary><strong>Prompt used (translated, collapsed)</strong></summary>
+
+  Disclaimer: The PoC runs were executed using a **German** prompt. For documentation purposes, the prompt is **translated into English** below.
+
+  ```text
+  Role:
+  You are an experienced UX and UI expert specializing in heuristic evaluation, visual consistency, and digital accessibility (WCAG 2.1 AA).
+
+  Task:
+  Perform a full UX health check for the website with the following URL: [Website-URL]
+
+  Goal:
+  Analyze both UX content aspects as well as visual and technical UI criteria. The analysis should be structured, easy to understand, and actionable—ideal for stakeholders in product, design, and engineering. Use the following criteria and provide the evaluation as a structured list with recommendations.
+
+  ---
+
+  Evaluation criteria:
+
+  1. Navigation structure & orientation
+     - Is navigation intuitive, consistent, and always reachable?
+     - Is the information architecture logically structured?
+     - Is there a clearly identifiable home page or “Home” anchor?
+     - Are navigation items understandable on mobile (e.g., burger menu with clear labeling)?
+
+  2. Accessibility (WCAG 2.1 AA)
+     - Color contrast: Are contrasts sufficient? (Recommended: at least 4.5:1 for body text, 3:1 for large text)
+     - Font sizes:
+       - Minimum body text size: 16 px (~1rem) on desktop
+       - On mobile: at least 16 px, ideally 18 px
+       - Large text (e.g., headings): 20–24 px and above
+     - Operability: Do all interactive elements work via keyboard (tab focus, Enter)?
+     - Alternative text: Are images/icons correctly labeled with alt text or aria-labels?
+     - Focus indicators: Are they clearly visible (e.g., outline or contrast change)?
+
+  3. Interactive elements & usability
+     - Are buttons and links visually recognizable as interactive (shape, color, hover state)?
+     - Are labels clear and action-oriented (e.g., “Submit now” instead of “OK”)?
+     - Are there contextual error messages that describe causes and solutions?
+     - For forms: is autocomplete supported?
+
+  4. UI consistency & design system
+     - Are UI components (e.g., buttons, input fields) used consistently?
+     - Are there clear rules for colors, spacing, typography and sizes?
+     - Are there contradictory visual patterns (e.g., two different button styles for the same action)?
+     - Are components derived from a unified design system?
+
+  5. Mobile usage & responsive design
+     - Is the website fully responsive?
+     - Are there layout shifts or horizontal scrolling?
+     - Touch targets:
+       - Are all tappable elements at least 44 x 44 px? (Apple HIG / WCAG)
+       - Is spacing sufficient to prevent accidental taps?
+     - Are font sizes and spacing well adapted on small viewports (no forced zooming)?
+
+  6. Performance & load time
+     - Is page load time below 3 seconds (First Contentful Paint)?
+     - Are there performance issues from unoptimized images, fonts, or JavaScript?
+     - Is lazy loading used for off-screen content?
+
+  ---
+
+  Output format per main category that shows problems:
+  - Provide a rating per category on a 1–5 scale (1 = major need for action, 5 = very good)
+
+  Output format per finding:
+  - Status: [Problem]
+  - Location: [URL, page/section, description e.g., contrast issues, small touch targets, too-small font sizes]
+  - Rationale: Why is this a problem?
+  - Recommendation: What should be improved?
+  - Improvement potential: List concrete improvements by priority (impact x effort)
+  ```
+
+</details>
+
+### Executive comparison
+
+| Category | Agent S2 rating | Anthropic Computer Use rating |
+|---|---:|---:|
+| Navigation structure & orientation | 3/5 | 4/5 |
+| Accessibility (WCAG 2.1 AA) | 5/5 | 4/5 |
+| Interactive elements & usability | 3/5 | 3/5 |
+| UI consistency & design system | 5/5 | 4/5 |
+| Mobile usage & responsive design | 5/5 | 4/5 |
+| Performance & load time | 5/5 | 2/5 |
+
+### Findings (details)
+
+The sections below contain a consolidated view of the **most important findings** for each agent, written in English for this documentation.
+
+<details>
+  <summary><strong>Results – Agent S2 (collapsed)</strong></summary>
+
+  ### Executive summary
+
+  - The output focuses on a small number of critical blockers and otherwise reports “no issues” across most categories.
+  - Key issues flagged relate to **external linking behavior** and **test execution stability**.
+
+  ### Key findings (table)
+
+  | Category | Status | Location | Rationale | Recommendation | Priority |
+  |---|---|---|---|---|---|
+  | Navigation structure & orientation | Critical | Social media button → external Twitter/X (x.com) | Users are redirected to an external platform and may not be able to return to the original site due to login prompts/cookie banners; back navigation reportedly does not restore the prior state. | Open social media actions in a new tab/window or implement a dedicated share solution (e.g., JS-based sharing). | High |
+  | Interactive elements & usability | Critical | Leipzig site “Bürgerservice” section (automated test flow) | Automated test run blocks completely; the agent stops performing actions and shows repeated error messages, making the test process unusable. | Improve test automation robustness and implement fallback mechanisms for blocked actions. | High |
+
+  ### Prioritized recommendations
+
+  - **Critical (immediate):** Open social links in a new tab to prevent session loss.
+  - **Critical (immediate):** Add fallback mechanisms in test automation to avoid full run failure.
+
+  ### Overall conclusion
+
+  - Overall rating reported: **4/5** (solid UX baseline, but impacted by critical navigation/external linking and test stability issues).
+
+</details>
+
+<details>
+  <summary><strong>Results – Anthropic Computer Use (collapsed)</strong></summary>
+
+  ### Executive summary
+
+  - Provides a broad UX health check across categories.
+  - Highlights **performance** as the main area requiring significant improvement.
+  - Also flags opportunities around accessibility (contrast and alt-text auditing), labels, touch target sizes, and button hierarchy.
+
+  ### Key findings (table)
+
+  | Category | Status | Location | Rationale | Recommendation | Priority |
+  |---|---|---|---|---|---|
+  | Navigation structure & orientation | Low | Language dropdown (top navigation) | Functional but could be clearer for international users. | Add a language label (e.g., “Language/Sprache”) alongside the icon. | Low |
+  | Accessibility (WCAG 2.1 AA) | Medium | Link/button contrast | Some blue links may have insufficient contrast. | Verify and adjust contrast to at least 4.5:1 where required. | Medium |
+  | Accessibility (WCAG 2.1 AA) | High | Image alt text | Without a dedicated audit/screen-reader validation, alt-text coverage is not verifiable; alt text is critical for accessibility. | Run a complete alt-text audit and remediate gaps. | High |
+  | Interactive elements & usability | Low/Medium | Search field and search button | Button label and placeholder text could be clearer. | Improve button labeling and search placeholder copy; consider autocomplete. | Medium |
+  | Mobile usage & responsive design | Medium | Touch targets on mobile | Some navigation elements may be too small for comfortable tapping. | Increase touch targets to at least 44×44 px and adjust padding/spacing. | Medium |
+  | UI consistency & design system | Medium | Button hierarchy / button styles | Primary vs secondary buttons are not always clearly distinguishable. | Define a clear button hierarchy and apply consistently across the design system. | Medium |
+  | Performance & load time | High | General load times (RSS feeds, contact, media library, search) | Multiple areas reportedly exceed 3 seconds. | Optimize server performance, implement caching, and compress assets. | High |
+  | Performance & load time | High | Image optimization | Large images without lazy loading/compression can significantly impact performance. | Use WebP, add lazy loading, and implement responsive images. | High |
+
+  ### Prioritized recommendations
+
+  - **Critical (immediate):** Performance optimization (server response time, caching, asset compression).
+  - **Critical (immediate):** Image compression + lazy loading (WebP, responsive images).
+  - **High (next):** Accessibility audit (alt text + contrast), touch targets ≥44 px, establish button hierarchy.
+
+  ### Overall conclusion
+
+  - Overall rating reported: **3.5/5** (good structure and navigation; biggest gap is performance).
+
+</details>
+
+<details>
+  <summary><strong>Expert assessment (collapsed)</strong></summary>
+
+  The expert assessment below compares the practical value of the two result sets from a UX/UI perspective.
+
+  - **Navigation & orientation:** Anthropic Computer Use picks up the language dropdown topic (important for orientation/accessibility). Agent S2 does not mention it here, but highlights the separate-tab behavior for social media functions, which Anthropic did not cover.
+  - **Accessibility:** Both agents are assessed as relatively weak in this category.
+    - Anthropic claims font sizes are sufficient, but the expert notes smaller text (e.g., meta navigation/breadcrumb ~14 px) and insufficient contrast.
+    - Contrast recommendations require manual verification; alt text cannot be verified automatically but is critical.
+    - Agent S2 does not mention small font sizes/low contrast and misses existing contrast issues.
+  - **Interactive elements & usability:** Expert questions some details (e.g., search button label) and notes missing coverage of hover states for icon buttons/assistive icons. Recommendations around touch target sizing are considered good, but would be stronger with precise locations (URL/page/section).
+  - **UI consistency/design system, mobile, performance:** Expert notes Agent S2 misses most issues, while Anthropic provides useful recommendations but often needs manual follow-up and more precise locations.
+  - **Overall:** Anthropic surfaces more issues and includes neutral/positive aspects; Agent S2 tends to miss many issues and focuses more on problems without balancing positives.
+
+</details>

content/en/docs/Autonomous UAT Agent/results/poc-validation/run-3-task-based-ux-analysis/index.md

@@ -0,0 +1,197 @@
+---
+title: "Run 3: Task-based UX Analysis (Legacy PoC)"
+linkTitle: "Run 3 – Task-based UX Analysis"
+weight: 30
+description: >
+  Legacy PoC run executed with the Anthropic API and Claude Sonnet 4.5 to analyze end-to-end task flows and usability friction
+---
+## Purpose
+
+This run demonstrates how an autonomous agent can execute a representative **end-to-end user task** and produce an analysis of usability and experience quality.
+
+Compared to a UI element checklist, task-based analysis focuses on whether a user can complete a goal efficiently and confidently.
+
+## Model and execution context
+
+- Execution period: early prototyping / PoC phase (legacy)
+- Model provider: Anthropic API
+- Model used: Claude Sonnet 4.5
+- Role in this run: combined *vision* (screen understanding) and *thinking* (planning, evaluation, recommendation)
+
+Comparison note: The legacy PoC compares **two agent approaches**—the **Anthropic Computer Use Agent** and **Agent S2**—both executed via the **Anthropic API** using **Claude Sonnet 4.5** for **thinking** and **vision/grounding**.
+
+Note: The current D66 target stack differs due to project constraints. See [Model Stack](../../../model-stack/).
+
+## What the agent evaluates
+
+Typical evaluation dimensions in a task-based run include:
+
+- Task completion success and failure points
+- Number of steps and unnecessary detours
+- Clarity of labels, instructions, and calls to action
+- Feedback quality (loading, confirmations, error messages)
+- Form friction (validation, input constraints, error recovery)
+- Consistency of navigation and ability to backtrack safely
+
+## Expected outputs (evidence)
+
+A task-based run is expected to produce:
+
+- A step-by-step trace (report + log) of the journey
+- A summary table of friction points and recommendations
+- Optional: a “to-be” improved flow proposal
+
+## Legacy artifacts
+
+This page is the intended location to attach the **original legacy artifacts** from the Anthropic/Claude run (logs and the generated report).
+
+If the artifacts are stored elsewhere, link them here and/or copy them into this page bundle folder.
+
+## Results (Use Case 3) – Agent S2 vs Anthropic Computer Use
+
+This section summarizes the **most important findings** from two legacy PoC runs for Use Case 3:
+
+- Agent S2
+- Anthropic Computer Use (Anthropic API, Claude Sonnet 4.5)
+
+The original source documents (German) are stored in the repository under the PoC Validation Confluence export folder.
+
+### Source documents (German, original)
+
+- Prompt: [../POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Prompt.md](../POC%20Validation%20Confluence%20docs/3%20-%20Task-based%20UX-Analyse/3%20-%20Prompt.md)
+- Results – Agent S2: [../POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Ergebnisse Agent S2.md](../POC%20Validation%20Confluence%20docs/3%20-%20Task-based%20UX-Analyse/3%20-%20Ergebnisse%20Agent%20S2.md)
+- Results – Anthropic Computer Use: [../POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Ergebnisse Anthropic Computer Use.md](../POC%20Validation%20Confluence%20docs/3%20-%20Task-based%20UX-Analyse/3%20-%20Ergebnisse%20Anthropic%20Computer%20Use.md)
+- Expert assessment: [../POC Validation Confluence docs/3 - Task-based UX-Analyse/3 - Experteneinschätzung zum Vergleich der Agent Frameworks.md](../POC%20Validation%20Confluence%20docs/3%20-%20Task-based%20UX-Analyse/3%20-%20Experteneinsch%C3%A4tzung%20zum%20Vergleich%20der%20Agent%20Frameworks.md)
+
+<details>
+  <summary><strong>Prompt used (translated, collapsed)</strong></summary>
+
+  Disclaimer: The PoC runs were executed using a **German** prompt. For documentation purposes, the prompt is **translated into English** below.
+
+  ```text
+  Role:
+  You are a realistic, critical test user with basic understanding of digital products—but without expert knowledge. Your task is to complete a concrete task on a website the way real users would. You report each step, thought, and reaction, and identify usability problems and opportunities for improvement.
+
+  Goal:
+  Simulate a realistic usability test on [Website-URL]. You receive a typical user task and describe step by step how you perform it, what you notice, where you get stuck, and how you find your way.
+
+  Approach:
+  - Act like an average user in this situation.
+  - Describe your thoughts out loud (“think-aloud”).
+  - Do not analyze as an expert; report user perception.
+  - At the end, summarize the biggest usability issues and your improvement suggestions.
+
+  Notes:
+  - Use visual descriptions when you see UI elements (e.g., “grey button at bottom right”).
+  - Pay particular attention to classic usability principles (Jakob Nielsen):
+    - Understandable navigation
+    - Wording aligned with user expectations
+    - Visibility of interactions & states
+    - Error prevention and error messages
+    - Mobile optimization and touch targets (min. 44x44px)
+    - Text readability (min. 16 px, preferably 18 px on mobile)
+
+  ---
+
+  Task (please adapt as needed):
+  “On <Website-URL>, find out how to subscribe to the newsletter and sign up.”
+
+  ---
+
+  Output format:
+
+  Task:
+  [The concrete task]
+
+  Step-by-step procedure:
+  1. What I want to do (goal/subtask)
+  2. What I do (interaction on the page)
+  3. What I expect (system response/information)
+  4. What happens (actual response)
+  5. What I notice (positive/negative observations)
+  6. What irritates or confuses me
+  7. How I continue / whether I go back / abort
+  (repeat for each step)
+
+  At the end:
+  Summary of main problems:
+  - [Usability problems along the flow]
+
+  Improvement suggestions:
+  - [Concrete improvements]
+  ```
+
+</details>
+
+### Executive comparison
+
+| Dimension | Agent S2 | Anthropic Computer Use |
+|---|---|---|
+| Task completion | Completed | Completed |
+| Main focus | Technical QA / “no issues found” | Think-aloud usability observations |
+| Key improvement theme | Ongoing QA/monitoring | Discoverability and recovery/navigation |
+
+### Findings (details)
+
+The sections below contain a consolidated view of the **most important findings** for each agent, written in English for this documentation.
+
+<details>
+  <summary><strong>Results – Agent S2 (collapsed)</strong></summary>
+
+  ### Executive summary
+
+  - The task (newsletter subscription on leipzig.de using a provided email address) was reported as completed.
+  - No usability or functional issues were reported in the flow.
+
+  ### Reported findings
+
+  - **Issues found:** None reported.
+
+  ### Recommendations
+
+  Since no issues were detected, the recommendations focus on continuous quality assurance:
+
+  1. Implement regular automated tests for the newsletter signup flow
+  2. Set up performance monitoring for critical user journeys
+  3. Run monthly manual usability checks
+  4. Continuously verify responsive behavior across devices
+  5. Regularly validate accessibility against WCAG standards
+
+</details>
+
+<details>
+  <summary><strong>Results – Anthropic Computer Use (collapsed)</strong></summary>
+
+  ### Executive summary
+
+  - The signup flow is described as generally user-friendly and functional.
+  - Multiple usability improvements are suggested, mainly around **discoverability** and **error recovery**.
+
+  ### Key findings (table)
+
+  | Area | Observation | Why it matters | Recommendation |
+  |---|---|---|---|
+  | Discoverability | Newsletter button is not in the main navigation; users need to scroll to find it. | Users may not find the feature quickly; increases friction. | Add a “Newsletter” link in top navigation and/or make it persistently visible in header/footer. |
+  | Findability via search | No dedicated search support for “newsletter” is mentioned as an entry point. | Users often try search first; missing entry increases abandonment. | Include newsletter signup in site search results for “newsletter”. |
+  | Validation UX | Missing client-side validation before redirecting to CleverReach. | Preventable errors reduce user confidence. | Add frontend email validation before submission/redirect. |
+  | Error recovery | After an error, there is no direct link back; user must use browser back button. | Poor recovery increases frustration and drop-off. | Add a “Back to signup” link/button on the error page. |
+  | Mobile UX | Mobile behavior is assumed OK but recommended to verify touch target sizes. | Small touch targets cause mis-taps; accessibility risk. | Verify on mobile; ensure touch targets ≥44×44 px. |
+
+  ### Overall conclusion
+
+  - Overall assessment: works well with clear, incremental improvement opportunities.
+
+</details>
+
+<details>
+  <summary><strong>Expert assessment (collapsed)</strong></summary>
+
+  The expert assessment below compares the practical value of the two result sets from a UX/UI perspective.
+
+  - Both agents completed the task.
+  - Agent S2 focuses more on technical/operational recommendations (monitoring, automated testing), whereas Anthropic Computer Use focuses on usability optimizations.
+  - In practice, users likely need to scroll to find the newsletter button; some would likely try search first.
+  - Anthropic Computer Use provides helpful usability findings and concrete improvement suggestions.
+
+</details>
+

content/en/docs/Autonomous UAT Agent/running-auata-scripts.md

@@ -0,0 +1,113 @@
+---
+title: "Running Autonomous UAT Agent Scripts"
+linkTitle: "Running Autonomous UAT Agent Scripts"
+weight: 3
+description: >
+  How to run the key D66 evaluation scripts and what they produce
+---
+
+The **Autonomous UAT Agent** is the overall UX/UI testing use case built on top of the Agent S codebase and scripts in this repo.
+
+All commands below assume you are running from the **Agent-S repository root** (Linux/ECS), `~/Projects/Agent_S3/Agent-S`. To do that, connect to the server via SSH. You will need a key pair for authentication and an open inbound port in the firewall. For information on how to obtain the key pair and request firewall access, contact [tom.sakretz@telekom.de](mailto:tom.sakretz@telekom.de).
+
+## Template for running a script from command line terminal
+
+### 1) Connect from Windows
+
+```powershell
+ssh -i "C:\Path to KeyPair\KeyPair-ECS.pem" ubuntu@80.158.3.120
+```
+
+### 2) Prepare the ECS runtime (GUI + browser)
+
+```bash
+# Activate venv
+source ~/Projects/Agent_S3/Agent-S/venv/bin/activate
+
+# Go to Agent-S repo root
+cd ~/Projects/Agent_S3/Agent-S
+
+# Start VNC (DISPLAY=:1) and a browser
+vncserver :1
+export XAUTHORITY="$HOME/.Xauthority"
+export DISPLAY=":1"
+firefox &
+```
+
+### 3) One-command recommended run (ECS)
+
+If you only want to produce clean, repeatable evidence (screenshots with click markers), run the following command CLI:
+
+```bash
+python staging_scripts/gui_agent_cli.py --prompt "Go to telekom.de and click the cart icon" --max-steps 10
+```
+
+This will produce:
+
+- Screenshots: `./results/gui_agent_cli/<timestamp>/screenshots/`
+- Text log: `./results/gui_agent_cli/<timestamp>/logs/run.log`
+- JSON comm log: `./results/gui_agent_cli/<timestamp>/logs/run.log`
+
+
+## Prerequisites (runtime)
+
+- Linux GUI session (VNC/Xvfb) because these scripts drive a real browser via `pyautogui`.
+- A working `DISPLAY` (default for all scripts is `:1`).
+- Network access to the model endpoints (thinking + vision/grounding).
+
+
+## Key scripts (repo locations)
+
+The GUI Agent CLI script is the most flexible entry point and is therefore the only one described in more detail in this documentation. Assumes you are in project root `~/Projects/Agent_S3/Agent-S`.
+
+- GUI Agent CLI: `staging_scripts/gui_agent_cli.py`
+
+Historically, we used purpose-built scripts for individual tasks. We now recommend using `gui_agent_cli.py` as the primary entry point, because the same scenarios can usually be expressed via a well-scoped prompt while keeping the workflow more flexible and easier to maintain. The scripts below are kept for reference and may not reflect the current, preferred workflow.
+
+- UI check (Agent S3): `staging_scripts/1_UI_check_AS3.py`
+- Functional correctness check: `staging_scripts/1_UI_functional_correctness_check.py`
+- Visual quality audit: `staging_scripts/2_UX_visual_quality_audit.py`
+- Task-based UX flow (newsletter): `staging_scripts/3_UX_taskflow_newsletter_signup.py`
+
+
+## Golden run (terminal on ECS)
+
+This is the “golden run” command sequence currently used for D66 evidence generation. The golden run is a complete workflow that works as a template for reproducible outcomes.
+
+```bash
+python staging_scripts/gui_agent_cli.py \
+  --prompt "Role: You are a UI/UX testing agent specializing in functional correctness.
+Goal: Test all interactive elements in the header navigation on www.telekom.de for functional weaknesses.
+Tasks:
+1. Navigate to the website
+2. Identify and test interactive elements (buttons, links, forms, menus)
+3. Check for broken flows, defective links, non-functioning elements
+4. Document issues found
+Report Format:
+Return findings in the 'issues' field as a list of objects:
+- element: Name/description of the element
+- location: Where on the page
+- problem: What doesn't work
+- recommendation: How to fix it
+If no problems found, return an empty array: []" \
+  --max-steps 30
+```
+
+Golden run artifacts:
+
+- Screenshots: `./results/gui_agent_cli/<timestamp>/screenshots/`
+- Text log: `./results/gui_agent_cli/<timestamp>/logs/run.log`
+- Optional JSON comm log (if enabled): `./results/gui_agent_cli/<timestamp>/logs/calibration_log_*.json`
+
+An example golden run with screenshots and log outputs can be seen in [Results](./results/).
+
+## Alternative: run the agent via a web interface (Frontend)
+
+Work in progress.
+
+We are currently updating the web-based view and its ECS runner integration. This section will be filled with the correct, up-to-date instructions once the frontend flow supports the current Autonomous UAT Agent + `gui_agent_cli.py` workflow.
+
+
+## Notes on model usage
+
+Some scripts still contain legacy model configs (Claude/Pixtral). The D66 target configuration is documented in [Model Stack](./model-stack.md).

content/en/docs/_index.md

@@ -6,24 +6,12 @@ menu:
     weight: 20
 ---
 
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
 # Edge Developer Platform (EDP) Documentation
 
 Welcome to the EDP documentation. This documentation serves developers, engineers, and auditors who want to understand, use, and audit the Edge Developer Platform.
 
+It describes the outcomes and products of the edgeDeveloperFramework (eDF) sub-project within IPCEI-CIS.
+
 ## Target Audience
 
 * **Developers & Engineers**: Learn how to use the platform, deploy applications, and integrate services
@@ -32,14 +20,8 @@ Welcome to the EDP documentation. This documentation serves developers, engineer
 
 ## Documentation Structure
 
-The documentation follows a top-down approach focusing on outcomes and practical usage:
+The documentation is organized into three core areas:
 
-* **Platform Overview**: High-level introduction and product structure
+* **[Edge Developer Platform (EDP)](/docs/edp/)**: The central platform to support developers working at the edge, based around Forgejo
-* **Components**: Individual platform components and their usage
+* **[EdgeConnect Cloud](/docs/edgeconnect/)**: The sovereign edge cloud context and key deployment target for EDP integrations
-* **Getting Started**: Onboarding and quick start guides
+* **[Governance](/docs/governance/)**: Project history, decision context, and audit-oriented traceability
-* **Operations**: Deployment, monitoring, and troubleshooting
-* **Governance**: Project history, decisions, and compliance
-
-## Purpose
-
-This documentation describes the outcomes and products of the edgeDeveloperFramework (eDF) project. The EDP is designed as a usable, integrated platform with clear links to repositories and implementation details.

content/en/docs/components/TEMPLATE.md

@@ -1,141 +0,0 @@
----
-title: "[Component Name]"
-linkTitle: "[Short Name]"
-weight: 1
-description: >
-  [Brief one-line description of the component]
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### C4 charts
-
-Embed C4 charts this way:
-
-1. add a likec4-view with the name of the view
-{{< likec4-view view="components-template-documentation" project="architecture" title="Example Documentation Diagram" >}}
-
-2. create the LikeC4 view somewhere in ```./resources/edp-likec4/views```, the example above is in ```./resources/edp-likec4/views/documentation/components-template-documentation.c4```
-
-3. run ```task likec4:generate``` to create the webcomponent
-
-4. if you are in ```task:serve``` hot-reload mode the view will show up directly
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/_index.md

@@ -1,39 +0,0 @@
----
-title: "Components"
-linkTitle: "Components"
-weight: 30
-description: >
-  Overview of EDP platform components and their integration.
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: Stephan
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-This section documents all components of the Edge Developer Platform based on the product structure.
-
-## Component Categories
-
-The EDP consists of the following main component categories:
-
-* **Orchestrator**: Platform and infrastructure orchestration
-* **Forgejo & CI/CD**: Source code management and automation
-* **Deployments**: Deployment targets and edge connectivity
-* **Dev Environments**: Development environment provisioning
-* **Physical Environments**: Runtime infrastructure
-
-### Product Component Structure
-
-[TODO] Links
-
-![alt text](website-and-documentation_resources_product-structure.svg)

content/en/docs/components/deployments/_index.md

@@ -1,28 +0,0 @@
----
-title: "Deployments"
-linkTitle: "Deployments"
-weight: 40
-description: >
-  Deployment targets and edge connectivity solutions.
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6733](https://jira.telekom-mms.com/browse/IPCEICIS-6733)
-* **Assignee**: Patrick
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-Deployment components manage connections to various deployment targets including cloud infrastructure and edge devices.
-
-## Components
-
-* **OTC**: Open Telekom Cloud deployment target
-* **EdgeConnect**: Secure edge connectivity solution

content/en/docs/components/deployments/edgeconnect/_index.md

@@ -1,128 +0,0 @@
----
-title: "EdgeConnect"
-linkTitle: "EdgeConnect"
-weight: 20
-description: >
-  Secure connectivity solution for edge devices and environments
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
-* **Assignee**: Waldemar
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md

@@ -1,128 +0,0 @@
----
-title: "EdgeConnect Client"
-linkTitle: "EdgeConnect Client"
-weight: 30
-description: >
-  Client software for establishing EdgeConnect connections
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
-* **Assignee**: Waldemar
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md

@@ -1,128 +0,0 @@
----
-title: "EdgeConnect SDK"
-linkTitle: "EdgeConnect SDK"
-weight: 10
-description: >
-  Software Development Kit for establishing EdgeConnect connections
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
-* **Assignee**: Waldemar
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/deployments/otc.md

@@ -1,128 +0,0 @@
----
-title: "OTC (Open Telekom Cloud)"
-linkTitle: "OTC"
-weight: 10
-description: >
-  Open Telekom Cloud deployment and infrastructure target
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6733](https://jira.telekom-mms.com/browse/IPCEICIS-6733)
-* **Assignee**: Patrick
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/dev-environments.md

@@ -1,128 +0,0 @@
----
-title: "Development Environments"
-linkTitle: "DevEnvironments"
-weight: 30
-description: >
-  Development environment provisioning and management
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/documentationsystem.md

@@ -1,27 +0,0 @@
----
-title: "Documentation System"
-linkTitle: "Documentation System"
-weight: 100
-description: The developer 'documentation as code' documentation System we use ourselfes and over to use for each development team.
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6736](https://jira.telekom-mms.com/browse/IPCEICIS-6736)
-* **Assignee**: Stephan
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-The Orchestration manages platform and infrastructure provisioning, providing the foundation for the EDP deployment model.
-
-## Sub-Components
-
-* **Infrastructure Provisioning**: Low-level infrastructure deployment (infra-deploy, infra-catalogue)
-* **Platform Provisioning**: Platform-level component deployment via Stacks

content/en/docs/components/forgejo/_index.md

@@ -1,28 +0,0 @@
----
-title: "Forgejo"
-linkTitle: "Forgejo"
-weight: 20
-description: >
-  Self-hosted Git service with project management and CI/CD capabilities.
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-Forgejo provides source code management, project management, and CI/CD automation for the EDP.
-
-## Sub-Components
-
-* **Project Management**: Issue tracking and project management features
-* **Actions**: CI/CD automation (see CI/CD section)

content/en/docs/components/forgejo/actions/_index.md

@@ -1,27 +0,0 @@
----
-title: "Forgejo Actions"
-linkTitle: "Forgejo Actions"
-weight: 20
-description: Forgejo Actions.
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6730](https://jira.telekom-mms.com/browse/IPCEICIS-6730)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-Forgejo provides source code management, project management, and CI/CD automation for the EDP.
-
-## Sub-Components
-
-* **Project Management**: Issue tracking and project management features
-* **Actions**: CI/CD automation (see CI/CD section)

content/en/docs/components/forgejo/actions/actions.md

@@ -1,127 +0,0 @@
----
-title: "Forgejo Actions"
-linkTitle: "Actions"
-weight: 10
-description: GitHub Actions-compatible CI/CD automation
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/forgejo/actions/runner-orchestration.md

@@ -1,127 +0,0 @@
----
-title: "Runner Orchestration"
-linkTitle: "Runner Orchestration"
-weight: 30
-description: GARM
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/forgejo/actions/runner.md

@@ -1,128 +0,0 @@
----
-title: "Action Runner"
-linkTitle: "Runner"
-weight: 20
-description: >
-  Self-hosted runner infrastructure with orchestration capabilities
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/forgejo/forgejo.md

@@ -1,66 +0,0 @@
----
-title: "Forgejo Integration, Extension, and Community Collaboration"
-linkTitle: Forgejo Software Forge
-date: "2025-11-17"
-description: "Summary of the project's work integrating GARM with Forgejo and contributing key features back to the community."
-tags: ["Forgejo", "GARM", "CI/CD", "OSS", "Community", "Project Report"]
-categories: ["Workpackage Results"]
-weight: 10
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6731](https://jira.telekom-mms.com/browse/IPCEICIS-6731)
-* **Assignee**: Daniel
-* **Status**: Draft
-* **Last Updated**: 2025-11-17
-* **TODO**:
-  * [ ] Add concrete quick start steps
-  * [ ] Include prerequisites and access information
-  * [ ] Create first application tutorial
-* **Review/Feedback**:
-  * [ ] Stephan: 
-    * in general:
-      * [ ] some parts are worth to go th 'Governance'
-      * [ ] perhaps we should remove the emojis?
-      * [ ] perhaps we should avoid the impression that the text was copy/pated from AI
-    * some details/further ideas:
-      * [ ] where is it, this Forgejo? Why is it called 'edp.buildth.ing'?
-        * [ ] what are the components we use - package managament, actions, ...
-      * [ ] Friendly users? organisations? Public/private stuff?
-      * [ ] App Management discussions (we don't!)?
-      * [ ] what about code snippets how forgejo is deployed? SSO? user base? Federation options?
-        * [ ] storages, Redis, Postgres ... deployment options ... helm charts ...
-      * [ ] Migrations we did, where is the migration code?
-        * [ ] git POSIX filesystem concurrency discussion, S/3 bucket
-      * [ ] what is our general experience?
-        * [ ] repository centric domain data model
-      * [ ] how did we develop? which version did we take first? how did we upgrade? 
-        * [ ] which development flows did we use? which pipleines?
-      * [ ] provide codeberg links for the PRs
-      * [ ] provide architecture drawings and repo links for the cache registry thing
-      * [ ] provide a hight level actions arch diagram from the perspective of forgejo - link to the GARM component here
-{{% /alert %}}
-
-## 🧾 Result short description / cognitions
-
-Here is the management summary of the work package results:
-
-* **📈 Strategic Selection:** We chose **[Forgejo](https://forgejo.org/)** as the project's self-hosted Git service. This decision was based on several key strategic factors:
-  * **EU-Based & Data Sovereignty:** The project is stewarded by **[Codeberg e.V.](https://docs.codeberg.org/getting-started/what-is-codeberg/)**, a non-profit based in Berlin, Germany. This is a massive win for our "funding agency" stakeholders, as it aligns with **GDPR, compliance, and data sovereignty goals**. It's governed by EU laws, not a US tech entity.
-  * **True Open Source (GPL v3+):** Forgejo is a community-driven fork of Gitea, created to *guarantee* it stays 100% free and open-source (FOSS).
-  * **License Protects Our Contributions:** It uses the **GPL v3+ "copyleft" license**. This is *perfect* for our collaboration goal. It legally ensures that the features we contribute back (like GARM support) can **never be taken and locked into a proprietary, closed-source product by anyone**. It protects our work and keeps the community open.
-
-* **⚙️ Core Use Case:** Forgejo is used for all project source code **versioning** and as the backbone for our **CI/CD (Continuous Integration/Continuous Deployment)** pipelines.
-
-* **🛠️ Key Extension (GARM Support):** The main technical achievement was integrating **[GARM (GitHub Actions Runner Manager)](https://github.com/cloudbase/garm)**. This was *not* supported by Forgejo out-of-the-box.
-
-* **✨ Required Enhancements:** To make GARM work, our team developed and implemented several critical features:
-  * Webhook support for workflow events (to tell runners when to start).
-  * Support for ephemeral runners (for secure, clean-slate builds every time).
-  * GitHub API-compatible endpoints (to allow the runners to register themselves correctly).
-
-* **💖 Community Contribution:** We didn't just keep this for ourselves! We contributed all these features **directly back to the upstream Forgejo community**. This wasn't just a code-dump; we actively collaborated via **issues**, **feature requests**, and **pull requests (PRs) on [codeberg.org](https://codeberg.org/)**.
-
-* **🚀 Bonus Functionality:** We also implemented **artifact caching**. This configures Forgejo to act as a **pull-through proxy** for remote container registries (like Docker Hub), which seriously speeds up our build times and saves bandwidth.

content/en/docs/components/forgejo/project-mgmt.md

@@ -1,128 +0,0 @@
----
-title: "Project Management"
-linkTitle: "Forgejo Project Mgmt"
-weight: 50
-description: >
-  Project and issue management capabilities within Forgejo
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/_index.md

@@ -1,28 +0,0 @@
----
-title: "Orchestratiion"
-linkTitle: "Orchestration"
-weight: 10
-description: >
-  Platform and infrastructure orchestration components.
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
-* **Assignee**: Stephan
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-The Orchestration manages platform and infrastructure provisioning, providing the foundation for the EDP deployment model.
-
-## Sub-Components
-
-* **Infrastructure Provisioning**: Low-level infrastructure deployment (infra-deploy, infra-catalogue)
-* **Platform Provisioning**: Platform-level component deployment via Stacks

content/en/docs/components/orchestration/application.md

@@ -1,128 +0,0 @@
----
-title: "Application Orchestration"
-linkTitle: "Application Orchestration"
-weight: 30
-description: >
-  Application-level component provisioning via Stacks
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/infrastructure/_index.md

@@ -1,128 +0,0 @@
----
-title: "Infrastructure Orchestration"
-linkTitle: "Infrastructure Orchestration"
-weight: 10
-description: >
-  Infrastructure deployment and catalog management (infra-deploy, infra-catalogue)
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732)
-* **Assignee**: Martin
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/infrastructure/provider.md

@@ -1,127 +0,0 @@
----
-title: "Provider"
-linkTitle: "Provider"
-weight: 20
-description: Used Provider we deploy on 
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732)
-* **Assignee**: Martin
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/infrastructure/terraform.md

@@ -1,128 +0,0 @@
----
-title: "Terrafrom"
-linkTitle: "Terraform"
-weight: 10
-description: >
-  Infrastructure deployment and catalog management (infra-deploy, infra-catalogue)
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732)
-* **Assignee**: Martin
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/platform.md

@@ -1,128 +0,0 @@
----
-title: "Platform Orchestration"
-linkTitle: "Platform Orchestration"
-weight: 20
-description: >
-  Platform-level component provisioning via Stacks
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/stacks/_index.md

@@ -1,128 +0,0 @@
----
-title: "Stacks"
-linkTitle: "Stacks"
-weight: 40
-description: >
-  Platform-level component provisioning via Stacks
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-6729](https://jira.telekom-mms.com/browse/IPCEICIS-6729)
-* **Assignee**: Stephan
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/stacks/component-1.md

@@ -1,128 +0,0 @@
----
-title: "Component 1"
-linkTitle: "Component 1"
-weight: 20
-description: >
-  Component 1
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TBD]
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/orchestration/stacks/component-2.md

@@ -1,128 +0,0 @@
----
-title: "Component 2"
-linkTitle: "Component 2"
-weight: 30
-description: >
-  Component 2
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TBD]
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/physical-envs/_index.md

@@ -1,16 +0,0 @@
----
-title: "Physical Environments"
-linkTitle: "Physical Envs"
-weight: 60
-description: >
-  Physical runtime environments and infrastructure providers.
----
-
-Physical environment components provide the runtime infrastructure for deploying and running applications.
-
-## Components
-
-* **Docker**: Container runtime
-* **Kubernetes**: Container orchestration
-* **LXC**: Linux Containers
-* **Provider**: Infrastructure provider abstraction

content/en/docs/components/physical-envs/docker.md

@@ -1,128 +0,0 @@
----
-title: "Docker"
-linkTitle: "Docker"
-weight: 10
-description: >
-  Container runtime for running containerized applications
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/physical-envs/kubernetes.md

@@ -1,128 +0,0 @@
----
-title: "Kubernetes"
-linkTitle: "Kubernetes"
-weight: 20
-description: >
-  Container orchestration platform for managing containerized workloads
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/physical-envs/lxc.md

@@ -1,128 +0,0 @@
----
-title: "LXC"
-linkTitle: "LXC"
-weight: 30
-description: >
-  Linux Containers for lightweight system-level virtualization
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/components/physical-envs/provider.md

@@ -1,128 +0,0 @@
----
-title: "Infrastructure Provider"
-linkTitle: "Provider"
-weight: 40
-description: >
-  Infrastructure provider abstraction for managing physical resources
----
-
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
-## Overview
-
-[Detailed description of the component - what it is, what it does, and why it exists]
-
-## Key Features
-
-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
-
-## Repository
-
-**Code**: [Link to source code repository]
-
-**Documentation**: [Link to component-specific documentation]
-
-## Getting Started
-
-### Prerequisites
-
-* [Prerequisite 1]
-* [Prerequisite 2]
-
-### Quick Start
-
-[Step-by-step guide to get started with this component]
-
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Verification
-
-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
-
-```bash
-# Example commands
-```
-
-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
-
-## Architecture
-
-[Optional: Add architectural diagrams and descriptions]
-
-### Component Architecture (C4)
-
-[Add C4 Container or Component diagrams showing the internal structure]
-
-### Sequence Diagrams
-
-[Add sequence diagrams showing key interaction flows with other components]
-
-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
-
-## Configuration
-
-[Key configuration options and how to set them]
-
-## Troubleshooting
-
-### [Common Issue 1]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-### [Common Issue 2]
-
-**Problem**: [Description]
-
-**Solution**: [How to fix]
-
-## Status
-
-**Maturity**: [Production / Beta / Experimental]
-
-## Additional Resources
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]

content/en/docs/documentation-guide/_index.md

@@ -1,151 +0,0 @@
----
-title: "WiP Documentation Guide"
-linkTitle: "WiP Doc Guide"
-weight: 1
-description: Guidelines and templates for creating EDP documentation. This page will be removed in the final documentation.
----
-
-{{% alert title="WiP - Only during creation phase" %}}
-This page will be removed in the final documentation.
-{{% /alert %}}
-
-## Purpose
-
-This guide helps team members create consistent, high-quality documentation for the Edge Developer Platform.
-
-
-## Documentation Principles
-
-### 1. Focus on Outcomes
-
-1. Describe how the platform is comprised and which Products we deliver
-2. If you need inspiration for our EDP product structure look at [EDP product structure tree](../components/website-and-documentation_resources_product-structure.svg)
-2. Include links to repositories for deeper technical information or for not beeing too verbose and redundant with existing doumentation within the IPCEI-CIS scope or our EDP repos scope.
-
-### 2. Write for the Audience
-
-1. **Developers**: How to use the software products
-2. **Engineers**: Architecture
-3. **Auditors**: Project history, decisions, compliance information
-
-### 3. Keep It Concise
-
-1. Top-down approach: start with overview, drill down as needed
-2. Less is more - avoid deep nested structures
-3. Avoid emojis
-4. **When using AI**: Review the text that you paste, check integration into the rest of the documentation
-
-### 4. Maintain Quality
-
-1. Use present tense ("The system processes..." not "will process")
-2. Run `task test:quick` before committing changes
-
-## Documentation Structure
-
-The EDP documentation is organized into five main sections:
-
-### 1. Platform Overview
-
-High-level introduction to EDP, target audience, purpose, and product structure.
-
-**Content focus**: Why EDP exists, who uses it, what it provides
-
-### 2. Getting Started
-
-Onboarding guides and quick start instructions.
-
-**Content focus**: Prerequisites, step-by-step setup, first application deployment
-
-### 3. Components
-
-Detailed documentation for each platform component.
-
-**Content focus**: What each component does, how to use it, integration points
-
-**Template**: Use `components/TEMPLATE.md` as starting point
-
-### 4. Operations
-
-Deployment, monitoring, troubleshooting, and maintenance procedures.
-
-**Content focus**: How to operate the platform, resolve issues, maintain health
-
-### 5. Governance
-
-Project history, architecture decisions, compliance, and audit information.
-
-**Content focus**: Why decisions were made, project evolution, external relations
-
-## Writing Documentation
-
-### Components
-
-#### Using Templates
-
-In section 'Components' Templates are provided for common documentation types:
-
-* **Component Documentation**: `content/en/docs/components/TEMPLATE.md`
-
-#### Content Structure
-
-Follow this pattern for component documentation:
-
-1. **Overview**: What it is and what it does
-2. **Key Features**: Bullet list of main capabilities
-3. **Purpose in EDP**: Why it's part of the platform
-4. **Getting Started**: Quick start guide
-5. **Usage Examples**: Common scenarios
-6. **Integration Points**: How it connects to other components
-7. **Status**: Current maturity level
-8. **Documentation Notes**: Instructions for filling in details (remove when complete)
-
-### Frontmatter
-
-Every markdown file starts with YAML frontmatter according to [Docsy](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter):
-
-```yaml
----
-title: "Full Page Title"
-linkTitle: "Short Nav Title"
-weight: 10
-description: >
-  Brief description for search and previews.
----
-```
-
-* **title**: Full page title (appears in page header)
-* **linkTitle**: Shorter title for navigation menu
-* **weight**: Sort order (lower numbers appear first)
-* **description**: Brief summary for SEO and page previews
-
-## Testing Documentation
-
-Before committing changes:
-
-```bash
-# Run all tests
-task test:quick
-
-# Build site locally
-task build
-
-# Preview changes
-task serve
-```
-
-## Adding New Sections
-
-When adding a new documentation section:
-
-1. Create directory: `content/en/docs/[section-name]/`
-2. Create index file: `_index.md` with frontmatter
-3. Add weight to control sort order
-4. Update navigation in parent `_index.md` if needed
-5. Test with `task test`
-
-## Reference
-
-* **Main README**: `/doc/README-technical-writer.md`
-* **Component Template**: `/content/en/docs/components/TEMPLATE.md`
-* **Hugo Documentation**: <https://gohugo.io/documentation/>
-* **Docsy Theme**: <https://www.docsy.dev/docs/>

content/en/docs/edge-connect-ecosystem/_index.md

@@ -0,0 +1,91 @@
+---
+title: Edge Connect Ecosystem 
+linkTitle: Edge Connect Ecosystem
+weight: 1
+description: >
+  Build Your Edge Cloud Solutions in Minutes
+---
+
+## **Key Integrations** - Choose Your Workflow
+
+### **Command Line Interface (CLI)** - Power at Your Fingertips
+The **EdgeConnect CLI** is your command-line companion for rapid edge deployments. Transform complex deployment workflows into simple, intuitive commands. With intelligent state comparison, deployment planning, and YAML-based configuration parsing, this battle-tested tool brings professional-grade deployment management directly to your terminal. Whether you're orchestrating multi-platform releases or managing application lifecycles, the CLI provides the speed and precision that DevOps engineers demand.
+
+**Key Features:**
+- Configuration parsing and validation via YAML files
+- Deployment planning with state comparison capabilities
+- Cross-platform support
+
+**Repository**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client
+
+### **Go SDK** - Build Edge-Native Applications
+Embed Edge Connect directly into your Go applications with the **Go SDK**. Whether you're building custom deployment tools, automation pipelines, or management dashboards, the SDK provides native Go bindings for the complete Edge Connect API. Clean, idiomatic Go code with comprehensive error handling and type safety means you can focus on building features, not wrestling with HTTP clients.
+
+**Perfect For:** Custom tooling, automation scripts, CI/CD integrations, and any Go application that needs programmatic access to Edge Connect infrastructure.
+
+**Repository**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client
+
+### **Terraform Provider** - Infrastructure as Code, Simplified
+Declare your edge infrastructure with confidence using the **Terraform Provider for Edge Connect**. Manage applications and instances across regions with familiar HCL syntax. Full CRUD lifecycle management, Kubernetes manifest support, and seamless integration with your existing Terraform workflows. Deploy once, replicate everywhere—the infrastructure-as-code way.
+
+**Repository**: https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect
+
+### **GitHub Actions Suite** - CI/CD on Autopilot
+Three powerful actions that integrate Edge Connect directly into your GitHub workflows:
+
+- **Deploy Action**: Push your containers to the edge with a single workflow step, powered by Edge Connect SDK 2.0.1
+- **Delete Action**: Clean up resources effortlessly with force-delete capabilities
+- **Action Demo**: A complete working example showing automated builds triggered by commit SHAs, complete with Kubernetes manifests and CI/CD best practices
+
+Turn every git push into an edge deployment with no manual intervention required.
+
+**Repositories**:
+- https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action
+- https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action
+- https://edp.buildth.ing/DevFW-CICD/edgeconnect-action-demo
+
+### **MCP Server** - AI-Native Edge Management
+The **Edge Connect MCP Server** brings cutting-edge AI tooling to infrastructure management. Built on the Model Context Protocol, it offers:
+
+- Rich, interactive web-based dashboards powered by MCP-UI
+- Full application lifecycle management through conversational interfaces
+- Local (stdio) and remote (HTTP streaming) operation modes
+
+Manage your edge infrastructure through Claude Desktop or any MCP-compatible client. The future of infrastructure management is conversational.
+
+**Repository**: https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp
+
+## **Use Cases** - See It in Action
+
+### **Deployment Examples** - Hit the Ground Running
+The **edge-connect-deployment-examples** repository is your blueprint for success. Featuring real-world Terraform configurations for Edge Connect, including database integrations and infrastructure bootstrapping templates. Clone, customize, and deploy your edge solution can be live in minutes, not days.
+
+**Repository**: https://edp.buildth.ing/DevFW-CICD/edge-connect-deployment-examples
+
+### **GARM Provider** - Scale Your GitHub Actions Runners
+Transform your CI/CD capacity with the **GARM Edge Connect Provider**. Deploy ephemeral GitHub Actions runners as Kubernetes pods across edge locations. Automatic resource cleanup, customizable pod specs, and multi-platform support mean your pipelines scale elastically across the edge. Why pay for idle cloud runners when you can deploy exactly what you need, where you need it?
+
+**Repository**: https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect
+
+### **Coder Integration** - Your Development Environment, Anywhere on the Edge (In development)
+Bring the power of cloud development environments directly to the edge with the **Coder Edge Connect Integration**. This Terraform-based workspace template seamlessly deploys fully-featured VS Code development environments as Kubernetes workloads on Edge Connect infrastructure.
+
+**What It Does:**
+- **On-Demand Workspaces**: Spin up isolated development environments with customizable CPU, memory, and disk configurations
+- **Browser-Based IDE**: Automatic code-server provisioning gives you VS Code in your browser—code from anywhere, deploy to the edge
+- **Real-Time Monitoring**: Built-in Coder agent integration tracks CPU, memory, disk usage, and load averages for both containers and host systems
+- **Edge-Native Deployment**: Workspaces run as Kubernetes pods directly on Edge Connect cloudlets, bringing compute closer to your dataent
+
+**Perfect For:** Distributed development teams, edge application developers, and organizations needing secure, scalable development environments close to production edge infrastructure.
+
+**Repository**: https://edp.buildth.ing/DevFW/POC-coder-edge-connect
+
+## **The Edge Connect Advantage**
+
+This isn't just another cloud platform. It's a **complete ecosystem** designed for developer velocity:
+
+- **Multi-language support**: CLI, Go SDK, Terraform, GitHub Actions
+- **AI-native tooling**: MCP server integration for conversational infrastructure management
+- **Open and extensible**: From simple demos to complex GARM integrations
+
+**Your edge infrastructure, your way. Deploy in minutes, scale without limits.**

content/en/docs/edgeconnect/_index.md

@@ -0,0 +1,46 @@
+---
+title: EdgeConnect
+linkTitle: EdgeConnect Cloud
+weight: 20
+description: >
+  Sovereign edge cloud for running applications
+---
+
+## Overview
+
+EdgeConnect is a custom cloud provided by the project as a whole. It has several goals, including retaining sovereign control over cloud compute resources, and supporting sustainability-aware infrastructure choices.
+
+While EdgeConnect is managed outwith our Edge Developer Platform, we have produced a number of tools to facilitate its use and broaden its applicability. These are an [SDK](/docs/edgeconnect/edgeconnect-sdk/), command-line [client](/docs/edgeconnect/edgeconnect-client/), bespoke [provider](/docs/edgeconnect/terraform-provider/) for [Terraform](https://developer.hashicorp.com/terraform), and tailor-made [Forgejo Actions](/docs/edgeconnect/edgeconnect-actions/).
+
+{{< likec4-view view="edgeconnect-context" project="architecture" title="EdgeConnect Context View: Users, Tooling and Control Plane" >}}
+
+The diagram summarizes how EdgeConnect is typically consumed and operated. Developers and automation do not interact with edge clusters directly; instead they use stable entry points (CLI, SDK, Terraform) that talk to the EdgeConnect API.
+
+EdgeConnect itself is shown as a single cloud boundary that contains the control plane (API + controllers) and the managed resource model (e.g., App, AppInstance). Controllers continuously reconcile the desired state expressed via the API and drive deployments into the runtime.
+
+EDP appears here as an external consumer: it can automate provisioning and deployment workflows (for example via Terraform) while EdgeConnect remains a separately managed cloud. This separation clarifies responsibilities: EDP orchestrates delivery processes, EdgeConnect provides the target runtime and lifecycle management.
+
+## Key Features
+
+* Managed by the broader project, not specifically by EDP
+* Focus on sovereignty and sustainability
+* Utilities such as [CLI](/docs/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/edgeconnect/terraform-provider/) encourage widespread platform use
+* [EDP](/docs/edp/) products such as [Forgejo](/docs/edp/forgejo/) are hosted on [OTC](/docs/edp/deployment/otc/) rather than EdgeConnect
+
+## Purpose in EDP
+
+EdgeConnect is documented here because it is a key deployment target and integration point for the broader platform. Even though EdgeConnect is operated separately from EDP (and core EDP services are hosted on OTC), EDP tooling and automation frequently needs to provision or deploy workloads into EdgeConnect in a consistent, repeatable way.
+
+Working with EdgeConnect also helps ensure that our developer workflows and platform components remain portable and “cloud-ready” beyond a single environment. By integrating with a sovereign system and making sustainability-aware choices visible in practice, we align platform engineering with the project’s wider goals and enable closer collaboration with the teams operating the EdgeConnect cloud.
+
+### Access
+
+* [Gardener console access](https://gardener.apps.mg3.mdb.osc.live/namespace/garden-platform/shoots)
+    - Choose `Log in with mg3` then `platform` before entering credentials set up by the Platform Team.
+* [Edge cluster](https://hub.apps.edge.platform.mg3.mdb.osc.live/)
+* [Orca cluster](https://hub.apps.orca.platform.mg3.mdb.osc.live/)
+
+
+### Notes
+
+Documentation for EdgeConnect is provided using other systems, including Confluence.

content/en/docs/edgeconnect/edge-connect-mcp.md

@@ -0,0 +1,257 @@
+---
+title: Edge Connect MCP Server
+linkTitle: MCP Server
+weight: 40
+description: Model Context Protocol server enabling AI-assisted EdgeConnect management
+---
+
+## Overview
+
+The Edge Connect MCP Server enables AI assistants like [Claude](https://claude.ai) to directly interact with EdgeConnect through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). This allows natural language requests to manage applications and instances, with AI agents autonomously executing API operations on your behalf.
+
+MCP is an open protocol that connects AI systems to data sources and tools. In agentic coding workflows, AI assistants can plan, execute, and verify infrastructure operations through conversational interfaces while maintaining full visibility and control.
+
+## Key Features
+
+* **Natural language control**: Manage EdgeConnect resources through conversational AI interactions
+* **Full API coverage**: Supports all App and AppInstance operations (create, list, show, update, delete, refresh)
+* **Rich visualizations**: Interactive dashboards and detail views via [MCP-UI](https://github.com/MCP-UI-Org/mcp-ui). Tools return both JSON and HTML responses — clients like [Goose](https://github.com/block/goose) render the HTML dashboards, while others use the JSON data.
+* **Multiple integration modes**: Local stdio for desktop apps, remote HTTP/SSE for web clients
+* **Production-ready security**: OAuth 2.1 authorization with JWT validation and PKCE for remote deployments
+* **Graceful fallbacks**: Returns structured JSON when UI resources aren't supported
+
+## Purpose in EDP
+
+Manual infrastructure operations don't scale, but writing automation scripts for every task is costly. The Edge Connect MCP Server bridges this gap by enabling AI assistants to act as automation agents — understanding natural language requests, planning operations, and executing them through the [EdgeConnect API](https://swagger.edge.platform.mg3.mdb.osc.live/).
+
+This expands EdgeConnect accessibility beyond developers comfortable with [CLIs](/docs/edgeconnect/edgeconnect-client/) and [APIs](https://swagger.edge.platform.mg3.mdb.osc.live/), enabling infrastructure management through conversation while maintaining the precision and repeatability of programmatic control. For teams already using AI coding assistants, it integrates EdgeConnect operations directly into their development workflow.
+
+## Repository
+
+**Code**: https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp
+
+**Releases**: https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp/releases
+
+## Getting Started
+
+### Prerequisites
+
+* EdgeConnect access credentials (username/password or bearer token)
+* For [Claude Desktop](https://claude.ai/download): macOS or Windows with Claude Desktop installed
+* For [Claude Code](https://github.com/anthropics/claude-code): Claude CLI installed
+* For remote deployment: Server infrastructure and optional OAuth provider
+
+### Quick Start
+
+1. Download the binary from [releases](https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp/releases) or build from source:
+   ```bash
+   go build -o edge-connect-mcp
+   ```
+
+2. Configure for Claude Desktop by editing the config file:
+
+   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+   ```json
+   {
+     "mcpServers": {
+       "edge-connect": {
+         "command": "/path/to/edge-connect-mcp",
+         "env": {
+           "EDGE_CONNECT_BASE_URL": "https://hub.apps.edge.platform.mg3.mdb.osc.live",
+           "EDGE_CONNECT_AUTH_TYPE": "credentials",
+           "EDGE_CONNECT_USERNAME": "your-username",
+           "EDGE_CONNECT_PASSWORD": "your-password",
+           "EDGE_CONNECT_DEFAULT_REGION": "EU"
+         }
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Desktop and verify the MCP server appears in the tools menu
+
+### Verification
+
+Ask Claude: "List my EdgeConnect applications in the EU region." If the MCP server is configured correctly, Claude will retrieve and display your applications.
+
+## Usage Examples
+
+### Conversational Operations
+
+The MCP server enables natural interactions like:
+
+* "Show me all running application instances"
+* "Create a new app called nginx-test using the nginx:latest image"
+* "Deploy my-app version 2.0 to the Munich cloudlet"
+* "Delete all instances of old-app"
+
+Claude interprets these requests, selects appropriate tools, and executes the operations while explaining each step.
+
+### Integration with Claude Code CLI
+
+Configure the MCP server using the Claude CLI:
+
+```bash
+# Add MCP server
+claude mcp add edge-connect
+
+# Configure
+claude mcp edit edge-connect --set command=/path/to/edge-connect-mcp
+claude mcp edit edge-connect --set-env EDGE_CONNECT_BASE_URL=https://hub.apps.edge.platform.mg3.mdb.osc.live
+claude mcp edit edge-connect --set-env EDGE_CONNECT_AUTH_TYPE=credentials
+claude mcp edit edge-connect --set-env EDGE_CONNECT_USERNAME=your-username
+claude mcp edit edge-connect --set-env EDGE_CONNECT_PASSWORD=your-password
+
+# Test
+claude mcp test edge-connect
+```
+
+### Remote Deployment
+
+For team access or web-based clients, run in remote mode with [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09):
+
+```bash
+# Edge Connect configuration
+export EDGE_CONNECT_BASE_URL="https://hub.apps.edge.platform.mg3.mdb.osc.live"
+export EDGE_CONNECT_AUTH_TYPE="credentials"
+export EDGE_CONNECT_USERNAME="your-username"
+export EDGE_CONNECT_PASSWORD="your-password"
+
+# MCP server configuration
+export MCP_SERVER_MODE="remote"
+export MCP_REMOTE_HOST="0.0.0.0"
+export MCP_REMOTE_PORT="8080"
+
+# OAuth 2.1 configuration
+export OAUTH_ENABLED="true"
+export OAUTH_RESOURCE_URI="https://mcp.example.com"
+export OAUTH_AUTH_SERVERS="https://auth.example.com"
+export OAUTH_ISSUER="https://auth.example.com"
+export OAUTH_JWKS_URL="https://auth.example.com/.well-known/jwks.json"
+
+./edge-connect-mcp -mode remote
+```
+
+Web clients connect via `http://your-server:8080/mcp` using OAuth bearer tokens.
+
+**Note**: No shared remote server endpoint is currently deployed. Users must run their own instance locally or on their infrastructure. A shared deployment may be provided in future.
+
+## Configuration
+
+### Environment Variables
+
+**EdgeConnect API** (required):
+- `EDGE_CONNECT_BASE_URL`: API endpoint
+- `EDGE_CONNECT_AUTH_TYPE`: Authentication method (`token`, `credentials`, or `none`)
+- `EDGE_CONNECT_TOKEN`: Bearer token (when `auth_type=token`)
+- `EDGE_CONNECT_USERNAME`: Username (when `auth_type=credentials`)
+- `EDGE_CONNECT_PASSWORD`: Password (when `auth_type=credentials`)
+
+**Note on Authentication**: Username/password credentials are currently required because federated access with short-lived credentials is not yet available. The Platform Team plans to provide federated authentication in the coming months.
+
+**Optional**:
+- `EDGE_CONNECT_DEFAULT_REGION`: Default region (default: `EU`)
+- `EDGE_CONNECT_DEBUG`: Enable debug logging (`true` or `1`)
+
+**Remote Mode**:
+- `MCP_SERVER_MODE`: Server mode (`stdio` or `remote`)
+- `MCP_REMOTE_HOST`: Bind address (default: `0.0.0.0`)
+- `MCP_REMOTE_PORT`: Port (default: `8080`)
+- `MCP_REMOTE_AUTH_REQUIRED`: Enable simple bearer token auth (`true` or `false`)
+- `MCP_REMOTE_AUTH_TOKENS`: Comma-separated bearer tokens
+
+**OAuth 2.1** (recommended for production remote deployments):
+- `OAUTH_ENABLED`: Enable OAuth (`true` or `false`)
+- `OAUTH_RESOURCE_URI`: Protected resource identifier
+- `OAUTH_AUTH_SERVERS`: Authorization server URLs (comma-separated)
+- `OAUTH_ISSUER`: JWT token issuer
+- `OAUTH_JWKS_URL`: JSON Web Key Set endpoint
+
+### Command-Line Flags
+
+Flags override environment variables:
+- `-mode`: Server mode (`stdio` or `remote`)
+- `-host`: Bind address for remote mode
+- `-port`: Port for remote mode
+
+### Available Tools
+
+**App Management**:
+- `create_app`: Create new application
+- `show_app`: Retrieve application details (with UI visualization)
+- `list_apps`: List applications matching filters (with UI dashboard)
+- `update_app`: Update existing application
+- `delete_app`: Delete application (idempotent)
+
+**App Instance Management**:
+- `create_app_instance`: Create instance on cloudlet
+- `show_app_instance`: Retrieve instance details
+- `list_app_instances`: List instances matching filters (with UI dashboard)
+- `update_app_instance`: Update instance configuration
+- `refresh_app_instance`: Refresh instance state
+- `delete_app_instance`: Delete instance (idempotent)
+
+### MCP-UI Visualization Support
+
+This server implements [MCP-UI](https://github.com/MCP-UI-Org/mcp-ui), returning both structured JSON and rich HTML visualizations in every response. The HTML includes interactive dashboards with status indicators, filtering, and visual organization of infrastructure data.
+
+MCP clients that support UI resources (currently [Goose](https://github.com/block/goose)) will automatically render these HTML views. Clients without UI support (like [Claude Desktop](https://claude.ai/download) and [Claude Code](https://github.com/anthropics/claude-code)) receive the JSON data and work normally without the visual enhancements.
+
+Operations with UI support include `list_apps`, `show_app`, `list_app_instances`, and `show_app_instance`.
+
+## Integration Points
+
+* **EdgeConnect API**: Communicates with [EdgeConnect platform](https://hub.apps.edge.platform.mg3.mdb.osc.live) for all operations
+* **EdgeConnect SDK**: Built on the [Go SDK](/docs/edgeconnect/edgeconnect-sdk/) for authentication and API client implementation
+* **[MCP-UI](https://github.com/MCP-UI-Org/mcp-ui)**: All tools return dual-format responses (JSON + HTML). Clients that support UI resources (like [Goose](https://github.com/block/goose)) render rich HTML dashboards; others use the JSON data automatically.
+* **[Claude Desktop](https://claude.ai/download)/[Code](https://github.com/anthropics/claude-code)**: Primary integration targets for AI-assisted infrastructure management
+* **OAuth Providers**: Supports [Auth0](https://auth0.com/), [Amazon Cognito](https://aws.amazon.com/cognito/), [Keycloak](https://www.keycloak.org/), and other [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09)-compliant systems
+
+## Troubleshooting
+
+### MCP Server Not Appearing
+
+**Problem**: Claude Desktop doesn't show the edge-connect tools
+
+**Solution**:
+- Verify the config file path is correct for your OS
+- Check the `command` path points to the binary
+- Restart Claude Desktop after configuration changes
+- Check Claude Desktop logs for MCP initialization errors
+
+### Authentication Errors
+
+**Problem**: Operations fail with "authentication failed" or "unauthorized"
+
+**Solution**:
+- Verify credentials in environment variables are correct
+- Ensure `EDGE_CONNECT_BASE_URL` uses HTTPS and has no trailing slash
+- Check `EDGE_CONNECT_AUTH_TYPE` matches your credential type
+- Test credentials with the [EdgeConnect CLI](/docs/edgeconnect/edgeconnect-client/) first
+
+### Remote Server Connection Issues
+
+**Problem**: Can't connect to remote MCP server
+
+**Solution**:
+- Verify server is running: check `/health` endpoint returns `{"status":"healthy"}`
+- If OAuth is enabled, ensure client has valid JWT bearer token
+- Check firewall rules allow connections to the MCP port
+- Verify CORS headers if connecting from web clients
+- Review server logs for authentication or validation errors
+
+## Status
+
+**Maturity**: Production
+
+## Additional Resources
+
+* [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+* [MCP-UI Documentation](https://github.com/MCP-UI-Org/mcp-ui)
+* [EdgeConnect API Documentation](https://swagger.edge.platform.mg3.mdb.osc.live/)
+* [Claude Desktop](https://claude.ai/download)
+* [OAuth 2.1 RFC](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09)
+* [Source Code Repository](https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp)

content/en/docs/edgeconnect/edgeconnect-actions.md

@@ -0,0 +1,286 @@
+---
+title: Forgejo Actions
+linkTitle: Forgejo Actions
+weight: 40
+description: >
+  CI/CD actions for automated EdgeConnect deployment and deletion
+---
+
+## Overview
+
+The EdgeConnect Actions are custom composite actions for use in [Forgejo](/docs/edp/forgejo/actions/)/[GitHub Actions](https://forgejo.org/docs/latest/user/actions/github-actions/) that automate EdgeConnect application deployments in CI/CD pipelines. They wrap the [EdgeConnect Client](/docs/edgeconnect/edgeconnect-client/) to provide a simple, declarative way to deploy and delete applications without manual CLI installation or configuration.
+
+Two actions are available:
+- **edge-connect-deploy-action**: Deploys applications using declarative YAML configuration
+- **edge-connect-delete-action**: Deletes applications and their instances from EdgeConnect
+
+## Key Features
+
+* **Zero installation**: Actions automatically download and use the EdgeConnect Client
+* **Declarative workflow**: Deploy applications using YAML configuration files
+* **CI/CD optimized**: Designed for automated pipelines with auto-approve and dry-run support
+* **Version pinning**: Specify exact EdgeConnect Client version for reproducible builds
+* **Secrets management**: Credentials passed securely through workflow secrets
+* **Compatible with GitHub and Forgejo Actions**: Works in both ecosystems
+
+## Purpose in EDP
+
+CI/CD automation is essential for modern development workflows. While the [EdgeConnect Client](/docs/edgeconnect/edgeconnect-client/) provides powerful deployment capabilities, integrating it into CI/CD pipelines requires downloading binaries, managing credentials, and configuring authentication for each workflow run.
+
+These actions eliminate that boilerplate by:
+- Automatically fetching the correct Client version
+- Handling authentication setup
+- Providing a clean, reusable action interface
+- Reducing pipeline configuration to a few lines
+
+This enables teams to focus on application configuration rather than pipeline plumbing, while maintaining the full power of declarative EdgeConnect deployments.
+
+The actions complement the [Terraform provider](/docs/edgeconnect/terraform-provider/) by offering a simpler option for teams already using Forgejo/GitHub Actions who want deployment automation without adopting Terraform.
+
+## Repository
+
+**Deploy Action**: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action
+
+**Delete Action**: https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action
+
+**Demo Repository**: https://edp.buildth.ing/DevFW-CICD/edgeconnect-action-demo
+
+## Getting Started
+
+### Prerequisites
+
+* Forgejo or GitHub repository with Actions enabled
+* EdgeConnect access credentials (username and password)
+* `EdgeConnectConfig.yaml` file defining your application (see [YAML Configuration Format](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format))
+* For Kubernetes apps: K8s manifest file referenced in the config
+* Repository secrets configured with EdgeConnect credentials
+
+### Quick Start
+
+1. Create an `EdgeConnectConfig.yaml` file in your repository defining your application (see [Client documentation](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format))
+2. Add EdgeConnect credentials as repository secrets:
+   - `EDGEXR_PLATFORM_USERNAME`
+   - `EDGEXR_PLATFORM_PASSWORD`
+3. Create a workflow file (e.g., `.forgejo/workflows/deploy.yaml`) using the action
+4. Commit and push to trigger the workflow
+
+### Verification
+
+After the workflow runs successfully:
+- Check the workflow logs for deployment status
+- Verify resources appear in the [EdgeConnect console](https://hub.apps.edge.platform.mg3.mdb.osc.live/)
+- Test application endpoints are accessible
+
+## Usage Examples
+
+### Minimal Deploy Action
+
+```yaml
+- name: Deploy to EdgeConnect
+  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
+  with:
+    configFile: ./EdgeConnectConfig.yaml
+    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
+    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
+    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
+```
+
+### Minimal Delete Action
+
+```yaml
+- name: Delete from EdgeConnect
+  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action@main
+  with:
+    configFile: ./EdgeConnectConfig.yaml
+    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
+    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
+    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
+```
+
+### Complete Workflow Example
+
+A typical deployment workflow that builds, tags, and deploys:
+
+```yaml
+name: deploy
+
+on:
+  workflow_run:
+    workflows: [build]
+    types:
+      - completed
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Update manifest with image tag
+        run: |
+          sha="${{ github.sha }}"
+          shortSha="${sha:0:7}"
+          echo "Setting image version to: registry.example.com/myapp:${shortSha}"
+          sed -i "s@###IMAGETAG###@registry.example.com/myapp:${shortSha}@g" ./k8s-deployment.yaml
+
+      - name: Deploy to EdgeConnect
+        uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
+        with:
+          configFile: ./EdgeConnectConfig.yaml
+          baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
+          username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
+          password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
+```
+
+### Dry-Run Mode
+
+Preview changes without applying them:
+
+```yaml
+- name: Preview deployment
+  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
+  with:
+    configFile: ./EdgeConnectConfig.yaml
+    dryRun: 'true'
+    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
+    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
+    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
+```
+
+### Version Pinning
+
+Use a specific EdgeConnect Client version:
+
+```yaml
+- name: Deploy with specific version
+  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
+  with:
+    configFile: ./EdgeConnectConfig.yaml
+    version: 'v2.0.1'
+    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
+    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
+    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
+```
+
+## Integration Points
+
+* **EdgeConnect Client**: Actions download and execute the Client CLI tool
+* **EdgeConnect SDK**: Client uses the SDK for all API interactions
+* **Forgejo/GitHub Actions**: Native integration with both action ecosystems
+* **EdgeConnect API**: All operations communicate with EdgeConnect platform APIs
+* **Container Registries**: Works with any registry for application images
+
+## Configuration
+
+### Action Inputs
+
+Both deploy and delete actions accept the same inputs:
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `configFile` | Yes | - | Path to EdgeConnectConfig.yaml file |
+| `baseUrl` | Yes | - | EdgeConnect API base URL (e.g., https://hub.apps.edge.platform.mg3.mdb.osc.live) |
+| `username` | Yes | - | EdgeConnect username for authentication |
+| `password` | Yes | - | EdgeConnect password for authentication |
+| `dryRun` | No | `false` | Preview changes without applying (set to `'true'` to enable) |
+| `version` | No | `v2.0.1` | EdgeConnect Client version to download and use |
+
+### YAML Configuration File
+
+The `configFile` parameter points to an `EdgeConnectConfig.yaml` that defines your application and deployment targets. See the [EdgeConnect Client YAML Configuration Format](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format) for the complete specification.
+
+Example structure:
+
+```yaml
+kind: edgeconnect-deployment
+metadata:
+  name: "my-app"
+  appVersion: "1.0.0"
+  organization: "myorg"
+spec:
+  k8sApp:
+    manifestFile: "./k8s-deployment.yaml"
+  infraTemplate:
+    - region: "EU"
+      cloudletOrg: "TelekomOp"
+      cloudletName: "Munich"
+      flavorName: "EU.small"
+```
+
+### Secrets Management
+
+Configure repository secrets in Forgejo/GitHub:
+
+1. Navigate to repository Settings → Secrets
+2. Add secrets:
+   - Name: `EDGEXR_PLATFORM_USERNAME`, Value: your EdgeConnect username
+   - Name: `EDGEXR_PLATFORM_PASSWORD`, Value: your EdgeConnect password
+3. Reference in workflows using `${{ secrets.SECRET_NAME }}`
+
+## Troubleshooting
+
+### Action Fails with "Failed to download edge-connect-client"
+
+**Problem**: Action cannot download the Client binary
+
+**Solution**:
+- Verify the `version` parameter matches an actual release version
+    - Ensure the release exists at https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases
+- Check network connectivity from the runner
+- Try using default version by omitting the `version` parameter
+
+### Authentication Errors
+
+**Problem**: "authentication failed" or "unauthorized" errors
+
+**Solution**:
+- Verify secrets are correctly configured in repository settings
+- Check secret names match exactly (case-sensitive)
+- Ensure `baseUrl` is correct for your target environment (Edge vs Orca)
+- Confirm credentials work by testing with the [client](../edgeconnect-client/)
+
+### "Configuration validation failed"
+
+**Problem**: YAML configuration file validation errors
+
+**Solution**:
+- Verify `configFile` path is correct relative to repository root
+- Check YAML syntax is valid (use a YAML validator)
+- Ensure all required fields are present (see [Client docs](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format))
+- Verify manifest file paths in the config exist and are correct
+
+### Resources Not Appearing in Console
+
+**Problem**: Action succeeds but resources don't appear in EdgeConnect console
+
+**Solution**:
+- Verify you're checking the correct environment (Edge vs Orca)
+- Ensure `baseUrl` parameter matches the console you're viewing
+- Check organization name in config matches your console access
+- Review action logs for any warnings or skipped operations
+
+### Deployment Succeeds but App Doesn't Work
+
+**Problem**: Deployment completes but application is not functioning
+
+**Solution**:
+- Check application logs in the EdgeConnect console
+- Verify image tags are correct (common issue with placeholder replacement)
+- Ensure manifest files reference correct image registry and paths
+- Check network configuration allows required outbound connections
+- Verify cloudlet has sufficient resources for the specified flavor
+
+## Status
+
+**Maturity**: Production
+
+## Additional Resources
+
+* [EdgeConnect Client Documentation](/docs/edgeconnect/edgeconnect-client/)
+* [EdgeConnect SDK Documentation](/docs/edgeconnect/edgeconnect-sdk/)
+* [Terraform Provider Documentation](/docs/edgeconnect/terraform-provider/)
+* [EdgeConnect Console](https://hub.apps.edge.platform.mg3.mdb.osc.live/)
+* [Demo Repository](https://edp.buildth.ing/DevFW-CICD/edgeconnect-action-demo)
+* [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)

content/en/docs/edgeconnect/edgeconnect-client.md

@@ -0,0 +1,246 @@
+---
+title: EdgeConnect Client
+linkTitle: Client
+weight: 20
+description: >
+  Client software for establishing EdgeConnect connections
+---
+
+## Overview
+
+The EdgeConnect Client is a command-line tool for managing EdgeConnect applications and instances. It is built using our Golang [SDK](/docs/edgeconnect/edgeconnect-sdk/), and supports functionality to create, destroy, describe and list various resources.
+
+The tool provides both imperative commands (for direct resource management) and declarative workflows (using YAML configuration files) to deploy applications across multiple edge cloudlets. It supports different EdgeConnect deployment environments through an API version selector.
+
+## Key Features
+
+* **Dual workflow support**: Imperative commands for direct operations, declarative YAML for infrastructure-as-code
+* **Multi-cloudlet deployment**: Deploy applications to multiple edge locations from a single configuration
+* **Deployment planning**: Preview and approve changes before applying them (dry-run mode)
+* **Environment compatibility**: Works with different EdgeConnect deployment environments (configured via `api-version`)
+* **CI/CD ready**: Designed for automated deployments with auto-approve and exit codes
+
+## Purpose in EDP
+
+No system can be considered useful unless it is actually, in practice, used. While the Edge Connect [console](https://hub.apps.edge.platform.mg3.mdb.osc.live/) and [API](https://swagger.edge.platform.mg3.mdb.osc.live/) are essential tools to allow the platform to be used by developers, there are numerous use cases for interaction that is automated but simpler to use than an API.
+
+The EdgeConnect Client bridges the gap between manual console operations and direct API integration, enabling automated deployments in CI/CD pipelines, infrastructure-as-code workflows, and scripted operations while maintaining simplicity and usability.
+
+## Repository
+
+**Code**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client
+
+**Releases**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases
+
+## Getting Started
+
+### Prerequisites
+
+* Access credentials for the EdgeConnect platform (username and password)
+* Knowledge of your target deployment environment (determines `api-version` setting)
+* For Kubernetes deployments: K8s manifest files
+* For Docker deployments: Docker image reference
+
+### Quick Start
+
+1. Download the Edge Connect Client binary from the Forgejo [releases page](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases) for your platform (Linux, macOS, or Windows)
+2. Extract and move to your PATH: `tar -xzf edge-connect-client_*.tar.gz && sudo mv edge-connect /usr/local/bin/`
+3. Configure authentication using environment variables or a config file (see Configuration section)
+4. Verify installation: `edge-connect --help`
+
+### Verification
+
+Run `edge-connect app list --org <your-org> --region <region>` to verify you can authenticate and communicate with the EdgeConnect API.
+
+## Usage Examples
+
+### Declarative Deployment (Recommended)
+
+Create an `EdgeConnectConfig.yaml` file defining your application and deployment targets, then apply it:
+
+```bash
+edge-connect apply -f EdgeConnectConfig.yaml
+```
+
+Use `--dry-run` to preview changes without applying them, and `--auto-approve` for automated CI/CD workflows.
+
+### Imperative Commands
+
+Direct resource management using CLI commands:
+
+```bash
+# Create an application
+edge-connect app create --org myorg --name myapp --version 1.0.0 --region EU
+
+# Create an instance on a specific cloudlet
+edge-connect instance create --org myorg --name myinstance \
+  --app myapp --version 1.0.0 --region EU \
+  --cloudlet Munich --cloudlet-org TelekomOp --flavor EU.small
+
+# List resources
+edge-connect app list --org myorg --region EU
+edge-connect instance list --org myorg --region EU
+
+# Delete resources
+edge-connect instance delete --org myorg --name myinstance --region EU \
+  --cloudlet Munich --cloudlet-org TelekomOp
+edge-connect app delete --org myorg --name myapp --version 1.0.0 --region EU
+```
+
+## Integration Points
+
+* **EdgeConnect API**: Communicates with EdgeConnect platform APIs for all resource operations
+* **EdgeConnect SDK**: Built on top of the Golang SDK, sharing authentication and client implementation
+* **CI/CD Pipelines**: Designed for integration with GitLab CI, GitHub Actions, and other automation tools
+* **Infrastructure-as-Code**: YAML configuration files enable GitOps workflows
+
+## Configuration
+
+### Global Settings
+
+The client can be configured via config file, environment variables, or command-line flags (in order of precedence: flags > env vars > config file).
+
+**Config File** (`~/.edge-connect.yaml` or use `--config` flag):
+
+```yaml
+base_url: "https://hub.apps.edge.platform.mg3.mdb.osc.live"
+username: "your-username@example.com"
+password: "your-password"
+api_version: "v2"  # v1 or v2 - identifies deployment environment
+```
+
+**Environment Variables**:
+
+- `EDGE_CONNECT_BASE_URL`: API base URL
+- `EDGE_CONNECT_USERNAME`: Authentication username
+- `EDGE_CONNECT_PASSWORD`: Authentication password
+- `EDGE_CONNECT_API_VERSION`: API version selector (v1 or v2, default: v2)
+
+**Global Flags** (available on all commands):
+
+- `--base-url`: API base URL
+- `--username`: Authentication username
+- `--password`: Authentication password
+- `--api-version`: API version selector (v1 or v2) - specifies which deployment environment to target
+- `--config`: Path to config file
+- `--debug`: Enable debug logging
+
+**Note on API Versions**: The `api-version` setting (v1 or v2) is an internal label used to distinguish between different EdgeConnect deployment environments, not an official API version designation from the platform.
+
+### Commands
+
+**App Management** (`edge-connect app <command>`):
+
+CLI command `app` corresponds to **App** in the platform console.
+
+- `create`: Create app (flags: `--org`, `--name`, `--version`, `--region`)
+- `show`: Show app details (flags: same as create)
+- `list`: List apps (flags: `--org`, `--region`, optional: `--name`, `--version`)
+- `delete`: Delete app (flags: `--org`, `--name`, `--version`, `--region`)
+
+**App Instance Management** (`edge-connect instance <command>`):
+
+CLI command `instance` corresponds to **App Instance** in the platform console.
+
+- `create`: Create app instance (flags: `--org`, `--name`, `--app`, `--version`, `--region`, `--cloudlet`, `--cloudlet-org`, `--flavor`)
+- `show`: Show app instance details (flags: `--org`, `--name`, `--cloudlet`, `--cloudlet-org`, `--region`, `--app-id`)
+- `list`: List app instances (flags: same as show, all optional)
+- `delete`: Delete app instance (flags: `--org`, `--name`, `--cloudlet`, `--cloudlet-org`, `--region`)
+
+**Declarative Operations**:
+
+- `apply`: Deploy from YAML (flags: `-f <file>`, `--dry-run`, `--auto-approve`)
+- `delete`: Delete from YAML (flags: `-f <file>`, `--dry-run`, `--auto-approve`)
+
+### YAML Configuration Format
+
+The `EdgeConnectConfig.yaml` file defines apps and their deployment targets:
+
+```yaml
+kind: edgeconnect-deployment
+metadata:
+  name: "my-app"                    # App name (required)
+  appVersion: "1.0.0"               # App version (required)
+  organization: "myorg"             # Organization (required)
+
+spec:
+  # Choose ONE: k8sApp OR dockerApp
+  k8sApp:
+    manifestFile: "./k8s-deployment.yaml"  # Path to K8s manifest
+
+  # OR dockerApp:
+  #   image: "registry.example.com/myimage:tag"
+  #   manifestFile: "./docker-compose.yaml"  # Optional
+
+  # Deployment targets (at least one required)
+  infraTemplate:
+    - region: "EU"                  # Region (required)
+      cloudletOrg: "TelekomOp"      # Cloudlet provider (required)
+      cloudletName: "Munich"        # Cloudlet name (required)
+      flavorName: "EU.small"        # Instance size (required)
+    - region: "US"
+      cloudletOrg: "TelekomOp"
+      cloudletName: "gardener-shepherd-test"
+      flavorName: "default"
+
+  # Optional network configuration
+  network:
+    outboundConnections:
+      - protocol: "tcp"             # tcp, udp, or icmp
+        portRangeMin: 80
+        portRangeMax: 80
+        remoteCIDR: "0.0.0.0/0"
+      - protocol: "tcp"
+        portRangeMin: 443
+        portRangeMax: 443
+        remoteCIDR: "0.0.0.0/0"
+
+  # Optional deployment strategy (default: recreate)
+  deploymentStrategy: "recreate"    # recreate, blue-green, or rolling
+```
+
+**Key Points**:
+- Manifest file paths are relative to the config file location
+- Multiple `infraTemplate` entries deploy to multiple cloudlets simultaneously
+- Network configuration is optional; outbound connections default to platform settings
+- Deployment strategy currently only supports "recreate" (others planned)
+
+## Troubleshooting
+
+### Authentication Failures
+
+**Problem**: Errors like "authentication failed" or "unauthorized"
+
+**Solution**:
+- Verify credentials are correct in config file or environment variables
+- Ensure `base_url` includes the scheme (https://) and has no trailing path
+- Check that you're connecting to the correct cloud instance (Edge or Orca)
+- Ensure the correct `api-version` is set for your deployment environment
+
+### "Configuration validation failed" Errors
+
+**Problem**: YAML configuration file validation errors
+
+**Solution**:
+- Check that all required fields are present (name, appVersion, organization)
+- Ensure you have exactly one of `k8sApp` or `dockerApp` (not both, not neither)
+- Verify manifest file paths exist relative to the config file location
+- Check for leading/trailing whitespace in string values
+- Ensure at least one `infraTemplate` entry is defined
+
+### Wrong API Version or Cloud Instance
+
+**Problem**: Commands work but resources don't appear in the console, or vice versa
+
+**Solution**: Verify both the `base_url` and `api-version` match your target environment. There are two cloud instances (Edge and Orca) with different URLs and API versions. Check with your platform administrator for the correct configuration.
+
+## Status
+
+**Maturity**: Production
+
+## Additional Resources
+
+* [EdgeConnect SDK Documentation](/docs/edgeconnect/edgeconnect-sdk/)
+* **Edge Cloud**: [Console](https://hub.apps.edge.platform.mg3.mdb.osc.live/) | [API Docs](https://swagger.edge.platform.mg3.mdb.osc.live/)
+* **Orca Cloud**: [Console](https://hub.apps.orca.platform.mg3.mdb.osc.live/) | [API Docs](https://swagger.orca.platform.mg3.mdb.osc.live/)
+* [Source Code Repository](https://edp.buildth.ing/DevFW-CICD/edge-connect-client)

content/en/docs/edgeconnect/edgeconnect-sdk.md

@@ -0,0 +1,70 @@
+---
+title: EdgeConnect SDK
+linkTitle: SDK
+weight: 10
+description: >
+  Software Development Kit for interacting with EdgeConnect
+---
+
+## Overview
+
+The EdgeConnect SDK is a Go library which provides a simple method for interacting with Edge Connect within programs. It is designed to be used by other tools, such as the [EdgeConnect Client](/docs/edgeconnect/edgeconnect-client/) or [Terraform provider](/docs/edgeconnect/terraform-provider/),
+
+## Key Features
+
+* Allows querying endpoints without the need to manage API calls and responses directly
+* Wraps the existing [Edge Connect API](https://swagger.edge.platform.mg3.mdb.osc.live/)
+* Supports multiple unnumbered versions of the API
+
+## Purpose in EDP
+
+No system can be considered useful unless it is actually, in practice, used. While the Edge Connect [console](https://hub.apps.edge.platform.mg3.mdb.osc.live/) and [API](https://swagger.edge.platform.mg3.mdb.osc.live/) are essential tools to allow the platform to be used by developers, there are numerous use cases for interaction that is automated but simpler to use than an API. These include a [command-line tool](/docs/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/edgeconnect/terraform-provider/).
+
+While each such tool could simply independently wrap existing endpoints, this is generally too low-level for sustainable development. It would involve extensive boilerplate code in each such package, plus small changes to API endpoints or error handling may require constant rework.
+
+To avoid this, the Edge Connect SDK aims to provide a common library for interacting with EdgeConnect, allowing the abstraction of HTTP requests and authentication procedures while nonetheless allowing access directly to the endpoints available.
+
+## Repository
+
+**Code**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client
+
+**Documentation**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk
+
+## Getting Started
+
+### Prerequisites
+
+* Golang
+* Edge Connect credentials
+
+### Quick Start
+
+[Step-by-step guide to get started with this component]
+
+1. Simply [import](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#installation) the SDK to your project
+2. [Initialise and configure](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#configuration-options) a client with your credentials
+3. [Build](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#examples) your code around the existing endpoints
+
+### Verification
+
+[How to verify the component is working correctly]
+
+## Usage Examples
+
+See [README](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#examples) for simple code examples, or repositories for [EdgeConnect Client](/docs/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/edgeconnect/terraform-provider/) for full projects relying on it.
+
+## Troubleshooting
+
+### Varying code versions
+
+**Problem**: While the Edge Connect API does not (at time of writing) have different semantic versions, it does have different iterations which function differently. The SDK provides two different libraries, labelled [v1](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect) and [v2](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect/v2) and referring to API definitions similarly stored as [v1](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/api/swagger_v1.json) and [v2](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/api/swagger_v2.json).
+
+**Solution**: If you receive errors when using the SDK, consider changing the version you import:
+```go
+import v1 "edp.buildth.ing/DevFW-CICD/edge-connect-client/sdk/edgeconnect"
+import v2 "edp.buildth.ing/DevFW-CICD/edge-connect-client/v2/sdk/edgeconnect/v2"
+```
+
+## Status
+
+**Maturity**: Beta

content/en/docs/edgeconnect/terraform-provider.md

@@ -0,0 +1,80 @@
+---
+title: Terraform provider for Edge cloud
+linkTitle: Terraform provider
+weight: 30
+description: Custom Terraform provider for orchestrating Edge deployments
+---
+
+## Overview
+
+This work-in-progress Terraform provider for Edge cloud allows orchestration of selected resources using flexible, concise [HCL](https://developer.hashicorp.com/terraform/language). This allows deployment to Edge Cloud through a familiar format, abstracting away specific endpoints and authentication elements, and allowing seamless combination of Edge resources with others: on OTC, other clouds, or local utilities.
+
+## Key Features
+
+* Interact with Apps and AppInstances using widely-used Terraform framework
+* Using Terraform's systems, provide minimal configuration: just an endpoint and credentials, then no need to deal with headers or other API boilerplate
+* Also works with community-driven OpenTofu
+* Provider currently under development: more features can be added when requested.
+
+## Purpose in EDP
+
+Interacting with infrastructure is a complex process, with many parameters and components working together. Doing so by clicking buttons in a web UI ("ClickOps") is extremely difficult to scale, rapidly becoming highly confusing.
+
+Instead, automations are possible through APIs and SDKs. Working directly with an API (e.g. via `curl`) inevitably tends to involve large amounts of boilerplate code to manage authentication, rarely-changing configuration such as region/tenant selection, and more. When one resource (say, a web server) must interact with another (say, a DNS record), the cross-references further increase this complexity.
+
+An SDK mitigates this complexity when coding software, by providing library functions which interact with the API in abstracted ways which require a minimum of necessary information. Our SDK for Edge Connect is described in a [separate section](/docs/edgeconnect/edgeconnect-sdk/).
+
+However, when simply wanting to deploy infrastructure in isolation - say, updating the status of a Kubernetes or App resource after a change in configuration - an SDK is still an overly complicated tool.
+
+This is where [Terraform](https://developer.hashicorp.com/terraform) or its community-led alternative [OpenTofu](https://opentofu.org/), come in. They provide a simple language for defining resources, with a level of abstraction that retains the power and flexibility of the API while greatly simplifying definitions and execution.
+
+Terraform is widely used for major infrastructure systems such as [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs), [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) or general [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs). However, it is highly flexible, supporting a range of resource types which are not inherently tied to infrastructure: [file](https://registry.terraform.io/search/providers?q=file) manipulation; package setup through [Ansible](https://registry.terraform.io/providers/ansible/aap/1.4.0); secret generation in [Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs).
+
+As a result of this breadth of functionality and cross-compatibility, Terraform support is considered by some as necessary for a platform to be used 'seriously' - that is, at scale, or in major workloads. Our provider thus unlocks broad market relevance for the platform in a way few other tools or features could.
+
+## Repository
+
+**Code**: https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect
+
+**Documentation**: Provider is intended to ultimately wrap each resource-based endpoint of the [Edge API](https://swagger.edge.platform.mg3.mdb.osc.live/), but currently supports a limited [subset of resources](https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect#resources).
+
+## Getting Started
+
+### Prerequisites
+
+* [Terraform](https://developer.hashicorp.com/terraform) or [OpenTofu](https://opentofu.org/)
+* Edge access and credentials
+
+### Quick Start
+
+1. Configure Terraform to use the provider by [including it](https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect#using-terraform-registry-recommended) in `provider.tf`
+1. In the same directory, create terraform resources in `.tf` files according to the [spec](https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect#resources)
+1. [Set up credentials](https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect/src/branch/main/README.md#provider-configuration) using environment variables or a `provider` block
+1. Run `terraform init` in the directory
+1. Execute `terraform plan` and/or `terraform apply` to deploy your application
+1. `terraform destroy` can be used to remove all deployed resources
+
+### Verification
+
+If `terraform apply` completes successfully (without errors), the provider is working correctly. You can also manually validate in the Edge UI that your resources have been deployed/reconfigured as Terraform indicated.
+
+
+## Status
+
+**Maturity**: Experimental
+
+## Additional Resources
+
+* [Terralist](https://www.terralist.io/)
+* [Terraform](https://developer.hashicorp.com/terraform)
+* [OpenTofu](https://opentofu.org/)
+* [Edge Connect API](https://swagger.edge.platform.mg3.mdb.osc.live)
+
+## Integration Points
+
+* **Edge Connect SDK**: The provider uses the [Edge Connect SDK](http://localhost:1313/docs/components/deployments/edgeconnect/edgeconnect-sdk/) under the hood.
+* **Terralist**: The provider is published using a [custom instance](https://terralist.edp.buildth.ing/) of [Terralist](https://www.terralist.io/). This [can only](https://edp.buildth.ing/DevFW-CICD/stacks/src/commit/5b438097bbd027f0025d6198c34c22f856392a03/template/stacks/terralist/terralist/values.yaml#L9-L38) be written to with a login via [Forgejo](https://edp.buildth.ing/), but can be read publicly. See [the repository README](https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect#terralist) for more information.
+
+### Component Architecture (C4)
+
+<likec4-view view-id="provider" browser="true"></likec4-view>

content/en/docs/edp/_index.md

@@ -0,0 +1,52 @@
+---
+title: Edge Developer Platform
+linkTitle: Edge Developer Platform
+weight: 10
+description: >
+  A platform to support developers working in the Edge, based around Forgejo
+---
+
+## Purpose
+
+The Edge Developer Platform (EDP) is a comprehensive DevOps platform designed to enable developers to build, deploy, and operate cloud-native applications at the edge. It provides an integrated suite of tools and services covering the entire software development lifecycle.
+
+{{< likec4-view view="application-transition" project="architecture" title="EDP Context View: Edge Developer Platform Components and User Interaction" >}}
+
+The magenta **EDP** represents the developer platform: a shared, productized layer that enables modern DevOps by standardizing how applications are described, built, deployed, and observed. In the **inner loop**, developers iterate locally (fast feedback: code → run → test). EDP then connects that work to an **outer loop** where additional roles (review, test, operations, audit/compliance) contribute feedback and controls for production readiness.
+
+In this modern DevOps setup, EDP acts as the hub: it synchronizes with local development and **deploys applications to target clouds** (for example, an EdgeConnect cloud), while providing the operational capabilities needed to run them safely. Agentic AI can support both loops—for example by assisting developers with implementation and testing in the inner loop, and by automating reviews, policy checks, release notes, and deployment verification (including drift detection and remediation) in the outer loop.
+
+
+## Product Structure
+
+EDP consists of multiple integrated components organized in layers:
+
+### Core Platform Services
+
+The foundation layer provides essential platform capabilities including source code management, CI/CD, and container orchestration.
+
+For documentation, see: [Basic Platform Concepts](./deployment/basics/) and [Forgejo](./forgejo/)
+
+### Developer Experience
+
+Tools and services that developers interact with directly to build, test, and deploy applications.
+
+For documentation, see: [Forgejo](./forgejo/) and [Deployment](./deployment/)
+
+### Infrastructure & Operations
+
+Infrastructure automation, observability, and operational tooling for platform management.
+
+For documentation, see: [Operations](./operations/) and [Infrastructure as Code](./deployment/infrastructure/)
+
+## Getting Started
+
+EDP is available at https://edp.buildth.ing.
+
+EDP includes a Forgejo instance that hosts both public and private repositories containing all EDP components.
+
+To request access and get onboarded, start with the welcome repository:
+
+- https://edp.buildth.ing/edp-team/welcome
+
+Once you have access to the repositories, you can explore the EDP documentation according to the product structure above.

content/en/docs/edp/deployment/_index.md

@@ -0,0 +1,509 @@
+---
+title: Deployment
+linkTitle: Deployment
+weight: 10
+description: >
+  Platform-level component provisioning via Stacks - Orchestrating the platform infrastructure itself
+---
+
+## Overview
+
+Platform Orchestration refers to the automation and management of the platform infrastructure itself. This includes the provisioning, configuration, and lifecycle management of all components that make up the Internal Developer Platform (IDP).
+
+In the context of IPCEI-CIS, Platform Orchestration means:
+
+- **Platform Bootstrap**: Initial setup of Kubernetes clusters and core services
+- **Platform Services Management**: Deployment and management of ArgoCD, Forgejo, Keycloak, etc.
+- **Infrastructure-as-Code**: Declarative management using Terraform and GitOps
+- **Multi-Cluster Orchestration**: Coordination across different Kubernetes clusters
+- **Platform Stacks**: Reusable bundles of platform components (CNOE concept)
+
+### Target Audience
+
+Platform Orchestration is primarily aimed at:
+
+- **Platform Engineering Teams**: Teams that build and operate the IDP
+- **Infrastructure Architects**: Those responsible for the platform architecture
+- **SRE Teams**: Teams responsible for reliability and operations
+
+## Key Features
+
+### Declarative Platform Definition
+
+The entire platform is defined declaratively as code:
+
+- **GitOps-First**: Everything is versioned in Git and traceable
+- **Reproducibility**: The platform can be rebuilt at any time
+- **Environment Parity**: Consistency between Dev, Test, and Production
+- **Auditability**: Complete history of all changes
+
+### Self-Bootstrapping
+
+The platform can bootstrap itself:
+
+1. **Initial Bootstrap**: Minimal tool (like `idpbuilder`) starts the platform
+2. **Self-Management**: After bootstrap, ArgoCD takes over management
+3. **Continuous Reconciliation**: Platform is continuously reconciled with Git state
+4. **Self-Healing**: Automatic recovery on deviations
+
+### Stack-based Composition
+
+Platform components are organized as reusable stacks (CNOE concept):
+
+- **Modularity**: Components can be updated individually
+- **Reusability**: Stacks can be used across different environments
+- **Composability**: Compose complex platforms from simple building blocks
+- **Versioning**: Stacks can be versioned and tested
+
+**In IPCEI-CIS**: The stacks concept from CNOE is the core organizational principle for platform components.
+
+### Multi-Cluster Support
+
+Platform Orchestration supports different cluster topologies:
+
+- **Control Plane + Worker Clusters**: Centralized control, distributed workloads
+- **Hub-and-Spoke**: One management cluster manages multiple target clusters
+- **Federation**: Coordination across multiple independent clusters
+
+## Purpose in EDP
+
+Platform Orchestration is the foundation of the IPCEI-CIS Edge Developer Platform. It enables:
+
+### Foundation for Developer Self-Service
+
+Platform Orchestration ensures all services are available that developers need for self-service:
+
+- **GitOps Engine** (ArgoCD) for continuous deployment
+- **Source Control** (Forgejo) for code and configuration management
+- **Identity Management** (Keycloak) for authentication and authorization
+- **Observability** (Grafana, Prometheus) for monitoring and logging
+- **CI/CD** (Forgejo Actions/Pipelines) for automated build and test
+
+### Consistency Across Environments
+
+Through declarative definition, consistency is guaranteed:
+
+- Development, test, and production environments are identically configured
+- No "configuration drift" between environments
+- Predictable behavior across all stages
+
+### Platform as Code
+
+The platform itself is treated like software:
+
+- **Version Control**: All changes are versioned in Git
+- **Code Review**: Platform changes go through review processes
+- **Testing**: Platform configurations can be tested
+- **Rollback**: Easy rollback on problems
+
+### Reduced Operational Overhead
+
+Automation reduces manual effort:
+
+- No manual installation steps
+- Automatic updates and patching
+- Self-healing on failures
+- Standardized deployment processes
+
+## Repository
+
+**CNOE Reference Implementation**: [cnoe-io/stacks](https://github.com/cnoe-io/stacks)
+
+**CNOE idpbuilder**: [cnoe-io/idpbuilder](https://github.com/cnoe-io/idpbuilder)
+
+**Documentation**: [CNOE.io Documentation](https://cnoe.io/docs/)
+
+## Getting Started
+
+### Prerequisites
+
+- **Docker**: For local Kubernetes clusters (Kind)
+- **kubectl**: Kubernetes CLI tool
+- **Git**: For repository management
+- **idpbuilder**: CNOE bootstrap tool
+
+### Quick Start
+
+Platform Orchestration with CNOE Reference Implementation:
+
+```bash
+# 1. Install idpbuilder
+curl -fsSL https://cnoe.io/install.sh | bash
+
+# 2. Bootstrap platform
+idpbuilder create \
+  --use-path-routing \
+  --package-dir https://github.com/cnoe-io/stacks//ref-implementation
+
+# 3. Wait for platform ready (ca. 10 minutes)
+kubectl get applications -A
+```
+
+### Verification
+
+Verify the platform is running correctly:
+
+```bash
+# Get platform secrets (credentials)
+idpbuilder get secrets
+
+# Check all ArgoCD applications
+kubectl get applications -n argocd
+
+# Expected: All applications "Synced" and "Healthy"
+```
+
+Access URLs (with path-routing):
+
+- **ArgoCD**: `https://cnoe.localtest.me:8443/argocd`
+- **Forgejo**: `https://cnoe.localtest.me:8443/gitea`
+- **Keycloak**: `https://cnoe.localtest.me:8443/keycloak`
+
+## Usage Examples
+
+### Use Case 1: Platform Bootstrap
+
+Initial bootstrapping of a new platform instance:
+
+```bash
+idpbuilder create \
+  --use-path-routing \
+  --package-dir https://github.com/cnoe-io/stacks//ref-implementation \
+  --log-level debug
+
+# Workflow:
+# 1. Creates Kind cluster
+# 2. Installs ingress-nginx
+# 3. Clones and installs ArgoCD
+# 4. Installs Forgejo
+# 5. Waits for core services
+# 6. Creates technical users
+# 7. Configures Git repositories
+# 8. Installs remaining stacks via ArgoCD
+```
+
+After approximately 10 minutes, the platform is fully deployed.
+
+### Use Case 2: Adding New Platform Components
+
+Add new platform components via ArgoCD:
+
+```bash
+# Create ArgoCD Application for new component
+cat <<EOF | kubectl apply -f -
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: external-secrets
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://charts.external-secrets.io
+    targetRevision: 0.9.9
+    chart: external-secrets
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: external-secrets-system
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+EOF
+```
+
+### Use Case 3: Platform Updates
+
+Update platform components:
+
+```bash
+# 1. Update via Git (GitOps)
+cd your-platform-config-repo
+git pull
+
+# 2. Update stack version
+vim argocd/applications/component.yaml
+# Change targetRevision to new version
+
+# 3. Commit and push
+git add .
+git commit -m "Update component to v1.2.3"
+git push
+
+# 4. ArgoCD will automatically sync
+# 5. Monitor the update
+argocd app sync component --watch
+```
+
+## Integration Points
+
+### ArgoCD Integration
+
+- **Bootstrap**: ArgoCD is initially installed via idpbuilder
+- **Self-Management**: After bootstrap, ArgoCD manages itself via Application CRD
+- **Platform Coordination**: ArgoCD orchestrates all other platform components
+- **Health Monitoring**: ArgoCD monitors health status of all platform services
+
+### Forgejo Integration
+
+- **Source of Truth**: Git repositories contain all platform definitions
+- **GitOps Workflow**: Changes in Git trigger platform updates
+- **Backup**: Git serves as backup of platform configuration
+- **Audit Trail**: Git history documents all platform changes
+- **CI/CD**: Forgejo Actions can automate platform operations
+
+### Terraform Integration
+
+- **Infrastructure Provisioning**: Terraform provisions cloud resources for platform
+- **State Management**: Terraform state tracks infrastructure
+- **Integration**: Terraform can be triggered via Forgejo pipelines
+- **Multi-Cloud**: Support for multiple cloud providers
+
+## Architecture
+
+### Platform Orchestration Flow
+
+```text
+┌─────────────────┐
+│   idpbuilder    │  Bootstrap Tool
+│  (Initial Run)  │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────────┐
+│              Kubernetes Cluster                      │
+│                                                      │
+│  ┌──────────────┐         ┌──────────────┐         │
+│  │   ArgoCD     │────────▶│   Forgejo    │         │
+│  │  (GitOps)    │         │  (Git Repo)  │         │
+│  └──────┬───────┘         └──────────────┘         │
+│         │                                            │
+│         │  Monitors & Syncs                         │
+│         │                                            │
+│         ▼                                            │
+│  ┌──────────────────────────────────────┐          │
+│  │     Platform Stacks                  │          │
+│  │                                      │          │
+│  │  ┌──────────┐  ┌──────────┐        │          │
+│  │  │Forgejo   │  │Keycloak  │        │          │
+│  │  └──────────┘  └──────────┘        │          │
+│  │  ┌──────────┐  ┌──────────┐        │          │
+│  │  │Observ-   │  │Ingress   │        │          │
+│  │  │ability   │  │          │        │          │
+│  │  └──────────┘  └──────────┘        │          │
+│  └──────────────────────────────────────┘          │
+└─────────────────────────────────────────────────────┘
+```
+
+### Platform Bootstrap Sequence
+
+The idpbuilder executes the following workflow:
+
+1. Create Kind Kubernetes cluster
+2. Install ingress-nginx controller
+3. Install ArgoCD
+4. Install Forgejo Git server
+5. Wait for services to be ready
+6. Create technical users in Forgejo
+7. Create repository for platform state in Forgejo
+8. Push platform stacks to Forgejo
+9. Create ArgoCD Applications for all stacks
+10. ArgoCD takes over continuous synchronization
+
+### Deployment Architecture
+
+The platform is deployed in different namespaces:
+
+- `argocd`: ArgoCD and its components
+- `gitea`: Forgejo Git server
+- `keycloak`: Identity and access management
+- `observability`: Prometheus, Grafana, etc.
+- `ingress-nginx`: Ingress controller
+
+## Configuration
+
+### idpbuilder Configuration
+
+Key configuration options for idpbuilder:
+
+```bash
+# Path-based routing (recommended for local development)
+idpbuilder create --use-path-routing
+
+# Custom package directory
+idpbuilder create --package-dir /path/to/custom/packages
+
+# Custom Kind cluster config
+idpbuilder create --kind-config custom-kind.yaml
+
+# Enable debug logging
+idpbuilder create --log-level debug
+```
+
+### ArgoCD Configuration
+
+Important ArgoCD configurations for platform orchestration:
+
+```yaml
+# argocd-cm ConfigMap
+data:
+  # Enable automatic sync
+  application.instanceLabelKey: argocd.argoproj.io/instance
+
+  # Repository credentials
+  repositories: |
+    - url: https://github.com/cnoe-io/stacks
+      name: cnoe-stacks
+      type: git
+
+  # Resource exclusions
+  resource.exclusions: |
+    - apiGroups:
+      - cilium.io
+      kinds:
+      - CiliumIdentity
+```
+
+### Platform Stack Configuration
+
+Configuration of platform stacks via Kustomize:
+
+```yaml
+# kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+namespace: platform-system
+
+resources:
+  - argocd-app.yaml
+  - forgejo-app.yaml
+  - keycloak-app.yaml
+
+patches:
+  - target:
+      kind: Application
+    patch: |-
+      - op: add
+        path: /spec/syncPolicy
+        value:
+          automated:
+            prune: true
+            selfHeal: true
+```
+
+## Troubleshooting
+
+### Platform not reachable
+
+**Problem**: After `idpbuilder create`, platform services are not reachable
+
+**Solution**:
+
+```bash
+# 1. Check if all pods are running
+kubectl get pods -A
+
+# 2. Check ArgoCD application status
+kubectl get applications -n argocd
+
+# 3. Check ingress
+kubectl get ingress -A
+
+# 4. Verify DNS resolution
+nslookup cnoe.localtest.me
+
+# 5. Check idpbuilder logs
+idpbuilder get logs
+```
+
+### ArgoCD Applications not synchronized
+
+**Problem**: ArgoCD Applications show status "OutOfSync"
+
+**Solution**:
+
+```bash
+# 1. Check application details
+argocd app get <app-name>
+
+# 2. View sync status
+argocd app sync <app-name> --dry-run
+
+# 3. Force sync
+argocd app sync <app-name> --force
+
+# 4. Check for errors in ArgoCD logs
+kubectl logs -n argocd deployment/argocd-application-controller
+```
+
+### Git Repository Connection Issues
+
+**Problem**: ArgoCD cannot access Git repository
+
+**Solution**:
+
+```bash
+# 1. Verify repository configuration
+argocd repo list
+
+# 2. Test connection
+argocd repo get https://your-git-repo
+
+# 3. Check credentials
+kubectl get secret -n argocd
+
+# 4. Re-add repository with correct credentials
+argocd repo add https://your-git-repo \
+  --username <user> \
+  --password <token>
+```
+
+## Platform Orchestration Best Practices
+
+Based on experience and [CNCF Guidelines](https://tag-app-delivery.cncf.io/whitepapers/platforms/):
+
+1. **Start Simple**: Begin with the CNOE reference stack, extend gradually
+2. **Automate Everything**: Manual platform changes are anti-pattern
+3. **Monitor Continuously**: Use observability tools for platform health
+4. **Document Well**: Platform documentation is essential for adoption
+5. **Version Everything**: All platform components should be versioned
+6. **Test Changes**: Platform updates should be tested in non-prod
+7. **Plan for Disaster**: Backup and disaster recovery strategies are important
+8. **Use Stacks**: Organize platform components as reusable stacks
+
+## Status
+
+**Maturity**: Production (for CNOE Reference Implementation)
+
+**Stability**: Stable
+
+**Support**: Community Support via CNOE Community
+
+## Additional Resources
+
+### CNOE Resources
+
+- [CNOE Official Website](https://cnoe.io/)
+- [CNOE GitHub Organization](https://github.com/cnoe-io)
+- [CNOE Reference Implementation](https://github.com/cnoe-io/stacks)
+- [CNOE Community Slack](https://cloud-native.slack.com/archives/C05TN9WFN5S)
+
+### Platform Engineering
+
+- [CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/)
+- [Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/)
+- [Team Topologies](https://teamtopologies.com/) - Organizational patterns
+
+### GitOps
+
+- [GitOps Working Group](https://opengitops.dev/)
+- [ArgoCD Best Practices](https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/)
+- [GitOps Principles](https://opengitops.dev/)
+
+### CNOE Stacks
+
+- [Understanding CNOE Stacks](https://cnoe.io/docs/reference-implementation/stacks/)
+- [Creating Custom Stacks](https://cnoe.io/docs/reference-implementation/customization/)

content/en/docs/edp/deployment/basics/_index.md

@@ -0,0 +1,479 @@
+---
+title: Basic Concepts
+linkTitle: Basic Concepts
+weight: 1
+description: >
+  Platform-level component provisioning via Stacks - Orchestrating the platform infrastructure itself
+---
+
+## Overview
+
+Platform Orchestration refers to the automation and management of the platform infrastructure itself. This includes the provisioning, configuration, and lifecycle management of all components that make up the Internal Developer Platform (IDP).
+
+In the context of IPCEI-CIS, Platform Orchestration means:
+
+- **Platform Bootstrap**: Initial setup of Kubernetes clusters and core services
+- **Platform Services Management**: Deployment and management of ArgoCD, Forgejo, Keycloak, etc.
+- **Infrastructure-as-Code**: Declarative management using Terraform and GitOps
+- **Multi-Cluster Orchestration**: Coordination across different Kubernetes clusters
+- **Platform Stacks**: Reusable bundles of platform components (CNOE concept)
+
+### Target Audience
+
+Platform Orchestration is primarily aimed at:
+
+- **Platform Engineering Teams**: Teams that build and operate the IDP
+- **Infrastructure Architects**: Those responsible for the platform architecture
+- **SRE Teams**: Teams responsible for reliability and operations
+
+## Key Features
+
+### Declarative Platform Definition
+
+The entire platform is defined declaratively as code:
+
+- **GitOps-First**: Everything is versioned in Git and traceable
+- **Reproducibility**: The platform can be rebuilt at any time
+- **Environment Parity**: Consistency between Dev, Test, and Production
+- **Auditability**: Complete history of all changes
+
+### Self-Bootstrapping
+
+The platform can bootstrap itself:
+
+1. **Initial Bootstrap**: Minimal tool (like `idpbuilder`) starts the platform
+2. **Self-Management**: After bootstrap, ArgoCD takes over management
+3. **Continuous Reconciliation**: Platform is continuously reconciled with Git state
+4. **Self-Healing**: Automatic recovery on deviations
+
+### Stack-based Composition
+
+Platform components are organized as reusable stacks (CNOE concept):
+
+- **Modularity**: Components can be updated individually
+- **Reusability**: Stacks can be used across different environments
+- **Composability**: Compose complex platforms from simple building blocks
+- **Versioning**: Stacks can be versioned and tested
+
+**In IPCEI-CIS**: The stacks concept from CNOE is the core organizational principle for platform components.
+
+### Multi-Cluster Support
+
+Platform Orchestration supports different cluster topologies:
+
+- **Control Plane + Worker Clusters**: Centralized control, distributed workloads
+- **Hub-and-Spoke**: One management cluster manages multiple target clusters
+- **Federation**: Coordination across multiple independent clusters
+
+## Purpose in EDP
+
+Platform Orchestration is the foundation of the IPCEI-CIS Edge Developer Platform. It enables:
+
+### Foundation for Developer Self-Service
+
+Platform Orchestration ensures all services are available that developers need for self-service:
+
+- **GitOps Engine** (ArgoCD) for continuous deployment
+- **Source Control** (Forgejo) for code and configuration management
+- **Identity Management** (Keycloak) for authentication and authorization
+- **Observability** (Grafana, Prometheus) for monitoring and logging
+- **CI/CD** (Forgejo Actions/Pipelines) for automated build and test
+
+### Consistency Across Environments
+
+Through declarative definition, consistency is guaranteed:
+
+- Development, test, and production environments are identically configured
+- No "configuration drift" between environments
+- Predictable behavior across all stages
+
+### Platform as Code
+
+The platform itself is treated like software:
+
+- **Version Control**: All changes are versioned in Git
+- **Code Review**: Platform changes go through review processes
+- **Testing**: Platform configurations can be tested
+- **Rollback**: Easy rollback on problems
+
+### Reduced Operational Overhead
+
+Automation reduces manual effort:
+
+- No manual installation steps
+- Automatic updates and patching
+- Self-healing on failures
+- Standardized deployment processes
+
+## Repository
+
+**CNOE Reference Implementation**: [cnoe-io/stacks](https://github.com/cnoe-io/stacks)
+
+**CNOE idpbuilder**: [cnoe-io/idpbuilder](https://github.com/cnoe-io/idpbuilder)
+
+**Documentation**: [CNOE.io Documentation](https://cnoe.io/docs/)
+
+## Getting Started
+
+### Prerequisites
+
+- **Docker**: For local Kubernetes clusters (Kind)
+- **kubectl**: Kubernetes CLI tool
+- **Git**: For repository management
+- **idpbuilder**: CNOE bootstrap tool
+
+### Quick Start
+
+Platform Orchestration with CNOE Reference Implementation:
+
+```bash
+# 1. Install idpbuilder
+curl -fsSL https://cnoe.io/install.sh | bash
+
+# 2. Bootstrap platform
+idpbuilder create \
+  --use-path-routing \
+  --package-dir https://github.com/cnoe-io/stacks//ref-implementation
+
+# 3. Wait for platform ready (ca. 10 minutes)
+kubectl get applications -A
+```
+
+### Verification
+
+Verify the platform is running correctly:
+
+```bash
+# Get platform secrets (credentials)
+idpbuilder get secrets
+
+# Check all ArgoCD applications
+kubectl get applications -n argocd
+
+# Expected: All applications "Synced" and "Healthy"
+```
+
+Access URLs (with path-routing):
+
+- **ArgoCD**: `https://cnoe.localtest.me:8443/argocd`
+- **Forgejo**: `https://cnoe.localtest.me:8443/gitea`
+- **Keycloak**: `https://cnoe.localtest.me:8443/keycloak`
+
+## Usage Examples
+
+### Use Case 1: Platform Bootstrap
+
+Initial bootstrapping of a new platform instance:
+
+```bash
+idpbuilder create \
+  --use-path-routing \
+  --package-dir https://github.com/cnoe-io/stacks//ref-implementation \
+  --log-level debug
+
+# Workflow:
+# 1. Creates Kind cluster
+# 2. Installs ingress-nginx
+# 3. Clones and installs ArgoCD
+# 4. Installs Forgejo
+# 5. Waits for core services
+# 6. Creates technical users
+# 7. Configures Git repositories
+# 8. Installs remaining stacks via ArgoCD
+```
+
+After approximately 10 minutes, the platform is fully deployed.
+
+### Use Case 2: Adding New Platform Components
+
+Add new platform components via ArgoCD:
+
+```bash
+# Create ArgoCD Application for new component
+cat <<EOF | kubectl apply -f -
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: external-secrets
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://charts.external-secrets.io
+    targetRevision: 0.9.9
+    chart: external-secrets
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: external-secrets-system
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+EOF
+```
+
+### Use Case 3: Platform Updates
+
+Update platform components:
+
+```bash
+# 1. Update via Git (GitOps)
+cd your-platform-config-repo
+git pull
+
+# 2. Update stack version
+vim argocd/applications/component.yaml
+# Change targetRevision to new version
+
+# 3. Commit and push
+git add .
+git commit -m "Update component to v1.2.3"
+git push
+
+# 4. ArgoCD will automatically sync
+# 5. Monitor the update
+argocd app sync component --watch
+```
+
+## Integration Points
+
+### ArgoCD Integration
+
+- **Bootstrap**: ArgoCD is initially installed via idpbuilder
+- **Self-Management**: After bootstrap, ArgoCD manages itself via Application CRD
+- **Platform Coordination**: ArgoCD orchestrates all other platform components
+- **Health Monitoring**: ArgoCD monitors health status of all platform services
+
+### Forgejo Integration
+
+- **Source of Truth**: Git repositories contain all platform definitions
+- **GitOps Workflow**: Changes in Git trigger platform updates
+- **Backup**: Git serves as backup of platform configuration
+- **Audit Trail**: Git history documents all platform changes
+- **CI/CD**: Forgejo Actions can automate platform operations
+
+### Terraform Integration
+
+- **Infrastructure Provisioning**: Terraform provisions cloud resources for platform
+- **State Management**: Terraform state tracks infrastructure
+- **Integration**: Terraform can be triggered via Forgejo pipelines
+- **Multi-Cloud**: Support for multiple cloud providers
+
+## Architecture
+
+### Platform Orchestration Flow
+
+{{< likec4-view view="platform_orchestration_flow" title="Platform Orchestration Flow" >}}
+
+### Platform Bootstrap Sequence
+
+The idpbuilder executes the following workflow:
+
+1. Create Kind Kubernetes cluster
+2. Install ingress-nginx controller
+3. Install ArgoCD
+4. Install Forgejo Git server
+5. Wait for services to be ready
+6. Create technical users in Forgejo
+7. Create repository for platform state in Forgejo
+8. Push platform stacks to Forgejo
+9. Create ArgoCD Applications for all stacks
+10. ArgoCD takes over continuous synchronization
+
+### Deployment Architecture
+
+The platform is deployed in different namespaces:
+
+- `argocd`: ArgoCD and its components
+- `gitea`: Forgejo Git server
+- `keycloak`: Identity and access management
+- `observability`: Prometheus, Grafana, etc.
+- `ingress-nginx`: Ingress controller
+
+## Configuration
+
+### idpbuilder Configuration
+
+Key configuration options for idpbuilder:
+
+```bash
+# Path-based routing (recommended for local development)
+idpbuilder create --use-path-routing
+
+# Custom package directory
+idpbuilder create --package-dir /path/to/custom/packages
+
+# Custom Kind cluster config
+idpbuilder create --kind-config custom-kind.yaml
+
+# Enable debug logging
+idpbuilder create --log-level debug
+```
+
+### ArgoCD Configuration
+
+Important ArgoCD configurations for platform orchestration:
+
+```yaml
+# argocd-cm ConfigMap
+data:
+  # Enable automatic sync
+  application.instanceLabelKey: argocd.argoproj.io/instance
+
+  # Repository credentials
+  repositories: |
+    - url: https://github.com/cnoe-io/stacks
+      name: cnoe-stacks
+      type: git
+
+  # Resource exclusions
+  resource.exclusions: |
+    - apiGroups:
+      - cilium.io
+      kinds:
+      - CiliumIdentity
+```
+
+### Platform Stack Configuration
+
+Configuration of platform stacks via Kustomize:
+
+```yaml
+# kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+namespace: platform-system
+
+resources:
+  - argocd-app.yaml
+  - forgejo-app.yaml
+  - keycloak-app.yaml
+
+patches:
+  - target:
+      kind: Application
+    patch: |-
+      - op: add
+        path: /spec/syncPolicy
+        value:
+          automated:
+            prune: true
+            selfHeal: true
+```
+
+## Troubleshooting
+
+### Platform not reachable
+
+**Problem**: After `idpbuilder create`, platform services are not reachable
+
+**Solution**:
+
+```bash
+# 1. Check if all pods are running
+kubectl get pods -A
+
+# 2. Check ArgoCD application status
+kubectl get applications -n argocd
+
+# 3. Check ingress
+kubectl get ingress -A
+
+# 4. Verify DNS resolution
+nslookup cnoe.localtest.me
+
+# 5. Check idpbuilder logs
+idpbuilder get logs
+```
+
+### ArgoCD Applications not synchronized
+
+**Problem**: ArgoCD Applications show status "OutOfSync"
+
+**Solution**:
+
+```bash
+# 1. Check application details
+argocd app get <app-name>
+
+# 2. View sync status
+argocd app sync <app-name> --dry-run
+
+# 3. Force sync
+argocd app sync <app-name> --force
+
+# 4. Check for errors in ArgoCD logs
+kubectl logs -n argocd deployment/argocd-application-controller
+```
+
+### Git Repository Connection Issues
+
+**Problem**: ArgoCD cannot access Git repository
+
+**Solution**:
+
+```bash
+# 1. Verify repository configuration
+argocd repo list
+
+# 2. Test connection
+argocd repo get https://your-git-repo
+
+# 3. Check credentials
+kubectl get secret -n argocd
+
+# 4. Re-add repository with correct credentials
+argocd repo add https://your-git-repo \
+  --username <user> \
+  --password <token>
+```
+
+## Platform Orchestration Best Practices
+
+Based on experience and [CNCF Guidelines](https://tag-app-delivery.cncf.io/whitepapers/platforms/):
+
+1. **Start Simple**: Begin with the CNOE reference stack, extend gradually
+2. **Automate Everything**: Manual platform changes are anti-pattern
+3. **Monitor Continuously**: Use observability tools for platform health
+4. **Document Well**: Platform documentation is essential for adoption
+5. **Version Everything**: All platform components should be versioned
+6. **Test Changes**: Platform updates should be tested in non-prod
+7. **Plan for Disaster**: Backup and disaster recovery strategies are important
+8. **Use Stacks**: Organize platform components as reusable stacks
+
+## Status
+
+**Maturity**: Production (for CNOE Reference Implementation)
+
+**Stability**: Stable
+
+**Support**: Community Support via CNOE Community
+
+## Additional Resources
+
+### CNOE Resources
+
+- [CNOE Official Website](https://cnoe.io/)
+- [CNOE GitHub Organization](https://github.com/cnoe-io)
+- [CNOE Reference Implementation](https://github.com/cnoe-io/stacks)
+- [CNOE Community Slack](https://cloud-native.slack.com/archives/C05TN9WFN5S)
+
+### Platform Engineering
+
+- [CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/)
+- [Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/)
+- [Team Topologies](https://teamtopologies.com/) - Organizational patterns
+
+### GitOps
+
+- [GitOps Working Group](https://opengitops.dev/)
+- [ArgoCD Best Practices](https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/)
+- [GitOps Principles](https://opengitops.dev/)
+
+### CNOE Stacks
+
+- [Understanding CNOE Stacks](https://cnoe.io/docs/reference-implementation/stacks/)
+- [Creating Custom Stacks](https://cnoe.io/docs/reference-implementation/customization/)

content/en/docs/edp/deployment/basics/application.md

@@ -0,0 +1,776 @@
+---
+title: "Application Orchestration"
+linkTitle: "Application Orchestration"
+weight: 30
+description: >
+  Application deployment via CI/CD pipelines and GitOps - Orchestrating application deployments
+---
+
+## Overview
+
+Application Orchestration deals with the automation of application deployment and lifecycle management. It encompasses the entire workflow from source code to running application in production.
+
+In the context of IPCEI-CIS, Application Orchestration includes:
+
+- **CI/CD Pipelines**: Automated build, test, and deployment pipelines
+- **GitOps Deployment**: Declarative application deployment via ArgoCD
+- **Progressive Delivery**: Canary deployments, blue-green deployments
+- **Application Configuration**: Environment-specific configuration management
+- **Golden Paths**: Standardized deployment templates and workflows
+
+### Target Audience
+
+Application Orchestration is primarily for:
+
+- **Application Developers**: Teams developing and deploying applications
+- **DevOps Teams**: Teams responsible for deployment automation
+- **Product Teams**: Teams responsible for application lifecycle
+
+## Key Features
+
+### Automated CI/CD Pipelines
+
+Forgejo Actions provides GitHub Actions-compatible CI/CD:
+
+- **Build Automation**: Automatic building of container images
+- **Test Automation**: Automated unit, integration, and E2E tests
+- **Security Scanning**: Vulnerability scanning of dependencies and images
+- **Artifact Publishing**: Publishing to container registries
+- **Deployment Triggering**: Automatic deployment after successful build
+
+### GitOps-based Deployment
+
+ArgoCD enables declarative application deployment:
+
+- **Declarative Configuration**: Applications defined as Kubernetes manifests
+- **Automated Sync**: Automatic synchronization between Git and cluster
+- **Rollback Capability**: Easy rollback to previous versions
+- **Multi-Environment**: Consistent deployment across Dev/Test/Prod
+- **Health Monitoring**: Continuous monitoring of application health
+
+### Progressive Delivery
+
+Support for advanced deployment strategies:
+
+- **Canary Deployments**: Gradual rollout to subset of users
+- **Blue-Green Deployments**: Zero-downtime deployments with instant rollback
+- **A/B Testing**: Traffic splitting for feature testing
+- **Feature Flags**: Dynamic feature enablement without deployment
+
+### Configuration Management
+
+Flexible configuration for different environments:
+
+- **Environment Variables**: Configuration via environment variables
+- **ConfigMaps**: Kubernetes-native configuration
+- **Secrets Management**: Secure handling of sensitive data
+- **External Secrets**: Integration with external secret stores (Vault, etc.)
+
+## Purpose in EDP
+
+Application Orchestration is the core of developer experience in IPCEI-CIS Edge Developer Platform.
+
+### Developer Self-Service
+
+Developers can deploy applications independently:
+
+- **Self-Service Deployment**: No dependency on operations team
+- **Standardized Workflows**: Clear, documented deployment processes
+- **Fast Feedback**: Quick feedback through automated pipelines
+- **Environment Parity**: Consistent behavior across all environments
+
+### Quality and Security
+
+Automated checks ensure quality and security:
+
+- **Automated Testing**: All changes are automatically tested
+- **Security Scans**: Vulnerability scanning of dependencies and images
+- **Policy Enforcement**: Automated policy checks (OPA, Kyverno)
+- **Compliance**: Auditability of all deployments
+
+### Efficiency and Productivity
+
+Automation increases team efficiency:
+
+- **Faster Time-to-Market**: Faster deployment of new features
+- **Reduced Manual Work**: Automation of repetitive tasks
+- **Fewer Errors**: Fewer manual mistakes through automation
+- **Better Collaboration**: Clear interfaces between Dev and Ops
+
+## Repository
+
+**Forgejo**: [forgejo.org](https://forgejo.org/)
+
+**Forgejo Actions**: [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)
+
+**ArgoCD**: [argoproj.github.io/cd](https://argoproj.github.io/cd/)
+
+## Getting Started
+
+### Prerequisites
+
+- **Forgejo Account**: Access to Forgejo instance
+- **Kubernetes Cluster**: Target cluster for deployments
+- **ArgoCD Access**: Access to ArgoCD instance
+- **Git**: For repository management
+
+### Quick Start: Application Deployment
+
+1. **Create Application Repository**
+
+```bash
+# Create new repository in Forgejo
+git init my-application
+cd my-application
+
+# Add application code and Dockerfile
+cat > Dockerfile <<EOF
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+EOF
+```
+
+2. **Add CI/CD Pipeline**
+
+Create `.forgejo/workflows/build.yaml`:
+
+```yaml
+name: Build and Push
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      
+      - name: Login to Registry
+        uses: docker/login-action@v2
+        with:
+          registry: registry.example.com
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+      
+      - name: Build and push
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          push: ${{ github.event_name == 'push' }}
+          tags: registry.example.com/my-app:${{ github.sha }}
+```
+
+3. **Create Kubernetes Manifests**
+
+Create `k8s/deployment.yaml`:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-application
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: my-application
+  template:
+    metadata:
+      labels:
+        app: my-application
+    spec:
+      containers:
+      - name: app
+        image: registry.example.com/my-app:latest
+        ports:
+        - containerPort: 3000
+        env:
+        - name: NODE_ENV
+          value: "production"
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-application
+spec:
+  selector:
+    app: my-application
+  ports:
+  - port: 80
+    targetPort: 3000
+```
+
+4. **Configure ArgoCD Application**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: my-application
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://forgejo.example.com/myteam/my-application
+    targetRevision: main
+    path: k8s
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+5. **Deploy**
+
+```bash
+# Commit and push
+git add .
+git commit -m "Add application and deployment configuration"
+git push origin main
+
+# ArgoCD will automatically deploy the application
+argocd app sync my-application --watch
+```
+
+## Usage Examples
+
+### Use Case 1: Multi-Environment Deployment
+
+Deploy application to multiple environments:
+
+**Repository Structure:**
+
+```text
+my-application/
+├── .forgejo/
+│   └── workflows/
+│       └── build.yaml
+├── base/
+│   ├── deployment.yaml
+│   ├── service.yaml
+│   └── kustomization.yaml
+├── overlays/
+│   ├── dev/
+│   │   ├── kustomization.yaml
+│   │   └── patches.yaml
+│   ├── staging/
+│   │   ├── kustomization.yaml
+│   │   └── patches.yaml
+│   └── production/
+│       ├── kustomization.yaml
+│       └── patches.yaml
+```
+
+**Kustomize Base** (`base/kustomization.yaml`):
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - deployment.yaml
+  - service.yaml
+
+commonLabels:
+  app: my-application
+```
+
+**Environment Overlay** (`overlays/production/kustomization.yaml`):
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+bases:
+  - ../../base
+
+namespace: production
+
+replicas:
+  - name: my-application
+    count: 5
+
+images:
+  - name: my-app
+    newTag: v1.2.3
+
+patches:
+  - patches.yaml
+```
+
+**ArgoCD Applications for each environment:**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: my-application-prod
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://forgejo.example.com/myteam/my-application
+    targetRevision: main
+    path: overlays/production
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+### Use Case 2: Canary Deployment
+
+Progressive rollout with canary strategy:
+
+**Argo Rollouts Canary:**
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: my-application
+spec:
+  replicas: 10
+  strategy:
+    canary:
+      steps:
+      - setWeight: 10
+      - pause: {duration: 5m}
+      - setWeight: 30
+      - pause: {duration: 5m}
+      - setWeight: 60
+      - pause: {duration: 5m}
+      - setWeight: 100
+  selector:
+    matchLabels:
+      app: my-application
+  template:
+    metadata:
+      labels:
+        app: my-application
+    spec:
+      containers:
+      - name: app
+        image: registry.example.com/my-app:v2.0.0
+```
+
+### Use Case 3: Feature Flags
+
+Dynamic feature control without deployment:
+
+**Application Code with Feature Flag:**
+
+```javascript
+const Unleash = require('unleash-client');
+
+const unleash = new Unleash({
+  url: 'http://unleash.platform/api/',
+  appName: 'my-application',
+  customHeaders: {
+    Authorization: process.env.UNLEASH_API_TOKEN
+  }
+});
+
+// Use feature flag
+if (unleash.isEnabled('new-checkout-flow')) {
+  // New checkout implementation
+  renderNewCheckout();
+} else {
+  // Old checkout implementation
+  renderOldCheckout();
+}
+```
+
+## Integration Points
+
+### Forgejo Integration
+
+Forgejo serves as central source code management and CI/CD platform:
+
+- **Source Control**: Git repositories for application code
+- **CI/CD Pipelines**: Forgejo Actions for automated builds and tests
+- **Container Registry**: Built-in container registry for images
+- **Webhook Integration**: Triggers for external systems
+- **Pull Request Workflows**: Code review and approval processes
+
+### ArgoCD Integration
+
+ArgoCD handles declarative application deployment:
+
+- **GitOps Sync**: Continuous synchronization with Git state
+- **Health Monitoring**: Application health status monitoring
+- **Rollback Support**: Easy rollback to previous versions
+- **Multi-Cluster**: Deployment to multiple clusters
+- **UI and CLI**: Web interface and command-line access
+
+### Observability Integration
+
+Integration with monitoring and logging:
+
+- **Metrics**: Prometheus metrics from applications
+- **Logs**: Centralized log collection via Loki/ELK
+- **Tracing**: Distributed tracing with Jaeger/Tempo
+- **Alerting**: Alert rules for application issues
+
+## Architecture
+
+### Application Deployment Flow
+
+{{< likec4-view view="application_deployment_flow" title="Application Deployment Flow" >}}
+
+### CI/CD Pipeline Architecture
+
+Typical Forgejo Actions pipeline stages:
+
+1. **Checkout**: Clone source code
+2. **Build**: Compile application and dependencies
+3. **Test**: Run unit and integration tests
+4. **Security Scan**: Scan dependencies and code for vulnerabilities
+5. **Build Image**: Create container image
+6. **Push Image**: Push to container registry
+7. **Update Manifests**: Update Kubernetes manifests with new image tag
+8. **Notify**: Send notifications on success/failure
+
+## Configuration
+
+### Forgejo Actions Configuration
+
+Example for Node.js application:
+
+```yaml
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  REGISTRY: registry.example.com
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run tests
+        run: npm test
+      
+      - name: Run linter
+        run: npm run lint
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'fs'
+          scan-ref: '.'
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+
+  build-and-push:
+    needs: [test, security]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      
+      - name: Login to Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+      
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix={{branch}}-
+      
+      - name: Build and push
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+### ArgoCD Application Configuration
+
+Complete configuration example:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: my-application
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: default
+  
+  source:
+    repoURL: https://forgejo.example.com/myteam/my-application
+    targetRevision: main
+    path: k8s/overlays/production
+    
+    # Kustomize options
+    kustomize:
+      version: v5.0.0
+      images:
+        - my-app=registry.example.com/my-app:v1.2.3
+  
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: production
+  
+  # Sync policy
+  syncPolicy:
+    automated:
+      prune: true        # Delete resources not in Git
+      selfHeal: true     # Override manual changes
+      allowEmpty: false  # Don't delete everything on empty repo
+    
+    syncOptions:
+      - CreateNamespace=true
+      - PruneLast=true
+      - RespectIgnoreDifferences=true
+    
+    retry:
+      limit: 5
+      backoff:
+        duration: 5s
+        factor: 2
+        maxDuration: 3m
+  
+  # Ignore differences (avoid sync loops)
+  ignoreDifferences:
+    - group: apps
+      kind: Deployment
+      jsonPointers:
+        - /spec/replicas  # Ignore if HPA manages replicas
+```
+
+## Troubleshooting
+
+### Pipeline Fails
+
+**Problem**: Forgejo Actions pipeline fails
+
+**Solution**:
+
+```bash
+# 1. Check pipeline logs in Forgejo UI
+# Navigate to: Repository → Actions → Select failed run
+
+# 2. Check runner status
+# In Forgejo: Site Admin → Actions → Runners
+
+# 3. Check runner logs
+kubectl logs -n forgejo-runner deployment/act-runner
+
+# 4. Test pipeline locally with act
+act -l  # List available jobs
+act -j build  # Run specific job
+```
+
+### ArgoCD Application OutOfSync
+
+**Problem**: Application shows "OutOfSync" status
+
+**Solution**:
+
+```bash
+# 1. Check differences
+argocd app diff my-application
+
+# 2. View sync status details
+argocd app get my-application
+
+# 3. Manual sync
+argocd app sync my-application
+
+# 4. Hard refresh (ignore cache)
+argocd app sync my-application --force
+
+# 5. Check for ignored differences
+argocd app get my-application --show-operation
+```
+
+### Application Deployment Fails
+
+**Problem**: Application pod crashes after deployment
+
+**Solution**:
+
+```bash
+# 1. Check pod status
+kubectl get pods -n production
+
+# 2. View pod logs
+kubectl logs -n production deployment/my-application
+
+# 3. Describe pod for events
+kubectl describe pod -n production <pod-name>
+
+# 4. Check resource limits
+kubectl top pod -n production
+
+# 5. Rollback via ArgoCD
+argocd app rollback my-application
+```
+
+### Image Pull Errors
+
+**Problem**: Kubernetes cannot pull container image
+
+**Solution**:
+
+```bash
+# 1. Verify image exists
+docker pull registry.example.com/my-app:v1.2.3
+
+# 2. Check image pull secret
+kubectl get secret -n production regcred
+
+# 3. Create image pull secret if missing
+kubectl create secret docker-registry regcred \
+  --docker-server=registry.example.com \
+  --docker-username=user \
+  --docker-password=password \
+  -n production
+
+# 4. Reference secret in deployment
+kubectl patch deployment my-application -n production \
+  -p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'
+```
+
+## Best Practices
+
+### Golden Path Templates
+
+Provide standardized templates for common use cases:
+
+1. **Web Application Template**: Node.js, Python, Go web services
+2. **API Service Template**: RESTful API with OpenAPI
+3. **Batch Job Template**: Kubernetes CronJob configurations
+4. **Microservice Template**: Service mesh integration
+
+Example repository template structure:
+
+```text
+application-template/
+├── .forgejo/
+│   └── workflows/
+│       ├── build.yaml
+│       ├── test.yaml
+│       └── deploy.yaml
+├── k8s/
+│   ├── base/
+│   └── overlays/
+├── src/
+│   └── ...
+├── Dockerfile
+├── README.md
+└── .gitignore
+```
+
+### Deployment Checklist
+
+Before deploying to production:
+
+- ✅ All tests passing
+- ✅ Security scans completed
+- ✅ Resource limits defined
+- ✅ Health checks configured
+- ✅ Monitoring and alerts set up
+- ✅ Backup strategy defined
+- ✅ Rollback plan documented
+- ✅ Team notified about deployment
+
+### Configuration Management
+
+- Use ConfigMaps for non-sensitive configuration
+- Use Secrets for sensitive data
+- Use External Secrets Operator for vault integration
+- Never commit secrets to Git
+- Use environment-specific overlays (Kustomize)
+- Document all configuration options
+
+## Status
+
+**Maturity**: Production
+
+**Stability**: Stable
+
+**Support**: Internal Platform Team
+
+## Additional Resources
+
+### Forgejo
+
+- [Forgejo Documentation](https://forgejo.org/docs/latest/)
+- [Forgejo Actions Guide](https://forgejo.org/docs/latest/user/actions/)
+- [Forgejo API Reference](https://forgejo.org/docs/latest/api/)
+
+### ArgoCD
+
+- [ArgoCD Documentation](https://argo-cd.readthedocs.io/)
+- [ArgoCD Best Practices](https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/)
+- [ArgoCD Sync Waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/)
+
+### GitOps
+
+- [GitOps Principles](https://opengitops.dev/)
+- [GitOps Patterns](https://www.gitops.tech/)
+- [Kubernetes Deployment Strategies](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy)
+
+### CI/CD
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions) (Forgejo Actions compatible)
+- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
+- [Container Security Best Practices](https://kubernetes.io/docs/concepts/security/pod-security-standards/)

content/en/docs/edp/deployment/basics/orchestration.md

@@ -0,0 +1,224 @@
+---
+title: Platform Orchestration
+linkTitle: Platform Orchestration
+weight: 1
+description: >
+  Orchestration in the context of Platform Engineering - coordinating infrastructure, platform, and application delivery.
+---
+
+## Overview
+
+Orchestration in the context of Platform Engineering refers to the coordinated automation and management of infrastructure, platform, and application components throughout their entire lifecycle. It is a fundamental concept that bridges the gap between declarative specifications (what should be deployed) and actual execution (how it is deployed).
+
+## The Role of Orchestration in Platform Engineering
+
+Platform Engineering has emerged as a discipline to improve developer experience and reduce cognitive load on development teams ([CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/)). Orchestration is the central mechanism that enables this vision:
+
+1. **Automation of Complex Workflows**: Orchestration coordinates multiple steps and dependencies automatically
+2. **Consistency and Reproducibility**: Guaranteed, repeatable deployments across different environments
+3. **Self-Service Capabilities**: Developers can independently orchestrate resources and deployments
+4. **Governance and Compliance**: Centralized control over policies and best practices
+
+### What Does Orchestration Do?
+
+Orchestration systems perform the following tasks:
+
+- **Workflow Coordination**: Coordination of complex, multi-step deployment processes
+- **Dependency Management**: Resolution and management of dependencies between components
+- **State Management**: Continuous monitoring and reconciliation between desired and actual state
+- **Resource Provisioning**: Automatic provisioning of infrastructure and services
+- **Configuration Management**: Management of configurations across different environments
+- **Health Monitoring**: Monitoring the health of deployed resources
+
+## Three Layers of Orchestration
+
+In modern Platform Engineering, we distinguish three fundamental layers of orchestration:
+
+### [Infrastructure Orchestration](../infrastructure/)
+
+Infrastructure Orchestration deals with the lowest level - the physical and virtual infrastructure layer. This includes:
+
+- Provisioning of compute, network, and storage resources
+- Cloud resource management (VMs, networking, storage)
+- Infrastructure-as-Code deployment (Terraform, etc.)
+- Bare metal and hypervisor management
+
+**Target Audience**: Infrastructure Engineers, Cloud Architects
+
+**Note**: Detailed documentation for Infrastructure Orchestration is maintained separately.
+
+More details: [Infrastructure Orchestration →](../infrastructure/)
+
+### [Platform Orchestration](../otc/)
+
+Platform Orchestration focuses on deploying and managing the platform itself - the services and tools that development teams use. This includes:
+
+- Installation and configuration of Kubernetes clusters
+- Deployment of platform services (GitOps tools, Observability, Security)
+- Management of platform components via Stacks
+- Multi-cluster orchestration
+
+**Target Audience**: Platform Engineering Teams, SRE Teams
+
+**In IPCEI-CIS**: Platform orchestration is realized using the CNOE stack concept with ArgoCD and Forgejo.
+
+More details: [Platform Orchestration →](../otc/)
+
+### [Application Orchestration](application/)
+
+Application Orchestration concentrates on the deployment and lifecycle management of applications running on the platform. This includes:
+
+- Deployment of microservices and containerized applications
+- CI/CD pipeline orchestration
+- Configuration management and secrets handling
+- Application health monitoring and auto-scaling
+
+**Target Audience**: Application Developers, DevOps Engineers
+
+**In IPCEI-CIS**: Application orchestration uses Forgejo pipelines for CI/CD and ArgoCD for GitOps-based deployment.
+
+More details: [Application Orchestration →](application/)
+
+## GitOps as Orchestration Paradigm
+
+A central approach in modern platform orchestration solutions is **GitOps**. GitOps uses Git repositories as the single source of truth for declarative infrastructure and applications:
+
+- **Declarative Approach**: The desired state is defined in Git
+- **Automatic Synchronization**: Controllers monitor Git and reconcile the live state
+- **Audit Trail**: All changes are traceable in Git history
+- **Rollback Capability**: Easy rollback through Git revert
+
+### Continuous Reconciliation
+
+An important concept is **continuous reconciliation**:
+
+1. The orchestrator monitors both the source (Git) and the target (e.g., Kubernetes cluster)
+2. Deviations trigger automatic corrective actions
+3. Health checks validate that the desired state has been achieved
+4. Drift detection warns of unexpected changes
+
+## Orchestration Tools in IPCEI-CIS
+
+Within the IPCEI-CIS platform, we utilize the [CNOE (Cloud Native Operational Excellence)](https://cnoe.io/) stack concept with the following orchestration components:
+
+### ArgoCD
+
+- **Continuous Delivery** for Kubernetes based on GitOps
+- Synchronizes Kubernetes manifests from Git repositories
+- Supports Helm Charts, Kustomize, Jsonnet, and plain YAML
+- Multi-cluster deployment capabilities
+- Application Sets for parameterized deployments
+
+**Role in IPCEI-CIS**: ArgoCD is the central component for GitOps-based deployment management. After the initial bootstrapping phase, ArgoCD takes over the technical coordination of all components.
+
+### Forgejo
+
+- **Git Repository Management** and source control
+- **CI/CD Pipelines** via Forgejo Actions (GitHub Actions compatible)
+- **Developer Portal Capabilities** (initially planned, project discontinued)
+- Package registry and artifact management
+- Integration with ArgoCD for GitOps workflows
+
+**Role in IPCEI-CIS**: Forgejo serves as the Git repository host and CI/CD engine. It was initially planned as a developer portal (similar to Backstage's role in other stacks) but this aspect was not fully realized before project completion.
+
+**Note on Backstage**: In typical CNOE implementations, Backstage serves as the developer portal providing golden paths through software templates. IPCEI-CIS initially planned to use Forgejo for this purpose but the project concluded before full implementation.
+
+### Terraform
+
+- **Infrastructure-as-Code** provisioning
+- Multi-cloud resource management
+- State management for infrastructure
+- Integration with Forgejo pipelines for automated deployment
+
+**Role in IPCEI-CIS**: Terraform handles infrastructure provisioning at the infrastructure orchestration layer, integrated into automated workflows via Forgejo pipelines.
+
+### CNOE Stacks Concept
+
+- **Modular Platform Components** bundled as stacks
+- Reusable, composable platform building blocks
+- Version-controlled stack definitions
+- GitOps-based stack deployment via ArgoCD
+
+**Role in IPCEI-CIS**: The stacks concept from CNOE provides the structural foundation for platform orchestration, enabling modular deployment and management of platform components.
+
+## The Orchestration Workflow
+
+A typical orchestration workflow in the IPCEI-CIS platform:
+
+{{< likec4-view view="orchestration_workflow" title="Orchestration Workflow" >}}
+
+**Workflow Steps**:
+
+1. **Definition**: Developer defines application/infrastructure as code
+2. **Commit**: Changes are committed to Forgejo Git repository
+3. **CI Pipeline**: Forgejo Actions build, test, and package the application
+4. **Sync**: ArgoCD detects changes and triggers deployment
+5. **Provision**: Terraform orchestrates required cloud resources (if needed)
+6. **Deploy**: Application is deployed to Kubernetes
+7. **Monitor**: Continuous monitoring and health checks
+8. **Reconcile**: Automatic correction on drift detection
+
+## Benefits of Coordinated Orchestration
+
+The integration of infrastructure, platform, and application orchestration provides crucial advantages:
+
+- **Reduced Complexity**: Developers don't need to know all infrastructure details
+- **Faster Time-to-Market**: Automated workflows accelerate deployments
+- **Consistency**: Standardized patterns across all teams
+- **Governance**: Central policies are automatically enforced
+- **Scalability**: Platform teams can support many application teams
+- **Self-Service**: Developers can provision services independently
+- **Audit and Compliance**: Complete traceability through Git history
+
+## Best Practices
+
+Successful orchestration follows proven principles ([Platform Engineering Principles](https://platformengineering.org/blog/what-is-platform-engineering)):
+
+1. **Platform as a Product**: Treat the platform as a product with focus on user experience
+2. **Self-Service First**: Enable developers to use services autonomously
+3. **Documentation**: Comprehensive documentation of golden paths
+4. **Feedback Loops**: Continuous improvement through user feedback
+5. **Thin Platform Layer**: Use managed services where possible instead of building everything
+6. **Progressive Disclosure**: Offer different abstraction levels
+7. **Focus on Common Problems**: Solve recurring problems centrally
+8. **Treat Glue as Valuable**: Integration of different tools is valuable
+9. **Clear Mission**: Define clear goals and responsibilities
+
+## Avoiding Anti-Patterns
+
+Common mistakes in platform orchestration ([How to fail at Platform Engineering](https://www.cncf.io/blog/2024/03/08/how-to-fail-at-platform-engineering/)):
+
+- **Product Misfit**: Building platform without involving developers
+- **Overly Complex Design**: Too many features and unnecessary complexity
+- **Swiss Knife Syndrome**: Trying to solve all problems with one tool
+- **Insufficient Documentation**: Missing or outdated documentation
+- **Siloed Development**: Platform and development teams working in isolation
+- **Stagnant Platform**: Platform not continuously evolved
+
+## Sub-Components
+
+The orchestration component includes the following sub-areas:
+
+- **[Infrastructure Orchestration](infrastructure/)**: Low-level infrastructure deployment and provisioning
+- **[Platform Orchestration](platform/)**: Platform-level component deployment via Stacks
+- **[Application Orchestration](application/)**: Application-level deployment and CI/CD
+- **[Stacks](stacks/)**: Reusable component bundles and compositions
+
+## Further Resources
+
+### Fundamentals
+
+- [CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/) - Comprehensive paper on Platform Engineering
+- [Platform Engineering Definition](https://platformengineering.org/blog/what-is-platform-engineering) - What is Platform Engineering?
+- [Team Topologies](https://teamtopologies.com/) - Organizational structures for modern teams
+
+### GitOps
+
+- [GitOps Principles](https://opengitops.dev/) - Official GitOps principles
+- [ArgoCD Documentation](https://argo-cd.readthedocs.io/) - ArgoCD documentation
+
+### Tools
+
+- [CNOE.io](https://cnoe.io/) - Cloud Native Operational Excellence Framework
+- [Forgejo](https://forgejo.org/) - Self-hosted Git service with CI/CD
+- [Terraform](https://www.terraform.io/) - Infrastructure as Code tool

content/en/docs/edp/deployment/infrastructure/_index.md

@@ -0,0 +1,201 @@
+---
+title: Infrastructure as Code
+linkTitle: Infrastructure as Code
+weight: 10
+description: >
+  Managing infrastructure through machine-readable definition files rather than manual configuration
+---
+
+## Overview
+
+Infrastructure as Code (IaC) is the practice of managing and provisioning infrastructure through code rather than manual processes. Instead of clicking through web consoles or running one-off commands, infrastructure is defined in version-controlled files that can be executed repeatedly to produce identical environments.
+
+This approach treats infrastructure with the same rigor as application code: it's versioned, reviewed, tested, and deployed through automated pipelines.
+
+## Why Infrastructure as Code?
+
+### The problem with manual infrastructure
+
+Traditional infrastructure management faces several challenges:
+
+- **Inconsistency**: Manual steps vary between operators and environments
+- **Undocumented**: Critical knowledge exists only in operators' heads
+- **Error-Prone**: Human mistakes during repetitive tasks
+- **Slow**: Manual provisioning takes hours or days
+- **Untrackable**: No audit trail of what changed, when, or why
+- **Irreproducible**: Difficulty recreating environments exactly
+
+### The IaC solution
+
+Infrastructure as Code addresses these challenges by making infrastructure:
+
+**Declarative** - Describe the desired state, not the steps to achieve it. The IaC tool handles the implementation details.
+
+**Versioned** - Every infrastructure change is committed to Git, providing complete history and the ability to rollback.
+
+**Automated** - Infrastructure deploys through pipelines without human intervention, eliminating manual errors.
+
+**Testable** - Infrastructure changes can be validated before production deployment.
+
+**Documented** - The code itself is the documentation, always current and accurate.
+
+**Reproducible** - The same code produces identical infrastructure every time, across all environments.
+
+## Core Concepts
+
+### Declarative vs imperative
+
+**Imperative** approaches specify the exact steps: "Create a server, then install software, then configure networking."
+
+**Declarative** approaches specify the desired outcome: "I need a server with this software and network configuration." The IaC tool determines the necessary steps.
+
+Most modern IaC tools use the declarative approach, making them more maintainable and resilient.
+
+### State Management
+
+IaC tools maintain a "state" - a record of what infrastructure currently exists. When you change your code and re-run the tool, it compares the desired state (your code) with the actual state (what exists) and makes only the necessary changes.
+
+This enables:
+- **Drift detection** - Identify manual changes made outside IaC
+- **Safe updates** - Modify only what changed
+- **Dependency management** - Update resources in the correct order
+
+### Idempotency
+
+Running the same IaC code multiple times produces the same result. If infrastructure already matches the code, the tool makes no changes. This property is called idempotency and is essential for reliable automation.
+
+## Infrastructure as Code in EDP
+
+The Edge Developer Platform uses IaC extensively:
+
+### Terraform and Terragrunt
+
+[Terraform](terraform/) is our primary IaC tool for provisioning cloud resources. We use [Terragrunt](https://terragrunt.gruntwork.io/) as an orchestration layer to manage multiple Terraform modules and reduce code duplication.
+
+Our implementation includes:
+- **[infra-catalogue](https://edp.buildth.ing/DevFW/infra-catalogue)** - Reusable infrastructure components (modules, units, and stacks)
+- **[infra-deploy](https://edp.buildth.ing/DevFW/infra-deploy)** - Full environment definitions using catalogue components
+
+### Platform stacks
+
+We organize infrastructure into [stacks](stacks/) - coherent bundles of related components:
+
+- **[Core Stack](stacks/core/)** - Essential platform services
+- **[Forgejo Stack](stacks/forgejo/)** - Source control and CI/CD
+- **[Observability Stack](stacks/observability/)** - Monitoring and logging
+- **[OTC Stack](stacks/otc/)** - Cloud provider resources
+- **[Coder Stack](stacks/coder/)** - Development environments
+- **[Terralist Stack](stacks/terralist/)** - Terraform registry
+
+Each stack is defined as code, versioned independently, and can be deployed across different environments.
+
+### GitOps integration
+
+Our IaC integrates with GitOps principles:
+
+1. All infrastructure definitions live in Git repositories
+2. Changes go through code review processes
+3. Automated pipelines deploy infrastructure
+4. ArgoCD continuously reconciles Kubernetes resources with Git state
+
+This creates an auditable, automated, and reliable deployment process.
+
+## Benefits realized
+
+### Consistency across environments
+
+Development, testing, and production environments are deployed from the same code. This eliminates the "works on my machine" problem at the infrastructure level.
+
+### Rapid environment provisioning
+
+A complete EDP environment can be provisioned in minutes rather than days. This enables:
+- Quick disaster recovery
+- Easy creation of test environments
+- Fast onboarding for new team members
+
+### Reduced operational risk
+
+Code review catches infrastructure errors before deployment. Automated testing validates changes. Version control enables instant rollback if problems occur.
+
+### Knowledge sharing
+
+Infrastructure configuration is explicit and discoverable in code. New team members can understand the platform by reading the repository rather than shadowing experienced operators.
+
+### Compliance and auditability
+
+Every infrastructure change is tracked in Git history with author, timestamp, and reason. This provides audit trails required for compliance and simplifies troubleshooting.
+
+## Getting started
+
+To work with EDP's Infrastructure as Code:
+
+1. **Understand Terraform basics** - Review [Terraform documentation](https://developer.hashicorp.com/terraform)
+2. **Explore infra-catalogue** - Browse [infra-catalogue](https://edp.buildth.ing/DevFW/infra-catalogue) to understand available components
+3. **Review existing deployments** - Examine [infra-deploy](https://edp.buildth.ing/DevFW/infra-deploy) to see how components are composed
+4. **Follow the Terraform guide** - See [Terraform-based deployment](terraform/) for detailed instructions
+
+## Best Practices
+
+Based on our experience building and operating IaC:
+
+**Version everything** - All infrastructure code belongs in version control. No exceptions.
+
+**Keep it simple** - Start with basic modules. Add abstraction only when duplication becomes painful.
+
+**Test before production** - Deploy infrastructure changes to test environments first.
+
+**Use meaningful commit messages** - Explain why changes were made, not just what changed.
+
+**Review all changes** - Infrastructure changes should go through the same review process as application code.
+
+**Document assumptions** - Use code comments to explain non-obvious decisions.
+
+**Manage secrets securely** - Never commit credentials to version control. Use secret management tools.
+
+**Plan for drift** - Regularly compare actual infrastructure with code state to detect manual changes.
+
+## Challenges and limitations
+
+Infrastructure as Code is powerful but has challenges:
+
+**Learning curve** - Teams need to learn IaC tools and practices. Initial productivity may decrease.
+
+**State management complexity** - State files must be stored securely and accessed by multiple team members. State corruption can cause serious issues.
+
+**Provider limitations** - Not all infrastructure can be managed as code. Some resources require manual configuration.
+
+**Breaking changes** - Poorly written code can destroy infrastructure. Safeguards and testing are essential.
+
+**Tool lock-in** - Switching IaC tools (e.g., Terraform to Pulumi) requires rewriting infrastructure code.
+
+Despite these challenges, the benefits far outweigh the costs for any infrastructure of meaningful complexity.
+
+## Why we invest in IaC
+
+The IPCEI-CIS Edge Developer Platform requires reliable, reproducible infrastructure. Manual provisioning cannot meet these requirements at scale.
+
+By investing in Infrastructure as Code:
+- We can deploy complete environments consistently
+- Platform engineers can focus on improvement rather than repetitive tasks
+- Infrastructure changes are transparent and auditable
+- New team members can contribute confidently
+- Disaster recovery becomes routine rather than heroic
+
+Our IaC tools ([infra-catalogue](https://edp.buildth.ing/DevFW/infra-catalogue) and [infra-deploy](https://edp.buildth.ing/DevFW/infra-deploy)) embody these principles and enable the platform's reliability.
+
+## Additional Resources
+
+### Terraform Ecosystem
+- [Terraform Documentation](https://developer.hashicorp.com/terraform)
+- [OpenTofu](https://opentofu.org/) - Community-driven Terraform fork
+- [Terragrunt](https://terragrunt.gruntwork.io/) - Terraform orchestration
+
+### Infrastructure as Code Concepts
+- [Infrastructure as Code book](https://www.oreilly.com/library/view/infrastructure-as-code/9781098114664/) by Kief Morris
+- [Terraform Best Practices](https://www.terraform-best-practices.com/)
+- [CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/)
+
+### EDP-Specific Resources
+- [Terraform-based deployment](terraform/) - Detailed deployment guide
+- [Infrastructure Stacks](stacks/) - Reusable component bundles
+- [Platform Orchestration](../) - How IaC fits into overall deployment