updated README.md

README.md

@@ -60,3 +60,87 @@ The new directory contains:
 > 🧩 After creation, you'll work entirely within your new project — **cpp-build-system** remains the master template.
 
 > ⚠️ Do **not** run `cmake` directly — always use the provided scripts.
+---
+
+### 3️⃣ Configure the Project
+
+In your new project directory (`~/dev/MyApp/`), edit these two files before your first build:
+
+> ⚠️ **Important Notice:**  
+> Do **not modify** the root `CMakeLists.txt` file in your project.  
+> All changes, targets, and configurations must be made in **`project.cmake`** only.  
+> The top-level `CMakeLists.txt` is managed by cpp-build-system and is required for
+> correct cross-platform builds, packaging, and CI integration.
+
+#### **`config.sh`**
+Defines your project’s **identity, features, and build behavior**:
+
+- **Identity & versioning:**  
+  `PROJECT_NAME`, `PROJECT_DESC`, `PROJECT_URL`,  
+  `PROJECT_MAJOR_VERSION`, `PROJECT_MINOR_VERSION`, `PROJECT_REVISION_VERSION`, `PROJECT_RELEASE_VERSION`, `PROJECT_ITERATION_VERSION`
+- **Apps & testing:**  
+  `PROJECT_APP_LIST` and `PROJECT_ENABLE_TESTING`
+- **Build/link behavior:**  
+  `PROJECT_STATIC_LINK` (defaults to ON), `PROJECT_ENABLE_*` flags for dependencies such as Boost, Curl, FUSE, JSON, libsodium, OpenSSL, RocksDB, SQLite, spdlog, etc.
+- **Platform-specific settings:**  
+  `PROJECT_ENABLE_WIN32_LONG_PATH_NAMES`, macOS bundle identifiers, app icons, bundle names
+- **Security, signing, and keys:**  
+  `PROJECT_PUBLIC_KEY`, `PROJECT_PRIVATE_KEY`
+- **Optional Flutter integration:**  
+  `PROJECT_FLUTTER_BASE_HREF`
+- **Overrides:**  
+  A local `override.sh` (if present) is automatically sourced for per-machine customizations and is, by default, ignored in `.gitignore`
+
+#### **`project.cmake`**
+Owns your project’s **CMake build graph** — defining what gets built and how:
+
+- **Targets:** Add **executables** and **libraries** (static/shared as needed)
+- **Sources & includes:** Declare source lists, include paths, compiler flags, and definitions
+- **Linkage:** Link enabled third-party dependencies (toggled in `config.sh`)
+- **Config & resources:** Install or bundle configuration files and runtime assets
+- **Install/export:** Define `install()` rules, export targets, generate package metadata
+- **Conditionals:** Wrap optional targets behind `PROJECT_ENABLE_*` feature flags
+
+Default `project.cmake`:
+```cmake
+add_project_library(lib${PROJECT_NAME} "" "" "${PROJECT_ADDITIONAL_SOURCES}")
+
+add_project_executable(${PROJECT_NAME} lib${PROJECT_NAME} lib${PROJECT_NAME})
+
+add_project_test_executable(${PROJECT_NAME}_test lib${PROJECT_NAME} lib${PROJECT_NAME})
+```
+
+Together, `config.sh` (identity & features) and `project.cmake` (targets & wiring) define a complete, reproducible build configuration across all platforms.
+
+---
+
+### 4️⃣ Build the Project
+
+Use the provided build wrappers — they take two arguments:
+```
+<arch> <config>
+```
+
+> Default \<arch> is `x86_64` if not specified
+> Default \<configuration> is `RelWithDebInfo` if not specified
+
+#### 🐧 Unix/Linux/macOS (via Alpine containers)
+```bash
+./scripts/make_unix.sh # x86_64 RelWithDebInfo
+./scripts/make_unix.sh x86_64 Release
+./scripts/make_unix.sh aarch64 Debug
+```
+
+#### 🪟 Windows (MinGW64 or MSYS2)
+```bash
+# Cross-compile Windows x64 using MinGW64 (preferred)
+./scripts/make_win32.sh  x86_64 RelWithDebInfo
+
+# Build on Windows via MSYS2 (dynamic, for testing)
+./scripts/make_win32.cmd x86_64 Debug
+```
+
+> `make_unix.sh` automatically builds inside **Alpine containers** for reproducible static binaries using **musl-libc**.  
+> `make_win32.*` supports both **MinGW64 cross-builds** (mostly static) and **MSYS2** builds (dynamic fallback).
+
+---