docs: overview plus introduction

Author: dieppa

docs/overview/Introduction.md

@@ -6,56 +6,81 @@ title: " "
 
 # Introduction
 
-Flamingock is a change management framework that ensures your distributed systems evolve safely and consistently. It applies versioned, auditable changes to any target system (message brokers, APIs, cloud services, databases, and any other external service) with guaranteed safety and recovery mechanisms.
+**Flamingock** brings *Change-as-Code (CaC)* to your entire stack.  
+It applies **versioned, auditable changes** to the external systems your application depends on — such as databases, schemas, message brokers, APIs, and cloud services.  
+
+Unlike infrastructure-as-code tools, Flamingock runs **inside your application** (or via the **CLI**).  
+It ensures these systems evolve **safely, consistently, and in sync with your code at runtime**.  
+
+---
+
+### What Flamingock manages
+Flamingock focuses on **application-level changes** that your code requires to run safely:
+
+- Database schemas and reference data  
+- Message queues and schemas  
+- APIs and configuration values  
+- Cloud service resources directly tied to your application  
+- Configuration changes (feature flags, secrets, runtime values)  
+
+### What Flamingock does *not* manage
+Flamingock is **not an infrastructure-as-code tool**. It does not provision servers, clusters, or networks — those belong in Terraform, Pulumi, or similar. Instead, Flamingock **complements them by handling the runtime changes your application depends on**.
+
+---
 
 ## Core principles
 
-### Safety by default
+### 🔒 Safety by default
 When Flamingock cannot guarantee a safe outcome, it stops and requires manual intervention. This prevents silent data corruption and ensures predictable deployments.
 
-### Complete auditability
+### 📝 Complete auditability
 Every change execution is tracked in an audit store, providing a complete history of what was applied, when, by whom, and with what result.
 
-### Recovery strategies
-Configurable recovery mechanisms determine how Flamingock handles failures:
-- **Manual intervention** (default): Stops on failure and requires human review
-- **Always retry**: Automatically retries idempotent operations  
+### 🔄 Recovery strategies
+Configurable mechanisms determine how Flamingock handles failures:
+- **Manual intervention** (default): stops on failure and requires human review  
+- **Always retry**: automatically retries idempotent operations  
 
+---
 
 ## Target systems
 
 Flamingock can apply changes to any external service your application interacts with. Examples include:
-- **Message brokers**: Kafka, RabbitMQ, AWS SQS
-- **Cloud services**: S3, Lambda, API Gateway
-- **APIs**: REST endpoints, GraphQL schemas
-- **Configuration systems**: Feature flags, vault secrets
-- **Databases**: SQL (PostgreSQL, MySQL) and NoSQL (MongoDB, DynamoDB)
-- **And any other external system** your application needs to evolve
+
+- **Databases**: SQL (PostgreSQL, MySQL) and NoSQL (MongoDB, DynamoDB)  
+- **Message brokers**: Kafka, RabbitMQ, AWS SQS  
+- **Cloud services**: S3, Lambda, API Gateway  
+- **APIs**: REST endpoints, GraphQL schemas  
+- **Configuration systems**: feature flags, vault secrets  
+- **And any other external system** your application needs to evolve  
+
+---
 
 ## Architecture overview
 
 ### Changes
-The fundamental unit of change. Each Change:
-- Has a unique identifier and execution order
-- Targets a specific system
-- Contains execution and rollback logic
-- Is executed exactly once
+The fundamental unit of change. Each **Change**:
+- Has a unique identifier and execution order  
+- Targets a specific system  
+- Contains execution logic (and optionally rollback logic)  
+- Is executed exactly once  
 
 ### Audit store vs target system
-- **Audit store**: Where Flamingock tracks execution history (managed by Flamingock)
-- **Target system**: Where your business changes are applied (any external service your application interacts with)
+- **Audit store** → where Flamingock tracks execution history (managed by Flamingock).  
+- **Target system** → where your business changes are applied (any external service your application interacts with).  
 
 ### Execution flow
-1. Application startup triggers Flamingock
-2. Flamingock discovers all Changes
-3. Checks audit store for pending changes
-4. Acquires distributed lock
-5. Executes changes in order
-6. Records results in audit store
-7. Handles failures according to recovery strategy  
+1. Application startup (or CLI invocation) triggers Flamingock  
+2. Flamingock discovers all Changes  
+3. Checks audit store for pending changes  
+4. Acquires a distributed lock  
+5. Executes changes in order  
+6. Records results in the audit store  
+7. Handles failures according to the configured recovery strategy  
 
+---
 
 ## Next steps
-- [Quick start](quick-start.md) - Minimum setup to run Flamingock
-- [Core concepts](core-concepts.md) - Detailed explanation of key concepts
-- [Audit store vs target system](audit-store-vs-target-system.md) - Understanding the dual-system architecture  
+- [Quick start](quick-start.md) – minimum setup to run Flamingock  
+- [Core concepts](core-concepts.md) – detailed explanation of key concepts  
+- [Changes](../changes/introduction.md) – anatomy and execution of Changes  

docs/overview/overview.md

@@ -0,0 +1,108 @@
+---
+id: overview
+title: Overview
+sidebar_position: 0
+---
+
+# Flamingock Documentation
+
+**Flamingock** brings *Change-as-Code (CaC)* to your entire stack.  
+It applies **versioned, auditable changes** to the external systems your application depends on — such as databases, schemas, message brokers, APIs, and cloud services.  
+
+Unlike infrastructure-as-code tools, Flamingock runs **inside your application** (or via the **CLI**).  
+It ensures these systems evolve **safely, consistently, and in sync with your code at runtime**.  
+
+👉 For a deeper explanation, see the [Introduction](./get-started/introduction.md)
+
+---
+
+## 🔎 What It Looks Like
+
+A simple change in Flamingock:
+
+```java
+@TargetSystem("user-database")
+@Change(id = "add-user-status", author = "dev-team")
+public class _0001__AddUserStatus {
+
+    @Apply
+    public void apply(MongoDatabase database) {
+        database.getCollection("users")
+                .updateMany(
+                    new Document("status", new Document("$exists", false)),
+                    new Document("$set", new Document("status", "active"))
+                );
+    }
+
+    @Rollback
+    public void rollback(MongoDatabase database) {
+        database.getCollection("users")
+                .updateMany(
+                    new Document(),
+                    new Document("$unset", new Document("status", ""))
+                );
+    }
+}
+```
+
+👉 **Continue to [Quick Start Guide](./quick-start)**
+👉 **Learn the [Core Concepts](./core-concepts)**
+👉 **Read the full [Introduction](./Introduction)**
+
+---
+
+## 🔑 Core Building Blocks
+
+**Changes** – versioned, auditable operations (e.g. schema migrations, config toggles, S3 bucket creation).
+
+**Target Systems** – external systems you evolve (MongoDB, DynamoDB, Kafka, S3, REST APIs, …).
+
+**Audit Store** – log where Flamingock records applied changes.
+
+**Runners** – how Flamingock integrates with your app (Standalone, Spring Boot, …).
+
+---
+
+## 📚 Documentation Structure
+
+**Get started** – [Introduction](./Introduction), [Quick Start](./quick-start), [Core Concepts](./core-concepts), [Change-as-Code](./Change-as-Code)
+
+**Changes** – [Anatomy](../changes/anatomy-and-structure), [Apply and rollback methods](../changes/apply-and-rollback-methods), [Types & implementation](../changes/types-and-implementation), [Best practices](../changes/best-practices)
+
+**Target Systems** – Supported integrations ([SQL](../target-systems/sql-target-system), [MongoDB](../target-systems/mongodb-target-system), [DynamoDB](../target-systems/dynamodb-target-system), [Introduction](../target-systems/introduction), …)
+
+**Community Audit Stores** – [MongoDB](../community-audit-stores/mongodb-audit-store), [DynamoDB](../community-audit-stores/dynamodb-audit-store), [SQL](../community-audit-stores/sql-audit-store)
+
+**Safety & Recovery** – [Recovery strategies](../safety-and-recovery/introduction), [Safety mechanisms](../safety-and-recovery/introduction)
+
+**Templates** – [How to use](../templates/templates-how-to-use), [Introduction](../templates/templates-introduction)
+
+**Supported Frameworks** – [Spring Boot](../frameworks/springboot-integration/introduction), [Standalone runner](../flamingock-library-config/setup-and-stages)
+
+**Testing** – [Unit testing](../testing/unit-testing), [Integration testing](../testing/integration-testing), [Spring Boot testing](../testing/springboot-integration-testing)
+
+**CLI** – Command-line usage and operations
+
+**Resources** – Examples, FAQ, migration guides
+
+---
+
+## 🛠 Editions
+
+**Community Edition (CE)** – open source, library only
+
+**Cloud Edition** – SaaS with dashboard, observability, and premium features
+
+**Self-Hosted Edition** – Cloud features, deployable in your infra
+
+👉 **Learn more about [Cloud Edition](../cloud-edition/cloud-edition)**
+
+---
+
+## 🔍 Resources
+
+[GitHub repository](https://github.com/flamingock/flamingock-project)
+
+[Releases](https://github.com/flamingock/flamingock-project/releases)
+
+[Issue tracker](https://github.com/flamingock/flamingock-project/issues)