diff --git a/README.md b/README.md
index d31e810..cc455ad 100644
--- a/README.md
+++ b/README.md
@@ -15,3 +15,61 @@ Reusable CMake entry point for embedding in a larger project:
 The primary schema root folder is configurable via:
 
 - `CPPBESSOT_WORKDIR` (defaults to `db`)
+
+## Simple Integration Guide
+
+### 1) Add the module from your parent project
+
+```cmake
+# Parent project CMakeLists.txt
+cmake_minimum_required(VERSION 3.16)
+project(MyApp LANGUAGES CXX)
+
+# Optional: where schema versions live (default is "db")
+set(CPPBESSOT_WORKDIR "db")
+
+# Required for generation/library selection
+set(DB_SCHEMA_VERSION_TO_GENERATE "v1.1")
+
+# Optional: only needed if you will run db_gen_migrations
+# set(DB_SCHEMA_MIGRATION_VERSION_FROM "v1.1")
+# set(DB_SCHEMA_MIGRATION_VERSION_TO "v1.2")
+
+include(path/to/cppbessot/cmake/cppbessot/CppBeSSOT.cmake)
+```
+
+### 2) Build generation targets manually
+
+```bash
+cmake -S . -B build
+cmake --build build --target db_gen_orm_serdes_and_zod
+cmake --build build --target db_gen_sql_ddl
+cmake --build build --target db_check_schema_changes
+```
+
+Optional migration generation:
+
+```bash
+cmake -S . -B build \
+  -DDB_SCHEMA_MIGRATION_VERSION_FROM=v1.1 \
+  -DDB_SCHEMA_MIGRATION_VERSION_TO=v1.2
+cmake --build build --target db_gen_migrations
+```
+
+### 3) Link generated libraries
+
+```cmake
+target_link_libraries(my_app PRIVATE
+  cppbessot::openai_model_gen
+  cppbessot::odb_sqlite   # if sqlite odb sources exist
+  cppbessot::odb_pgsql    # if postgre odb sources exist
+)
+```
+
+### Optional manual enable mode
+
+```cmake
+set(CPPBESSOT_AUTO_ENABLE OFF)
+include(path/to/cppbessot/cmake/cppbessot/CppBeSSOT.cmake)
+cppbessot_enable()
+```
diff --git a/cmake/cppbessot/README.md b/cmake/cppbessot/README.md
deleted file mode 100644
index 18e2357..0000000
--- a/cmake/cppbessot/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# CppBeSSOT CMake Module
-
-## Quick include from a parent project
-
-```cmake
-# Optional overrides before include:
-set(CPPBESSOT_WORKDIR "db")
-set(DB_SCHEMA_VERSION_TO_GENERATE "v1.1")
-set(DB_SCHEMA_MIGRATION_VERSION_FROM "v1.1")
-set(DB_SCHEMA_MIGRATION_VERSION_TO "v1.2")
-
-include(path/to/cppbessot/cmake/cppbessot/CppBeSSOT.cmake)
-```
-
-By default the include auto-registers targets and libraries. To disable auto setup:
-
-```cmake
-set(CPPBESSOT_AUTO_ENABLE OFF)
-include(path/to/cppbessot/cmake/cppbessot/CppBeSSOT.cmake)
-cppbessot_enable()
-```