docs: update concepts

docs/kusion/3-concepts/0-overview.md

@@ -4,17 +4,25 @@ id: overview
 
 # Overview
 
-In this article, we will provide an overview of the core concepts of Kusion from the perspective of the Kusion workflow. 
+## Platform Orchestrator
+
+![platform orchestrator](/img/docs/concept/platform-orchestrator.png)
+
+A Platform Orchestrator is a system designed to capture and "orchestrate" intents from different configurations coming from different roles, and connecting them with different infrastructures. It serves as the glue for different intents throughout the software development lifecycle, from deployment to monitoring and operations, ensuring that users' intentions can seamlessly integrate and flow across different environments and infrastructures.
+
+## Kusion Workflow
+
+In this section, we will provide an overview of the core concepts of Kusion from the perspective of the Kusion workflow. 
 
 ![kusion workflow](/img/docs/concept/kusion_workflow.png)
 
 The workflow of Kusion is illustrated in the diagram above, which consists of three steps. 
 
-The first step is **Write**, where the platform engineers build the [Kusion Modules](./3-module/1-overview.md) and initialize a [Workspace](./4-workspace.md). And the application developers declare their operational intent in [AppConfiguration](./5-appconfiguration.md) under a specific [Project](./1-project/1-overview.md) and [Stack](./2-stack/1-overview.md) path. 
+The first step is **Write**, where the platform engineers build the [Kusion Modules](./3-module/1-overview.md) and initialize a [Workspace](./4-workspace/1-overview.md). And the application developers declare their operational intent in [AppConfiguration](./5-appconfiguration.md) under a specific [Project](./1-project/1-overview.md) and [Stack](./2-stack/1-overview.md) path. 
 
-The second step is the **Build** process, which results in the creation of the **SSoT** (Single Source of Truth), also known as the [Spec](./6-spec.md) of the current operational task. If you need version management of the SSoT, we recommend you manage the `Spec` with a VCS (Version Control System) tool like **Git**. 
+The second step is the **Generate** process, which results in the creation of the **SSoT** (Single Source of Truth), also known as the [Spec](./6-spec.md) of the current operation. Kusion stores and version controls the Spec as part of a [Release](./8-release.md).
 
-The third step is **Apply**, which makes the `Spec` effective. Kusion parses the operational intent based on the `Spec` produced in the previous step. Before applying the `Spec`, Kusion will execute the `Preview` command (you can also execute this command manually) which will use a three-way diff algorithm to preview changes and prompt users to make sure all changes meet their expectations. And the `Apply` command will then actualize the operation intent onto various infrastructure platforms, currently supporting **Kubernetes**, **Terraform**, and **On-Prem** infrastructures. A [Release](./9-release.md) file will be created in the [Storage Backend](./7-backend.md) to record an operation. The `Destroy` command will delete the resources recorded in the `Release` file of a project in a specific workspace. 
+The third step is **Apply**, which makes the `Spec` effective. Kusion parses the operational intent based on the `Spec` produced in the previous step. Before applying the `Spec`, Kusion will execute the `Preview` command (you can also execute this command manually) which will use a three-way diff algorithm to preview changes and prompt users to make sure all changes meet their expectations. And the `Apply` command will then actualize the operation intent onto various infrastructure platforms, currently supporting **Kubernetes**, **Terraform**, and **On-Prem** infrastructures. A [Release](./8-release.md) file will be created in the [Storage Backend](./7-backend/1-overview.md) to record an operation. The `Destroy` command will delete the resources recorded in the `Release` file of a project in a specific workspace. 
 
 A more detailed demonstration of the Kusion engine can be seen below. 
 

docs/kusion/3-concepts/1-project/1-overview.md

@@ -5,8 +5,10 @@ id: overview
 
 # Overview
 
-A project in Kusion is defined as a folder that contains a `project.yaml` file and is generally recommended to be linked to a Git repository. Typically, the mapping between a project and a repository is 1:1, however, it is possible to have multiple projects connected to a single repository — for example, in the case of a monorepo. A project consists of one or more applications.
+Projects, [Stacks](../2-stack/1-overview.md), [Modules](../3-module/1-overview.md) and [Workspaces](../4-workspace/1-overview.md) are the most pivotal concepts when using Kusion.
 
-The purpose of the project is to bundle application configurations there are relevant. Specifically, it organizes logical configurations for internal components to orchestrate the application and assembles these configurations to suit different roles, such as developers and SREs, thereby covering the entire lifecycle of application development.
+A project in Kusion is defined as a folder that contains a `project.yaml` file and is generally recommended to be stored to a Git repository. There are generally no constraints on where this folder may reside. In some cases it can be stored in a large monorepo that manages configurations for multiple applications. It could also be stored either in a separate repo or alongside the application code. A project can logically consist of one or more applications.
 
-From the perspective of the application development lifecycle, the configurations delineated by the project is decoupled from the application code. It takes an immutable image as input, allowing users to perform operations and maintain the application within an independent configuration codebase.
+The purpose of the project is to bundle application configurations that are relevant. Specifically, it contains configurations for internal components that makes up the application and orchestrates these configurations to suit different roles, such as developers and SREs, thereby covering the entire lifecycle of application deployment.
+
+From the perspective of the application development lifecycle, the configurations delineated by the project is decoupled from the application code. It takes an immutable application image as input, allowing users to perform operations and maintain the application within an independent configuration codebase.

docs/kusion/3-concepts/10-resources.md

@@ -0,0 +1,7 @@
+# Resources
+
+Resources are persisted by Kusion server.
+
+## Resource Graphs
+
+More to come...

docs/kusion/3-concepts/8-configuration.md → docs/kusion/3-concepts/11-cli-configuration.md

@@ -1,11 +1,15 @@
 ---
 id: configuration
-sidebar_label: Configuration
+sidebar_label: CLI Configurations
 ---
 
-# Configuration
+# CLI Configurations
 
-Kusion can be configured with some global settings, which are separate from the AppConfiguration written by the application developers and the workspace configurations written by the platform engineers. 
+:::tip
+If you are using Kusion server, this article does NOT apply.
+:::
+
+Kusion CLI can be configured with some global settings, which are separate from the AppConfiguration written by the application developers and the workspace configurations written by the platform engineers. 
 
 The configurations are only relevant to the Kusion itself, and can be managed by command `kusion config`. The configuration items are specified, which are in the hierarchical format with full stop for segmentation, such as `backends.current`. For now, only the backend configurations are included.
 

docs/kusion/3-concepts/2-stack/1-overview.md

@@ -9,7 +9,7 @@ A stack in Kusion is defined as a folder within the project directory that conta
 
 The most common way to leverage stacks is to denote different phases of the software development lifecycle, such as `development`, `staging`, `production`, etc. For instance, in the case where the image and resource requirements for an application workload might be different across different phases in the SDLC, they can be represented by different stacks in the same project, namely `dev`, `stage` and `prod`.
 
-To distinguish this from the deploy-time concept of a "target environment" - which Kusion defines as `workspaces`, **stack** is a development-time concept for application developers to manage different configurations. One way to illustrate the difference is that you can easily be deploying the `prod` stack to multiple target environments, for example, `aws-prod-us-east`, `aws-prod-us-east-2` and `azure-prod-westus`.
+To distinguish this from the deploy-time concept of a "target environment" - which Kusion defines as [workspaces](../4-workspace/1-overview.md), **stack** is a development-time concept for application developers to manage different configurations. One way to illustrate the difference is that you can easily be deploying the `prod` stack to multiple target environments, for example, `aws-prod-us-east`, `aws-prod-us-east-2` and `azure-prod-westus`.
 
 ## High Level Schema
 

docs/kusion/3-concepts/3-module/1-overview.md

@@ -1,14 +1,14 @@
 # Overview
 
-A Kusion module is a reusable building block designed by platform engineers to standardize application deployments and enable app developers to self-service. It consists of two parts:
+A Kusion module is a reusable building block designed by platform engineers to standardize application deployments and enable application developers to self-service. It consists of two parts:
 
-- App developer-oriented schema: It is a [KCL schema](https://kcl-lang.io/docs/user_docs/guides/schema-definition/). Fields in this schema are recommended to be understandable to application developers and workspace-agnostic. For example, a database Kusion module schema only contains fields like database engine type and database version.
-- Kusion module generator: It is a piece of logic that generates the Intent with an instantiated schema mentioned above, along with platform configurations ([workspace](../workspace)). As a building block, Kusion module hides the complexity of infrastructures. A database Kusion module not only represents a cloud RDS, but it also contains logic to configure other resources such as security groups and IAM policies. Additionally, it seamlessly injects the database host address, username, and password into the workload's environment variables. The generator logic can be very complex in some situations so we recommend implementing it in a GPL like [go](https://go.dev/).
+- App developer-friendly schema: It is a [KCL schema](https://kcl-lang.io/docs/user_docs/guides/schema-definition/). Fields in this schema are recommended to be understandable to application developers and workspace-agnostic. For example, a database Kusion module schema only contains fields like database engine type and database version.
+- Kusion module generator: It is a piece of logic that generates the [Spec](../6-spec.md) with an instantiated schema mentioned above, along with platform configurations managed in [workspaces](../4-workspace/1-overview.md). As the most fundamental building block, Kusion module provides the necessary abstraction to the developers by hiding the complexity of infrastructures. A database Kusion module not only represents a cloud RDS, but it also contains logic to configure other resources such as security groups and IAM policies. Additionally, it seamlessly injects the database host address, username, and password into the workload's environment variables. The generator logic can be very complex in some situations so we recommend implementing it in a GPL like [go](https://go.dev/).
 
 Here are some explanations of the Kusion Module:
 
 1. It represents an independent unit that provides a specific capability to the application with clear business semantics.
-2. It consists of one or multiple infrastructure resources (K8s/Terraform resources), but it is not merely a collection of unrelated resources. For instance, a database, monitoring capabilities, and network access are typical Kusion Modules.
+2. It may consist of one or multiple infrastructure resources (K8s/Terraform resources), but it is not merely a collection of unrelated resources. For instance, a database, monitoring capabilities, and network access are typical Kusion Modules.
 3. Modules should not have dependencies or be nested within each other.
 4. AppConfig is not a Module.
 5. Kusion Module is a superset of [KPM](https://www.kcl-lang.io/docs/user_docs/guides/package-management/quick-start). It leverages the KPM to manage KCL schemas in the Kusion module.

docs/kusion/3-concepts/3-module/2-develop-guide.md

@@ -12,7 +12,7 @@ To follow this guide, you will need:
 As a platform engineer, the workflow of developing a Kusion module looks like this:
 
 1. Communicate with app developers and identify the fields that should exposed to them in the dev-orient schema
-2. Identify module input parameters that should be configured by platform engineers in the [workspace](../workspace)
+2. Identify module input parameters that should be configured by platform engineers in the [workspace](../4-workspace/1-overview.md)
 3. Define the app dev-orient schema
 4. Develop the module by implementing gRPC interfaces
 
@@ -113,7 +113,7 @@ service:                    Service
 randomPassword:             RandomPassword
 ```
 
-3. **Implement the [gRPC proto](https://github.com/KusionStack/kusion/blob/main/pkg/modules/proto/module.proto) generate interface.** The `generate` interface consumes the application developer's config described in the [`AppConfiguration`](../app-configuration) and the platform engineer's config described in the [`workspace`](../workspace) to generate all infrastructure resources represented by this module.
+3. **Implement the [gRPC proto](https://github.com/KusionStack/kusion/blob/main/pkg/modules/proto/module.proto) generate interface.** The `generate` interface consumes the application developer's config described in the [`AppConfiguration`](../app-configuration) and the platform engineer's config described in the [`workspace`](../4-workspace/1-overview.md) to generate all infrastructure resources represented by this module.
 
 ```go
 func (k *Kawesome) Generate(_ context.Context, request *module.GeneratorRequest) (*module.GeneratorResponse, error) {

docs/kusion/3-concepts/3-module/4-registration.md

@@ -0,0 +1,41 @@
+# Module Registration
+
+After a module is published, it needs to be registered before it can be used in **Kusion server**. This is to help the server to accurately generate a necessary `kcl.mod` file that describes the dependency of a configurations (i.e. what modules can I use as a developer).
+
+This step is not required when using Kusion CLI.
+
+## APIs
+
+The APIs to manage workspaces can be found in the swagger docs under `{server-endpoint}/docs/index.html#/module`.
+
+## Register a module via Developer Portal
+
+To register a new module via the developer portal, switch to the `Modules` tab and click on `New Module`.
+
+![module-create](/img/docs/concept/module-create.png)
+
+Fill out the module details. It's always recommended to provide a link to the module's documentation for developers to read.
+
+![module-details](/img/docs/concept/module-details.png)
+
+## Edit a registered module
+
+To edit a registered module, click the `edit` button.
+
+![module-edit](/img/docs/concept/module-edit.png)
+
+## Delete a registered module
+
+To delete a registered module, click the `delete` button.
+
+![module-delete](/img/docs/concept/module-delete.png)
+
+## Generate kcl.mod
+
+To generate the `kcl.mod` for a stack targeting a workspace, go the workspace page and select `Available Modules`, then click on `Generate kcl.mod`.
+
+![generate-kcl-mod](/img/docs/concept/generate-kcl-mod.png)
+
+A text box appears with the module dependency content generated. This should be copied and pasted into the `kcl.mod` file in the stack folder.
+
+![kcl-mod-generated](/img/docs/concept/kcl-mod-generated.png)