From 758f7f6a30eb91e0bf5a118703ea5658d984523e Mon Sep 17 00:00:00 2001
From: Yunus Emre Kalkan <emre.kalkan@volosoft.com>
Date: Wed, 7 Jan 2026 11:08:55 +0300
Subject: [PATCH] Added secrets and metadata to studio concepts document

resolves https://github.com/volosoft/abp-studio/issues/4143
---
 docs/en/studio/concepts.md | 39 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/en/studio/concepts.md b/docs/en/studio/concepts.md
index 1e6afb4fab..1530f3a029 100644
--- a/docs/en/studio/concepts.md
+++ b/docs/en/studio/concepts.md
@@ -43,6 +43,45 @@ An ABP Studio module is a sub-solution that contains zero, one or multiple packa
 
 An ABP Studio Package typically matches to a .NET project (`csproj`).
 
+### Metadata
+
+Metadata is a collection of key-value pairs that provide additional information for various ABP Studio features. Metadata follows a hierarchical structure where values defined at lower levels override those at higher levels:
+
+**Hierarchy (from highest to lowest priority):**
+1. **Helm Chart Metadata** - Defined in chart properties (Kubernetes context only)
+2. **Kubernetes Profile Metadata** / **Run Profile Metadata** - Defined in profile settings (context-dependent)
+3. **Solution Metadata** - Defined via *Solution Explorer* → right-click solution → *Manage Metadata*
+4. **Global Metadata** - Defined via *Tools* → *Global Metadata*
+
+**Common Metadata Keys:**
+
+| Key | Description | Used By |
+|-----|-------------|---------|
+| `k8ssuffix` | Appends a suffix to Kubernetes namespace (e.g., for multi-developer scenarios) | Kubernetes integration |
+| `dotnetEnvironment` | Specifies the .NET environment (e.g., `Development`, `Staging`) | Helm chart installation |
+| `projectPath` | Path to the project for Docker image building | Docker image build |
+| `imageName` | Docker image name | Docker image build |
+| `projectType` | Project type (`dotnet` or `angular`) | Docker image build |
+
+> Metadata defined in *Global Metadata* is available for all solutions but will not be shared with team members. Metadata defined at *Solution* or *Profile* level will be shared through solution files.
+
+### Secrets
+
+Secrets are key-value pairs designed for storing sensitive information such as passwords, API keys, and connection strings. Unlike metadata, secrets are stored in the local file system and are not included in solution files for security reasons.
+
+**Hierarchy (from highest to lowest priority):**
+1. **Kubernetes Profile Secrets** / **Run Profile Secrets** - Defined in profile settings (context-dependent)
+2. **Solution Secrets** - Defined via *Solution Explorer* → right-click solution → *Manage Secrets*
+3. **Global Secrets** - Defined via *Tools* → *Global Secrets*
+
+**Common Secret Keys:**
+
+| Key | Description | Used By |
+|-----|-------------|---------|
+| `wireGuardPassword` | Password for WireGuard VPN connection to Kubernetes cluster | Kubernetes integration |
+
+> Secrets are stored locally and are not shared with team members by default. Each developer needs to configure their own secrets.
+
 ## ABP Studio vs .NET Terms
 
 Some ABP Studio terms may seem conflict with .NET and Visual Studio. To make them even more clear, you can use the following table.