From 9c02414255c46033bba90772bff7619553fc1e3a Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Mon, 27 Jul 2026 09:18:50 +0700
Subject: [PATCH 01/20] Update for Proxy

---
 src/dp/structural/Proxy.cpp | 175 ++++++++++--------------------------
 1 file changed, 45 insertions(+), 130 deletions(-)

diff --git a/src/dp/structural/Proxy.cpp b/src/dp/structural/Proxy.cpp
index 649955a..dd7427c 100644
--- a/src/dp/structural/Proxy.cpp
+++ b/src/dp/structural/Proxy.cpp
@@ -1,36 +1,31 @@
-// Proxy is a structural design pattern that lets you provide a substitute or
-// placeholder for another object. A proxy controls access to the original
-// object, allowing you to perform something either before or after the request
-// gets through to the original object. A proxy receives client requests, does
-// some work (access control, caching, etc.) and then passes the request to a
-// service object. Appicability:
-// (*)   Lazy initialization (virtual proxy) /  Logging requests (logging proxy)
-// / Caching request results (caching proxy)
-// (**)  Access control (protection proxy).
-// (***) Local execution of a remote service (remote proxy). This is when the
-// service object is located on a remote server.
-
 // Composition - lazy
 // Aggregation - x
-// UML: docs/uml/patterns_structural_proxy.drawio.svg
 
-#include <iostream>
+#include <memory>
 #include <utility>
 
 #include "ExampleRegistry.h"
+#include "Logger.h"
 
 namespace {
-namespace problem {
-const std::string kAdmin = "admin";
-
+/// @class Server Interface
 class IServer {
  public:
   virtual ~IServer() = default;
-  virtual void request1() = 0;
-  virtual void request2() = 0;
-  virtual void request3() = 0;
+
+  /// @brief api
+  virtual void request() = 0;
 };
 
+/// @brief User code
+void clientCode(IServer* s) {
+  if (s != nullptr) {
+    s->request();
+  }
+}
+
+namespace problem {
+const std::string kAdmin = "admin";
 class Server : public IServer {
  private:
   std::string id_;
@@ -38,184 +33,104 @@ class Server : public IServer {
  public:
   explicit Server(std::string id) : id_{std::move(id)} {
     // [P1] Heavy or complex construction, so ideally should be lazy-loaded
-    std::cout << "[Server] Constructor: " << id_ << "\n";
+    LOG_S("CTR: " << id_);
   }
 
   // [P2] Need access control
   // [P3] Need to log requests without modifying the Server itself
-  void request1() override {
+  void request() override {
     if (id_ != kAdmin) {
-      std::cout << "[Server] Invalid ID: " << id_ << "\n";
+      LOG_S("Invalid ID: " << id_);
       return;
     }
-    std::cout << "[Server] Handling request-1 for: " << id_ << "\n";
-  }
-
-  void request2() override {
-    if (id_ != kAdmin) {
-      std::cout << "[Server] Invalid ID: " << id_ << "\n";
-      return;
-    }
-    std::cout << "[Server] Handling request-2 for: " << id_ << "\n";
-  }
-
-  void request3() override {
-    if (id_ != kAdmin) {
-      std::cout << "[Server] Invalid ID: " << id_ << "\n";
-      return;
-    }
-    std::cout << "[Server] Handling request-3 for: " << id_ << "\n";
+    LOG_S("Handling request for: " << id_);
   }
 };
 
-namespace client {
-void clientCode(IServer* s) {
-  if (s != nullptr) {
-    s->request1();
-    s->request2();
-    s->request3();
-  }
-}
-}  // namespace client
-
 void run() {
-  std::cout << "\n\n";
-
   {
     std::string connection_id = "admin";
     // [P4] The Server is constructed immediately even if we do not call any
     // requests
-    IServer* server = new Server(connection_id);
-    std::cout << "User request\n";
-    client::clientCode(server);
-    delete server;
+    auto server = std::make_unique<Server>(connection_id);
+    LOG("User request");
+    clientCode(server.get());
   }
 
   {
     // [P4] Server is constructed even for invalid ID, wasting resources
     std::string invalid_id = "xxx";
-    auto* server = new Server(invalid_id);
-    client::clientCode(server);
-    delete server;
+    auto server = std::make_unique<Server>(invalid_id);
+    LOG("User request");
+    clientCode(server.get());
   }
 }
 }  // namespace problem
 
 namespace proxy_pattern {
 const std::string kAdmin = "admin";
-
-class IServer {
- public:
-  virtual ~IServer() = default;
-  virtual void request1() = 0;
-  virtual void request2() = 0;
-  virtual void request3() = 0;
-};
-
 class Server : public IServer {
  private:
   std::string id_;
 
  public:
   explicit Server(std::string id) : id_{std::move(id)} {
-    std::cout << "[Server] Constructor: " << id_ << "\n";
-  }
-
-  void request1() override {
-    std::cout << "[Server] Handling request-1 for: " << id_ << "\n";
-  }
-
-  void request2() override {
-    std::cout << "[Server] Handling request-2 for: " << id_ << "\n";
+    LOG_S("CTR: " << id_);
   }
 
-  void request3() override {
-    std::cout << "[Server] Handling request-3 for: " << id_ << "\n";
-  }
+  void request() override { LOG_S("Handling request for: " << id_); }
 };
 
 class ServerProxy : public IServer {
  private:
   std::string id_;
-  Server* server_{};
+  std::unique_ptr<Server> server_;
 
   bool checkAccess() {
-    std::cout << "[Proxy] Checking access before forwarding request.\n";
+    LOG("Checking access before forwarding request.");
     if (id_ != kAdmin) {
+      LOG("Invalid id. Return");
       return false;
     }
 
     // Lazy initialization: construct Server only on first access
     if (server_ == nullptr) {
-      server_ = new Server(id_);
+      server_ = std::make_unique<Server>(id_);
     }
     return true;
   }
 
-  void logAccess() const {
-    std::cout << "[Proxy] Logging request time: " << id_ << " .\n";
-  }
+  void logAccess() const { LOG_S("Logging request time: " << id_); }
 
  public:
   explicit ServerProxy(std::string id) : id_{std::move(id)} {
-    std::cout << "[Proxy] Constructor: " << id_ << "\n";
-  }
-
-  ~ServerProxy() override {
-    std::cout << "[Proxy] Destructor: " << id_ << "\n";
-
-    delete server_;
+    LOG_S("CTR: " << id_);
   }
 
-  void request1() override {
+  void request() override {
     if (checkAccess()) {
-      server_->request1();
-      logAccess();
-    }
-  }
-
-  void request2() override {
-    if (checkAccess()) {
-      server_->request2();
-      logAccess();
-    }
-  }
-
-  void request3() override {
-    if (checkAccess()) {
-      server_->request3();
+      server_->request();
       logAccess();
     }
   }
 };
 
-namespace client {
-void clientCode(IServer* s) {
-  if (s != nullptr) {
-    s->request1();
-    s->request2();
-    s->request3();
-  }
-}
-}  // namespace client
-
 void run() {
-  std::cout << "\n\n";
-
   {
     std::string connection_id = "admin";
     // Server is not constructed until first request is made
-    IServer* server = new ServerProxy(connection_id);
-    std::cout << "User request\n";
-    client::clientCode(server);
-    delete server;
+    auto server_proxy = std::make_unique<ServerProxy>(connection_id);
+    LOG("User request");
+    clientCode(server_proxy.get());
   }
 
-  // Server is not constructed if id is invalid
-  std::string invalid_id = "xxx";
-  auto* server = new Server(invalid_id);
-  client::clientCode(server);
-  delete server;
+  {
+    // Server is not constructed if id is invalid
+    std::string invalid_id = "xxx";
+    auto server_proxy = std::make_unique<ServerProxy>(invalid_id);
+    LOG("User request");
+    clientCode(server_proxy.get());
+  }
 }
 }  // namespace proxy_pattern
 

From aa331305f6f54b1a770f229b2c746e614e88f7b1 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Mon, 27 Jul 2026 09:28:16 +0700
Subject: [PATCH 02/20] Update for Adapter

---
 src/dp/structural/Adapter.cpp | 100 ++++++++++++++++------------------
 1 file changed, 46 insertions(+), 54 deletions(-)

diff --git a/src/dp/structural/Adapter.cpp b/src/dp/structural/Adapter.cpp
index 6ea3755..e881bd1 100644
--- a/src/dp/structural/Adapter.cpp
+++ b/src/dp/structural/Adapter.cpp
@@ -1,79 +1,73 @@
-// Adapters is a structural design pattern that allows objects with incompatible
-// interfaces to collaborate. Appicability:
-// (*) When you want to use some existing class, but its interface isn’t
-// compatible with the rest of your code
-// (**)When you want to reuse several existing subclasses that lack some common
-// functionality that can’t be added to the superclass.
-
-// UML: docs/uml/patterns_structural_adapter.drawio.svg
-
+#include <memory>
 #include "Logger.h"
 
+#include "ExampleRegistry.h"
+
 namespace adapter_pattern {
-/**
- * The Adaptee contains some useful behavior, but its interface is incompatible
- * with the existing client code. The Adaptee needs some adaptation before the
- * client code can use it.
- */
+
+/// @class Adaptee
+/// @brief Existing class with an incompatible interface
 class Adaptee {
  public:
   void specific_request() {
-    dummy_++;
-    LOG("executed");
+    ++dummy_;
+    LOG("Adaptee::specific_request()");
   }
 
  private:
-  int dummy_{};
+  int dummy_{0};
 };
 
-/**
- * The Target defines the domain-specific interface used by the client code.
- */
+/// @class Target
+/// @brief Interface expected by the client
 class Target {
  public:
-  virtual void request() { LOG("executed"); }
+  virtual ~Target() = default;
+
+  virtual void request() = 0;
 };
 
-// ============================================================================================================
-// [Q] How can we make the clientCode works with Adaptee without change this
-// function (e.g this is in front-end)
-// => Create an Adapter
-// ============================================================================================================
+/// @class ConcreteTarget
+/// @brief A normal implementation of Target
+class ConcreteTarget : public Target {
+ public:
+  void request() override { LOG("request"); }
+};
 
-/**
- * The Adapter makes the Adaptee's interface compatible with the Target's
- * interface.
- */
+/// @class Adapter
+/// @brief Converts the Target interface into the Adaptee interface
 class Adapter : public Target {
- private:
-  Adaptee* adaptee_;
-
  public:
-  explicit Adapter(Adaptee* adaptee) : adaptee_{adaptee} { LOG("constructed"); }
+  explicit Adapter(std::unique_ptr<Adaptee> adaptee)
+      : adaptee_(std::move(adaptee)) {
+    LOG("CTR");
+  }
+
+  void request() override { adaptee_->specific_request(); }
 
-  void request() override { return adaptee_->specific_request(); }
+ private:
+  std::unique_ptr<Adaptee> adaptee_;
 };
 
+/// @brief Client code only depends on Target.
+void client_code(Target& target) {
+  LOG("");
+  target.request();
+}
+
 void run() {
   LOG("Adapter Example");
+  {
+    ConcreteTarget target;
+    client_code(target);
+  }
+  LOG("");
 
-  // The client code supports all classes that follow the Target interface.
-  auto client_code = [](Target* target) {
-    LOG("executed");
-    target->request();
-  };
-
-  LOG("Client: Can work just fine with the Target objects:");
-  Target target = Target();
-  client_code(&target);
-
-  LOG("Client: Cannot work with the Adaptee objects:");
-  Adaptee adaptee = Adaptee();
-  // Client::clientCode(&adaptee); // error
-
-  LOG("Client: But can work with it via the Adapter:");
-  auto adapter = Adapter(&adaptee);
-  client_code(&adapter);
+  {
+    auto adaptee = std::make_unique<Adaptee>();
+    Adapter adapter(std::move(adaptee));
+    client_code(adapter);
+  }
 }
 }  // namespace adapter_pattern
 
@@ -140,8 +134,6 @@ void run() {
 }
 }  // namespace case_study
 
-#include "ExampleRegistry.h"
-
 class AdapterExample : public IExample {
  public:
   std::string group() const override { return "dp/structural"; }

From 6a79e162d0bc136f038b9c076048e7672ee68d46 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Mon, 27 Jul 2026 10:19:19 +0700
Subject: [PATCH 03/20] Update for bridge

---
 src/dp/structural/Bridge.cpp | 59 +++++++++++-------------------------
 1 file changed, 17 insertions(+), 42 deletions(-)

diff --git a/src/dp/structural/Bridge.cpp b/src/dp/structural/Bridge.cpp
index bceb942..c59b7d2 100644
--- a/src/dp/structural/Bridge.cpp
+++ b/src/dp/structural/Bridge.cpp
@@ -1,16 +1,3 @@
-// Bridge lets we split a large class or a set of closely related classes
-// into two separate hierarchies—abstraction and implementation
-// which can be developed independently of each other.
-// Appicability:
-// (*)   when you want to divide and organize a monolithic class that has
-// several variants of some functionality
-//       (for example, if the class can work with various database servers).
-// (**)  when you need to extend a class in several orthogonal (independent)
-// dimensions.
-// (***) when you you need to be able to switch implementations at runtime.
-
-// UML: docs/uml/patterns_structural_bridge.drawio.svg
-
 #include <memory>
 #include <utility>
 #include "ExampleRegistry.h"
@@ -24,7 +11,6 @@ class Widget {
   virtual void click_on() const = 0;
 };
 
-/* Concrete variations for Button */
 class Button : public Widget {
  public:
   void click_on() const override { LOG("executed"); }
@@ -46,7 +32,6 @@ class ButtonLinux : public Button {
   }
 };
 
-/* Concrete variations for Label */
 class Label : public Widget {
  public:
   void click_on() const override { LOG("executed"); }
@@ -70,8 +55,6 @@ class LabelLinux : public Label {
 
 void run() {
   LOG("Problem");
-  /* Concrete variations for others widgets like Text,CCombo  or new platform
- * macOS etc*/
   // [Problem 1] We have to write the Text/TextLinux ...
   auto client_code = [](const Widget* widget) {
     if (widget != nullptr)
@@ -87,13 +70,8 @@ void run() {
 }  // namespace problem
 
 namespace bridge_pattern {
-/**
- * The Implementation defines the interface for all implementation classes. It
- * doesn't have to match the Abstraction's interface. In fact, the two
- * interfaces can be entirely different. Typically the Implementation interface
- * provides only primitive Widgets, while the Abstraction defines higher-
- * level Widgets based on those primitives.
- */
+/// @class Implemetation Interface
+/// @brief Define the interface for all implementation classes
 class OsImplemetation {
  public:
   virtual void click_on_ipl() const = 0;
@@ -110,11 +88,8 @@ class LinuxImplemetation : public OsImplemetation {
   void click_on_ipl() const override { LOG("[Linux]"); }
 };
 
-/**
- * The Abstraction defines the interface for the "control" part of the two class
- * hierarchies. It maintains a reference to an object of the Implementation
- * hierarchy and delegates all of the real work to this object.
- */
+/// @class Abstractio Class
+/// @brief Define the interface for the control part
 class WidgetAbstraction {
  protected:
   std::shared_ptr<OsImplemetation> implementation_;
@@ -127,9 +102,6 @@ class WidgetAbstraction {
   virtual void click_on() const = 0;
 };
 
-/**
- * We can extend the Abstraction without changing the Implementation classes.
- */
 class ButtonAbstraction : public WidgetAbstraction {
  public:
   explicit ButtonAbstraction(std::shared_ptr<OsImplemetation> implemetation)
@@ -153,20 +125,23 @@ class LabelAbstraction : public WidgetAbstraction {
 void run() {
   LOG("Bridge Example");
   auto client_code = [](const WidgetAbstraction* widget) {
-    if (widget != nullptr)
+    if (widget != nullptr) {
+      LOG("");
       widget->click_on();
+    }
   };
 
-  std::shared_ptr<OsImplemetation> os =
-      std::make_shared<WindowsImplemetation>();
-  WidgetAbstraction* widget = new ButtonAbstraction(os);
-  client_code(widget);
-
-  os = std::make_shared<LinuxImplemetation>();
-  widget = new LabelAbstraction(os);
-  client_code(widget);
+  {
+    auto os = std::make_shared<WindowsImplemetation>();
+    auto widget = std::make_unique<ButtonAbstraction>(os);
+    client_code(widget.get());
+  }
 
-  delete widget;
+  {
+    auto os = std::make_shared<LinuxImplemetation>();
+    auto widget = std::make_unique<LabelAbstraction>(os);
+    client_code(widget.get());
+  }
 }
 }  // namespace bridge_pattern
 

From 2b93fac0c65adca392961f37c789068ca51baa60 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Mon, 27 Jul 2026 11:19:34 +0700
Subject: [PATCH 04/20] Create an demo for dlopen

---
 src/CMakeLists.txt             |  1 +
 src/demo/CMakeLists.txt        |  1 +
 src/demo/dlopen/CMakeLists.txt | 16 +++++++++
 src/demo/dlopen/README.md      | 43 +++++++++++++++++++++++
 src/demo/dlopen/bridge.cpp     | 62 ++++++++++++++++++++++++++++++++++
 src/demo/dlopen/bridge.h       | 12 +++++++
 src/demo/dlopen/main.cpp       | 55 ++++++++++++++++++++++++++++++
 src/demo/dlopen/sample_app.cpp | 22 ++++++++++++
 8 files changed, 212 insertions(+)
 create mode 100644 src/demo/CMakeLists.txt
 create mode 100644 src/demo/dlopen/CMakeLists.txt
 create mode 100644 src/demo/dlopen/README.md
 create mode 100644 src/demo/dlopen/bridge.cpp
 create mode 100644 src/demo/dlopen/bridge.h
 create mode 100644 src/demo/dlopen/main.cpp
 create mode 100644 src/demo/dlopen/sample_app.cpp

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 191aecb..2185b50 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -8,6 +8,7 @@ add_subdirectory(controller)
 add_subdirectory(dp)
 add_subdirectory(socket)
 add_subdirectory(ap)
+add_subdirectory(demo)
 
 # Header files directory
 set(APP_HEADERS
diff --git a/src/demo/CMakeLists.txt b/src/demo/CMakeLists.txt
new file mode 100644
index 0000000..7641d6a
--- /dev/null
+++ b/src/demo/CMakeLists.txt
@@ -0,0 +1 @@
+add_subdirectory(dlopen)
\ No newline at end of file
diff --git a/src/demo/dlopen/CMakeLists.txt b/src/demo/dlopen/CMakeLists.txt
new file mode 100644
index 0000000..d3550ba
--- /dev/null
+++ b/src/demo/dlopen/CMakeLists.txt
@@ -0,0 +1,16 @@
+# bridge shared lib
+add_library(bridge SHARED
+    bridge.cpp
+)
+
+# shared lib
+add_library(sample_app SHARED
+    sample_app.cpp
+)
+target_link_libraries(sample_app PRIVATE bridge)
+
+# executable demo
+add_executable(demo_dlopen
+    main.cpp
+)
+target_link_libraries(demo_dlopen PRIVATE bridge sample_app)
\ No newline at end of file
diff --git a/src/demo/dlopen/README.md b/src/demo/dlopen/README.md
new file mode 100644
index 0000000..bf13be4
--- /dev/null
+++ b/src/demo/dlopen/README.md
@@ -0,0 +1,43 @@
+# dlopen demo
+
+Minimal demo of the **host process + `dlopen` plugin + shared-lib bridge** pattern
+
+## Layout
+
+```text
+dlopen_plugin_demo/
+├── CMakeLists.txt
+├── bridge.h/.cpp    # shared bridge API + singleton
+├── sample_app       # SHARED lib with main()
+├── main.cpp         # executable that dlopen + dlsym(main)
+└── README.md
+```
+
+---
+**Expected flow:**
+1. `demo_dlopen` loads `libsample_app.so`
+2. finds symbol `main` via `dlsym`
+3. background thread marks bridge ready
+4. plugin waits, then write/read a fake register through `libbridge.so`
+5. both sides share **one** bridge singleton (because bridge is **SHARED**)
+
+```text
+demo:     host  --dlopen-->  libsample_app.so  --calls-->  libbridge.so
+```
+
+## Why bridge must be SHARED
+
+If `bridge` were STATIC, `host` and `libsample_app.so` would each get a private singleton -> `bridge_wait_ready()` would hang forever (plugin never sees host’s `ready` flag).
+
+Try the broken variant (optional experiment):
+
+```cmake
+# in CMakeLists.txt, change:
+add_library(bridge STATIC bridge.cpp)
+```
+
+Rebuild & run => plugin will block on `bridge_wait_ready()`.
+
+----
+EOF
+----
\ No newline at end of file
diff --git a/src/demo/dlopen/bridge.cpp b/src/demo/dlopen/bridge.cpp
new file mode 100644
index 0000000..1a13ef6
--- /dev/null
+++ b/src/demo/dlopen/bridge.cpp
@@ -0,0 +1,62 @@
+#include "bridge.h"
+
+#include <condition_variable>
+#include <iostream>
+#include <mutex>
+#include <unordered_map>
+
+namespace {
+
+struct BridgeState {
+  std::unordered_map<std::uintptr_t, std::uint32_t> regs;
+  std::mutex mtx;
+  std::condition_variable cv;
+  bool ready = false;
+};
+
+BridgeState& state() {
+  /// skelton
+  static BridgeState s;
+  return s;
+}
+
+}  // namespace
+
+void bridge_write_reg(std::uintptr_t addr, std::uint32_t value) {
+  auto& s = state();
+  std::lock_guard<std::mutex> lock(s.mtx);
+  s.regs[addr] = value;
+  std::cout << "[bridge] write 0x" << std::hex << addr << " = 0x" << value
+            << std::dec << "\n";
+}
+
+std::uint32_t bridge_read_reg(std::uintptr_t addr) {
+  auto& s = state();
+  std::lock_guard<std::mutex> lock(s.mtx);
+  auto it = s.regs.find(addr);
+  const std::uint32_t value = (it == s.regs.end()) ? 0U : it->second;
+  std::cout << "[bridge] read  0x" << std::hex << addr << " -> 0x" << value
+            << std::dec << "\n";
+  return value;
+}
+
+void bridge_set_ready() {
+  auto& s = state();
+  {
+    std::lock_guard<std::mutex> lock(s.mtx);
+    s.ready = true;
+  }
+  s.cv.notify_all();
+  std::cout << "[bridge] host marked ready\n";
+}
+
+void bridge_wait_ready() {
+  auto& s = state();
+  std::unique_lock<std::mutex> lock(s.mtx);
+  s.cv.wait(lock, [&] { return s.ready; });
+  std::cout << "[bridge] plugin saw ready\n";
+}
+
+const char* bridge_name() {
+  return "libbridge.so";
+}
\ No newline at end of file
diff --git a/src/demo/dlopen/bridge.h b/src/demo/dlopen/bridge.h
new file mode 100644
index 0000000..b037f7b
--- /dev/null
+++ b/src/demo/dlopen/bridge.h
@@ -0,0 +1,12 @@
+#pragma once
+
+#include <cstdint>
+
+// Shared-lib bridge: one copy in the process for both host and plugin.
+void bridge_write_reg(std::uintptr_t addr, std::uint32_t value);
+std::uint32_t bridge_read_reg(std::uintptr_t addr);
+
+void bridge_set_ready();
+void bridge_wait_ready();
+
+const char* bridge_name();
\ No newline at end of file
diff --git a/src/demo/dlopen/main.cpp b/src/demo/dlopen/main.cpp
new file mode 100644
index 0000000..722bce0
--- /dev/null
+++ b/src/demo/dlopen/main.cpp
@@ -0,0 +1,55 @@
+#include "bridge.h"
+
+#include <dlfcn.h>
+
+#include <chrono>
+#include <iostream>
+#include <thread>
+
+using app_main_t = int (*)(int, char**);
+
+int main(int argc, char* argv[]) {
+  const char* plugin_path = "./libsample_app.so";
+  if (argc > 1) {
+    plugin_path = argv[1];
+  }
+
+  std::cout << "[host] starting (bridge=" << bridge_name() << ")\n";
+  std::cout << "[host] dlopen: " << plugin_path << "\n";
+
+  void* handle = dlopen(plugin_path, RTLD_LAZY | RTLD_GLOBAL);
+  if (!handle) {
+    std::cerr << "[host] dlopen failed: " << dlerror() << "\n";
+    return 1;
+  }
+
+  dlerror();  // clear
+  auto* app_main = reinterpret_cast<app_main_t>(dlsym(handle, "main"));
+  const char* err = dlerror();
+  if (err != nullptr || app_main == nullptr) {
+    std::cerr << "[host] dlsym(main) failed: " << (err ? err : "null") << "\n";
+    dlclose(handle);
+    return 1;
+  }
+
+  // init on another thread, then notify plugin
+  std::thread init_thread([] {
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    bridge_write_reg(0x0000, 0x1U);  // fake "device present"
+    bridge_set_ready();
+  });
+
+  char arg0[] = "sample_app";
+  char arg1[] = "hello";
+  char* app_argv[] = {arg0, arg1, nullptr};
+  const int app_argc = 2;
+
+  std::cout << "[host] calling plugin main()\n";
+  const int rc = app_main(app_argc, app_argv);
+  std::cout << "[host] plugin returned " << rc << "\n";
+
+  init_thread.join();
+  dlclose(handle);
+  std::cout << "[host] done\n";
+  return rc;
+}
\ No newline at end of file
diff --git a/src/demo/dlopen/sample_app.cpp b/src/demo/dlopen/sample_app.cpp
new file mode 100644
index 0000000..36e27fd
--- /dev/null
+++ b/src/demo/dlopen/sample_app.cpp
@@ -0,0 +1,22 @@
+#include "bridge.h"
+
+#include <cstdint>
+#include <iostream>
+
+extern "C" int main(const int argc, const char* argv[]) {
+  std::cout << "[plugin] main() started (argc=" << argc << ")\n";
+  for (int i = 0; i < argc; ++i) {
+    std::cout << "[plugin]   argv[" << i << "] = " << argv[i] << "\n";
+  }
+
+  std::cout << "[plugin] waiting for host via " << bridge_name() << "...\n";
+  bridge_wait_ready();
+
+  bridge_write_reg(0x1000, 0xA5A5A5A5U);
+  const std::uint32_t v = bridge_read_reg(0x1000);
+  std::cout << "[plugin] round-trip value = 0x" << std::hex << v << std::dec
+            << "\n";
+
+  std::cout << "[plugin] main() done\n";
+  return 0;
+}
\ No newline at end of file

From 91d28044329f32e9ef9780ff77e95b508a51feb3 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Fri, 7 Aug 2026 09:58:18 +0700
Subject: [PATCH 05/20] Update for decorator

---
 src/dp/structural/Decorator.cpp | 145 ++++++++++----------------------
 1 file changed, 45 insertions(+), 100 deletions(-)

diff --git a/src/dp/structural/Decorator.cpp b/src/dp/structural/Decorator.cpp
index 4947542..5676fc3 100644
--- a/src/dp/structural/Decorator.cpp
+++ b/src/dp/structural/Decorator.cpp
@@ -1,16 +1,10 @@
-// Decorator is a structural design pattern that lets you attach new behaviors
-// to objects by placing these objects inside special wrapper objects that
-// contain the behaviors. Appicability:
-// (*)   when you need to be able to assign extra behaviors to objects at
-// runtime without breaking the code that uses these objects.
-// (**)  when it’s awkward or not possible to extend an object’s behavior using
-// inheritance. UML: docs/uml/patterns_structural_decorator.drawio.svg
-
-#include <iostream>
+#include <memory>
 #include <string>
+#include "Logger.h"
+
+#include "ExampleRegistry.h"
 
 namespace {
-namespace problem {
 
 class IComponent {
  public:
@@ -18,6 +12,11 @@ class IComponent {
   virtual std::string operation() const = 0;
 };
 
+auto client_code = [](const IComponent* comp) {
+  LOG(comp->operation());
+};
+
+namespace problem {
 class ConcreteComponent : public IComponent {
  public:
   std::string operation() const override { return "ConcreteComponent"; }
@@ -44,86 +43,50 @@ class ComponentWithAandB : public ConcreteComponent {
   }
 };
 
-// [P1]
-// If you have 3 features , e.g FeatureC -> many combinations
-// If you have 5 features -> 32 subclasses
-
-namespace client {
-void clientCode(const IComponent& comp) {
-  std::cout << comp.operation() << "\n";
-}
-}  // namespace client
-
 void run() {
-  std::cout << "\n\nProblem\n";
-  IComponent* simple = new ConcreteComponent;
-  client::clientCode(*simple);
-
-  IComponent* with_a = new ComponentWithA;
-  client::clientCode(*with_a);
+  // [P1]
+  // If you have 3 features , e.g FeatureC -> many combinations
+  // If you have 5 features -> 32 subclasses
+  LOG("Problem");
+  std::unique_ptr<IComponent> simple = std::make_unique<ConcreteComponent>();
+  client_code(simple.get());
 
-  IComponent* with_b = new ComponentWithB;
-  client::clientCode(*with_b);
+  std::unique_ptr<IComponent> with_a = std::make_unique<ComponentWithA>();
+  client_code(with_a.get());
 
-  IComponent* with_ab = new ComponentWithAandB;
-  client::clientCode(*with_ab);
+  std::unique_ptr<IComponent> with_b = std::make_unique<ComponentWithB>();
+  client_code(with_b.get());
 
-  delete simple;
-  delete with_a;
-  delete with_b;
-  delete with_ab;
+  std::unique_ptr<IComponent> with_ab = std::make_unique<ComponentWithAandB>();
+  client_code(with_ab.get());
 }
-
 }  // namespace problem
 
 namespace decorator_pattern {
-class IComponent {
- public:
-  virtual ~IComponent() = default;
-  virtual std::string operation() const = 0;
-};
-
-/**
- * Concrete Component
- * - is a class of objects being wrapped.
- * - defines the basic behavior, which can be altered by decorators.
- */
+/// @class Concrete Component
 class ConcreteComponent : public IComponent {
  public:
   std::string operation() const override { return "ConcreteComponent"; }
 };
 
-/**
- * The base Decorator class follows the same interface as the other components.
- * - has a field for referencing a wrapped object.
- * - the field’s type should be declared as the component interface so it can
- * contain both concrete components and decorators.
- * - the base decorator delegates all operations to the wrapped object.
- */
+/// @class Base Decorator
 class BaseDecorator : public IComponent {
  protected:
-  IComponent* component_;
+  std::unique_ptr<IComponent> component_;
 
  public:
-  explicit BaseDecorator(IComponent* component) : component_{component} {}
+  explicit BaseDecorator(std::unique_ptr<IComponent> component)
+      : component_(std::move(component)) {}
 
-  /**
-   * The Decorator delegates all work to the wrapped component.
-   */
+  /// the Decorator delegates all work to the wrapped componentx
   std::string operation() const override { return component_->operation(); }
 };
 
-/**
- * Concrete Decorators :
- * - call the wrapped object and alter its result in some way.
- * - define extra behaviors that can be added to components dynamically.
- * - override methods of the base decorator and execute their behavior either
- * before or after calling the parent method.
- */
+/// @class Concrete Decorator
 class ConcreteDecoratorA : public BaseDecorator {
  public:
-  explicit ConcreteDecoratorA(IComponent* component)
-      : BaseDecorator{component} {}
+  explicit ConcreteDecoratorA(std::unique_ptr<IComponent> component)
+      : BaseDecorator(std::move(component)) {}
 
   std::string operation() const override {
     return BaseDecorator::operation() + " + FeatureA";
@@ -132,8 +95,8 @@ class ConcreteDecoratorA : public BaseDecorator {
 
 class ConcreteDecoratorB : public BaseDecorator {
  public:
-  explicit ConcreteDecoratorB(IComponent* component)
-      : BaseDecorator{component} {}
+  explicit ConcreteDecoratorB(std::unique_ptr<IComponent> component)
+      : BaseDecorator(std::move(component)) {}
 
   std::string operation() const override {
     return BaseDecorator::operation() + " + FeatureB";
@@ -142,49 +105,31 @@ class ConcreteDecoratorB : public BaseDecorator {
 
 class ConcreteDecoratorC : public BaseDecorator {
  public:
-  explicit ConcreteDecoratorC(IComponent* component)
-      : BaseDecorator{component} {}
+  explicit ConcreteDecoratorC(std::unique_ptr<IComponent> component)
+      : BaseDecorator(std::move(component)) {}
 
   std::string operation() const override {
     return BaseDecorator::operation() + " + FeatureC";
   }
 };
 
-namespace client {
-void clientCode(const IComponent& comp) {
-  std::cout << comp.operation() << "\n";
-}
-}  // namespace client
-
 void run() {
-  std::cout << "\n\nDecorator\n";
-  IComponent* simple = new ConcreteComponent;
-  client::clientCode(*simple);
-
-  IComponent* with_a = new ConcreteDecoratorA(simple);
-  client::clientCode(*with_a);
-
-  IComponent* with_b = new ConcreteDecoratorB(simple);
-  client::clientCode(*with_b);
-
-  IComponent* with_ab = new ConcreteDecoratorB(with_a);
-  client::clientCode(*with_ab);
-
-  IComponent* with_abc = new ConcreteDecoratorC(with_ab);
-  client::clientCode(*with_abc);
-
-  delete simple;
-  delete with_a;
-  delete with_b;
-  delete with_ab;
-  delete with_abc;
+  LOG("Decorator");
+  std::unique_ptr<IComponent> simple = std::make_unique<ConcreteComponent>();
+  client_code(simple.get());
+
+  std::unique_ptr<IComponent> with_a =
+      std::make_unique<ConcreteDecoratorA>(std::move(simple));
+  std::unique_ptr<IComponent> with_ab =
+      std::make_unique<ConcreteDecoratorB>(std::move(with_a));
+  std::unique_ptr<IComponent> with_abc =
+      std::make_unique<ConcreteDecoratorC>(std::move(with_ab));
+  client_code(with_abc.get());
 }
 }  // namespace decorator_pattern
 
 }  // namespace
 
-#include "ExampleRegistry.h"
-
 class DecoratorExample : public IExample {
  public:
   std::string group() const override { return "dp/structural"; }

From 60a267a438fe619483ec76e712fa75c581c9275d Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Fri, 11 Sep 2026 23:01:54 +0700
Subject: [PATCH 06/20] Preserve pre-existing working tree changes (tests
 disabled, gitignore)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 .gitignore     | 3 ++-
 CMakeLists.txt | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index e84cd09..5577478 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,4 +8,5 @@ coverage_lcov
 !.vscode/launch.json
 !.vscode/tasks.json
 .cache
-__pycache__/
\ No newline at end of file
+__pycache__/
+*Testing*
\ No newline at end of file
diff --git a/CMakeLists.txt b/CMakeLists.txt
index b03e79d..f7cc84f 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -61,4 +61,5 @@ enable_testing()
 
 # Add project modules
 add_subdirectory(src)
-add_subdirectory(tests)
\ No newline at end of file
+
+# add_subdirectory(tests)
\ No newline at end of file

From 13b615e61454ad11f7a5500e1901342d38c66469 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Fri, 11 Sep 2026 23:01:54 +0700
Subject: [PATCH 07/20] Add CLAUDE.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 CLAUDE.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9b3022b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+A C++20 learning lab: many small, self-contained examples (language features, STL, concurrency, design patterns, sockets, a PID controller) compiled into one interactive menu-driven executable, plus a few standalone executables (GTK4 MVC/MVVM apps, a `dlopen` demo) and a bare-metal ARM example that sits outside CMake.
+
+## Build & run
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug   # configure
+cmake --build build                            # build all targets
+./build/bin/cpp_lab_project                    # interactive examples menu (optional: -mode Dev|Uat|Prod)
+./scripts/run.sh                               # build + cppcheck + run (needs private/genid.py, which is gitignored)
+```
+
+- Configuring needs **gtkmm-4.0** (`libgtkmm-4.0-dev`). `cmake/Dependencies.cmake` marks it `REQUIRED`, so configure fails without it, even if you only want the main executable. GoogleTest is fetched over the network with FetchContent on the first configure.
+- Executables go to `build/bin/` and shared libs to `build/lib/`. VS Code tasks/launch use `build/debug` instead.
+- Other targets: `ap`, `mvc_ap`, `mvvm_ap` (GTK4 GUIs in `src/ap/`) and `demo_dlopen` (loads `libsample_app.so` at runtime; see `src/demo/dlopen/README.md` for why `bridge` must stay SHARED).
+- `src/embedded/` is not part of CMake. Build and boot it in QEMU with `cd src/embedded && ./run.sh [gui|debug]` (requires `gcc-arm-none-eabi` and `qemu-system-arm`).
+
+## Tests
+
+GoogleTest/GMock tests live in `tests/` (the target is `cpp_lab_project_unit_test`; mocks and fakes are in `tests/mock/`). **`add_subdirectory(tests)` is currently commented out in the top-level `CMakeLists.txt`**, so uncomment it before building or running tests.
+
+```bash
+ctest --test-dir build --output-on-failure             # all tests
+ctest --test-dir build -R 'DivTest'                    # subset (tests registered via gtest_discover_tests)
+./build/bin/cpp_lab_project_unit_test --gtest_filter='DivTest.InvalidNumbers'
+./scripts/gen_coverage_lcov.sh                         # or gen_coverage_gcovr.sh; CI uses -DENABLE_COVERAGE=ON
+```
+
+The test target compiles only the sources listed in `tests/CMakeLists.txt` (currently `src/DeleteMe.cpp`). Add any source under test to that list.
+
+## Static analysis & formatting
+
+CI (`.github/workflows/cpp-build-test-coverage.yml`, on push/PR to `master`, inside the `urboob21/cpp-lab:latest` Docker image) fails on cppcheck findings:
+
+```bash
+cppcheck --enable=warning,style,performance,portability --inconclusive --inline-suppr --quiet --error-exitcode=1 ./src ./include
+clang-tidy -p build -header-filter='^src/.*' $(find src -name "*.cpp")   # not enforced in CI
+clang-format -i <file>                                                     # Google-based style (.clang-format)
+```
+
+The `.clang-tidy` naming rules are lower_case variables and namespaces, CamelCase types, and a trailing `_` on class members. Code also uses `kName` for constants and enumerators.
+
+## Architecture: the example registry
+
+The main executable is a plugin-style registry that fills itself during static initialization:
+
+- `include/IExample.h` is the interface. It has `group()`, `name()`, `description()`, and `execute()`.
+- `include/ExampleRegistry.h` is a singleton map `group -> name -> factory`. The `REGISTER_EXAMPLE(Class)` macro at the bottom of each example `.cpp` defines a static registrar object that registers the class before `main` runs.
+- `src/main.cpp` only renders the menu from the registry. Groups are shown sorted, but examples inside a group follow `unordered_map` order, so menu numbers are unstable and piping choices into stdin is unreliable.
+
+**Adding an example:**
+1. Create a `.cpp` that puts its code in an anonymous namespace (often `namespace { namespace problem {...} namespace some_pattern {...} }`, each with its own `run()`).
+2. Define an `IExample` subclass and call `REGISTER_EXAMPLE(ThatClass);`.
+3. **Add the file to the module's source list** (`CORE_SOURCES`, `DP_SOURCES`, `SOCKET_SOURCES`, or `CONTROLLER_SOURCES` in `src/<module>/CMakeLists.txt`). There is no globbing, and a file missing from the list simply never shows up in the menu, with no error.
+
+Every module's sources link into the same `cpp_lab_project` binary. Keep helpers in anonymous namespaces and give the registered example class a unique name, because many files share names like `Array.cpp` and define their own `run()`. The `group()` string sets the menu category and doesn't always match the directory (for example, `function/operator_overloading/*` registers as `core/overloading_operator`).
+
+Use `LOG(msg)` / `LOG_S(a << b)` from `include/Logger.h` for output. Debug builds add a timestamp, file:line, and function; `NDEBUG` builds print plain lines. `version.h` is generated into `build/generated/` from `include/version.h.in`.
+
+## Docs
+
+`docs/README.md` indexes the per-module READMEs (`src/**/README.md`), which explain each topic and embed the draw.io UML diagrams from `docs/uml/`. When you add a design pattern example, update the matching README (and diagram if one exists).

From 00aabbfed898e8a42bf3ff6d3a3f2854c66299a0 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:25:52 +0700
Subject: [PATCH 08/20] Rewrite the lab around a self-registering example
 framework

Adding an example used to mean writing an IExample subclass, repeating the
group name, and remembering to add the file to a source list in CMake - a file
that was missing from the list simply never appeared in the menu. Menu entries
were also unordered, so the numbers changed between runs.

Framework (include/lab, src/lab):
- LAB_EXAMPLE("Name", "description" [, lab::kInteractive]) { ... } registers a
  file-local function before main() runs; the menu group is derived from the
  file's location, so ids like core/smart_pointer/Weak always match the tree.
- lab::Registry keeps examples sorted and rejects duplicate ids and invalid
  names instead of failing silently.
- Folder-style menu with search, plus a command line: --list, --run,
  --run-all, --list-ids, --plain, --mode, --version, --help.
- Logger gained LOG_FUNC/LOG_SECTION, colors only on a terminal, and a working
  Release build (the old release path could not compile LOG(string_view)).

Build:
- Example modules are globbed with CONFIGURE_DEPENDS, so no CMake edit is
  needed for a new example; OBJECT libraries keep the static registrations.
- Options: CPPLAB_BUILD_TESTS/DEMOS/GUI, CPPLAB_ENABLE_SANITIZERS,
  CPPLAB_WARNINGS_AS_ERRORS, ENABLE_COVERAGE. gtkmm-4.0 is now optional.
- Warnings, coverage and sanitizer flags moved to a cpplab::options target so
  they no longer apply to GoogleTest.
- One ctest smoke test per non-interactive example, discovered at test time.

Examples: all ~100 rewritten with a "what you will learn" header, sections,
fixed bugs (leaks in Command/Memento/Visitor, Builder's build() leaving a null
product, iterator vs nullptr comparison in UnorderedMap, wrong labels in
TemplateMethod, Dollars->Cents conversion, showpos demo, wcout/cout mixing,
a global set_terminate that stayed installed) and modern C++ (unique_ptr
ownership, ranges, concepts, std::format, jthread, variant). Examples no
longer execute undefined behavior or leave files behind, so the whole suite
passes under ASan/UBSan.

Sockets: TCPServer/TCPClient now report errno through std::system_error, close
their sockets exactly once, can stop a blocked accept(), and support port 0;
the new LoopbackEcho example runs a server thread and a client in one process.

Also: PID controller uses a unique_ptr pimpl and validates its parameters,
tests cover the framework, the PID and GoogleTest/GoogleMock usage, and the
GTK apps escape user text before building Pango markup.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 .clang-format                                 |   2 +-
 .clang-tidy                                   |   2 +-
 .cppcheck-suppressions                        |  53 ++
 .gitignore                                    |  27 +-
 CMakeLists.txt                                |  83 ++-
 cmake/CompilerOptions.cmake                   |  36 ++
 cmake/CppLab.cmake                            |  49 ++
 cmake/Dependencies.cmake                      |  57 +-
 cmake/DiscoverExampleTests.cmake              |  38 ++
 include/DeleteMe.h                            |  13 -
 include/ExampleRegistry.h                     |  45 --
 include/IExample.h                            |  12 -
 include/Logger.h                              |  89 ---
 include/lab/CommandLine.h                     |  45 ++
 include/lab/Example.h                         |  57 ++
 include/lab/Logger.h                          |  67 +++
 include/lab/Menu.h                            |  16 +
 include/lab/Registry.h                        |  80 +++
 include/lab/Runner.h                          |  19 +
 include/lab/version.h.in                      |  17 +
 include/version.h.in                          |   6 -
 src/CMakeLists.txt                            |  63 ++-
 src/DeleteMe.cpp                              |  32 --
 src/ap/CMakeLists.txt                         |  29 +-
 src/ap/README.md                              |   3 +
 src/ap/mvc/controller/Controller.cpp          |   5 +-
 src/ap/mvc/view/DisplayWidget.cpp             |   8 +-
 src/ap/mvc/view/DisplayWidget.h               |   2 +
 src/ap/mvc/view/EditorWidget.cpp              |   7 +-
 src/ap/mvc/view/EditorWidget.h                |   2 +-
 src/ap/mvvm/view/DisplayWidget.cpp            |   6 +-
 src/ap/mvvm/view/DisplayWidget.h              |   2 +
 src/ap/mvvm/view/EditorWidget.cpp             |   2 +
 src/ap/simple_ap.cpp                          |   5 +-
 src/controller/CMakeLists.txt                 |   8 -
 src/controller/README.md                      |  27 +
 src/controller/pid/PIDSim.cpp                 |  82 ++-
 src/controller/pid/pid.cpp                    | 142 ++---
 src/controller/pid/pid.h                      |  48 +-
 src/core/CMakeLists.txt                       | 113 ----
 src/core/basics/ControlFlow.cpp               | 189 +++----
 src/core/basics/Initialization.cpp            | 190 ++++---
 src/core/basics/Operations.cpp                | 207 ++++---
 src/core/basics/README.md                     |  43 ++
 src/core/basics/TypeQualifier.cpp             | 139 +++--
 src/core/class/Binding.cpp                    | 125 +++--
 src/core/class/Constructor.cpp                | 467 ++++++++--------
 src/core/class/Destructor.cpp                 | 156 ++++--
 src/core/class/Encapsulation.cpp              | 145 ++---
 src/core/class/Friend.cpp                     | 162 +++---
 src/core/class/README.md                      |  15 +
 src/core/class/Relationship.cpp               | 253 ++++++---
 src/core/class/RoleOfThreeFiveZero.cpp        | 290 ----------
 src/core/class/RuleOfThreeFiveZero.cpp        | 236 ++++++++
 src/core/class/SallowDeepCopying.cpp          | 167 ------
 src/core/class/ShallowDeepCopying.cpp         | 151 ++++++
 src/core/class/VirtualBase.cpp                | 149 +++--
 src/core/concurrency/ConditionVariable.cpp    | 174 ++++--
 src/core/concurrency/FuturePromise.cpp        | 176 +++---
 src/core/concurrency/README.md                |  44 ++
 src/core/concurrency/RaceCondition.cpp        | 147 ++---
 src/core/concurrency/SharingData.cpp          | 109 ++--
 src/core/concurrency/ThreadManagement.cpp     | 255 +++++----
 src/core/concurrency/Timing.cpp               |  83 ++-
 src/core/container/README.md                  |  27 +
 src/core/container/adapter/PriorityQueue.cpp  |  78 +++
 src/core/container/adapter/Queue.cpp          | 105 ++--
 src/core/container/adapter/Stack.cpp          | 114 ++--
 src/core/container/associative/Set.cpp        |  95 +++-
 src/core/container/sequence/Array.cpp         | 198 ++++---
 src/core/container/sequence/Deque.cpp         |  98 ++--
 src/core/container/sequence/Vector.cpp        | 170 ++++--
 src/core/container/unordered/UnorderedMap.cpp | 162 +++---
 src/core/datatype/Array.cpp                   | 102 +++-
 src/core/datatype/Enum.cpp                    | 146 +++--
 src/core/datatype/Fundamental.cpp             | 177 ++++--
 src/core/datatype/Pointer.cpp                 | 214 ++++----
 src/core/datatype/README.md                   |  46 ++
 src/core/datatype/Reference.cpp               | 179 +++---
 src/core/datatype/Struct.cpp                  | 145 +++--
 src/core/datatype/TypeConVersions.cpp         | 180 -------
 src/core/datatype/TypeConversions.cpp         | 178 ++++++
 src/core/datatype/Union.cpp                   | 150 ++++--
 src/core/datetime/README.md                   |   9 +
 src/core/datetime/Time.cpp                    | 110 ++--
 src/core/exception/BasicHandle.cpp            | 125 ++++-
 src/core/exception/README.md                  |  44 ++
 src/core/exception/ThrowNoexcept.cpp          | 132 +++--
 src/core/filehandle/BinaryFileHandling.cpp    | 213 ++++----
 src/core/filehandle/Directory.cpp             | 116 ++--
 src/core/filehandle/FileIO.cpp                | 181 +++----
 src/core/filehandle/IOStream.cpp              |  97 +++-
 src/core/filehandle/OutputFormatting.cpp      | 180 ++++---
 src/core/filehandle/README.md                 |  13 +
 src/core/filehandle/StringStream.cpp          | 121 +++--
 src/core/filehandle/TerminalColor.cpp         | 192 +++----
 src/core/function/FunctionPointer.cpp         | 161 ++++--
 src/core/function/Functional.cpp              | 147 +++--
 src/core/function/Lambda.cpp                  | 169 ++++--
 src/core/function/README.md                   |  52 ++
 .../AllocationOperator.cpp                    | 165 +++---
 .../ArithmeticOperator.cpp                    | 157 +++---
 .../AssignmentOperator.cpp                    | 110 ++--
 .../ClassMemberAccessOperator.cpp             | 127 +++--
 .../ComparisonOperator.cpp                    | 131 +++--
 .../FunctionCallOperator.cpp                  | 112 +++-
 .../operator_overloading/InDecOperator.cpp    | 120 +++--
 .../operator_overloading/StreamOperator.cpp   | 114 ++--
 .../SubscriptOperator.cpp                     | 109 +++-
 .../operator_overloading/TypeCast.cpp         |  97 ++--
 .../operator_overloading/UnaryOperator.cpp    |  85 ++-
 src/core/linkage/External.cpp                 |  23 +-
 src/core/linkage/External.h                   |  22 +-
 src/core/linkage/Internal.cpp                 |  34 +-
 src/core/linkage/Linkage.cpp                  |  94 ++--
 src/core/linkage/README.md                    |  39 ++
 src/core/linkage/sharing/Sharing.cpp          |  82 +--
 .../linkage/sharing/external/constants.cpp    |  18 +-
 src/core/linkage/sharing/external/constants.h |  24 +-
 src/core/linkage/sharing/inline/constants.h   |  24 +-
 src/core/linkage/sharing/internal/constants.h |  23 +-
 src/core/smart_pointer/README.md              |  39 ++
 src/core/smart_pointer/Shared.cpp             | 149 +++--
 src/core/smart_pointer/Unique.cpp             | 139 ++++-
 src/core/smart_pointer/Weak.cpp               | 141 +++--
 src/core/string/CString.cpp                   | 333 +++++-------
 src/core/string/README.md                     |  41 ++
 src/core/string/StdString.cpp                 | 327 +++++------
 src/core/string/StringFormatting.cpp          | 158 +++---
 src/core/utils/Algorithm.cpp                  | 169 ++++--
 src/core/utils/Optional.cpp                   | 189 +++----
 src/core/utils/README.md                      |  11 +
 src/core/utils/Regex.cpp                      | 136 +++--
 src/core/utils/TypeTrait.cpp                  | 119 ----
 src/core/utils/TypeTraits.cpp                 | 157 ++++++
 src/core/utils/Variadic.cpp                   | 184 ++++---
 src/demo/dlopen/CMakeLists.txt                |  33 +-
 src/demo/dlopen/README.md                     |  61 ++-
 src/demo/dlopen/main.cpp                      |  64 ++-
 src/demo/dlopen/sample_app.cpp                |  18 +-
 src/dp/CMakeLists.txt                         |  32 --
 src/dp/behavioral/ChainOfCommand.cpp          | 147 -----
 src/dp/behavioral/ChainOfResponsibility.cpp   | 125 +++++
 src/dp/behavioral/Command.cpp                 | 246 +++++----
 src/dp/behavioral/Iterator.cpp                | 300 +++++------
 src/dp/behavioral/Mediator.cpp                | 255 ++++-----
 src/dp/behavioral/Memento.cpp                 | 287 ++++------
 src/dp/behavioral/Observer.cpp                | 293 +++++-----
 src/dp/behavioral/README.md                   |   4 +
 src/dp/behavioral/State.cpp                   | 200 ++++---
 src/dp/behavioral/Strategy.cpp                | 197 ++++---
 src/dp/behavioral/TemplateMethod.cpp          | 183 +++----
 src/dp/behavioral/Visitor.cpp                 | 369 ++++++-------
 src/dp/creational/AbstractFactory.cpp         | 204 +++----
 src/dp/creational/Builder.cpp                 | 278 ++++++----
 src/dp/creational/FactoryMethod.cpp           | 180 +++----
 src/dp/creational/Prototype.cpp               | 174 +++---
 src/dp/creational/README.md                   |   3 +
 src/dp/creational/Singleton.cpp               | 131 +++--
 src/dp/structural/Adapter.cpp                 | 213 ++++----
 src/dp/structural/Bridge.cpp                  | 235 ++++----
 src/dp/structural/Composite.cpp               | 508 ++++--------------
 src/dp/structural/Decorator.cpp               | 201 +++----
 src/dp/structural/Facade.cpp                  | 329 ++++--------
 src/dp/structural/Flyweight.cpp               | 432 +++++----------
 src/dp/structural/Proxy.cpp                   | 199 +++----
 src/dp/structural/README.md                   |   3 +
 src/embedded/startup.c                        |   2 +-
 src/lab/CMakeLists.txt                        |  37 ++
 src/lab/CommandLine.cpp                       | 171 ++++++
 src/lab/Logger.cpp                            | 108 ++++
 src/lab/Menu.cpp                              | 255 +++++++++
 src/lab/Registry.cpp                          | 166 ++++++
 src/lab/Runner.cpp                            |  89 +++
 src/main.cpp                                  | 296 +++++-----
 src/socket/CMakeLists.txt                     |  11 -
 src/socket/README.md                          |  15 +
 src/socket/multiple_client/MultiTCPServer.cpp | 115 ++--
 src/socket/multiple_client/MultiTCPServer.h   |  31 +-
 src/socket/simple_tcp/LoopbackEcho.cpp        |  61 +++
 src/socket/simple_tcp/SimpleTCPClient.cpp     |  86 +--
 src/socket/simple_tcp/SimpleTCPServer.cpp     |  59 +-
 src/socket/simple_tcp/TCPClient.cpp           | 121 +++--
 src/socket/simple_tcp/TCPClient.h             |  40 +-
 src/socket/simple_tcp/TCPServer.cpp           | 310 ++++++-----
 src/socket/simple_tcp/TCPServer.h             |  87 +--
 tests/CMakeLists.txt                          |  65 +--
 tests/DeleteMeTest.cpp                        |  99 ----
 tests/README.md                               |  18 +
 tests/controller/PidTest.cpp                  |  47 ++
 tests/gtest_primer/Calculator.h               |  30 ++
 tests/gtest_primer/CalculatorTest.cpp         |  65 +++
 tests/gtest_primer/TurtleMockTest.cpp         |  66 +++
 tests/lab/CommandLineTest.cpp                 |  93 ++++
 tests/lab/MenuRunnerTest.cpp                  | 108 ++++
 tests/lab/RegistryTest.cpp                    | 129 +++++
 tests/mock/MockTurtle.h                       |  11 +-
 tests/mock/Painter.h                          |   9 +-
 tests/mock/Turtle.h                           |   5 +-
 199 files changed, 13242 insertions(+), 9566 deletions(-)
 create mode 100644 .cppcheck-suppressions
 create mode 100644 cmake/CompilerOptions.cmake
 create mode 100644 cmake/CppLab.cmake
 create mode 100644 cmake/DiscoverExampleTests.cmake
 delete mode 100644 include/DeleteMe.h
 delete mode 100644 include/ExampleRegistry.h
 delete mode 100644 include/IExample.h
 delete mode 100644 include/Logger.h
 create mode 100644 include/lab/CommandLine.h
 create mode 100644 include/lab/Example.h
 create mode 100644 include/lab/Logger.h
 create mode 100644 include/lab/Menu.h
 create mode 100644 include/lab/Registry.h
 create mode 100644 include/lab/Runner.h
 create mode 100644 include/lab/version.h.in
 delete mode 100644 include/version.h.in
 delete mode 100644 src/DeleteMe.cpp
 delete mode 100644 src/controller/CMakeLists.txt
 create mode 100644 src/controller/README.md
 delete mode 100644 src/core/CMakeLists.txt
 create mode 100644 src/core/basics/README.md
 delete mode 100644 src/core/class/RoleOfThreeFiveZero.cpp
 create mode 100644 src/core/class/RuleOfThreeFiveZero.cpp
 delete mode 100644 src/core/class/SallowDeepCopying.cpp
 create mode 100644 src/core/class/ShallowDeepCopying.cpp
 create mode 100644 src/core/concurrency/README.md
 create mode 100644 src/core/container/adapter/PriorityQueue.cpp
 create mode 100644 src/core/datatype/README.md
 delete mode 100644 src/core/datatype/TypeConVersions.cpp
 create mode 100644 src/core/datatype/TypeConversions.cpp
 create mode 100644 src/core/exception/README.md
 create mode 100644 src/core/function/README.md
 create mode 100644 src/core/linkage/README.md
 create mode 100644 src/core/smart_pointer/README.md
 create mode 100644 src/core/string/README.md
 delete mode 100644 src/core/utils/TypeTrait.cpp
 create mode 100644 src/core/utils/TypeTraits.cpp
 delete mode 100644 src/dp/CMakeLists.txt
 delete mode 100644 src/dp/behavioral/ChainOfCommand.cpp
 create mode 100644 src/dp/behavioral/ChainOfResponsibility.cpp
 create mode 100644 src/lab/CMakeLists.txt
 create mode 100644 src/lab/CommandLine.cpp
 create mode 100644 src/lab/Logger.cpp
 create mode 100644 src/lab/Menu.cpp
 create mode 100644 src/lab/Registry.cpp
 create mode 100644 src/lab/Runner.cpp
 delete mode 100644 src/socket/CMakeLists.txt
 create mode 100644 src/socket/simple_tcp/LoopbackEcho.cpp
 delete mode 100644 tests/DeleteMeTest.cpp
 create mode 100644 tests/controller/PidTest.cpp
 create mode 100644 tests/gtest_primer/Calculator.h
 create mode 100644 tests/gtest_primer/CalculatorTest.cpp
 create mode 100644 tests/gtest_primer/TurtleMockTest.cpp
 create mode 100644 tests/lab/CommandLineTest.cpp
 create mode 100644 tests/lab/MenuRunnerTest.cpp
 create mode 100644 tests/lab/RegistryTest.cpp

diff --git a/.clang-format b/.clang-format
index dc69733..274fb98 100644
--- a/.clang-format
+++ b/.clang-format
@@ -78,6 +78,6 @@ SpacesInCStyleCastParentheses: false
 SpacesInContainerLiterals: false
 SpacesInParentheses: false
 SpacesInSquareBrackets: false
-Standard: c++11
+Standard: c++20
 TabWidth: 4
 UseTab: Never
\ No newline at end of file
diff --git a/.clang-tidy b/.clang-tidy
index da93ae8..e010fe1 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -120,7 +120,7 @@ Checks: >
 # Turn all the warnings from the checks above into errors.
 WarningsAsErrors: "*"
 
-HeaderFilterRegex: "(google/cloud/|generator/).*\\.h$"
+HeaderFilterRegex: "(include/lab|src|tests)/.*\\.h$"
 
 CheckOptions:
   - { key: readability-identifier-naming.NamespaceCase,          value: lower_case }
diff --git a/.cppcheck-suppressions b/.cppcheck-suppressions
new file mode 100644
index 0000000..41fd99d
--- /dev/null
+++ b/.cppcheck-suppressions
@@ -0,0 +1,53 @@
+# cppcheck suppressions for cpp-lab
+
+#   cppcheck --suppressions-list=.cppcheck-suppressions ... ./src ./include
+
+# Format: <id> or <id>:<file> or <id>:<file>:<line>
+
+# --- checks that are noise in teaching code ---------------------------------
+# Example classes keep their member functions non-static so the examples read
+# like ordinary code.
+functionStatic
+# Explicit loops are often the point of an example; the algorithm version is
+# shown where it is the lesson (see core/utils/Algorithm).
+useStlAlgorithm
+
+# --- intentional demonstrations ---------------------------------------------
+# "the condition is always true/false" is exactly what these examples show
+knownConditionTrueFalse:src/core/datatype/Fundamental.cpp
+knownConditionTrueFalse:src/core/datatype/Reference.cpp
+knownConditionTrueFalse:src/core/datatype/TypeConversions.cpp
+knownConditionTrueFalse:src/core/string/StdString.cpp
+knownConditionTrueFalse:src/core/utils/Optional.cpp
+knownConditionTrueFalse:src/dp/structural/Adapter.cpp
+# pointer/reference rebinding and re-assignment shown on purpose
+redundantInitialization:src/core/datatype/Pointer.cpp
+redundantAssignment:src/core/function/operator_overloading/AssignmentOperator.cpp
+unreadVariable:src/core/datatype/TypeConversions.cpp
+constVariableReference:src/core/datatype/Array.cpp
+# at(3) must throw here, that is the lesson
+containerOutOfBounds:src/core/container/sequence/Array.cpp
+# std::deque guarantees that references survive push_front/push_back
+invalidContainerReference:src/core/container/sequence/Deque.cpp
+# placement new constructs into deliberately raw storage
+legacyUninitvar:src/core/function/operator_overloading/AllocationOperator.cpp
+# the null check after a move is the point of the example
+nullPointerRedundantCheck:src/core/smart_pointer/Unique.cpp
+accessMoved:src/core/class/Constructor.cpp
+accessMoved:src/core/class/RuleOfThreeFiveZero.cpp
+accessMoved:src/core/datatype/Reference.cpp
+# classes that show what the compiler generates for them
+noCopyConstructor:src/core/class/RuleOfThreeFiveZero.cpp
+noOperatorEq:src/core/class/RuleOfThreeFiveZero.cpp
+noCopyConstructor:src/core/class/ShallowDeepCopying.cpp
+noOperatorEq:src/core/class/ShallowDeepCopying.cpp
+noExplicitConstructor:src/core/class/Constructor.cpp
+duplInheritedMember:src/core/class/Binding.cpp
+virtualCallInConstructor:src/core/class/Binding.cpp
+postfixOperator:src/core/function/operator_overloading/InDecOperator.cpp
+# writing raw doubles is what binary file I/O looks like
+invalidPointerCast:src/core/filehandle/BinaryFileHandling.cpp
+# the plugin entry point must have main's signature
+constParameter:src/demo/dlopen/sample_app.cpp
+# startup code compares the linker-provided section symbols
+comparePointers:src/embedded/startup.c
diff --git a/.gitignore b/.gitignore
index 5577478..34b72fe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,12 +1,21 @@
-*build
-*private*
-.vscode/
+# Build directories (build/, build-asan/, build-release/, src/embedded/build/, ...)
+build/
+build-*/
+
+# Coverage reports (scripts/gen_coverage_*.sh)
+coverage_gcovr/
+coverage_lcov/
+
+# CTest output when ctest runs from the repository root
+Testing/
+
+# Local-only files
+/private/
+.cache/
+__pycache__/
 *Identifier
-*Testing*
-coverage_gcovr
-coverage_lcov
+
+# Editor settings: keep the shared VS Code launch and task configurations
+.vscode/*
 !.vscode/launch.json
 !.vscode/tasks.json
-.cache
-__pycache__/
-*Testing*
\ No newline at end of file
diff --git a/CMakeLists.txt b/CMakeLists.txt
index f7cc84f..e225b94 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,65 +1,60 @@
-cmake_minimum_required(VERSION 3.14)
+cmake_minimum_required(VERSION 3.16)
 
 # Project metadata
 project(cpp_lab_project # ${PROJECT_NAME}
     VERSION 1.0.0
-    DESCRIPTION "A C/C++ project uses CMake, GoogleTest, gcc, g++, cppcheck, and lcov, integrated with Docker and GitHub Actions for CI/CD."
+    DESCRIPTION "A C/C++ learning lab built with CMake, GoogleTest, gcc/g++, cppcheck and lcov, integrated with Docker and GitHub Actions for CI/CD."
     LANGUAGES CXX
 )
 
-# Output directories to build/bin
-# Executables
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
-# Shared libraries
-set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-# Static libraries
-set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-
-# Compiler and language configuration
-# Require at least C++17 for GoogleTest and modern C++ features
+list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+
+# ----------------------------------------------------------------------------------------
+# Options (pass with -D<OPTION>=<VALUE>)
+# ----------------------------------------------------------------------------------------
+option(CPPLAB_BUILD_TESTS "Build the unit tests and register one smoke test per example" ON)
+option(CPPLAB_BUILD_DEMOS "Build the standalone demos in src/demo" ON)
+set(CPPLAB_BUILD_GUI "AUTO" CACHE STRING "Build the GTK4 apps in src/ap: AUTO (if gtkmm-4.0 is found), ON or OFF")
+set_property(CACHE CPPLAB_BUILD_GUI PROPERTY STRINGS AUTO ON OFF)
+option(ENABLE_COVERAGE "Enable coverage reporting (gcc/clang)" OFF)
+option(CPPLAB_ENABLE_SANITIZERS "Build with AddressSanitizer and UndefinedBehaviorSanitizer" OFF)
+option(CPPLAB_WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
+
+# ----------------------------------------------------------------------------------------
+# Global build settings
+# ----------------------------------------------------------------------------------------
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
 
 # Export compile_commands.json (useful for clang-tidy, clangd, IDEs)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
-# Build metadata
-# Ensure directory exists for generated headers
-file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/generated)
-
-# Generate build timestamp
-string(TIMESTAMP BUILD_TIME "%Y-%m-%d %H:%M:%S")
-
-# Generate version header from template
-configure_file(
-    ${CMAKE_SOURCE_DIR}/include/version.h.in
-    ${CMAKE_BINARY_DIR}/generated/version.h
-)
-
-# External dependencies (GoogleTest,...)
-include(cmake/Dependencies.cmake)
-
-# Compiler warnings (useful for learning/debugging)
-add_compile_options(-Wall -Wextra -Wpedantic)
+# Default to a Debug build: debug info, assertions and log prefixes enabled
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+    set(CMAKE_BUILD_TYPE Debug CACHE STRING "Build type" FORCE)
+endif()
 
-message(STATUS "C Compiler: ${CMAKE_C_COMPILER}")
-message(STATUS "C++ Compiler: ${CMAKE_CXX_COMPILER}")
-message(STATUS "C++ Compiler ID: ${CMAKE_CXX_COMPILER_ID}")
-message(STATUS "C++ Compiler Version: ${CMAKE_CXX_COMPILER_VERSION}")
+# Output directories: executables in build/bin, libraries in build/lib
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 
-# Code coverage configuration
-option(ENABLE_COVERAGE "Enable coverage reporting" OFF)
+message(STATUS "C++ Compiler: ${CMAKE_CXX_COMPILER} (${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION})")
+message(STATUS "Build type  : ${CMAKE_BUILD_TYPE}")
 
-if(ENABLE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
-    message(STATUS "Enabling coverage flags")
-    add_compile_options(--coverage -O0 -g)
-    add_link_options(--coverage)
-endif()
+include(CompilerOptions)  # cpplab::options - warnings, coverage, sanitizers
+include(Dependencies)     # Threads, GoogleTest, gtkmm-4.0
+include(CppLab)           # cpplab_add_example_module(), cpplab_discover_example_tests()
 
-# Enable CTest framework (used by GoogleTest)
+# Enable CTest (unit tests + example smoke tests)
 enable_testing()
 
-# Add project modules
+# ----------------------------------------------------------------------------------------
+# Project modules
+# ----------------------------------------------------------------------------------------
 add_subdirectory(src)
 
-# add_subdirectory(tests)
\ No newline at end of file
+if(CPPLAB_BUILD_TESTS)
+    add_subdirectory(tests)
+endif()
diff --git a/cmake/CompilerOptions.cmake b/cmake/CompilerOptions.cmake
new file mode 100644
index 0000000..7cbed63
--- /dev/null
+++ b/cmake/CompilerOptions.cmake
@@ -0,0 +1,36 @@
+# ----------------------------------------------------------------------------------------
+# cpplab::options - compile/link settings shared by every target of the project.
+# Link it instead of using add_compile_options() so third-party code (GoogleTest) is not
+# affected by our warnings, coverage or sanitizer flags.
+# ----------------------------------------------------------------------------------------
+
+add_library(cpplab_options INTERFACE)
+add_library(cpplab::options ALIAS cpplab_options)
+
+target_compile_features(cpplab_options INTERFACE cxx_std_20)
+
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    # Compiler warnings (useful for learning/debugging)
+    target_compile_options(cpplab_options INTERFACE -Wall -Wextra -Wpedantic)
+
+    if(CPPLAB_WARNINGS_AS_ERRORS)
+        target_compile_options(cpplab_options INTERFACE -Werror)
+    endif()
+
+    # Code coverage configuration (see scripts/gen_coverage_*.sh)
+    if(ENABLE_COVERAGE)
+        message(STATUS "Enabling coverage flags")
+        target_compile_options(cpplab_options INTERFACE --coverage -O0 -g)
+        target_link_options(cpplab_options INTERFACE --coverage)
+    endif()
+
+    # Sanitizers catch memory errors and undefined behavior at run time:
+    #   cmake -S . -B build-asan -DCPPLAB_ENABLE_SANITIZERS=ON
+    #   cmake --build build-asan && ./build-asan/bin/cpp_lab_project --run-all
+    if(CPPLAB_ENABLE_SANITIZERS)
+        message(STATUS "Enabling AddressSanitizer + UndefinedBehaviorSanitizer")
+        target_compile_options(cpplab_options INTERFACE
+            -fsanitize=address,undefined -fno-omit-frame-pointer -fno-sanitize-recover=undefined)
+        target_link_options(cpplab_options INTERFACE -fsanitize=address,undefined)
+    endif()
+endif()
diff --git a/cmake/CppLab.cmake b/cmake/CppLab.cmake
new file mode 100644
index 0000000..ae321e3
--- /dev/null
+++ b/cmake/CppLab.cmake
@@ -0,0 +1,49 @@
+# ----------------------------------------------------------------------------------------
+# Helpers to build the example modules
+# ----------------------------------------------------------------------------------------
+
+# cpplab_add_example_module(<directory>)
+#
+# Compiles every .cpp file below <directory> (relative to the current CMakeLists.txt) into
+# an OBJECT library and appends the target to CPPLAB_EXAMPLE_TARGETS in the caller's scope.
+#
+# There is no list of files to maintain: a new example is picked up automatically the next
+# time you build (CONFIGURE_DEPENDS re-runs the glob when files are added or removed).
+#
+# OBJECT libraries are used on purpose: examples are only referenced through static
+# registration objects, and a STATIC library would let the linker drop those objects.
+function(cpplab_add_example_module directory)
+    file(GLOB_RECURSE sources CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/${directory}/*.cpp"
+    )
+    if(NOT sources)
+        message(WARNING "Example module '${directory}' contains no .cpp files")
+        return()
+    endif()
+
+    string(MAKE_C_IDENTIFIER "cpplab_examples_${directory}" target)
+    add_library(${target} OBJECT ${sources})
+    target_link_libraries(${target} PUBLIC cpplab::lab)
+
+    set(CPPLAB_EXAMPLE_TARGETS ${CPPLAB_EXAMPLE_TARGETS} ${target} PARENT_SCOPE)
+endfunction()
+
+# cpplab_discover_example_tests(<executable>)
+#
+# Registers one ctest test per non-interactive example ("example:<id>"). The list is
+# queried from the executable (--list-ids) each time ctest runs, like
+# gtest_discover_tests(), so new examples need no CMake changes.
+#
+#   ctest --test-dir build -L example            # all example smoke tests
+#   ctest --test-dir build -R example:dp/        # only the design patterns
+function(cpplab_discover_example_tests executable)
+    set(include_file "${CMAKE_CURRENT_BINARY_DIR}/${executable}_example_tests.cmake")
+    file(GENERATE
+        OUTPUT "${include_file}"
+        CONTENT "set(CPPLAB_EXECUTABLE \"$<TARGET_FILE:${executable}>\")
+set(CPPLAB_TEST_WORKING_DIRECTORY \"${CMAKE_BINARY_DIR}\")
+include(\"${PROJECT_SOURCE_DIR}/cmake/DiscoverExampleTests.cmake\")
+"
+    )
+    set_property(DIRECTORY APPEND PROPERTY TEST_INCLUDE_FILES "${include_file}")
+endfunction()
diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake
index ef689cc..f0e5dd5 100644
--- a/cmake/Dependencies.cmake
+++ b/cmake/Dependencies.cmake
@@ -1,25 +1,52 @@
+# ----------------------------------------------------------------------------------------
+# Dependencies - Threads (std::thread on POSIX)
+# ----------------------------------------------------------------------------------------
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_package(Threads REQUIRED)
 
 # ----------------------------------------------------------------------------------------
-# Dependencies - GoogleTest
+# Dependencies - GoogleTest (only needed for the unit tests)
 # ----------------------------------------------------------------------------------------
-# FetchContent allows downloading dependencies at configure time
-include(FetchContent)
+if(CPPLAB_BUILD_TESTS)
+    # FetchContent allows downloading dependencies at configure time
+    include(FetchContent)
 
-# Declare GoogleTest dependency
-FetchContent_Declare(
-    googletest
-    URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
-)
+    if(POLICY CMP0135)
+        cmake_policy(SET CMP0135 NEW)  # use the extraction time as file timestamps
+    endif()
 
-# Make GoogleTest available
-FetchContent_MakeAvailable(googletest)
+    # Declare GoogleTest dependency (pinned commit for reproducible builds)
+    FetchContent_Declare(
+        googletest
+        URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
+    )
 
+    set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
+
+    # Make GoogleTest available
+    FetchContent_MakeAvailable(googletest)
+endif()
 
 # ----------------------------------------------------------------------------------------
-# Dependencies - GTK4
+# Dependencies - GTK4 / gtkmm-4.0 (optional, only for the apps in src/ap)
 # ----------------------------------------------------------------------------------------
-# Use the package PkgConfig to detect GTK+ headers/library files
-find_package(PkgConfig REQUIRED)
+set(CPPLAB_GUI_ENABLED OFF)
+
+if(NOT CPPLAB_BUILD_GUI STREQUAL "OFF")
+    # Use the package PkgConfig to detect GTK+ headers/library files
+    find_package(PkgConfig QUIET)
+    if(PkgConfig_FOUND)
+        # Check for gtkmm-4.0 specifically, not just gtk4
+        pkg_check_modules(GTKMM QUIET IMPORTED_TARGET gtkmm-4.0)
+    endif()
 
-# Check for gtkmm-4.0 specifically, not just gtk4
-pkg_check_modules(GTKMM REQUIRED gtkmm-4.0)
+    if(GTKMM_FOUND)
+        set(CPPLAB_GUI_ENABLED ON)
+        message(STATUS "gtkmm-4.0 ${GTKMM_VERSION} found: building the GUI apps in src/ap")
+    elseif(CPPLAB_BUILD_GUI STREQUAL "ON")
+        message(FATAL_ERROR "CPPLAB_BUILD_GUI=ON but gtkmm-4.0 was not found. "
+                            "Install it with: sudo apt install libgtkmm-4.0-dev")
+    else()
+        message(STATUS "gtkmm-4.0 not found: skipping the GUI apps in src/ap")
+    endif()
+endif()
diff --git a/cmake/DiscoverExampleTests.cmake b/cmake/DiscoverExampleTests.cmake
new file mode 100644
index 0000000..bff146b
--- /dev/null
+++ b/cmake/DiscoverExampleTests.cmake
@@ -0,0 +1,38 @@
+# ----------------------------------------------------------------------------------------
+# Executed by ctest (not by cmake): asks the lab executable for the ids of all
+# non-interactive examples and registers one smoke test per example.
+#
+# Expected variables (set by cpplab_discover_example_tests()):
+#   CPPLAB_EXECUTABLE              path of cpp_lab_project
+#   CPPLAB_TEST_WORKING_DIRECTORY  working directory of the tests
+# ----------------------------------------------------------------------------------------
+
+if(EXISTS "${CPPLAB_EXECUTABLE}")
+    execute_process(
+        COMMAND "${CPPLAB_EXECUTABLE}" --list-ids
+        OUTPUT_VARIABLE example_ids
+        ERROR_VARIABLE discovery_error
+        RESULT_VARIABLE discovery_result
+    )
+else()
+    set(discovery_result "executable not found (build the project first)")
+endif()
+
+if(NOT discovery_result EQUAL 0)
+    # Surface the problem as a failing test instead of silently running nothing.
+    add_test(example:discovery "${CPPLAB_EXECUTABLE}" --list-ids)
+    set_tests_properties(example:discovery PROPERTIES LABELS "example")
+    message(WARNING "Example discovery failed: ${discovery_result} ${discovery_error}")
+else()
+    string(REPLACE "\n" ";" example_ids "${example_ids}")
+    foreach(example_id IN LISTS example_ids)
+        if(example_id)
+            add_test("example:${example_id}" "${CPPLAB_EXECUTABLE}" --plain --run "${example_id}")
+            set_tests_properties("example:${example_id}" PROPERTIES
+                LABELS "example"
+                TIMEOUT 60
+                WORKING_DIRECTORY "${CPPLAB_TEST_WORKING_DIRECTORY}"
+            )
+        endif()
+    endforeach()
+endif()
diff --git a/include/DeleteMe.h b/include/DeleteMe.h
deleted file mode 100644
index 5d1f603..0000000
--- a/include/DeleteMe.h
+++ /dev/null
@@ -1,13 +0,0 @@
-#pragma once
-class DeleteMe {
- private:
-  int m_lastResult;
-
- public:
-  DeleteMe();
-  ~DeleteMe();
-  bool add(int addend1, int addend2);
-  bool mul(int factor1, int factor2);
-  bool div(int dividend, int divisor);
-  int get_last_result();
-};
diff --git a/include/ExampleRegistry.h b/include/ExampleRegistry.h
deleted file mode 100644
index 5c843ad..0000000
--- a/include/ExampleRegistry.h
+++ /dev/null
@@ -1,45 +0,0 @@
-#pragma once
-#include <functional>
-#include <memory>
-#include <unordered_map>
-#include "IExample.h"
-
-#define REGISTER_EXAMPLE(CLASS)                        \
-  namespace {                                          \
-  struct CLASS##Registrar {                            \
-    CLASS##Registrar() {                               \
-      auto obj = std::make_unique<CLASS>();            \
-      ExampleRegistry::instance().registerExample(     \
-          obj->group(), obj->name(),                   \
-          []() { return std::make_unique<CLASS>(); }); \
-    }                                                  \
-  };                                                   \
-  static CLASS##Registrar global_##CLASS##Registrar;   \
-  }
-
-class ExampleRegistry {
- public:
-  using Factory = std::function<std::unique_ptr<IExample>()>;
-
-  static ExampleRegistry& instance() {
-    static ExampleRegistry inst;
-    return inst;
-  }
-
-  void registerExample(const std::string& group, const std::string& name,
-                       Factory factory) {
-    registry_[group][name] = std::move(factory);
-  }
-
-  const auto& getAll() const { return registry_; }
-
-  std::unique_ptr<IExample> create(const std::string& group,
-                                   const std::string& name) {
-
-    return registry_.at(group).at(name)();
-  }
-
- private:
-  std::unordered_map<std::string, std::unordered_map<std::string, Factory>>
-      registry_;
-};
diff --git a/include/IExample.h b/include/IExample.h
deleted file mode 100644
index eeaf027..0000000
--- a/include/IExample.h
+++ /dev/null
@@ -1,12 +0,0 @@
-#pragma once
-#include <string>
-class IExample {
- public:
-  virtual ~IExample() = default;
-
-  virtual std::string group() const = 0;
-  virtual std::string name() const = 0;
-  virtual std::string description() const = 0;
-
-  virtual void execute() = 0;
-};
\ No newline at end of file
diff --git a/include/Logger.h b/include/Logger.h
deleted file mode 100644
index 3f6614c..0000000
--- a/include/Logger.h
+++ /dev/null
@@ -1,89 +0,0 @@
-#ifndef LOGGER_H_
-#define LOGGER_H_
-
-#include <iostream>
-#include <sstream>
-
-#ifndef NDEBUG
-#include <mutex>
-#include <source_location>
-#include <string_view>
-
-class Logger {
- public:
-  static Logger& instance() {
-    static Logger logger;  // guaranteed single instance, thread-safe in C++11+
-    return logger;
-  }
-
-  void log(std::string_view msg, std::string_view level = "INFO",
-           std::source_location loc = std::source_location::current()) {
-    std::lock_guard<std::mutex> lock(mutex_);
-
-    // Extract filename only (no full path)
-    std::string_view file = loc.file_name();
-    auto pos = file.find_last_of("/\\");
-    if (pos != std::string_view::npos) {
-      file = file.substr(pos + 1);
-    }
-
-    // Get current time
-    auto now = std::chrono::system_clock::now();
-    auto t = std::chrono::system_clock::to_time_t(now);
-    std::tm tm{};
-    localtime_r(&t, &tm);
-
-    char time_buf[9];
-    std::strftime(time_buf, sizeof(time_buf), "%H:%M:%S", &tm);
-
-    constexpr const char* kGreen = "\033[32m";
-    constexpr const char* kReset = "\033[0m";
-
-    std::cout << "[" << time_buf << "]" << "[" << level << "]" << "[" << file
-              << ":" << loc.line() << "]" << "[" << loc.function_name() << "] "
-              << kGreen << msg << kReset << '\n';
-  }
-
-  // Prevent copies
-  Logger(const Logger&) = delete;
-  Logger& operator=(const Logger&) = delete;
-
- private:
-  Logger() = default;
-  std::mutex mutex_;
-};
-
-#define LOG(msg) Logger::instance().log(msg)
-
-#define LOG_S(expr)                       \
-  do {                                    \
-    std::ostringstream oss_;              \
-    oss_ << expr;                         \
-    std::string s_ = oss_.str();          \
-    if (!s_.empty() && s_.back() == '\n') \
-      s_.pop_back();                      \
-    Logger::instance().log(s_);           \
-  } while (0)
-
-#else
-
-inline void LOG(const std::string& msg) {
-  std::cout << msg << '\n';
-}
-
-inline void LOG_S_IMPL(std::ostringstream& oss) {
-  std::string s = oss.str();
-  if (!s.empty() && s.back() == '\n')
-    s.pop_back();
-  std::cout << s << '\n';
-}
-
-#define LOG_S(expr)          \
-  do {                       \
-    std::ostringstream oss_; \
-    oss_ << expr;            \
-    LOG_S_IMPL(oss_);        \
-  } while (0)
-
-#endif
-#endif
\ No newline at end of file
diff --git a/include/lab/CommandLine.h b/include/lab/CommandLine.h
new file mode 100644
index 0000000..2878b72
--- /dev/null
+++ b/include/lab/CommandLine.h
@@ -0,0 +1,45 @@
+#pragma once
+
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace lab {
+
+enum class Command {
+  kMenu,     ///< interactive menu (default)
+  kList,     ///< --list [filter]
+  kListIds,  ///< --list-ids [filter]
+  kRun,      ///< --run <id|filter>
+  kRunAll,   ///< --run-all [filter]
+  kHelp,     ///< --help
+  kVersion,  ///< --version
+};
+
+enum class AppMode { kDev, kUat, kProd };
+
+struct CommandLine {
+  Command command{Command::kMenu};
+  std::string argument;  ///< example id or filter, depending on the command
+  bool plain{false};     ///< no log prefixes, no colors
+  AppMode mode{AppMode::kDev};
+};
+
+struct ParseResult {
+  std::optional<CommandLine> value;  ///< set on success
+  std::string error;                 ///< set on failure
+};
+
+/// Parses the program arguments (without argv[0]).
+ParseResult parseCommandLine(const std::vector<std::string_view>& args);
+
+/// Help text for `--help`.
+std::string usage(std::string_view program);
+
+std::string_view toString(AppMode mode);
+
+/// Accepts "dev", "uat" and "prod" (case-insensitive).
+std::optional<AppMode> parseAppMode(std::string_view text);
+
+}  // namespace lab
diff --git a/include/lab/Example.h b/include/lab/Example.h
new file mode 100644
index 0000000..426f9b3
--- /dev/null
+++ b/include/lab/Example.h
@@ -0,0 +1,57 @@
+#pragma once
+
+// -----------------------------------------------------------------------------
+// LAB_EXAMPLE: declare a runnable example in a single line.
+//
+//   #include "lab/Example.h"
+//   #include "lab/Logger.h"
+//
+//   namespace {
+//   void demo() { LOG("Hello from the lab"); }
+//   }  // namespace
+//
+//   LAB_EXAMPLE("Hello", "Prints a greeting") { demo(); }
+//
+// - The menu group comes from the file location: an example defined in
+//   src/core/smart_pointer/Weak.cpp is listed as "core/smart_pointer/<name>".
+// - The name must be unique inside its folder and contain no spaces or '/'.
+// - Pass lab::kInteractive as a third argument for examples that read stdin,
+//   wait for a network peer or never return. They are skipped by --run-all
+//   and by the ctest smoke tests:
+//
+//   LAB_EXAMPLE("EchoServer", "TCP echo server on port 8080", lab::kInteractive)
+//   { ... }
+//
+// How it works: the macro declares a file-local function, registers its
+// address in lab::Registry from a static initializer (which runs before
+// main()), and then lets the braces that follow become the function body.
+// See docs/adding-examples.md.
+// -----------------------------------------------------------------------------
+
+#include "lab/Registry.h"  // IWYU pragma: export
+
+namespace lab::detail {
+
+// Turn the optional third macro argument into flags:
+// flags() for LAB_EXAMPLE(name, description), flags(value) otherwise.
+constexpr unsigned flags() noexcept {
+  return kNone;
+}
+constexpr unsigned flags(unsigned value) noexcept {
+  return value;
+}
+
+}  // namespace lab::detail
+
+#define LAB_DETAIL_CONCAT_IMPL(a, b) a##b
+#define LAB_DETAIL_CONCAT(a, b) LAB_DETAIL_CONCAT_IMPL(a, b)
+
+#define LAB_EXAMPLE(name, description, ...)                               \
+  LAB_DETAIL_EXAMPLE(LAB_DETAIL_CONCAT(lab_example_, __COUNTER__), name, \
+                     description, ::lab::detail::flags(__VA_ARGS__))
+
+#define LAB_DETAIL_EXAMPLE(function, name, description, flags)                    \
+  static void function();                                                         \
+  [[maybe_unused]] static const bool LAB_DETAIL_CONCAT(function, _registered) =   \
+      ::lab::Registry::instance().add(__FILE__, name, description, &function, flags); \
+  static void function()
diff --git a/include/lab/Logger.h b/include/lab/Logger.h
new file mode 100644
index 0000000..1cda0bb
--- /dev/null
+++ b/include/lab/Logger.h
@@ -0,0 +1,67 @@
+#pragma once
+
+#include <atomic>
+#include <mutex>
+#include <source_location>
+#include <sstream>  // IWYU pragma: keep (used by LOG_S)
+#include <string_view>
+
+namespace lab {
+
+/// Thread-safe line logger used by the examples.
+///
+/// Debug builds prefix every line with the time, file:line and the calling
+/// function, so you can see where each line of output comes from. Release
+/// builds (NDEBUG) and `--plain` print the bare message.
+class Logger {
+ public:
+  static Logger& instance();
+
+  Logger(const Logger&) = delete;
+  Logger& operator=(const Logger&) = delete;
+
+  /// Prints one line. A single trailing '\n' in `message` is dropped.
+  void log(std::string_view message,
+           const std::source_location& location =
+               std::source_location::current());
+
+  /// Prints the full signature of the calling function. Handy to see which
+  /// overload, constructor or operator the compiler picked.
+  void logFunction(const std::source_location& location =
+                       std::source_location::current());
+
+  /// Prints a visual separator: "--- title -----------".
+  void section(std::string_view title);
+
+  void setShowLocation(bool show) { show_location_ = show; }
+  void setUseColor(bool use) { use_color_ = use; }
+  bool showLocation() const { return show_location_; }
+
+ private:
+  Logger();
+  void write(std::string_view message, const std::source_location& location,
+             bool with_function);
+
+  std::mutex mutex_;
+  std::atomic<bool> show_location_;
+  std::atomic<bool> use_color_;
+};
+
+}  // namespace lab
+
+/// LOG("text") - log a string (anything convertible to std::string_view).
+#define LOG(message) ::lab::Logger::instance().log(message)
+
+/// LOG_S("x = " << x) - log anything that can be streamed into std::ostream.
+#define LOG_S(...)                                   \
+  do {                                               \
+    std::ostringstream lab_log_stream_;              \
+    lab_log_stream_ << __VA_ARGS__;                  \
+    ::lab::Logger::instance().log(lab_log_stream_.str()); \
+  } while (false)
+
+/// LOG_FUNC() - log the signature of the current function.
+#define LOG_FUNC() ::lab::Logger::instance().logFunction()
+
+/// LOG_SECTION("Title") - print a separator to structure the output.
+#define LOG_SECTION(title) ::lab::Logger::instance().section(title)
diff --git a/include/lab/Menu.h b/include/lab/Menu.h
new file mode 100644
index 0000000..515cf85
--- /dev/null
+++ b/include/lab/Menu.h
@@ -0,0 +1,16 @@
+#pragma once
+
+#include <iosfwd>
+
+#include "lab/Registry.h"
+
+namespace lab {
+
+/// Interactive menu that mirrors the folder structure of the examples.
+///
+/// Type a number to open a folder or run an example, `0` to go back, `q` to
+/// quit, or any other text to search. Returns when the user quits or the
+/// input stream ends.
+void runMenu(const Registry& registry, std::istream& in, std::ostream& out);
+
+}  // namespace lab
diff --git a/include/lab/Registry.h b/include/lab/Registry.h
new file mode 100644
index 0000000..a15e155
--- /dev/null
+++ b/include/lab/Registry.h
@@ -0,0 +1,80 @@
+#pragma once
+
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace lab {
+
+/// Optional traits of an example. Combine them with `|`.
+enum ExampleFlags : unsigned {
+  kNone = 0U,
+  /// The example needs a human or another process: it reads stdin, waits for a
+  /// network peer, or never returns. `--run-all` and the ctest smoke tests
+  /// skip these examples.
+  kInteractive = 1U << 0U,
+};
+
+using ExampleFunction = void (*)();
+
+/// Metadata and entry point of one runnable example.
+struct Example {
+  std::string id;           ///< "<group>/<name>", e.g. "core/smart_pointer/Weak"
+  std::string group;        ///< source directory below src/, e.g. "core/smart_pointer"
+  std::string name;         ///< short name shown in the menu, e.g. "Weak"
+  std::string description;  ///< one-line summary
+  std::string source;       ///< path relative to the repository root
+  ExampleFunction run{nullptr};
+  unsigned flags{kNone};
+
+  bool isInteractive() const { return (flags & kInteractive) != 0U; }
+};
+
+/// Collection of all examples.
+///
+/// Examples register themselves through LAB_EXAMPLE (see lab/Example.h) while
+/// static objects are initialized, i.e. before main() runs. The group of an
+/// example is derived from the directory of its source file, so the menu
+/// always mirrors the folder structure below src/.
+class Registry {
+ public:
+  /// The process-wide registry used by LAB_EXAMPLE.
+  static Registry& instance();
+
+  /// Registers an example. `file` is the __FILE__ of the example.
+  /// Returns false (and records an error) for invalid or duplicate examples.
+  bool add(std::string_view file, std::string_view name,
+           std::string_view description, ExampleFunction run,
+           unsigned flags = kNone);
+
+  /// All registered examples, sorted case-insensitively by id.
+  const std::vector<Example>& examples() const { return examples_; }
+
+  /// Looks up an example by id. Exact matches win over case-insensitive ones.
+  const Example* find(std::string_view id) const;
+
+  /// Examples whose id or description contains `filter` (case-insensitive).
+  /// An empty filter matches every example.
+  std::vector<const Example*> match(std::string_view filter) const;
+
+  /// Problems found while registering (duplicate ids, invalid names, ...).
+  const std::vector<std::string>& errors() const { return errors_; }
+
+ private:
+  std::vector<Example> examples_;
+  std::vector<std::string> errors_;
+};
+
+namespace detail {
+
+/// Makes `file` relative to `source_root`:
+/// "/repo/src/core/Weak.cpp" -> "src/core/Weak.cpp".
+std::string relativeSourcePath(std::string_view file,
+                               std::string_view source_root);
+
+/// Derives the menu group from a relative source path:
+/// "src/core/smart_pointer/Weak.cpp" -> "core/smart_pointer".
+std::string groupFromSourcePath(std::string_view relative_path);
+
+}  // namespace detail
+}  // namespace lab
diff --git a/include/lab/Runner.h b/include/lab/Runner.h
new file mode 100644
index 0000000..2697b66
--- /dev/null
+++ b/include/lab/Runner.h
@@ -0,0 +1,19 @@
+#pragma once
+
+#include <iosfwd>
+#include <string_view>
+
+#include "lab/Registry.h"
+
+namespace lab {
+
+/// Runs one example between a header and a footer. Exceptions that escape the
+/// example are caught and reported. Returns true if the example succeeded.
+bool runExample(const Example& example, std::ostream& out);
+
+/// Runs every non-interactive example that matches `filter` and prints a
+/// summary. Returns the number of failed examples.
+int runAll(const Registry& registry, std::string_view filter,
+           std::ostream& out);
+
+}  // namespace lab
diff --git a/include/lab/version.h.in b/include/lab/version.h.in
new file mode 100644
index 0000000..98e0b4b
--- /dev/null
+++ b/include/lab/version.h.in
@@ -0,0 +1,17 @@
+#pragma once
+
+// Generated by CMake from include/lab/version.h.in - do not edit.
+
+#include <string_view>
+
+namespace lab::version {
+
+inline constexpr std::string_view kName = "@PROJECT_NAME@";
+inline constexpr std::string_view kVersion = "@PROJECT_VERSION@";
+inline constexpr std::string_view kDescription = "@PROJECT_DESCRIPTION@";
+inline constexpr std::string_view kBuildTime = "@CPPLAB_BUILD_TIME@";
+inline constexpr std::string_view kBuildType = "@CMAKE_BUILD_TYPE@";
+inline constexpr std::string_view kCompiler =
+    "@CMAKE_CXX_COMPILER_ID@ @CMAKE_CXX_COMPILER_VERSION@";
+
+}  // namespace lab::version
diff --git a/include/version.h.in b/include/version.h.in
deleted file mode 100644
index 4d31f37..0000000
--- a/include/version.h.in
+++ /dev/null
@@ -1,6 +0,0 @@
-#pragma once
-
-#define APP_NAME        "@PROJECT_NAME@"
-#define APP_VERSION     "@PROJECT_VERSION@"
-#define APP_DESCRIPTION "@PROJECT_DESCRIPTION@"
-#define APP_BUILD_TIME  "@BUILD_TIME@"
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 2185b50..0fcb20c 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -1,36 +1,43 @@
 # ----------------------------------------------------------------------------------------
-# Main application target
+# lab framework (registry, logger, menu, command line)
 # ----------------------------------------------------------------------------------------
+add_subdirectory(lab)
 
-# Add project submodules
-add_subdirectory(core)
-add_subdirectory(controller)
-add_subdirectory(dp)
-add_subdirectory(socket)
-add_subdirectory(ap)
-add_subdirectory(demo)
+# ----------------------------------------------------------------------------------------
+# Example modules
+# Every .cpp below these folders is compiled into the menu application. To add an example,
+# create a file with LAB_EXAMPLE(...) in the right folder - no CMake change is required.
+# To add a new top-level topic, create the folder and add one line here.
+# ----------------------------------------------------------------------------------------
+set(CPPLAB_EXAMPLE_TARGETS)
+cpplab_add_example_module(core)        # C++ language and standard library
+cpplab_add_example_module(controller)  # control algorithms (PID)
+cpplab_add_example_module(dp)          # design patterns
+cpplab_add_example_module(socket)      # POSIX TCP sockets
 
-# Header files directory
-set(APP_HEADERS
-    ${PROJECT_SOURCE_DIR}/include
-    ${CMAKE_BINARY_DIR}/generated # cmake generated headers
+# ----------------------------------------------------------------------------------------
+# Main application target
+# ----------------------------------------------------------------------------------------
+add_executable(${PROJECT_NAME} main.cpp)
+target_link_libraries(${PROJECT_NAME}
+    PRIVATE
+        cpplab::lab
+        ${CPPLAB_EXAMPLE_TARGETS}
 )
 
-# Define the main application executable
-add_executable(${PROJECT_NAME}
-    main.cpp
-    ${CORE_SOURCES}
-    ${SOCKET_SOURCES}
-    ${CONTROLLER_SOURCES}
-    ${DP_SOURCES}
-)
+if(CPPLAB_BUILD_TESTS)
+    cpplab_discover_example_tests(${PROJECT_NAME})
+endif()
 
-# Add header include paths
-target_include_directories(${PROJECT_NAME}
-    PRIVATE ${APP_HEADERS}
-)
+# ----------------------------------------------------------------------------------------
+# Standalone programs
+# ----------------------------------------------------------------------------------------
+if(CPPLAB_GUI_ENABLED)
+    add_subdirectory(ap)     # MVC / MVVM with GTK4 (separate executables)
+endif()
+
+if(CPPLAB_BUILD_DEMOS)
+    add_subdirectory(demo)   # dlopen plugin demo
+endif()
 
-# Optional: add project-specific compiler options
-target_compile_options(${PROJECT_NAME}
-    PRIVATE -Wall -Wextra -Wpedantic
-)
\ No newline at end of file
+# src/embedded is a bare-metal ARM example built with its own script (see its README).
diff --git a/src/DeleteMe.cpp b/src/DeleteMe.cpp
deleted file mode 100644
index 75d112a..0000000
--- a/src/DeleteMe.cpp
+++ /dev/null
@@ -1,32 +0,0 @@
-#include "DeleteMe.h"
-
-DeleteMe::DeleteMe() {
-  m_lastResult = 0;
-}
-
-DeleteMe::~DeleteMe() {}
-
-bool DeleteMe::add(int addend1, int addend2) {
-  m_lastResult = addend1 + addend2;
-  return true;
-}
-
-// This is for checking that code coverage will not be <100%
-bool DeleteMe::mul(int factor1, int factor2) {
-  m_lastResult = factor1 * factor2;
-  return true;
-}
-
-bool DeleteMe::div(int dividend, int divisor) {
-  if (divisor == 0) {
-    m_lastResult = 0;
-    return false;
-  }
-
-  m_lastResult = dividend / divisor;
-  return true;
-}
-
-int DeleteMe::get_last_result() {
-  return m_lastResult;
-}
diff --git a/src/ap/CMakeLists.txt b/src/ap/CMakeLists.txt
index c6e1842..28e40af 100644
--- a/src/ap/CMakeLists.txt
+++ b/src/ap/CMakeLists.txt
@@ -1,21 +1,20 @@
-# Create the gtk4-setting interface library
-# Link against the libraries found for GTKMM
-add_library(gtk4-settings INTERFACE)
-target_link_libraries(gtk4-settings INTERFACE ${GTKMM_LIBRARIES})
-
-# Include the directories where gtkmm.h resides
-target_include_directories(gtk4-settings INTERFACE ${GTKMM_INCLUDE_DIRS})
+# ----------------------------------------------------------------------------------------
+# GTK4 (gtkmm-4.0) apps that compare three ways to structure the same small UI:
+#   ap       - everything in one window class (tightly coupled)
+#   mvc_ap   - Model / View / Controller
+#   mvvm_ap  - Model / View / ViewModel
+# Only built when gtkmm-4.0 is available (see CPPLAB_BUILD_GUI in the top-level CMakeLists).
+# ----------------------------------------------------------------------------------------
 
-# Add compiler flags (defines, etc.) required by gtkmm
-target_compile_options(gtk4-settings INTERFACE ${GTKMM_CFLAGS_OTHER})
+# Interface target with the gtkmm include paths, libraries and compile flags.
+# PkgConfig::GTKMM is an imported target, so its headers are treated as system headers and
+# do not trigger our -Wall -Wextra -Wpedantic warnings.
+add_library(gtk4-settings INTERFACE)
+target_link_libraries(gtk4-settings INTERFACE PkgConfig::GTKMM cpplab::options)
 
 # ap executable
-add_executable(ap)
-target_sources(ap
-    PRIVATE
-    simple_ap.cpp
-)
+add_executable(ap simple_ap.cpp)
 target_link_libraries(ap PRIVATE gtk4-settings)
 
 add_subdirectory(mvc)
-add_subdirectory(mvvm)
\ No newline at end of file
+add_subdirectory(mvvm)
diff --git a/src/ap/README.md b/src/ap/README.md
index 88afdb9..b5b80a4 100644
--- a/src/ap/README.md
+++ b/src/ap/README.md
@@ -1,3 +1,6 @@
+> Programs: `./build/bin/ap` (everything in one class), `./build/bin/mvc_ap`, `./build/bin/mvvm_ap`.
+> They are built only when gtkmm-4.0 is installed (`CPPLAB_BUILD_GUI`).
+
 ## Architecture Patterns
 ### 1. MVVM
 ![Diagram](../../docs/uml/ap/ap_mvvm_example.drawio.svg)
diff --git a/src/ap/mvc/controller/Controller.cpp b/src/ap/mvc/controller/Controller.cpp
index 843268a..8898f97 100644
--- a/src/ap/mvc/controller/Controller.cpp
+++ b/src/ap/mvc/controller/Controller.cpp
@@ -1,6 +1,9 @@
 #include "Controller.h"
 
-Controller::Controller(std::shared_ptr<SharedData> model) : model_(model) {}
+#include <utility>
+
+Controller::Controller(std::shared_ptr<SharedData> model)
+    : model_(std::move(model)) {}
 
 void Controller::updateRequest(const std::string& text) {
   if (text.empty())
diff --git a/src/ap/mvc/view/DisplayWidget.cpp b/src/ap/mvc/view/DisplayWidget.cpp
index 9686cbc..2eb6fdc 100644
--- a/src/ap/mvc/view/DisplayWidget.cpp
+++ b/src/ap/mvc/view/DisplayWidget.cpp
@@ -18,9 +18,11 @@ DisplayWidget::DisplayWidget(const std::string& title, const std::string& color,
 }
 
 void DisplayWidget::updateLabel(const std::string& text) {
-  // Use HTML markup to change text color
-  std::string markup = "<span foreground='" + color_ +
-                       "' size='x-large' weight='bold'>" + text + "</span>";
+  // Pango markup changes color and size. The text comes from the user, so it
+  // must be escaped: a '<' or '&' would otherwise break the markup.
+  const std::string markup = "<span foreground='" + color_ +
+                             "' size='x-large' weight='bold'>" +
+                             Glib::Markup::escape_text(text).raw() + "</span>";
   labelData_.set_markup(markup);
 }
 
diff --git a/src/ap/mvc/view/DisplayWidget.h b/src/ap/mvc/view/DisplayWidget.h
index 9eddc48..627848d 100644
--- a/src/ap/mvc/view/DisplayWidget.h
+++ b/src/ap/mvc/view/DisplayWidget.h
@@ -1,3 +1,5 @@
+#pragma once
+
 #include <gtkmm.h>
 #include "../IObserver.h"
 
diff --git a/src/ap/mvc/view/EditorWidget.cpp b/src/ap/mvc/view/EditorWidget.cpp
index 61a1d90..c2e4484 100644
--- a/src/ap/mvc/view/EditorWidget.cpp
+++ b/src/ap/mvc/view/EditorWidget.cpp
@@ -1,10 +1,12 @@
 #include "EditorWidget.h"
 
+#include <utility>
+
 EditorWidget::EditorWidget(std::shared_ptr<Controller> c,
                            const std::string& initData)
     : Gtk::Box(Gtk::Orientation::VERTICAL),
       innerBox_(Gtk::Orientation::VERTICAL),
-      controller_(c) {
+      controller_(std::move(c)) {
   // Create a beautiful border
   frame_.set_label("ZONE 1: EDITOR (Input View)");
   frame_.set_margin(10);
@@ -29,7 +31,8 @@ EditorWidget::EditorWidget(std::shared_ptr<Controller> c,
 }
 
 void EditorWidget::onDataChanged(const std::string& newData) {
-  // Fix string comparison error or do not thing ?
+  // Only touch the entry when the text really changed: set_text() would move
+  // the cursor and could start another round of notifications.
   if (entry_.get_text() != Glib::ustring(newData)) {
     entry_.set_text(newData);
   }
diff --git a/src/ap/mvc/view/EditorWidget.h b/src/ap/mvc/view/EditorWidget.h
index 88c69b9..6e6aef0 100644
--- a/src/ap/mvc/view/EditorWidget.h
+++ b/src/ap/mvc/view/EditorWidget.h
@@ -1,7 +1,7 @@
 #pragma once
 #include <gtkmm.h>
-#include "../controller/Controller.h"
 #include "../IObserver.h"
+#include "../controller/Controller.h"
 
 class EditorWidget : public Gtk::Box, public IObserver {
  public:
diff --git a/src/ap/mvvm/view/DisplayWidget.cpp b/src/ap/mvvm/view/DisplayWidget.cpp
index d18ad9b..c9bff40 100644
--- a/src/ap/mvvm/view/DisplayWidget.cpp
+++ b/src/ap/mvvm/view/DisplayWidget.cpp
@@ -23,8 +23,10 @@ mvvm::DisplayWidget::DisplayWidget(const std::string& title, std::string color,
 }
 
 void mvvm::DisplayWidget::updateLabel(const std::string& text) {
-  std::string markup = "<span foreground='" + color_ +
-                       "' size='x-large' weight='bold'>" + text + "</span>";
+  // The text comes from the user: escape it before building Pango markup.
+  const std::string markup = "<span foreground='" + color_ +
+                             "' size='x-large' weight='bold'>" +
+                             Glib::Markup::escape_text(text).raw() + "</span>";
   labelData_.set_markup(markup);
 }
 
diff --git a/src/ap/mvvm/view/DisplayWidget.h b/src/ap/mvvm/view/DisplayWidget.h
index 33864fb..94786b8 100644
--- a/src/ap/mvvm/view/DisplayWidget.h
+++ b/src/ap/mvvm/view/DisplayWidget.h
@@ -1,3 +1,5 @@
+#pragma once
+
 #include <gtkmm.h>
 #include <memory>
 #include "../IObserver.h"
diff --git a/src/ap/mvvm/view/EditorWidget.cpp b/src/ap/mvvm/view/EditorWidget.cpp
index 7607262..e7470a3 100644
--- a/src/ap/mvvm/view/EditorWidget.cpp
+++ b/src/ap/mvvm/view/EditorWidget.cpp
@@ -31,6 +31,8 @@ mvvm::EditorWidget::EditorWidget(std::shared_ptr<SharedDataVM> vm)
 }
 
 void mvvm::EditorWidget::onDataChanged(const std::string& newData) {
+  // Only touch the entry when the text really changed: set_text() would move
+  // the cursor and could start another round of notifications.
   if (entry_.get_text() != Glib::ustring(newData)) {
     entry_.set_text(newData);
   }
diff --git a/src/ap/simple_ap.cpp b/src/ap/simple_ap.cpp
index 4b23329..a1c4314 100644
--- a/src/ap/simple_ap.cpp
+++ b/src/ap/simple_ap.cpp
@@ -88,12 +88,13 @@ class MainWindow : public Gtk::Window {
         return;
 
       // Step 2: Update Monitor A (Hard-coded) directly
+      const std::string escaped = Glib::Markup::escape_text(text).raw();
       m_labelMonitorA_.set_markup("<span foreground='blue' size='x-large'>" +
-                                  text + "</span>");
+                                  escaped + "</span>");
 
       // Step 3: Update Monitor B (Hard-coded) directly
       m_labelMonitorB_.set_markup("<span foreground='red' size='x-large'>" +
-                                  text + "</span>");
+                                  escaped + "</span>");
       std::cout << "Updated directly without Model!" << std::endl;
     });
   }
diff --git a/src/controller/CMakeLists.txt b/src/controller/CMakeLists.txt
deleted file mode 100644
index 1e44de8..0000000
--- a/src/controller/CMakeLists.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-set(CONTROLLER_SOURCES
-
-    # PID
-    ${CMAKE_CURRENT_SOURCE_DIR}/pid/pid.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/pid/PIDSim.cpp
-)
-
-set(CONTROLLER_SOURCES ${CONTROLLER_SOURCES} PARENT_SCOPE)
\ No newline at end of file
diff --git a/src/controller/README.md b/src/controller/README.md
new file mode 100644
index 0000000..da8d3b0
--- /dev/null
+++ b/src/controller/README.md
@@ -0,0 +1,27 @@
+# Controller
+
+| Example      | Topic                                        |
+|--------------|----------------------------------------------|
+| `pid/PIDSim` | a PID controller driving a value to a setpoint |
+
+## PID controller
+
+A PID controller computes a correction from the error `e = setpoint - measured value`:
+
+```
+output = Kp * e                      proportional: reacts to the present error
+       + Ki * sum(e * dt)            integral:     removes the steady-state offset (the past)
+       + Kd * (e - e_previous) / dt  derivative:   damps overshoot (predicts the future)
+```
+
+The output is clamped to `[min, max]`, for example a motor's maximum power.
+
+| Gain too high | Effect                                   |
+|---------------|------------------------------------------|
+| `Kp`          | fast, but oscillates                     |
+| `Ki`          | removes offset, but overshoots and winds up |
+| `Kd`          | damps, but amplifies measurement noise   |
+
+`pid.h/pid.cpp` is based on the MIT-licensed implementation by Bradley J. Snyder. It uses the
+**pimpl** idiom: `PID` holds a `std::unique_ptr<PIDImpl>`, so the implementation can change without
+recompiling the code that uses it. The class is unit tested in `tests/controller/PidTest.cpp`.
diff --git a/src/controller/pid/PIDSim.cpp b/src/controller/pid/PIDSim.cpp
index 9a90e32..3314731 100644
--- a/src/controller/pid/PIDSim.cpp
+++ b/src/controller/pid/PIDSim.cpp
@@ -1,28 +1,70 @@
-#include <iostream>
-#include "pid.h"
+// -----------------------------------------------------------------------------
+// PID controller simulation
+//
+// A PID controller drives a process value toward a setpoint by combining
+// three reactions to the error e = setpoint - value:
+//
+//   P = Kp * e          present : the bigger the error, the stronger the push
+//   I = Ki * sum(e*dt)  past    : removes the remaining steady-state offset
+//   D = Kd * de/dt      future  : brakes when the error shrinks quickly
+//
+// Here the controller output is simply added to the value each step - a very
+// crude model of a real process - to show how the value converges.
+//
+// Reference: https://en.wikipedia.org/wiki/Proportional%E2%80%93integral%E2%80%93derivative_controller
+// -----------------------------------------------------------------------------
+
+#include <algorithm>
+#include <cmath>
+#include <string>
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
+#include "pid.h"
 
 namespace {
+
+std::string bar(double value, double scale_max) {
+  constexpr int kWidth = 40;
+  const int filled = static_cast<int>(
+      std::lround(std::clamp(value / scale_max, 0.0, 1.0) * kWidth));
+  return std::string(static_cast<std::size_t>(filled), '#') +
+         std::string(static_cast<std::size_t>(kWidth - filled), '.');
+}
+
 void run() {
-  PID pid = PID(0.1, 100, -100, 0.1, 0.01, 0.5);
-  double setpoint = 100;
-  double val = 20;
-  for (int i = 0; i < 200; i++) {
-    double inc = pid.calculate(setpoint, val);
-    std::cout << "setpoint:" << setpoint << " - val:" << val << " - inc:" << inc
-              << std::endl;
-    val += inc;
+  LOG_SECTION("Driving a value from 20 to the setpoint 100");
+  // dt = 0.1, output limits [-100, 100], Kp = 0.1, Kd = 0.01, Ki = 0.5
+  controller::PID pid(0.1, 100, -100, 0.1, 0.01, 0.5);
+  constexpr double kSetpoint = 100.0;
+  constexpr int kSteps = 200;
+  double value = 20.0;
+  int settled_at = -1;
+
+  for (int step = 0; step < kSteps; ++step) {
+    const double increment = pid.calculate(kSetpoint, value);
+    value += increment;
+
+    if (settled_at < 0 && std::abs(kSetpoint - value) < 0.5) {
+      settled_at = step;
+    }
+    if (step % 10 == 0 || step == kSteps - 1) {
+      LOG_S("step " << (step < 10    ? "  "
+                        : step < 100 ? " "
+                                     : "")
+                    << step << "  value " << bar(value, 120.0) << ' ' << value
+                    << "  (increment " << increment << ")");
+    }
   }
+
+  LOG_S("final value " << value << ", within 0.5 of the setpoint from step "
+                       << settled_at);
+  LOG("Try other gains: a larger Ki overshoots more, Kd = 0 oscillates "
+      "longer.");
 }
-}  // namespace
 
-class PIDSim : public IExample {
- public:
-  std::string group() const override { return "controller"; }
-  std::string name() const override { return "PIDSim"; }
-  std::string description() const override { return "PID example"; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(PIDSim);
+LAB_EXAMPLE("PIDSim", "simulate a PID controller converging to a setpoint") {
+  run();
+}
diff --git a/src/controller/pid/pid.cpp b/src/controller/pid/pid.cpp
index 0548ef8..154b63d 100644
--- a/src/controller/pid/pid.cpp
+++ b/src/controller/pid/pid.cpp
@@ -18,98 +18,70 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * Modified for cpp-lab: namespace, std::unique_ptr pimpl, input validation.
  */
 
-#ifndef _PID_SOURCE_
-#define _PID_SOURCE_
-
-#include <iostream>
-#include <cmath>
 #include "pid.h"
 
-using namespace std;
-
-class PIDImpl
-{
-    public:
-        PIDImpl( double dt, double max, double min, double Kp, double Kd, double Ki );
-        ~PIDImpl();
-        double calculate( double setpoint, double pv );
-
-    private:
-        double _dt;
-        double _max;
-        double _min;
-        double _Kp;
-        double _Kd;
-        double _Ki;
-        double _pre_error;
-        double _integral;
+#include <algorithm>
+#include <stdexcept>
+
+namespace controller {
+
+class PIDImpl {
+ public:
+  PIDImpl(double dt, double max, double min, double kp, double kd, double ki)
+      : dt_{dt}, max_{max}, min_{min}, kp_{kp}, kd_{kd}, ki_{ki} {
+    if (dt_ <= 0.0) {
+      throw std::invalid_argument("PID: dt must be greater than zero");
+    }
+    if (min_ > max_) {
+      throw std::invalid_argument("PID: min must not be greater than max");
+    }
+  }
+
+  double calculate(double setpoint, double process_value) {
+    const double error = setpoint - process_value;
+
+    // Proportional term: reacts to the current error.
+    const double proportional = kp_ * error;
+
+    // Integral term: accumulates past errors and removes steady-state offset.
+    integral_ += error * dt_;
+    const double integral = ki_ * integral_;
+
+    // Derivative term: reacts to how fast the error changes (damping).
+    const double derivative = kd_ * (error - previous_error_) / dt_;
+
+    previous_error_ = error;
+
+    // Restrict the output to [min, max].
+    return std::clamp(proportional + integral + derivative, min_, max_);
+  }
+
+ private:
+  double dt_;
+  double max_;
+  double min_;
+  double kp_;
+  double kd_;
+  double ki_;
+  double previous_error_{0.0};
+  double integral_{0.0};
 };
 
+PID::PID(double dt, double max, double min, double kp, double kd, double ki)
+    : impl_{std::make_unique<PIDImpl>(dt, max, min, kp, kd, ki)} {}
 
-PID::PID( double dt, double max, double min, double Kp, double Kd, double Ki )
-{
-    pimpl = new PIDImpl(dt,max,min,Kp,Kd,Ki);
-}
-double PID::calculate( double setpoint, double pv )
-{
-    return pimpl->calculate(setpoint,pv);
-}
-PID::~PID() 
-{
-    delete pimpl;
-}
-
-/**
- * Implementation
- */
-PIDImpl::PIDImpl( double dt, double max, double min, double Kp, double Kd, double Ki ) :
-    _dt(dt),
-    _max(max),
-    _min(min),
-    _Kp(Kp),
-    _Kd(Kd),
-    _Ki(Ki),
-    _pre_error(0),
-    _integral(0)
-{
-}
-
-double PIDImpl::calculate( double setpoint, double pv )
-{
-    
-    // Calculate error
-    double error = setpoint - pv;
-
-    // Proportional term
-    double Pout = _Kp * error;
-
-    // Integral term
-    _integral += error * _dt;
-    double Iout = _Ki * _integral;
-
-    // Derivative term
-    double derivative = (error - _pre_error) / _dt;
-    double Dout = _Kd * derivative;
-
-    // Calculate total output
-    double output = Pout + Iout + Dout;
-
-    // Restrict to max/min
-    if( output > _max )
-        output = _max;
-    else if( output < _min )
-        output = _min;
-
-    // Save error to previous error
-    _pre_error = error;
-
-    return output;
-}
+// Defined here, where PIDImpl is a complete type: std::unique_ptr needs that to
+// delete it. This is why a pimpl class declares its destructor in the header.
+PID::~PID() = default;
+PID::PID(PID&&) noexcept = default;
+PID& PID::operator=(PID&&) noexcept = default;
 
-PIDImpl::~PIDImpl()
-{
+double PID::calculate(double setpoint, double process_value) {
+  return impl_->calculate(setpoint, process_value);
 }
 
-#endif
\ No newline at end of file
+}  // namespace controller
diff --git a/src/controller/pid/pid.h b/src/controller/pid/pid.h
index d9a2445..044ecc6 100644
--- a/src/controller/pid/pid.h
+++ b/src/controller/pid/pid.h
@@ -18,32 +18,46 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * Modified for cpp-lab: namespace, std::unique_ptr pimpl, input validation.
  */
 
-#ifndef _PID_H_
-#define _PID_H_
+#pragma once
+
+#include <memory>
+
+namespace controller {
 
 class PIDImpl;
+
+/// Discrete PID controller.
+///
+///   error  = setpoint - process_value
+///   output = Kp * error + Ki * sum(error * dt) + Kd * (error - previous_error) / dt
+///
+/// The output is clamped to [min, max]. The implementation is hidden behind a
+/// pointer ("pimpl" idiom), so changing it does not recompile the users.
 class PID {
  public:
-  // Kp -  proportional gain
-  // Ki -  Integral gain
-  // Kd -  derivative gain
-  // dt -  loop interval time
-  // max - maximum value of manipulated variable
-  // min - minimum value of manipulated variable
-  PID(double dt, double max, double min, double Kp, double Kd, double Ki);
-
-  // Returns the manipulated variable given a setpoint and current process value
-  double calculate(double setpoint, double pv);
+  /// @param dt  loop interval time (must be > 0)
+  /// @param max maximum value of the manipulated variable
+  /// @param min minimum value of the manipulated variable (must be <= max)
+  /// @param kp  proportional gain
+  /// @param kd  derivative gain
+  /// @param ki  integral gain
+  PID(double dt, double max, double min, double kp, double kd, double ki);
   ~PID();
 
-    PID() = delete;
-    PID(const PID& other) = delete;
-    PID& operator=(const PID& other) = delete;
+  PID(const PID&) = delete;
+  PID& operator=(const PID&) = delete;
+  PID(PID&&) noexcept;
+  PID& operator=(PID&&) noexcept;
+
+  /// Returns the manipulated variable for a setpoint and the current process value.
+  double calculate(double setpoint, double process_value);
 
  private:
-  PIDImpl* pimpl;
+  std::unique_ptr<PIDImpl> impl_;
 };
 
-#endif
\ No newline at end of file
+}  // namespace controller
diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt
deleted file mode 100644
index 0da196b..0000000
--- a/src/core/CMakeLists.txt
+++ /dev/null
@@ -1,113 +0,0 @@
-# ----------------------------------------------------------------------------------------
-# Core module source files
-# This list contains all implementation files for the core module.
-# The variable will be exported to the parent CMakeLists via PARENT_SCOPE.
-# ----------------------------------------------------------------------------------------
-
-set(CORE_SOURCES
-
-    # Basic C++ language features
-    ${CMAKE_CURRENT_SOURCE_DIR}/basics/Initialization.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/basics/Operations.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/basics/TypeQualifier.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/basics/ControlFlow.cpp
-
-    # Linkage (internal / external / shared symbols)
-    ${CMAKE_CURRENT_SOURCE_DIR}/linkage/Internal.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/linkage/Linkage.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/linkage/External.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/linkage/sharing/Sharing.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/linkage/sharing/external/constants.cpp
-
-    # Fundamental data types
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Fundamental.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Array.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Reference.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Pointer.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Enum.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Struct.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/Union.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/datatype/TypeConVersions.cpp
-
-    # Classes and object lifecycle
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/Friend.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/Constructor.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/Destructor.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/SallowDeepCopying.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/RoleOfThreeFiveZero.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/Relationship.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/VirtualBase.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/Binding.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/class/Encapsulation.cpp
-
-    # String handling
-    ${CMAKE_CURRENT_SOURCE_DIR}/string/StringFormatting.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/string/CString.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/string/StdString.cpp
-
-    # Exception handling
-    ${CMAKE_CURRENT_SOURCE_DIR}/exception/BasicHandle.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/exception/ThrowNoexcept.cpp
-
-    # Streams and file handling
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/IOStream.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/StringStream.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/FileIO.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/Directory.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/OutputFormatting.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/BinaryFileHandling.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/filehandle/TerminalColor.cpp
-
-    # STL containers and expressions
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/sequence/Array.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/sequence/Vector.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/unordered/UnorderedMap.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/adapter/Queue.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/adapter/Stack.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/sequence/Deque.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/container/associative/Set.cpp
-
-    # Smart pointers
-    ${CMAKE_CURRENT_SOURCE_DIR}/smart_pointer/Unique.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/smart_pointer/Shared.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/smart_pointer/Weak.cpp
-
-    # Function
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/Lambda.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/FunctionPointer.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/Functional.cpp
-    ## Operator overloading
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/ArithmeticOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/StreamOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/UnaryOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/ComparisonOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/InDecOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/SubscriptOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/FunctionCallOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/TypeCast.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/AssignmentOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/ClassMemberAccessOperator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/function/operator_overloading/AllocationOperator.cpp
-
-    # Date and time
-    ${CMAKE_CURRENT_SOURCE_DIR}/datetime/Time.cpp
-
-    # Concurrency
-    ${CMAKE_CURRENT_SOURCE_DIR}/concurrency/ThreadManagement.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/concurrency/SharingData.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/concurrency/RaceCondition.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/concurrency/ConditionVariable.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/concurrency/FuturePromise.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/concurrency/Timing.cpp
-
-    # Utils
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils/Algorithm.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils/TypeTrait.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils/Optional.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils/Variadic.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils/Regex.cpp
-)
-
-# Export CORE_SOURCES to the parent CMakeLists.txt
-# so the main application target can use these sources
-set(CORE_SOURCES ${CORE_SOURCES} PARENT_SCOPE)
\ No newline at end of file
diff --git a/src/core/basics/ControlFlow.cpp b/src/core/basics/ControlFlow.cpp
index 5fca0c7..a985879 100644
--- a/src/core/basics/ControlFlow.cpp
+++ b/src/core/basics/ControlFlow.cpp
@@ -1,11 +1,35 @@
-#include "ExampleRegistry.h"
-#include "Logger.h"
+// -----------------------------------------------------------------------------
+// Control flow
+//
+// Statements that change the order in which code runs:
+//   - conditionals : if / else if / else, switch, if with initializer (C++17)
+//   - loops        : while, do-while, for, range-based for
+//   - jumps        : break, continue, return, goto
+//   - exceptions   : throw / try / catch (see core/exception for details)
+//   - halts        : std::exit / std::abort end the whole program
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/control-flow-introduction/
+// -----------------------------------------------------------------------------
+
+#include <random>
+#include <stdexcept>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
+
+/// std::rand() is simple but low quality; <random> is the modern way.
+int randomInt(int min, int max) {
+  static std::mt19937 engine{std::random_device{}()};
+  std::uniform_int_distribution<int> distribution(min, max);
+  return distribution(engine);
+}
+
 void conditionals() {
-  LOG("Conditional Examples");
-  // if-else
-  int x = rand();
+  LOG_SECTION("Conditionals: if / switch");
+
+  const int x = randomInt(-5, 5);
   LOG_S("x = " << x);
   if (x > 0) {
     LOG("x is positive");
@@ -15,121 +39,106 @@ void conditionals() {
     LOG("x is zero");
   }
 
-  // switch
-  int choice = rand() % 2 + 1;
-  LOG_S("Choice = " << std::to_string(x));
+  // C++17: if with initializer. `remainder` only exists inside the if/else.
+  if (const int remainder = x % 2; remainder == 0) {
+    LOG("x is even");
+  } else {
+    LOG("x is odd");
+  }
+
+  const int choice = randomInt(1, 3);
+  LOG_S("choice = " << choice);
   switch (choice) {
     case 1:
-      LOG("Choice is 1");
-      break;
+      LOG("choice is 1");
+      break;  // without break, execution "falls through" into the next case
     case 2:
-      LOG("Choice is 2");
-      break;
+      LOG("choice is 2, falling through on purpose...");
+      [[fallthrough]];  // documents that the fall through is intentional
     default:
-      LOG("Choice is something else");
+      LOG("reached the default label");
       break;
   }
 }
 
-void jumps() {
-  LOG("Jump Statement Examples");
-
-  // goto
-  int num = rand();
-  if (num == 3)
-    goto jumpLabel;
-  LOG("This line will be skipped.");
-
-jumpLabel:
-  LOG("Jumped here using goto!");
-
-  // break / continue
-  for (int i = 0; i < 5; ++i) {
-    if (i == 2)
-      continue;  // skip 2
-    if (i == 4)
-      break;  // stop loop at 4
-    LOG_S("i = " << i);
-  }
-}
-
-int square(int n) {
-  // return
-  return n * n;
-}
-
-void functionCalls() {
-  LOG("Function Call Examples");
-  // function call
-  int result = square(5);
-  LOG_S("square(5) = " << result);
-}
-
 void loops() {
-  LOG("Loop Examples");
+  LOG_SECTION("Loops");
 
-  // while
   int i = 0;
-  while (i < 3) {
-    LOG_S("while loop i = " << i);
+  while (i < 3) {  // checks the condition before every iteration
+    LOG_S("while      i = " << i);
     ++i;
   }
 
-  // do-while
-  int j = 0;
-  do {
-    LOG_S("do-while loop j = " << j);
+  int j = 5;
+  do {  // checks the condition after the body, so it runs at least once
+    LOG_S("do-while   j = " << j << "  (body ran although j < 2 is false)");
     ++j;
   } while (j < 2);
 
-  // for(initialization; condition; update)
-  for (int k = 0; k < 3; ++k) {
-    LOG_S("for loop k = " << k);
+  for (int k = 0; k < 3; ++k) {  // for (init; condition; update)
+    LOG_S("for        k = " << k);
   }
 
-  // ranged-for
-  const int arr[] = {10, 20, 30};
-  for (int value : arr) {
-    LOG_S("ranged-for value = " << value);
+  const int values[] = {10, 20, 30};
+  for (const int value : values) {  // range-based for (C++11)
+    LOG_S("range-for  value = " << value);
   }
 }
 
-void halts() {
-  LOG("Halt Examples");
+void jumps() {
+  LOG_SECTION("Jumps: break / continue / goto");
+
+  for (int i = 0; i < 6; ++i) {
+    if (i == 2) {
+      continue;  // skip the rest of this iteration
+    }
+    if (i == 4) {
+      break;  // leave the loop
+    }
+    LOG_S("i = " << i << "  (2 is skipped, the loop stops at 4)");
+  }
 
-  // std::exit() — terminates the program normally
-  // std::abort() — terminates abnormally (no cleanup)
-  // Uncomment one at a time to see behavior
+  // goto jumps to a label in the same function. It makes code hard to follow;
+  // leaving deeply nested loops is one of the few accepted uses.
+  for (int row = 0; row < 3; ++row) {
+    for (int col = 0; col < 3; ++col) {
+      if (row * col == 2) {
+        LOG_S("row * col == 2 at (" << row << ", " << col
+                                    << "), leaving both loops");
+        goto done;
+      }
+    }
+  }
+done:
+  LOG("after the nested loops");
+}
 
-  // std::exit(0);
-  // std::abort();
+int square(int n) {
+  return n * n;  // return ends the function and hands a value to the caller
 }
 
-void exceptions() {
-  LOG("Exception Handling Examples");
+void exceptionsAndHalts() {
+  LOG_SECTION("return, exceptions and halts");
+  LOG_S("square(5) = " << square(5));
 
-  // try - catch - throw
   try {
-    throw std::runtime_error("Something went wrong!");
+    throw std::runtime_error("thrown to jump to the matching catch block");
   } catch (const std::exception& e) {
-    LOG_S("Caught exception: " << e.what());
+    LOG_S("caught: " << e.what());
   }
+
+  // std::exit(0) : normal termination, destructors of static objects run.
+  // std::abort() : abnormal termination, no cleanup at all.
+  // Both would end the whole lab, so they are only mentioned here.
+  LOG("std::exit / std::abort would terminate the whole program");
 }
-}  // namespace
 
-class ControlFlow : public IExample {
- public:
-  std::string group() const override { return "core/basics"; }
-  std::string name() const override { return "ControlFlow"; }
-  std::string description() const override { return "ControlFlow"; }
-  void execute() override {
-    conditionals();
-    jumps();
-    functionCalls();
-    loops();
-    halts();
-    exceptions();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(ControlFlow);
+LAB_EXAMPLE("ControlFlow", "if/switch, loops, break/continue/goto, halts") {
+  conditionals();
+  loops();
+  jumps();
+  exceptionsAndHalts();
+}
diff --git a/src/core/basics/Initialization.cpp b/src/core/basics/Initialization.cpp
index 853af7e..580a0dd 100644
--- a/src/core/basics/Initialization.cpp
+++ b/src/core/basics/Initialization.cpp
@@ -1,114 +1,138 @@
-// cppcheck-suppress-file [unreadVariable, unusedVariable, uninitdata, uninitvar, unassignedVariable]
-
-#include "ExampleRegistry.h"
-#include "Logger.h"
-
-/// @brief Dummy class
-struct Dummy {
-  Dummy() { LOG("Default ctor"); }
-  explicit Dummy(int value) { LOG_S("Int ctor: " << value); }
-  Dummy(const Dummy&) { LOG("Copy ctor"); }
+// -----------------------------------------------------------------------------
+// Initialization
+//
+// C++ has several ways to give an object its first value:
+//   T x;           default initialization (built-in types: indeterminate value!)
+//   T x{};         value initialization   (built-in types: zero)
+//   T x(args);     direct initialization
+//   T x = expr;    copy initialization    (explicit constructors not allowed)
+//   T x{args};     list initialization    (C++11, rejects narrowing)
+//   T x{.a = 1};   designated initializer (C++20, aggregates only)
+//
+// Rule of thumb: prefer braces `T x{...}` - they always initialize and they
+// refuse narrowing conversions such as double -> int.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/initialization
+// -----------------------------------------------------------------------------
+
+#include <string>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+/// Logs which constructor runs for each form of initialization.
+struct Tracer {
+  Tracer() { LOG("  Tracer()              default constructor"); }
+  explicit Tracer(int value) {
+    LOG_S("  Tracer(int)           value = " << value);
+  }
+  Tracer(const Tracer& /*other*/) {
+    LOG("  Tracer(const Tracer&) copy constructor");
+  }
 };
 
-/// @brief Aggregate type
-struct Aggregate {
+/// An aggregate: no user-declared constructors and only public members.
+struct Point {
   int x;
   int y;
 };
 
-/// @brief Default Initialization
-void default_ini() {
-  int a;
-  LOG_S("a = " << a);
+void defaultInitialization() {
+  LOG_SECTION("Default initialization: T x;");
 
-  Dummy object;
+  [[maybe_unused]] int
+      number;  // indeterminate: reading it is undefined behavior
+  LOG("int number;   -> indeterminate value, assign before reading it");
 
-  auto* p1 = new int;
-  LOG_S("*p1 = " << *p1);
-  auto* p2 = new Dummy;
+  auto* heap_number = new int;  // also indeterminate
+  *heap_number = 42;
+  LOG_S("new int       -> indeterminate until assigned, now " << *heap_number);
+  delete heap_number;
 
-  delete p1;
-  delete p2;
+  LOG("Tracer tracer; -> class types run their default constructor:");
+  const Tracer tracer;
 }
 
-/// @brief Value Initialization
-void value_ini() {
-  // int x();Dummy obj();      // Most Vexing Parse:function declaration
+void valueInitialization() {
+  LOG_SECTION("Value initialization: T x{}; / T()");
 
-  int a = int();
-  int b{};
+  const int braces{};
+  const int parentheses = int();
+  LOG_S("int braces{} = " << braces << ", int() = " << parentheses);
 
-  LOG_S("a = " << a);
-  LOG_S("b = " << b);
+  auto* heap_number = new int();  // new int() and new int{} are zero
+  LOG_S("new int()     = " << *heap_number);
+  delete heap_number;
 
-  Dummy object1 = Dummy();  // value initialization x copy-initialization
-  Dummy object2{};
+  LOG("Tracer tracer{};");
+  const Tracer tracer{};
 
-  auto* p1 = new int();
-  LOG_S("*p1 = " << *p1);
-
-  auto* p2 = new Dummy();
-
-  delete p1;
-  delete p2;
+  // Tracer oops();  // Most vexing parse: this declares a FUNCTION named oops!
 }
 
-/// @brief Direct Initialization
-void direct_ini() {
-  int a(42);
+void directAndCopyInitialization() {
+  LOG_SECTION("Direct T x(args) and copy T x = other");
 
-  Dummy object1(1);
-  Dummy object2(static_cast<int>(2));
+  LOG("Tracer direct(1);");
+  const Tracer direct(1);
 
-  LOG_S("a = " << a);
-}
+  LOG("Tracer copy = direct;");
+  [[maybe_unused]] const Tracer copy = direct;
+  // Tracer implicit = 2;  // error: copy initialization ignores explicit constructors
 
-/// @brief Copy Initialization
-void copy_ini() {
-  Dummy source{1};
+  const std::string text = "copy-initialized from a string literal";
+  LOG(text);
+}
 
-  Dummy object1 = source;
-  Dummy object2 = Dummy{2};
+void listInitialization() {
+  LOG_SECTION("List initialization: T x{args}");
 
-  int value = 42;
+  LOG("Tracer direct_list{3};");
+  [[maybe_unused]] const Tracer direct_list{3};
 
-  LOG_S("value = " << value);
-}
+  LOG("Tracer copy_list = Tracer{4};   (C++17 guarantees no copy is made)");
+  [[maybe_unused]] const Tracer copy_list = Tracer{4};
 
-/// @brief List Initialization (since C++11)
-void list_ini() {
-  Dummy object1{1};                         // direct-list-init
-  Dummy object2 = {static_cast<Dummy>(2)};  // copy-list-init
+  const std::vector<int> listed{
+      3, 7};  // uses the std::initializer_list constructor
+  const std::vector<int> sized(3, 7);  // uses the (count, value) constructor
+  LOG_S("std::vector<int>{3, 7}.size() = " << listed.size()
+                                           << "  -> elements 3 and 7");
+  LOG_S("std::vector<int>(3, 7).size() = "
+        << sized.size() << "  -> three 7s. () and {} differ!");
 
-  int values1[]{1, 2, 3};
-  int values2[] = {4, 5, 6};
+  const double pi = 3.14159;
+  // const int narrowed{pi};  // error: braces reject narrowing conversions
+  const int truncated(pi);  // compiles and silently drops the fraction
+  LOG_S("int truncated(3.14159) = "
+        << truncated << "  (int narrowed{3.14159} does not compile)");
 }
 
-/// @brief Aggregate Initialization
-void aggregate_ini() {
-  Aggregate a1 = {1, 2};
-  Aggregate a2{3, 4};
-  Aggregate a3{.x = 3, .y = 4};
+void aggregateInitialization() {
+  LOG_SECTION("Aggregate initialization");
+
+  const Point p1 = {1, 2};
+  const Point p2{3, 4};
+  const Point p3{.x = 5, .y = 6};  // C++20: members named, in declaration order
+  const Point p4{};                // every member value-initialized (zero)
+  // Point p5{7};  // also valid: y is value-initialized to 0 (GCC warns with -Wextra)
 
-  LOG_S("a1 = {" << a1.x << ", " << a1.y << "}");
-  LOG_S("a2 = {" << a2.x << ", " << a2.y << "}");
-  LOG_S("a3 = {" << a3.x << ", " << a3.y << "}");
+  LOG_S("Point p1 = {1, 2}        -> {" << p1.x << ", " << p1.y << "}");
+  LOG_S("Point p2{3, 4}           -> {" << p2.x << ", " << p2.y << "}");
+  LOG_S("Point p3{.x = 5, .y = 6} -> {" << p3.x << ", " << p3.y << "}");
+  LOG_S("Point p4{}               -> {" << p4.x << ", " << p4.y << "}");
 }
 
-class Initialization : public IExample {
- public:
-  std::string group() const override { return "core/basics"; }
-  std::string name() const override { return "Initialization"; }
-  std::string description() const override { return "Initialization Examples"; }
-
-  void execute() override {
-    default_ini();
-    value_ini();
-    direct_ini();
-    copy_ini();
-    list_ini();
-    aggregate_ini();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Initialization);
\ No newline at end of file
+LAB_EXAMPLE("Initialization",
+            "default, value, direct, copy, list and aggregate initialization") {
+  defaultInitialization();
+  valueInitialization();
+  directAndCopyInitialization();
+  listInitialization();
+  aggregateInitialization();
+}
diff --git a/src/core/basics/Operations.cpp b/src/core/basics/Operations.cpp
index 5287455..c19d3d7 100644
--- a/src/core/basics/Operations.cpp
+++ b/src/core/basics/Operations.cpp
@@ -1,126 +1,111 @@
-#include <bitset>
-
-#include "ExampleRegistry.h"
-#include "Logger.h"
-
-void arithmeticOperator();
-void logicalOperator();
-void bitWiseOperator();
-
-class Operations : public IExample {
- public:
-  std::string group() const override { return "core/basics"; }
-  std::string name() const override { return "Operations"; }
-  std::string description() const override { return "Operation"; }
-  void execute() override {
-    arithmeticOperator();
-    logicalOperator();
-    bitWiseOperator();
-  }
-};
-
-REGISTER_EXAMPLE(Operations);
-
-void arithmeticOperator() {
-  LOG_S("\n--- ArithmeticOperator Examples ---\n");
-  int a{100};
-  int b{200};
-
-  // Addition
-  LOG_S("a = " << a << ", b = " << b);
-  int sum = a + b;
-  LOG_S("sum = " << sum);
-
-  // Subtraction
-  LOG_S("a = " << a << ", b = " << b);
-  uint32_t different = a - b;
-  LOG_S("different = " << different);
-
-  // Multiplication
-  LOG_S("a = " << a << ", b = " << b);
-  int product = a * b;
-  LOG_S("product = " << product);
-
-  // Division
-  LOG_S("a = " << a << ", b = " << b);
-  int quotient = a / b;
-  LOG_S("quotient = " << quotient);
-
-  // Modulus
-  LOG_S("a = " << a << ", b = " << b);
-  int remainder = a % b;
-  LOG_S("remainder = " << remainder);
+// -----------------------------------------------------------------------------
+// Operators
+//
+//   - arithmetic : + - * / %  ++ --  (integer division truncates toward zero)
+//   - logical    : && || !           (&& and || short-circuit)
+//   - bitwise    : & | ^ ~ << >>     (work on the bits of integers)
+//
+// Pitfalls:
+//   - Unsigned arithmetic wraps around; signed overflow is undefined behavior.
+//   - The comma operator evaluates both sides and yields the right one.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/expressions#Operators
+// -----------------------------------------------------------------------------
 
-  // Increment
-  LOG_S("a = " << a);
-  int pre_in = ++a;  // increase a, return a
-  LOG_S("preIn = " << pre_in);
+#include <bitset>
+#include <cstdint>
 
-  LOG_S("a = " << a);
-  int post_in = a++;  // copy a to a copy, then increase a, return copy
-  LOG_S("postIn = " << post_in);
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-  // Decrement
-  LOG_S("b = " << b);
-  int pre_de = --b;
-  LOG_S("preDe = " << pre_de);
+namespace {
 
-  LOG_S("b = " << b);
-  int post_de = b--;
-  LOG_S("postDe = " << post_de);
+void arithmetic() {
+  LOG_SECTION("Arithmetic operators");
 
-  // Comma:
-  int value = (a++, b);  // a is incremented, then b is returned
+  int a{100};
+  const int b{200};
   LOG_S("a = " << a << ", b = " << b);
-  LOG_S("comma(a++, b) = " << value);
+  LOG_S("a + b = " << a + b);
+  LOG_S("a - b = " << a - b);
+  LOG_S("a * b = " << a * b);
+  LOG_S("a / b = " << a / b << "     <- integer division drops the fraction");
+  LOG_S("a % b = " << a % b);
+  LOG_S("-7 / 2 = " << -7 / 2 << ", -7 % 2 = " << -7 % 2
+                    << "  <- truncates toward zero, % keeps the sign of -7");
+  LOG_S("7.0 / 2 = " << 7.0 / 2
+                     << "  <- a double operand gives floating-point division");
+
+  // Converting a negative value to an unsigned type wraps around modulo 2^32.
+  const auto wrapped = static_cast<std::uint32_t>(a - b);
+  LOG_S("uint32_t(a - b) = " << wrapped << "  <- -100 wrapped around");
+
+  LOG_SECTION("Increment and decrement");
+  const int pre = ++a;  // increments first, then yields the new value
+  LOG_S("++a yields " << pre << ", a is now " << a);
+  const int post = a++;  // yields a copy of the old value, then increments
+  LOG_S("a++ yields " << post << ", a is now " << a);
+
+  // Comma operator: evaluate the left side, discard it, yield the right side.
+  const int comma = (++a, b);
+  LOG_S("(++a, b) yields " << comma << ", a is now " << a);
 }
 
-void logicalOperator() {
-  LOG("\n--- LOG_SicalOperator Examples ---");
-  bool a = true;
-  bool b = false;
-  bool c = true;
-
-  // show true/false instead of 1/0
-  LOG_S(std::boolalpha << "a = " << a << ", b = " << b << ", c = " << c);
-
-  // AND (&&)
-  LOG_S("[AND] a && b = " << (a && b));
-
-  // OR (||)
-  LOG_S("[OR ] a || b = " << (a || b));
-
-  // NOT (!)
-  LOG_S("[NOT] !c = " << (!c));
+/// Returns `value` and logs that it was evaluated.
+bool traced(bool value, const char* label) {
+  LOG_S("  evaluated " << label);
+  return value;
 }
 
-void bitWiseOperator() {
-  LOG("\n--- BitWiseOperator Examples ---");
-  std::bitset<8> bits_a = 0b1111'1111;  std::bitset<8> bits_b = 0b1111'0000;
-
-  LOG_S("bitA = " << bits_a << ", bitB = " << bits_b);
-
-  // AND
-  std::bitset<8> result = bits_a & bits_b;
-  LOG_S("bitA && bitB= " << result);
+void logical() {
+  LOG_SECTION("Logical operators");
 
-  // OR
-  result = bits_a | bits_b;
-  LOG_S("bitA | bitB= " << result);
+  const bool yes = true;
+  const bool no = false;
+  LOG_S(std::boolalpha << "true && false = " << (yes && no));
+  LOG_S(std::boolalpha << "true || false = " << (yes || no));
+  LOG_S(std::boolalpha << "!true         = " << !yes);
 
-  // XOR
-  result = bits_a ^ bits_b;
-  LOG_S("bitA ^ bitB= " << result);
+  LOG("false && rhs -> rhs is never evaluated (short-circuit):");
+  const bool and_result = traced(false, "lhs") && traced(true, "rhs");
+  LOG("true || rhs  -> rhs is never evaluated either:");
+  const bool or_result = traced(true, "lhs") || traced(false, "rhs");
+  LOG_S(std::boolalpha << "results: " << and_result << ", " << or_result);
+}
 
-  // NOT
-  result = ~bits_a;
-  LOG_S("~bitA = " << result);
+void bitwise() {
+  LOG_SECTION("Bitwise operators");
+
+  const std::bitset<8> a{0b1111'0000};  // ' separates digits (C++14)
+  const std::bitset<8> b{0b1010'1010};
+  LOG_S("a      = " << a);
+  LOG_S("b      = " << b);
+  LOG_S("a & b  = " << (a & b) << "  (1 where both are 1)");
+  LOG_S("a | b  = " << (a | b) << "  (1 where either is 1)");
+  LOG_S("a ^ b  = " << (a ^ b) << "  (1 where they differ)");
+  LOG_S("~a     = " << ~a);
+  LOG_S("a << 1 = " << (a << 1));
+  LOG_S("a >> 1 = " << (a >> 1));
+
+  LOG_SECTION(
+      "Bit manipulation on an integer (typical for hardware registers)");
+  std::uint8_t reg = 0b0100'0001;
+  LOG_S("start        : " << std::bitset<8>(reg));
+  reg = static_cast<std::uint8_t>(reg | (1U << 3U));  // set bit 3
+  LOG_S("set bit 3    : " << std::bitset<8>(reg));
+  reg = static_cast<std::uint8_t>(reg ^ (1U << 0U));  // toggle bit 0
+  LOG_S("toggle bit 0 : " << std::bitset<8>(reg));
+  reg = static_cast<std::uint8_t>(reg & ~(1U << 3U));  // clear bit 3
+  LOG_S("clear bit 3  : " << std::bitset<8>(reg));
+  const bool bit0 = ((reg >> 0U) & 1U) != 0U;  // test bit 0
+  LOG_S("bit 0 is set : " << std::boolalpha << bit0);
+}
 
-  // LEFT SHIFT
-  result = bits_a << 1;
-  LOG_S("bitA << 1 = " << result);
+}  // namespace
 
-  // RIGHT SHIFT
-  result = bits_a >> 1;
-  LOG_S("bitA >> 1 = " << result);
-}
\ No newline at end of file
+LAB_EXAMPLE("Operations",
+            "arithmetic, logical (short-circuit) and bitwise operators") {
+  arithmetic();
+  logical();
+  bitwise();
+}
diff --git a/src/core/basics/README.md b/src/core/basics/README.md
new file mode 100644
index 0000000..c4d9087
--- /dev/null
+++ b/src/core/basics/README.md
@@ -0,0 +1,43 @@
+# Basics
+
+| Example          | Topic                                                                |
+|------------------|----------------------------------------------------------------------|
+| `ControlFlow`    | if/else, if with initializer, switch and `[[fallthrough]]`, loops, break/continue/goto |
+| `Initialization` | default, value, direct, copy, list and aggregate initialization      |
+| `Operations`     | arithmetic, logical (short-circuit) and bitwise operators            |
+| `TypeQualifier`  | `const`, `constexpr`, `consteval`, `constinit`, `mutable`, `volatile` |
+
+## 1. Initialization
+
+```cpp
+int a;             // default initialization: indeterminate value, reading it is UB
+int b{};           // value initialization: 0
+int c(42);         // direct initialization
+int d = 42;        // copy initialization
+int e{42};         // list initialization: rejects narrowing (int e{4.2} does not compile)
+Point p{.x = 1};   // designated initializer (C++20, aggregates only)
+```
+
+- Prefer braces `{}`: they always initialize and reject narrowing.
+- `T obj();` does not create an object. It declares a function (the "most vexing parse").
+- `std::vector<int>{3, 7}` holds the two elements 3 and 7, while `std::vector<int>(3, 7)` holds
+  three 7s.
+
+## 2. Operators
+
+- Integer division truncates toward zero. `%` keeps the sign of the left operand.
+- Unsigned arithmetic wraps around. **Signed overflow is undefined behavior.**
+- `&&` and `||` short-circuit: the right side runs only if needed.
+- Prefix `++x` returns the new value; postfix `x++` returns a copy of the old one.
+
+## 3. const vs constexpr vs consteval vs constinit
+
+| Keyword     | Guarantees                                                        |
+|-------------|-------------------------------------------------------------------|
+| `const`     | the value cannot change after initialization (may be known only at run time) |
+| `constexpr` | the value is computed at compile time; constexpr functions *may* run there |
+| `consteval` | the function *must* run at compile time (C++20)                    |
+| `constinit` | a static variable is initialized at compile time but stays mutable (C++20) |
+
+Use `constexpr` instead of `#define` for constants: it has a type, a scope, and shows up in the
+debugger.
diff --git a/src/core/basics/TypeQualifier.cpp b/src/core/basics/TypeQualifier.cpp
index 1044f29..b17ed6b 100644
--- a/src/core/basics/TypeQualifier.cpp
+++ b/src/core/basics/TypeQualifier.cpp
@@ -1,11 +1,28 @@
-// cppcheck-suppress-file [unreadVariable]
-
-// A constexpr function is implicitly inline.
-// A constexpr static data member is implicitly an inline variable (since C++17).
-
-#include "Logger.h"
+// -----------------------------------------------------------------------------
+// const, constexpr, consteval, constinit, mutable, volatile
+//
+//   const      : cannot be modified after initialization (value may come at run time)
+//   constexpr  : value known at compile time; constexpr functions MAY run there
+//   consteval  : (C++20) function that MUST run at compile time
+//   constinit  : (C++20) static variable that MUST be initialized at compile time
+//   mutable    : member that may change even inside a const member function
+//   volatile   : value may change outside the program (hardware register)
+//
+// Notes:
+//   - A constexpr function is implicitly inline.
+//   - A constexpr static data member is implicitly an inline variable (C++17).
+//
+// Reference: https://en.cppreference.com/w/cpp/language/constexpr
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
+
 constexpr int square(int x) {
   return x * x;
 }
@@ -14,55 +31,93 @@ consteval int cube(int x) {
   return x * x * x;
 }
 
-void run() {
-  // 1. Named constants
-  const double const_var_g{9.8};
-
-#define NAME "Phong"
+// Initialized at compile time (no static initialization order problems), but
+// the variable itself is not const and can change at run time.
+constinit int g_counter = square(3);
 
-  // 2. Literal constants
-  bool my_name_is_alex{true};  ///< true is a boolean literal -> type: bool
-  double d{3.4};  ///< 3.4 is a floating-point literal -> type: double
+// A macro is plain text replacement: no type, no scope, no debugger symbol.
+#define LAB_GRAVITY_MACRO 9.8
 
-  // "Hello, world!" is a string literal -> type: const char[14]
-  LOG("Hello, world!");
+class Sensor {
+ public:
+  int read() const {
+    ++reads_;  // allowed because reads_ is mutable
+    return 42;
+  }
+  int reads() const { return reads_; }
 
-  // 3. constexpr variables
-  constexpr double kConstexprVarG{9.8};  // compile-time constant
+ private:
+  mutable int reads_{
+      0};  // bookkeeping that does not change the "logical" state
+};
 
-  // 4. Constant expressions
-  constexpr double kSomething{kConstexprVarG};
+void constVariables() {
+  LOG_SECTION("const");
 
-  // Error:
-  // constexpr double something2{const_var_g};
-  // const_var_g is const, but not guaranteed to be a constant expression
+  // The value is only known at run time, but it can never change afterwards.
+  const std::size_t length = std::string("hello").size();
+  // length = 3;  // error: assignment of read-only variable
+  LOG_S("const std::size_t length = " << length);
+}
 
-  if constexpr (kConstexprVarG != 9.8) {
-    LOG("kConstexprVarG != 9.8");
+void compileTimeConstants() {
+  LOG_SECTION("constexpr and consteval");
+
+  constexpr double kGravity = 9.8;  // typed compile-time constant
+  constexpr int kArea = square(4);  // constexpr function at compile time
+  constexpr int kVolume = cube(3);  // consteval: always at compile time
+  static_assert(kArea == 16, "checked by the compiler, free at run time");
+
+  const int side = static_cast<int>(std::string("four").size());
+  const int runtime_area = square(side);  // the same function at run time
+  // constexpr int bad = square(side);    // error: side is not a constant expression
+  // const int also_bad = cube(side);     // error: consteval needs a constant argument
+
+  const int buffer[square(2)]{};  // constant expressions can size an array
+  LOG_S("kGravity = " << kGravity << ", kArea = " << kArea
+                      << ", kVolume = " << kVolume);
+  LOG_S("square(side) at run time = " << runtime_area);
+  LOG_S("int buffer[square(2)] has " << sizeof(buffer) / sizeof(buffer[0])
+                                     << " elements");
+  LOG_S("LAB_GRAVITY_MACRO = " << LAB_GRAVITY_MACRO
+                               << " (prefer constexpr over #define)");
+
+  if constexpr (sizeof(void*) == 8) {  // the other branch is discarded
+    LOG("64-bit build (decided at compile time with if constexpr)");
   } else {
-    LOG("kConstexprVarG == 9.8");
+    LOG("not a 64-bit build (decided at compile time with if constexpr)");
   }
+}
+
+void constinitVariables() {
+  LOG_SECTION("constinit (C++20)");
+  LOG_S("g_counter starts at square(3) = " << g_counter);
+  ++g_counter;
+  LOG_S("after ++g_counter            = " << g_counter);
+}
 
-  // 5. Const expression function
+void mutableAndVolatile() {
+  LOG_SECTION("mutable and volatile");
 
-  constexpr int a = square(5);  // compile-time
-  int b = square(5);            // runtime allowed
+  const Sensor sensor;
+  sensor.read();
+  sensor.read();
+  LOG_S("const Sensor was read " << sensor.reads()
+                                 << " times (mutable counter)");
 
-  constexpr int c = cube(5);  // OK
-  // int d = cube(5);          // Error if not compile-time
+  LOG("volatile: reads are never optimized away because the value may change");
+  LOG("outside the program, e.g. a memory-mapped register (see "
+      "TypeConversions).");
 }
 
 }  // namespace
 
-#include "ExampleRegistry.h"
-
-class TypeQualifier : public IExample {
- public:
-  std::string group() const override { return "core/basics"; }
-  std::string name() const override { return "TypeQualifier"; }
-  std::string description() const override { return "TypeQualifier"; }
-
-  void execute() override { run(); }
-};
+#undef LAB_GRAVITY_MACRO
 
-REGISTER_EXAMPLE(TypeQualifier);
\ No newline at end of file
+LAB_EXAMPLE("TypeQualifier",
+            "const, constexpr, consteval, constinit, mutable, volatile") {
+  constVariables();
+  compileTimeConstants();
+  constinitVariables();
+  mutableAndVolatile();
+}
diff --git a/src/core/class/Binding.cpp b/src/core/class/Binding.cpp
index dd5a516..73f87d8 100644
--- a/src/core/class/Binding.cpp
+++ b/src/core/class/Binding.cpp
@@ -1,84 +1,109 @@
-// cppcheck-suppress-file [functionStatic,duplInheritedMember]
-
-#include <iostream>
-#include "ExampleRegistry.h"
+// -----------------------------------------------------------------------------
+// Early binding vs late binding
+//
+//   Early (static) binding : the function is chosen at compile time from the
+//                            static type (non-virtual members, overloads).
+//   Late (dynamic) binding : a virtual function is chosen at run time from the
+//                            dynamic type of the object, through a vtable.
+//
+// Pitfalls:
+//   - A non-virtual function with the same name in a derived class HIDES the
+//     base version; calls through a base reference still reach the base.
+//   - Virtual calls inside a constructor do not reach the derived class: that
+//     part of the object has not been constructed yet.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/early-binding-and-late-binding/
+// -----------------------------------------------------------------------------
+
+#include <memory>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
+
 namespace early_binding {
 
 class Animal {
  public:
-  virtual ~Animal() = default;
-  void speak() {  // NOT virtual
-    std::cout << "Animal speaks\n";
-    dump_++;
-  }
-
- protected:
-  int dump_{0};
+  void speak() const { LOG("Animal::speak"); }  // NOT virtual
 };
 
 class Dog : public Animal {
  public:
-  void speak() {  // Hides Animal::speak()
-    std::cout << "Dog barks\n";
-    dump_++;
-  }
+  void speak() const { LOG("Dog::speak"); }  // hides Animal::speak
 };
 
-void print(int x) {
-  std::cout << "int: " << x << "\n";
+void print(int value) {
+  LOG_S("print(int)    called with " << value);
 }
 
-void print(double x) {
-  std::cout << "double: " << x << "\n";
+void print(double value) {
+  LOG_S("print(double) called with " << value);
 }
 
 void run() {
-  std::cout << "\n---EarlyBinding---\n";
-  Animal* a = new Dog();
-  a->speak();  // Early binding: Non-virtual member function
-
-  print(5);     // Early binding: int version chosen at compile time
-  print(0.5F);  // Early binding: float version chosen at compile time
-  delete a;
+  LOG_SECTION("Early binding: decided by the static type");
+
+  const Dog dog;
+  const Animal& as_animal = dog;
+  LOG("dog.speak():");
+  dog.speak();  // static type Dog
+  LOG("as_animal.speak() where as_animal refers to the same Dog:");
+  as_animal.speak();  // static type Animal -> Animal::speak
+
+  LOG("Overload resolution also happens at compile time:");
+  print(5);     // exact match: int
+  print(0.5F);  // float -> double (promotion) is preferred over float -> int
 }
+
 }  // namespace early_binding
 
 namespace late_binding {
+
 class Animal {
  public:
-  virtual ~Animal() = default;
-  virtual void speak() {  // Virtual!
-    std::cout << "Animal speaks\n";
+  Animal() {
+    LOG("Animal() calls describe():");
+    describe();  // intentional: shows that dynamic binding is not used yet
   }
+  virtual ~Animal() = default;
+  Animal(const Animal&) = delete;
+  Animal& operator=(const Animal&) = delete;
+
+  virtual void speak() const { LOG("Animal::speak"); }
+  virtual void describe() const { LOG("  Animal::describe"); }
 };
 
-class Dog : public Animal {
+class Dog final : public Animal {  // final: no class may derive from Dog
  public:
-  void speak() override { std::cout << "Dog barks\n"; }
+  void speak() const override { LOG("Dog::speak"); }
+  void describe() const override { LOG("  Dog::describe"); }
 };
 
 void run() {
-  std::cout << "\n---LateBinding---\n";
-  Animal* a = new Dog();
-  a->speak();  // Late binding
-  delete a;
-}
-}  // namespace late_binding
-}  // namespace
+  LOG_SECTION("Late binding: decided by the dynamic type (virtual)");
 
-class Binding : public IExample {
- public:
-  std::string group() const override { return "core/class"; };
+  const std::unique_ptr<Animal> animal = std::make_unique<Dog>();
+  LOG("  -> Animal::describe ran, because the Dog part did not exist yet");
 
-  std::string name() const override { return "Binding"; };
-  std::string description() const override { return "Binding examples"; };
+  LOG("animal->speak() through a pointer to Animal:");
+  animal->speak();
+  LOG("animal->describe() after construction:");
+  animal->describe();
 
-  void execute() override {
-    early_binding::run();
-    late_binding::run();
-  };
-};
+  LOG_S("sizeof(early_binding::Animal) = " << sizeof(early_binding::Animal)
+                                           << " (no virtual functions)");
+  LOG_S("sizeof(late_binding::Animal)  = " << sizeof(Animal)
+                                           << " (hidden vtable pointer)");
+}
+
+}  // namespace late_binding
 
-REGISTER_EXAMPLE(Binding);
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE("Binding",
+            "early (static) vs late (virtual) binding, hiding vs overriding") {
+  early_binding::run();
+  late_binding::run();
+}
diff --git a/src/core/class/Constructor.cpp b/src/core/class/Constructor.cpp
index f203c8c..ff9dacb 100644
--- a/src/core/class/Constructor.cpp
+++ b/src/core/class/Constructor.cpp
@@ -1,324 +1,323 @@
-// cppcheck-suppress-file [unusedVariable,unreadVariable]
-
-#include <iostream>
-
-// NOTE: We can throw an exception in a constructor to signal an error,
-// and then catch that error using a standard try-catch block
-// where the object is being instantiated.
-
-// **1. Members initializer list constructor**
-namespace initializer_list {
-class Constructor {
- private:
-  int x_, y_, z_;
-
+// -----------------------------------------------------------------------------
+// Constructors
+//
+//   1. Member initializer list : initialize members before the body runs
+//   2. Default constructor     : callable without arguments
+//   3. Delegating constructor  : one constructor forwards to another (C++11)
+//   4. Copy constructor        : T(const T&) creates an independent copy
+//   5. Move constructor        : T(T&&) steals the resources of an rvalue
+//   6. explicit                : forbids implicit conversions via a constructor
+//
+// Notes:
+//   - Members are initialized in DECLARATION order, whatever the order of the
+//     initializer list (-Wreorder warns about mismatches).
+//   - A constructor can throw to report failure; the object then never exists.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/constructor
+// -----------------------------------------------------------------------------
+
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+namespace member_initializer_list {
+
+class Point3D {
  public:
-  Constructor(int x, int y) : x_(x), y_(y) {
-    std::cout << "Called Constructor(int x, int y) : x_(x), y_(y) \n";
-    // z_{0}; // error, it already initialized, so only can do assigment
-    // z_(0); // error, it already initialized, so only can do assigment
-    z_ = 0;
+  // Preferred: every member is initialized directly with its final value.
+  Point3D(int x, int y, int z) : x_{x}, y_{y}, z_{z} {
+    LOG("Point3D(int, int, int) : x_{x}, y_{y}, z_{z}");
   }
 
-  // using brace init
-  Constructor(int x, int y, int z) : x_{x}, y_{y}, z_{z} {
-    std::cout << "Called Constructor(int x, int y, int z) : x_{x}, y_{y}, "
-                 "z_{z} \n";
-  }
-
-  // default arguments : must always be the RIGHTMOST parameters
-  explicit Constructor(int x = 1) {
-    std::cout << "Called Constructor(int x = 1) \n";
+  // Works for ints, but members are default-initialized first and assigned in
+  // the body. const members and references cannot be assigned, so they MUST
+  // use the initializer list.
+  Point3D(int x, int y) {
+    LOG("Point3D(int, int) assigns in the body");
     x_ = x;
-    y_ = 0;
+    y_ = y;
     z_ = 0;
   }
 
-  // Constructor() = default; error:
-  // ‘InitializerList::Constructor::Constructor(int)’ cannot be overloaded
-  // with ‘InitializerList::Constructor::Constructor(int x = 1)’
-
   void print() const {
-    std::cout << "x_ = " << x_ << ", y_ = " << y_ << ", z_ = " << z_ << "\n";
+    LOG_S("  -> {" << x_ << ", " << y_ << ", " << z_ << "}");
   }
-};
 
-void constructers() {
-  std::cout << "\n--- InitializerList Constructer Examples ---\n";
-  Constructor obj;
-  Constructor obj1 = Constructor(1, 2);
-  obj1.print();
+ private:
+  int x_;
+  int y_;
+  int z_;
+};
 
-  Constructor obj2 = Constructor(3, 4, 5);
-  obj2.print();
+void run() {
+  LOG_SECTION("1. Member initializer list");
+  const Point3D a(1, 2, 3);
+  a.print();
+  const Point3D b(4, 5);
+  b.print();
 }
-}  // namespace initializer_list
 
-// **2. Default constructor**
-// - It is a constructor that accepts no arguments.
-// - Generated if no constructors are declared
-// - Initializes members: basic types uninitialized, class types call their default constructor
+}  // namespace member_initializer_list
+
 namespace default_constructor {
-class UConstructors {
+
+/// No constructor declared: the compiler generates Implicit().
+class Implicit {
  public:
-  // User-defined default constructor without argument
-  UConstructors() { std::cout << "Called UConstructors() \n"; }
+  int value{7};  // default member initializer
 };
 
-class IConstructors {
+/// Declaring any constructor suppresses the implicit default constructor,
+/// `= default` brings it back.
+class Defaulted {
  public:
-  // Implicit default constructor is generated by the compiler when the class
-  // has no user-declared constructors
+  Defaulted() = default;
+  explicit Defaulted(double value) : value_{value} {}
+  double value() const { return value_; }
+
+ private:
+  double value_{1.5};
 };
 
-class EConstructors {
+class WithDefaultArgument {
  public:
-  // we already create the constructor ourselves
-  //  EConstructors(int a)
-  explicit EConstructors(float /*a*/)  // explicit ->
-                                       // EConstructors obj2 = 1; [ERROR]
-
-  {
-    std::cout << "Called explicit EConstructors(int a) \n";
+  // Default arguments must be the rightmost parameters. This constructor is
+  // also the default constructor, so `WithDefaultArgument() = default;` would
+  // be ambiguous.
+  explicit WithDefaultArgument(int x = 1) : x_{x} {
+    LOG_S("WithDefaultArgument(int x = 1), x = " << x_);
   }
 
-  // Explicit default constructor : also want the compiler to generate the
-  // default constructor.
-  EConstructors() = default;
+ private:
+  int x_;
 };
 
-void constructers() {
-  std::cout << "\n--- Default Constructer Examples ---\n";
-  UConstructors obj1;
-  //   UConstructors obj2(); // wrong, this is function declare
-  // FYI:
-  // void outer()
-  // {
-  //     void helper();
-  //     helper(); // defined later in the same file
-  // }
+void run() {
+  LOG_SECTION("2. Default constructor");
 
-  UConstructors obj3{};
+  const Implicit implicit;
+  LOG_S("Implicit implicit;      value = " << implicit.value);
 
-  IConstructors obj4;
-  IConstructors obj6{};
+  const Defaulted defaulted;
+  const Defaulted from_double{2.5};
+  LOG_S("Defaulted defaulted;    value = " << defaulted.value());
+  LOG_S("Defaulted{2.5};         value = " << from_double.value());
 
-  EConstructors obj7;
-  EConstructors obj9{};
+  [[maybe_unused]] const WithDefaultArgument uses_default;
+  [[maybe_unused]] const WithDefaultArgument uses_value{5};
 
-  EConstructors obj10(1.2);
-  EConstructors obj11{2};
+  // Implicit oops();  // most vexing parse: declares a function, not an object
 }
+
 }  // namespace default_constructor
 
-// **3. Delegate constructor: allow to delegate initialization to another**
-// constructor Never generated automatically
-namespace delegate {
-class Constructor {
- private:
-  int x_;
-  int y_;
+namespace delegating {
 
+class Rectangle {
  public:
-  Constructor(int x, int y) : x_{x}, y_{y} {
-    std::cout << "Called  Constructor(int x, int y) : x_{x}, y_{y} \n";
+  Rectangle(int width, int height) : width_{width}, height_{height} {
+    LOG("Rectangle(int, int)  <- does the real work");
   }
-
-  explicit Constructor(int x) : Constructor{x, 1} {
-    std::cout << "Called   Constructor(int x):Constructor(x,0) \n";
+  explicit Rectangle(int side) : Rectangle{side, side} {
+    LOG("Rectangle(int)       <- delegates to Rectangle(int, int)");
   }
-
-  Constructor() : Constructor(0) {
-    std::cout << "Called    Constructor() : Constructor(0) \n";
+  Rectangle() : Rectangle{1} {
+    LOG("Rectangle()          <- delegates to Rectangle(int)");
   }
 
-  void print() const { std::cout << "x_ = " << x_ << ", y_ = " << y_ << "\n"; }
+  int area() const { return width_ * height_; }
+
+ private:
+  int width_;
+  int height_;
 };
 
-void constructors() {
-  std::cout << "\n--- Delegate Constructer Examples ---\n";
-  Constructor obj1 = Constructor();
-  obj1.print();
+void run() {
+  LOG_SECTION("3. Delegating constructor");
+  const Rectangle unit;
+  LOG_S("area = " << unit.area());
 }
-}  // namespace delegate
-
-// **4.  Copy constructor:  initialize an copy object with an existing object**
-// - Generated if no copy/move constructor or `destructor` is declared
-// - Performs memberwise (shallow) copy
-//  * Copy constructor
-//      Object obj1 = obj2
-//      Object obj1(obj2)
-//      Object obj1{obj2}
-//  * Copy assigment
-//      obj1 = obj1
+
+}  // namespace delegating
+
 namespace copy {
-class IConstructor  // C++ will create a public implicit copy constructor for us
-                    // if we do not provide a one.
-{
- private:
-  int x_;
-  int y_;
 
+/// The compiler generates a member-wise copy constructor.
+class Implicit {
  public:
-  IConstructor(int x, int y) : x_{x}, y_{y} {
-    std::cout << "Called  IConstructor(int x, int y) : x_{x}, y_{y} \n";
-  }
-
-  void print() const { std::cout << "x_ = " << x_ << ", y_ = " << y_ << "\n"; }
-};
+  Implicit(int x, int y) : x_{x}, y_{y} {}
+  void print() const { LOG_S("  {" << x_ << ", " << y_ << "}"); }
 
-class EConstructor  // explicitly define our own copy constructor
-{
  private:
   int x_;
   int y_;
+};
 
+class Tracked {
  public:
-  EConstructor(int x, int y) : x_{x}, y_{y} {
-    std::cout << "Called  IConstructor(int x, int y) : x_{x}, y_{y} \n";
+  explicit Tracked(std::string name) : name_{std::move(name)} {
+    LOG_S("Tracked(std::string)            " << name_);
   }
-
-  // Implicit Copy constructor if there is no desconstrutor
-  // using `default` keyword
-  // EConstructor(const EConstructor &ref) = default;
-
-  // Explicit Copy constructor (a=EConstructor(b))
-  EConstructor(const EConstructor& ref) : x_{ref.x_}, y_{ref.x_} {
-    std::cout << "Called  EConstructor(const EConstructor& ref) : x_{ref.x_}, "
-                 "y_{ref.x_} \n";
+  Tracked(const Tracked& other) : name_{other.name_ + " (copy)"} {
+    LOG_S("Tracked(const Tracked&)         " << name_);
   }
-
-  // Copy assigment (a=b)
-  EConstructor& operator=(const EConstructor& other) {
-    if (this != &other) {
-      this->x_ = other.x_;
-      this->y_ = other.y_;
+  Tracked& operator=(const Tracked& other) {
+    LOG_S("operator=(const Tracked&)       " << other.name_);
+    if (this != &other) {  // self-assignment guard
+      name_ = other.name_;
     }
     return *this;
   }
+  ~Tracked() = default;
 
-  void print() const { std::cout << "x_ = " << x_ << ", y_ = " << y_ << "\n"; }
-};
-
-class DeConstructor  // Delete the copy constructor so no copies can be made
-{
  private:
-  int x_;
-  int y_;
+  std::string name_;
+};
 
+/// `= delete` removes the copy operations: this type can not be copied.
+class NonCopyable {
  public:
-  DeConstructor(int x, int y) : x_{x}, y_{y} {
-    std::cout << "Called  DeConstructor(int x, int y) : x_{x}, y_{y} \n";
-  }
+  NonCopyable() = default;
+  NonCopyable(const NonCopyable&) = delete;
+  NonCopyable& operator=(const NonCopyable&) = delete;
+};
 
-  // using `delete` keyword
-  DeConstructor(const DeConstructor& fraction) = delete;
+void takeByValue(const Tracked /*copy*/) {}
 
-  void print() const { std::cout << "x_ = " << x_ << ", y_ = " << y_ << "\n"; }
-};
+void run() {
+  LOG_SECTION("4. Copy constructor and copy assignment");
+
+  const Implicit a(1, 2);
+  const Implicit b{a};  // compiler-generated copy
+  b.print();
 
-void constructors() {
-  std::cout << "\n--- Copy Constructer Examples ---\n";
-  IConstructor obj1 = IConstructor(1, 2);
-  IConstructor obj2{obj1};
-  obj1.print();
-  obj2.print();
-
-  EConstructor obj3 = EConstructor(3, 4);
-  EConstructor obj4{obj3};
-  obj3.print();
-  obj4.print();
-
-  DeConstructor obj5 = DeConstructor(5, 6);
-  // DeConstructor obj6{obj5}; error
-  obj5.print();
+  const Tracked original{"original"};
+  LOG("Tracked copy1 = original;");
+  const Tracked copy1 = original;
+  LOG("Tracked copy2{original};");
+  const Tracked copy2{original};
+  LOG("takeByValue(original);  <- passing by value copies too");
+  takeByValue(original);
+  LOG("copy3 = original;       <- assignment to an existing object");
+  Tracked copy3{"copy3"};
+  copy3 = original;
+
+  [[maybe_unused]] const NonCopyable unique;
+  // NonCopyable duplicate{unique};  // error: use of deleted function
 }
+
 }  // namespace copy
 
-// **4. Move Constructor**
-// - Move constructor and move assignment transfer resource ownership
-// - from one object to another. This is usually cheaper than copying.
-// - A move constructor is implicitly generated only if no user-declared
-//   copy constructor, move constructor, or destructor exists.
 namespace move {
-class Model  // C++ will create a public implicit copy constructor for us if we
-             // do not provide a one.
-{
- private:
-  int x_;
-  int y_;
 
+/// Owns a (potentially large) buffer. Moving hands the buffer over instead of
+/// copying every element.
+class Buffer {
  public:
-  Model(int x, int y) : x_{x}, y_{y} { std::cout << "Call constructor \n"; }
+  explicit Buffer(std::size_t size) : data_(size) {}
 
-  ~Model() { std::cout << "Call destructor \n"; }
+  Buffer(const Buffer& other) : data_{other.data_} {
+    LOG_S("Buffer(const Buffer&)  copied " << data_.size() << " elements");
+  }
 
-  Model(const Model& other) : Model(other.x_, other.y_) {
-    std::cout << "Call copy constructor \n";
+  Buffer(Buffer&& other) noexcept : data_{std::move(other.data_)} {
+    LOG_S("Buffer(Buffer&&)       took over " << data_.size() << " elements");
   }
 
-  Model& operator=(const Model& other) {
-    std::cout << "Call copy assigment \n";
+  Buffer& operator=(const Buffer& other) {
+    LOG("operator=(const Buffer&)");
     if (this != &other) {
-      this->x_ = other.x_;
-      this->y_ = other.y_;
+      data_ = other.data_;
     }
     return *this;
   }
 
-  Model(Model&& source) noexcept : x_(source.x_), y_(source.y_) {
-    std::cout << "Call move constructor\n";
-
-    // reset source
-    source.x_ = 0;
-    source.y_ = 0;
-  }
-
-  Model& operator=(Model&& source) noexcept {
-    std::cout << "Call move assigment \n";
-    if (this != &source) {
-      this->x_ = source.x_;
-      this->y_ = source.y_;
-
-      // reset source
-      source.x_ = 0;
-      source.y_ = 0;
-    }
-
+  Buffer& operator=(Buffer&& other) noexcept {
+    LOG("operator=(Buffer&&)");
+    data_ = std::move(other.data_);
     return *this;
   }
 
-  void print() const { std::cout << "x_ = " << x_ << ", y_ = " << y_ << "\n"; }
-};
+  ~Buffer() = default;
 
-void constructers() {
-  std::cout << "\n--- Move Constructor Examples ---\n";
-  Model a(10, 20);
+  std::size_t size() const { return data_.size(); }
 
-  std::cout << "\nCase 1: Model b = std::move(a);\n";
-  Model b = std::move(a);  // move constructor
+ private:
+  std::vector<int> data_;
+};
 
-  std::cout << "\nCase 2: Model c(5,6); c = std::move(b);\n";
-  Model c(5, 6);
-  c = std::move(b);  // move assignment
-  std::cout << "\n";
+void run() {
+  LOG_SECTION("5. Move constructor and move assignment");
+
+  Buffer source(1000);
+  LOG("Buffer copied = source;");
+  const Buffer copied = source;
+  LOG("Buffer moved = std::move(source);");
+  const Buffer moved = std::move(source);
+  // A moved-from object is valid but unspecified; std::vector leaves it empty.
+  LOG_S("source.size() = " << source.size()
+                           << ", moved.size() = " << moved.size());
+
+  LOG("target = Buffer(10);   <- a temporary is an rvalue, so it is moved");
+  Buffer target(1);
+  target = Buffer(10);
+  LOG_S("target.size() = " << target.size()
+                           << ", copied.size() = " << copied.size());
 }
+
 }  // namespace move
 
-#include "ExampleRegistry.h"
+namespace explicit_constructor {
 
-class Constructor : public IExample {
+class Seconds {
  public:
-  std::string group() const override { return "core/class"; }
-  std::string name() const override { return "Constructor"; }
-  std::string description() const override { return ""; }
-  void execute() override {
-    initializer_list::constructers();
-    default_constructor::constructers();
-    delegate::constructors();
-    copy::constructors();
-    move::constructers();
-  }
+  Seconds(double value) : value_{value} {}  // NOLINT: implicit on purpose
+  double value() const { return value_; }
+
+ private:
+  double value_;
 };
 
-REGISTER_EXAMPLE(Constructor);
+class Meters {
+ public:
+  explicit Meters(double value) : value_{value} {}
+  double value() const { return value_; }
+
+ private:
+  double value_;
+};
+
+void sleepFor(Seconds seconds) {
+  LOG_S("sleepFor(" << seconds.value() << " s)");
+}
+
+void walk(Meters distance) {
+  LOG_S("walk(" << distance.value() << " m)");
+}
+
+void run() {
+  LOG_SECTION("6. explicit constructors");
+  sleepFor(1.5);  // silently converts double -> Seconds
+  // walk(2.0);   // error: Meters(double) is explicit
+  walk(Meters{2.0});  // the conversion must be spelled out
+}
+
+}  // namespace explicit_constructor
+
+}  // namespace
+
+LAB_EXAMPLE("Constructor",
+            "initializer lists, default, delegating, copy, move and explicit "
+            "constructors") {
+  member_initializer_list::run();
+  default_constructor::run();
+  delegating::run();
+  copy::run();
+  move::run();
+  explicit_constructor::run();
+}
diff --git a/src/core/class/Destructor.cpp b/src/core/class/Destructor.cpp
index c8b2249..bde7dfe 100644
--- a/src/core/class/Destructor.cpp
+++ b/src/core/class/Destructor.cpp
@@ -1,72 +1,126 @@
-#include <iostream>
-
-// ** 1. Basic Destructor**
-// - Generated if no destructor is declared
-// - Calls destructors of members automatically
-// - Does not free dynamically allocated memory unless you write it
-namespace basic {
-class Destructor {
+// -----------------------------------------------------------------------------
+// Destructors
+//
+//   - Run automatically when an object's lifetime ends (end of scope, delete,
+//     destruction of the owning object, stack unwinding after a throw).
+//   - Destruction order is the REVERSE of construction order:
+//     derived body -> members (reverse declaration order) -> base classes.
+//   - A class meant to be deleted through a base pointer needs a virtual
+//     destructor. Without it, `delete base_pointer` is undefined behavior.
+//   - RAII: acquire a resource in the constructor and release it in the
+//     destructor, so it can never be forgotten - not even when an exception
+//     is thrown.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/destructor
+// -----------------------------------------------------------------------------
+
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+class Member {
  public:
-  Destructor() { std::cout << "Called Destructor() \n"; }
+  explicit Member(std::string name) : name_{std::move(name)} {
+    LOG_S("  Member(" << name_ << ")");
+  }
+  ~Member() { LOG_S("  ~Member(" << name_ << ")"); }
+  Member(const Member&) = delete;
+  Member& operator=(const Member&) = delete;
 
-  ~Destructor() { std::cout << "Called ~Destructor() \n"; }
+ private:
+  std::string name_;
+};
 
-  // Using `default` keyword
-  // ~Destructor() = default;
+namespace order {
+
+class Base {
+ public:
+  Base() { LOG("  Base()"); }
+  ~Base() { LOG("  ~Base()"); }
+  Base(const Base&) = delete;
+  Base& operator=(const Base&) = delete;
+};
+
+class Derived : public Base {
+ public:
+  Derived() { LOG("  Derived()"); }
+  ~Derived() { LOG("  ~Derived()"); }
+  Derived(const Derived&) = delete;
+  Derived& operator=(const Derived&) = delete;
 
-  // Using `delete` // I forbid this destructor
-  // ~Destructor() = delete;
+ private:
+  Member first_{"first"};
+  Member second_{"second"};
 };
 
-void destructers() {
-  std::cout << "\n--- Basic Destructer Examples ---\n";
-  { Destructor obj; }
+void run() {
+  LOG_SECTION("Construction and destruction order");
+  {
+    const Derived derived;
+    LOG("-- leaving the scope --");
+  }
 }
-}  // namespace basic
 
-// **2. Virtual Destructor**
-namespace virtual_desctructor {
-class DestructorBase  // final => cannot inherit
-{
- public:
-  DestructorBase() { std::cout << "Called DestructorBase() \n"; }
+}  // namespace order
 
-  virtual ~DestructorBase() { std::cout << "Called ~DestructorBase() \n"; }
+namespace virtual_destructor {
 
-  // Using `default` keyword
-  // ~DestructorBase() = default;
+class Base {
+ public:
+  Base() = default;
+  virtual ~Base() { LOG("  ~Base()"); }
+  Base(const Base&) = delete;
+  Base& operator=(const Base&) = delete;
 };
 
-class DestructorDerived : public DestructorBase {
+class Derived : public Base {
  public:
-  DestructorDerived() { std::cout << "Called DestructorDerived() \n"; }
+  ~Derived() override { LOG("  ~Derived()  <- runs because ~Base is virtual"); }
 
-  ~DestructorDerived() override {
-    std::cout << "Called ~DestructorDerived() \n";
-  }
+ private:
+  Member resource_{"resource owned by Derived"};
 };
 
-void destructers() {
-  std::cout << "\n--- Virtual Destructer Examples ---\n";
-  DestructorDerived* derived = {new DestructorDerived()};
-  DestructorBase* base{derived};
-  delete base;
-  // without virtual -> only call ~DestructorBase()
-  // with virtual -> call ~DestructorBase() && ~DestructorDerived()
+void run() {
+  LOG_SECTION("Virtual destructor");
+  LOG("std::unique_ptr<Base> ptr = std::make_unique<Derived>(); ptr.reset();");
+  std::unique_ptr<Base> ptr = std::make_unique<Derived>();
+  ptr.reset();
+  // If ~Base() were not virtual, deleting a Derived through a Base pointer
+  // would be undefined behavior: typically ~Derived and its members never run
+  // and their resources leak.
 }
-}  // namespace virtual_desctructor
 
-#include "ExampleRegistry.h"
+}  // namespace virtual_destructor
 
-class Destructor : public IExample {
- public:
-  std::string group() const override { return "core/class"; }
-  std::string name() const override { return "Destructor"; }
-  std::string description() const override { return ""; }
-  void execute() override {
-    basic::destructers();
-    virtual_desctructor::destructers();
+namespace raii {
+
+void run() {
+  LOG_SECTION("RAII and stack unwinding");
+  try {
+    const Member lock{"lock"};
+    const Member connection{"connection"};
+    LOG("throwing while both resources are held...");
+    throw std::runtime_error("something failed");
+  } catch (const std::exception& e) {
+    LOG_S("caught '" << e.what() << "' - both destructors already ran");
   }
-};
+}
+
+}  // namespace raii
 
-REGISTER_EXAMPLE(Destructor);
+}  // namespace
+
+LAB_EXAMPLE(
+    "Destructor",
+    "destruction order, virtual destructors, RAII and stack unwinding") {
+  order::run();
+  virtual_destructor::run();
+  raii::run();
+}
diff --git a/src/core/class/Encapsulation.cpp b/src/core/class/Encapsulation.cpp
index 98cca75..6a712da 100644
--- a/src/core/class/Encapsulation.cpp
+++ b/src/core/class/Encapsulation.cpp
@@ -1,82 +1,97 @@
-// Encapsulation means grouping data and the functions that use that data
-// inside a single unit, usually a class.
-
-// Benefits of encapsulation:
-
-// 1. Data Hiding
-// The internal data of a class can be hidden from outside code.
-// Other code cannot directly modify it, which helps protect the object's state.
-
-// 2. Modularity
-// Data and related functions are organized in one place.
-// This makes the code easier to understand, maintain, and test.
-
-// 3. Flexibility and Maintainability
-// The internal implementation of a class can change without affecting
-// the code that uses it, as long as the public interface stays the same.
-
-// 4. Improved Security
-// Restricting access to internal data helps prevent unintended or incorrect use.
-
-// Implementation in C++:
-// Encapsulation is implemented using access specifiers such as
-// `private` and `protected` to restrict access to class members.
-// Public getter and setter functions can be used to access or modify
-// the internal data in a controlled way.
-
-#include <ExampleRegistry.h>
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Encapsulation
+//
+// Bundle data with the functions that use it, and hide the data behind a
+// small public interface.
+//
+// Benefits:
+//   1. Data hiding    : outside code cannot put the object into an invalid state.
+//   2. Invariants     : the class checks every change (e.g. balance >= 0).
+//   3. Modularity     : data and related functions live in one place.
+//   4. Flexibility    : the implementation can change without touching callers,
+//                       as long as the public interface stays the same.
+//
+// In C++: `private` / `protected` restrict access; `class` members are
+// private by default, `struct` members are public by default.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/the-benefits-of-data-hiding-encapsulation/
+// -----------------------------------------------------------------------------
+
+#include <stdexcept>
 #include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Person {
- private:
-  std::string name_;
-  int age_;
 
- public:
-  Person(const std::string& name, int age) : name_(name), age_(age) {}
+/// Without encapsulation anyone can break the rules.
+struct OpenAccount {
+  std::string owner;
+  long balance_cents{0};  // nothing stops `balance_cents = -1'000'000;`
+};
 
-  std::string getName() const { return name_; }
-  int getAge() const { return age_; }
+/// Invariant: the balance is never negative.
+class BankAccount {
+ public:
+  explicit BankAccount(std::string owner) : owner_{std::move(owner)} {}
 
-  void setAge(int age) {
-    if (age >= 0) {
-      age_ = age;
+  void deposit(long cents) {
+    if (cents <= 0) {
+      throw std::invalid_argument("deposit must be positive");
     }
+    balance_cents_ += cents;
   }
 
-  void introduce() const {
-    std::cout << "Name: " << name_ << ", Age: " << age_ << '\n';
+  /// Returns false instead of letting the balance go negative.
+  bool withdraw(long cents) {
+    if (cents <= 0 || cents > balance_cents_) {
+      return false;
+    }
+    balance_cents_ -= cents;
+    return true;
   }
-};
-
-void run() {
-  Person person("Alice", 25);
 
-  std::cout << "Initial state:\n";
-  person.introduce();
+  // Getters give read-only access. Returning `const std::string&` avoids a copy.
+  const std::string& owner() const { return owner_; }
+  long balance() const { return balance_cents_; }
 
-  std::cout << "\nUpdating age through setter:\n";
-  person.setAge(30);
-  person.introduce();
+ private:
+  std::string owner_;
+  long balance_cents_{0};
+};
 
-  std::cout << "\nAccessing data through getters:\n";
-  std::cout << "Name: " << person.getName() << '\n';
-  std::cout << "Age: " << person.getAge() << '\n';
+void run() {
+  LOG_SECTION("Without encapsulation");
+  OpenAccount open{"Bob", 100};
+  open.balance_cents = -1'000'000;  // compiles - the object is now invalid
+  LOG_S(open.owner << "'s balance: " << open.balance_cents << " cents");
+
+  LOG_SECTION("With encapsulation");
+  BankAccount account{"Alice"};
+  account.deposit(2'500);
+  LOG_S(account.owner() << " deposited 2500, balance: " << account.balance());
+
+  const bool ok = account.withdraw(1'000);
+  LOG_S("withdraw(1000) -> " << std::boolalpha << ok
+                             << ", balance: " << account.balance());
+
+  const bool too_much = account.withdraw(99'999);
+  LOG_S("withdraw(99999) -> " << std::boolalpha << too_much
+                              << ", balance unchanged: " << account.balance());
+
+  try {
+    account.deposit(-5);
+  } catch (const std::invalid_argument& e) {
+    LOG_S("deposit(-5) rejected: " << e.what());
+  }
+  // account.balance_cents_ = -1;  // error: 'balance_cents_' is private
 }
 
 }  // namespace
 
-class Encapsulation : public IExample {
- public:
-  std::string group() const override { return "core/class"; }
-  std::string name() const override { return "Encapsulation"; }
-  std::string description() const override {
-    return "Examples demonstrating encapsulation in C++";
-  }
-
-  void execute() override { run(); }
-};
-
-REGISTER_EXAMPLE(Encapsulation);
\ No newline at end of file
+LAB_EXAMPLE("Encapsulation",
+            "private data, class invariants, getters and setters") {
+  run();
+}
diff --git a/src/core/class/Friend.cpp b/src/core/class/Friend.cpp
index 66e8d7f..4538fe8 100644
--- a/src/core/class/Friend.cpp
+++ b/src/core/class/Friend.cpp
@@ -1,125 +1,143 @@
-// cppcheck-suppress-file [functionStatic]
-#include <iostream>
-#include "ExampleRegistry.h"
+// -----------------------------------------------------------------------------
+// Friends
+//
+// A friend declaration grants a function or a class access to the private and
+// protected members of the class that declares it.
+//
+//   1. Friend non-member function : typical for operator<< / operator>>
+//   2. Friend member function     : one specific member of another class
+//   3. Friend class               : every member of another class
+//
+// Friendship is granted, never taken; it is not inherited and not transitive.
+// Use it sparingly - it widens the set of code that depends on private data.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/friend-non-member-functions/
+// -----------------------------------------------------------------------------
+
+#include <ostream>
+#include <sstream>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
 namespace {
-namespace NonMember {
 
-class Accumulator {
- private:
-  int value_{0};
+namespace non_member {
 
+class Accumulator {
  public:
   void add(int value) { value_ += value; }
 
-  // print out the Accumulator use <<
-  // S1: Overloading
+  // As a MEMBER, operator<< must be called as `accumulator << stream`,
+  // because the left operand of a member operator is always *this.
   std::ostream& operator<<(std::ostream& os) const {
-    os << "S1: " << value_ << "\n";
-    return os;
+    return os << "member: " << value_;
   }
 
-  // S2: Friend
-  friend std::ostream& operator<<(std::ostream& os, const Accumulator& acc);
+  // As a friend NON-MEMBER, the natural `stream << accumulator` works and the
+  // function can still read value_.
+  friend std::ostream& operator<<(std::ostream& os,
+                                  const Accumulator& accumulator);
+
+ private:
+  int value_{0};
 };
 
-std::ostream& operator<<(std::ostream& os, const Accumulator& acc) {
-  os << "S2: " << acc.value_ << "\n";
-  return os;
+std::ostream& operator<<(std::ostream& os, const Accumulator& accumulator) {
+  return os << "friend non-member: " << accumulator.value_;
 }
 
 void run() {
-  Accumulator acc{};
-  acc.add(5);
+  LOG_SECTION("1. Friend non-member function");
+  Accumulator accumulator;
+  accumulator.add(5);
+
+  std::ostringstream backwards;
+  accumulator << backwards;  // works, but reads backwards
+  LOG_S("accumulator << stream  -> " << backwards.str());
+  LOG_S("stream << accumulator  -> " << accumulator);
+}
 
-  // Use S1:
-  acc << std::cout;  // backward and weird
+}  // namespace non_member
 
-  // Use S2: expect std::cout << acc;
-  std::cout << acc;  // good
-}
+namespace friend_member {
 
-}  // namespace NonMember
+class Accumulator;  // forward declaration
 
-namespace Member {
-class Accumulator;
 class Display {
  public:
-  void f_display(const Accumulator& acc) const;
-
-  void display(const Accumulator& acc) const;
+  void show(const Accumulator& accumulator) const;       // is a friend
+  void tryToShow(const Accumulator& accumulator) const;  // is not
 };
 
 class Accumulator {
- private:
-  int value_{0};
-
  public:
   void add(int value) { value_ += value; }
 
-  // Make Display class a friend of Acc
-  friend void Display::f_display(const Accumulator& acc) const;
+  // Only Display::show gets access, not the whole Display class.
+  friend void Display::show(const Accumulator& accumulator) const;
+
+ private:
+  int value_{0};
 };
 
-void Display::f_display(const Accumulator& acc) const {
-  std::cout << "S4: " << acc.value_ << "\n";
+void Display::show(const Accumulator& accumulator) const {
+  LOG_S("Display::show reads value_ = " << accumulator.value_);
 }
 
-void Display::display(const Accumulator& acc) const {
-  // std::cout << "S4: " << acc.value_ << "\n"; // cannot access
+void Display::tryToShow(const Accumulator& /*accumulator*/) const {
+  // LOG_S(accumulator.value_);  // error: 'value_' is private
+  LOG("Display::tryToShow has no access to value_");
 }
 
 void run() {
-  Accumulator acc{};
-  acc.add(-99);
-  Display d{};
-  d.display(acc);
-  d.f_display(acc);
+  LOG_SECTION("2. Friend member function");
+  Accumulator accumulator;
+  accumulator.add(-99);
+  const Display display;
+  display.show(accumulator);
+  display.tryToShow(accumulator);
 }
-}  // namespace Member
 
-}  // namespace
+}  // namespace friend_member
 
-namespace Class {
+namespace friend_class {
 
-class Display;
 class Accumulator {
- private:
-  int value_{0};
-
  public:
   void add(int value) { value_ += value; }
 
-  // Make Display class a friend of Acc
-  friend class Display;
+ private:
+  friend class Display;  // every member function of Display has access
+  int value_{0};
 };
 
 class Display {
  public:
-  void display(const Accumulator& acc) {
-    std::cout << "S3: " << acc.value_ << "\n";
+  void show(const Accumulator& accumulator) const {
+    LOG_S("Display::show reads value_ = " << accumulator.value_);
+  }
+  void showTwice(const Accumulator& accumulator) const {
+    LOG_S("Display::showTwice reads value_ * 2 = " << accumulator.value_ * 2);
   }
 };
 
 void run() {
-  Accumulator acc{};
-  acc.add(99);
-  Display d{};
-  d.display(acc);
+  LOG_SECTION("3. Friend class");
+  Accumulator accumulator;
+  accumulator.add(99);
+  const Display display;
+  display.show(accumulator);
+  display.showTwice(accumulator);
 }
-}  // namespace Class
-
-class Friend : public IExample {
- public:
-  std::string group() const override { return "core/class"; };
 
-  std::string name() const override { return "Friend"; };
-  std::string description() const override { return "Friend examples"; };
+}  // namespace friend_class
 
-  void execute() override {
-    NonMember::run();
-    Member::run();
-    Class::run();
-  };
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Friend);
\ No newline at end of file
+LAB_EXAMPLE("Friend",
+            "friend functions, friend member functions and friend classes") {
+  non_member::run();
+  friend_member::run();
+  friend_class::run();
+}
diff --git a/src/core/class/README.md b/src/core/class/README.md
index 2446c72..f467c1b 100644
--- a/src/core/class/README.md
+++ b/src/core/class/README.md
@@ -1,4 +1,19 @@
 # Classes
+
+| Example | Topic |
+|---|---|
+| `Encapsulation` | private data, invariants, getters and setters |
+| `Constructor` | initializer lists, default/delegating/copy/move, `explicit` |
+| `Destructor` | destruction order, virtual destructors, RAII, stack unwinding |
+| `ShallowDeepCopying` | why copying a pointer member is not copying the data |
+| `RuleOfThreeFiveZero` | which special member functions to write, and when to write none |
+| `Relationship` | composition, aggregation, association, dependency, nesting |
+| `Friend` | friend functions, friend members, friend classes |
+| `Binding` | early (static) vs late (virtual) binding, hiding vs overriding |
+| `VirtualBase` | the diamond problem and virtual inheritance |
+
+---
+# Classes
 - **A class** is a user-defined blueprint used to create objects. It defines the properties and behaviors that all objects of that type share.
 - **An object** is an instance of a class. It represents a real entity and contains actual values for the class’s attributes.
 - **An instance** is a specific object created from a class. (In practice, “object” and “instance” are often used interchangeably.)
diff --git a/src/core/class/Relationship.cpp b/src/core/class/Relationship.cpp
index a48482b..76a8656 100644
--- a/src/core/class/Relationship.cpp
+++ b/src/core/class/Relationship.cpp
@@ -1,158 +1,237 @@
-// cppcheck-suppress-file [functionStatic]
-#include <iostream>
-#include "ExampleRegistry.h"
+// -----------------------------------------------------------------------------
+// Relationships between classes (see README.md in this folder for UML)
+//
+//   Composition  "part-of"    : the whole owns the part; they live and die together
+//   Aggregation  "has-a"      : the whole uses a part it does not own
+//   Association  "uses-a"     : two otherwise independent objects collaborate
+//   Dependency   "depends-on" : a class uses another only temporarily
+//   Container    "holds many" : stores values (composition) or pointers (aggregation)
+//   Nested class               : a type defined inside another type
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/object-relationships/
+// -----------------------------------------------------------------------------
+
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
 namespace composition {
-// Engine is a part of the Car
-// Engine is managed by the Car
+
 class Engine {
  public:
-  Engine() { std::cout << "Engine created\n"; }
-  ~Engine() { std::cout << "Engine destroyed\n"; }
+  Engine() { LOG("  Engine created"); }
+  ~Engine() { LOG("  Engine destroyed"); }
+  Engine(const Engine&) = delete;
+  Engine& operator=(const Engine&) = delete;
 };
 
 class Car {
  public:
-  Car() { std::cout << "Car created\n"; }
-  ~Car() { std::cout << "Car destroyed\n"; }
+  Car() { LOG("  Car created"); }
+  ~Car() { LOG("  Car destroyed"); }
+  Car(const Car&) = delete;
+  Car& operator=(const Car&) = delete;
 
  private:
-  Engine engine_;  // composition
+  Engine engine_;  // composition: created and destroyed together with the Car
 };
 
 void run() {
-  std::cout << "\n---Composition---\n";
-  Car car;
+  LOG_SECTION("Composition (part-of)");
+  const Car car;
+  LOG("-- leaving scope: the Car takes its Engine with it --");
 }
-};  // namespace composition
 
-namespace aggregations {
-// Teacher is a part of the Department
-// Teacher can belong to one or more Department
-// Department does not managed Patient existence
+}  // namespace composition
+
+namespace aggregation {
+
 class Teacher {
  public:
-  std::string name;
-  explicit Teacher(const std::string& n) : name(n) {
-    std::cout << "Teacher created: " << name << "\n";
+  explicit Teacher(std::string name) : name_{std::move(name)} {
+    LOG_S("  Teacher " << name_ << " created");
   }
+  ~Teacher() { LOG_S("  Teacher " << name_ << " destroyed"); }
+  Teacher(const Teacher&) = delete;
+  Teacher& operator=(const Teacher&) = delete;
 
-  ~Teacher() { std::cout << "Teacher destroyed: " << name << "\n"; }
-};
+  const std::string& name() const { return name_; }
 
-class Department {
  private:
-  Teacher* teacher_;  // aggregation
+  std::string name_;
+};
 
+class Department {
  public:
-  explicit Department(Teacher* t) : teacher_(t) {
-    std::cout << "Department created \n";
+  explicit Department(std::string name, const Teacher& teacher)
+      : name_{std::move(name)}, teacher_{&teacher} {
+    LOG_S("  Department " << name_ << " created with " << teacher_->name());
   }
+  ~Department() { LOG_S("  Department " << name_ << " destroyed"); }
+  Department(const Department&) = delete;
+  Department& operator=(const Department&) = delete;
 
-  ~Department() { std::cout << "Department destroyed \n"; }
+ private:
+  std::string name_;
+  const Teacher* teacher_;  // aggregation: points to a Teacher it does NOT own
 };
 
 void run() {
-  std::cout << "\n---Aggregations---\n";
-  Teacher t{"Mr.A"};
+  LOG_SECTION("Aggregation (has-a)");
+  const Teacher teacher{"Mr. A"};
   {
-    Department dep1{&t};
-    Department dep2{&t};
+    const Department math{"Math", teacher};
+    const Department physics{"Physics",
+                             teacher};  // one teacher, two departments
+    LOG("-- departments close --");
   }
+  LOG("-- the teacher still exists --");
 }
-};  // namespace aggregations
 
-// Doctor uses Patient
-// Doctor does not managed Patient existence
-namespace associations {
+}  // namespace aggregation
+
+namespace association {
+
 class Patient {
  public:
-  Patient() { std::cout << "Patient created \n"; }
-  ~Patient() { std::cout << "Patient destroyed \n"; }
-  std::string name;
+  explicit Patient(std::string name) : name_{std::move(name)} {}
+  const std::string& name() const { return name_; }
+
+ private:
+  std::string name_;
 };
 
 class Doctor {
  public:
-  Doctor() { std::cout << "Doctor created \n"; }
-  ~Doctor() { std::cout << "Doctor destroyed \n"; }
-  void treat(const Patient& p) { std::cout << "Treating " << p.name << "\n"; }
+  // The Doctor neither owns nor stores the Patient; they only interact.
+  void treat(const Patient& patient) const {
+    LOG_S("  Treating " << patient.name());
+  }
 };
 
 void run() {
-  std::cout << "\n---Associations---\n";
-  Patient p{};
-  Doctor d{};
-  d.treat(p);
+  LOG_SECTION("Association (uses-a)");
+  const Doctor doctor;
+  const Patient alice{"Alice"};
+  const Patient bob{"Bob"};
+  doctor.treat(alice);
+  doctor.treat(bob);
 }
-}  // namespace associations
 
-// Car creates and uses Logger to log
+}  // namespace association
+
 namespace dependency {
-class Logger {
- public:
-  Logger() { std::cout << "Logger created \n"; }
-  ~Logger() { std::cout << "Logger destroyed \n"; }
 
-  void log(const std::string& msg) { std::cout << msg << std::endl; }
+class FileLogger {
+ public:
+  void write(const std::string& message) const {
+    LOG_S("  [file] " << message);
+  }
 };
 
 class Car {
  public:
-  Car() { std::cout << "Car created \n"; }
-  ~Car() { std::cout << "Car destroyed \n"; }
-
-  void start() {
-    std::cout << "Car started\n";
-    Logger logger;  // dependency
-    logger.log("Log Car started");
+  void start() const {
+    const FileLogger logger;  // dependency: only needed during this call
+    logger.write("Car started");
   }
 };
+
 void run() {
-  std::cout << "\n---Dependency---\n";
-  Car car{};
+  LOG_SECTION("Dependency (depends-on)");
+  const Car car;
   car.start();
 }
+
 }  // namespace dependency
 
 namespace container {
-// class Library1 {
-//  private:
-//   std::vector<std::string> books;  // copy values
-// };
-
-// class Library2 {
-//  private:
-//   std::vector<Teacher*> teachers;  // store pointers
-// };
+
+class Library {
+ public:
+  void addBook(std::string title) { books_.push_back(std::move(title)); }
+  std::size_t size() const { return books_.size(); }
+
+ private:
+  std::vector<std::string> books_;  // stores the values themselves
+};
+
+class School {
+ public:
+  void hire(const aggregation::Teacher& teacher) {
+    teachers_.push_back(&teacher);
+  }
+  void printStaff() const {
+    for (const aggregation::Teacher* teacher : teachers_) {
+      LOG_S("  staff: " << teacher->name());
+    }
+  }
+
+ private:
+  std::vector<const aggregation::Teacher*>
+      teachers_;  // stores non-owning pointers
+};
+
+void run() {
+  LOG_SECTION("Container");
+  Library library;
+  library.addBook("The C++ Programming Language");
+  library.addBook("Effective Modern C++");
+  LOG_S("  library holds " << library.size() << " books (by value)");
+
+  const aggregation::Teacher teacher_b{"Ms. B"};
+  const aggregation::Teacher teacher_c{"Mr. C"};
+  School school;
+  school.hire(teacher_b);
+  school.hire(teacher_c);
+  school.printStaff();
+}
+
 }  // namespace container
 
-namespace inner_class {
+namespace nested {
+
 class Car {
  public:
+  /// Nested class: a type that only makes sense in the context of Car.
   class Engine {
    public:
-    void start();
+    void start() const { LOG("  Car::Engine::start"); }
   };
+
+  void drive() const {
+    engine_.start();
+    LOG("  Car::drive");
+  }
+
+ private:
+  Engine engine_;
 };
-}  // namespace inner_class
-}  // namespace
 
-class Relationship : public IExample {
- public:
-  std::string group() const override { return "core/class"; };
+void run() {
+  LOG_SECTION("Nested (inner) class");
+  const Car car;
+  car.drive();
+  const Car::Engine spare;  // usable from outside because Engine is public
+  spare.start();
+}
 
-  std::string name() const override { return "Relationship"; };
-  std::string description() const override { return "Relationship examples"; };
+}  // namespace nested
 
-  void execute() override {
-    composition::run();
-    aggregations::run();
-    associations::run();
-    dependency::run();
-  };
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Relationship);
\ No newline at end of file
+LAB_EXAMPLE("Relationship",
+            "composition, aggregation, association, dependency, containers, "
+            "nested classes") {
+  composition::run();
+  aggregation::run();
+  association::run();
+  dependency::run();
+  container::run();
+  nested::run();
+}
diff --git a/src/core/class/RoleOfThreeFiveZero.cpp b/src/core/class/RoleOfThreeFiveZero.cpp
deleted file mode 100644
index e055742..0000000
--- a/src/core/class/RoleOfThreeFiveZero.cpp
+++ /dev/null
@@ -1,290 +0,0 @@
-// cppcheck-suppress-file [noCopyConstructor, noOperatorEq, accessMoved]
-
-#include <cstring>
-#include <iostream>
-#include <utility>
-
-namespace {
-namespace problem {
-class Model {
- private:
-  char* cstring_;
-
- public:
-  explicit Model(const char* s = "") : cstring_{nullptr} {
-    if (s) {
-      cstring_ = new char[std::strlen(s) + 1];  // allocate
-      std::strcpy(cstring_, s);                 // populate
-    }
-  }
-
-  // I. destructor
-  ~Model() {
-    // delete[] cstring; // [P2] Double call here
-    std::cout << "Deleted cstring at: " << static_cast<const void*>(cstring_)
-              << "\n";
-  }
-
-  // [P]
-  // What happen if we didn't define
-  // II. copy constructor
-  // III. copy assignment
-
-  // Helper functions
-  const char* c_str() const  // accessor
-  {
-    return cstring_;
-  }
-
-  void set_first_char(char ch) {
-    if (cstring_)
-      cstring_[0] = ch;
-  }
-};
-
-void run() {
-  {
-    std::cout << "\n\nProblem\n";
-    Model str1{"str1"};
-    Model str2 = str1;  // shallow copy  with "assigment = "
-    std::cout << "Before change:\n";
-    std::cout << "  str1 = " << str1.c_str() << "\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    std::cout << "\n[P1] Shallow copy (shared pointer).\n";
-    str2.set_first_char('X');
-    std::cout << "\nAfter modifying str2.set_first_char('X'):\n";
-    std::cout << "  str1 = " << str1.c_str() << "   <-- also changed!\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-    std::cout
-        << "\n[P2] Decontructor issue when releasing the shared pointer.\n";
-  }
-}
-}  // namespace problem
-
-// Rule of Three: define
-//  - destructor
-//  - copy constructor
-//  - copy assignment
-namespace role_of_three {
-class Model {
- private:
-  char* cstring_;
-
- public:
-  explicit Model(const char* s = "") : cstring_{nullptr} {
-    if (s) {
-      cstring_ = new char[std::strlen(s) + 1];  // allocate
-      std::strcpy(cstring_, s);                 // populate
-    }
-  }
-
-  // I. destructor
-  ~Model() {
-    delete[] cstring_;  // [P2] Double call here
-    std::cout << "Deleted cstring at: " << static_cast<const void*>(cstring_)
-              << "\n";
-  }
-
-  // II. copy constructor
-  Model(const Model& other) : Model(other.cstring_) {}
-
-  // III. copy assignment
-  Model& operator=(const Model& other) {
-    Model temp(other);
-    std::swap(cstring_, temp.cstring_);
-    return *this;
-  }
-
-  // Helper functions
-  const char* c_str() const  // accessor
-  {
-    return cstring_;
-  }
-
-  void set_first_char(char ch) {
-    if (cstring_)
-      cstring_[0] = ch;
-  }
-};
-
-void run() {
-  {
-    std::cout << "\n\nRole of three\n";
-    Model str1{"str1"};
-    Model str2 = str1;  // shallow copy  with "assigment = "
-    std::cout << "Before change:\n";
-    std::cout << "  str1 = " << str1.c_str() << "\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    str2.set_first_char('X');
-    std::cout << "\nAfter modifying str2.set_first_char('X'):\n";
-    std::cout << "  str1 = " << str1.c_str() << "   <-- not changed!\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    // [P] Role of three not cover this std::move
-    Model str{"there"};
-    Model str_move = std::move(str);
-    std::cout << "\nAfter moving str into str_move:\n";
-    std::cout << "  str.c_str()      = " << (str.c_str() ? str.c_str() : "null")
-              << "\n";
-    std::cout << "  str_move.c_str() = "
-              << (str_move.c_str() ? str_move.c_str() : "null") << "\n";
-  }
-}
-}  // namespace role_of_three
-
-// Rule of Five: Rule of Three and define
-//  - move constructor
-//  - move assignment
-namespace role_of_five {
-class Model {
- private:
-  char* cstring_;
-
- public:
-  explicit Model(const char* s = "") : cstring_{nullptr} {
-    if (s) {
-      cstring_ = new char[std::strlen(s) + 1];  // allocate
-      std::strcpy(cstring_, s);                 // populate
-    }
-  }
-
-  // I. destructor
-  ~Model() {
-    delete[] cstring_;  // [P2] Double call here
-    std::cout << "Deleted cstring at: " << static_cast<const void*>(cstring_)
-              << "\n";
-  }
-
-  // II. copy constructor
-  Model(const Model& other) : Model(other.cstring_) {}
-
-  // III. copy assignment
-  Model& operator=(const Model& other) {
-    Model temp(other);
-    std::swap(cstring_, temp.cstring_);
-    return *this;
-  }
-
-  // IV. move constructor
-  // noexcept is a specifier that indicates a function will not throw
-  // exceptions.
-  Model(Model&& other) noexcept
-      : cstring_(std::exchange(other.cstring_, nullptr)){};
-
-  // V. move assignment
-  Model& operator=(Model&& other) noexcept {
-    std::swap(cstring_, other.cstring_);
-    return *this;
-  }
-
-  // Helper functions
-  const char* c_str() const  // accessor
-  {
-    return cstring_;
-  }
-
-  void set_first_char(char ch) {
-    if (cstring_)
-      cstring_[0] = ch;
-  }
-};
-
-void run() {
-  {
-    std::cout << "\n\nRole of Five\n";
-    Model str1{"str1"};
-    Model str2 = str1;  // shallow copy  with "assigment = "
-    std::cout << "Before change:\n";
-    std::cout << "  str1 = " << str1.c_str() << "\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    str2.set_first_char('X');
-    std::cout << "\nAfter modifying str2.set_first_char('X'):\n";
-    std::cout << "  str1 = " << str1.c_str() << "   <-- not changed!\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    // Role of five covers this std::move
-    Model str{"there"};
-    Model str_move = std::move(str);
-    std::cout << "\nAfter moving str into str_move:\n";
-    std::cout << "  str.c_str()      = " << (str.c_str() ? str.c_str() : "null")
-              << "\n";
-    std::cout << "  str_move.c_str() = "
-              << (str_move.c_str() ? str_move.c_str() : "null") << "\n";
-  }
-}
-}  // namespace role_of_five
-
-// Rule of Zero: use RAII (std::string, std::vector, smart pointers,...), no
-// need to define any special functions except constructor
-namespace role_of_zero {
-class BaseOfFiveDefaults {
- public:
-  BaseOfFiveDefaults(const BaseOfFiveDefaults&) = default;
-  BaseOfFiveDefaults(BaseOfFiveDefaults&&) = default;
-  BaseOfFiveDefaults& operator=(const BaseOfFiveDefaults&) = default;
-  BaseOfFiveDefaults& operator=(BaseOfFiveDefaults&&) = default;
-  virtual ~BaseOfFiveDefaults() = default;
-};
-
-class Model {
- private:
-  std::string cstring_;
-  // int* ptr;	-> std::unique_ptr<int> ptr; (exclusive ownership)
-  // int* arr;	-> std::vector<int> arr; (automatic array management)
-  // int* shared;	-> std::shared_ptr<int> shared; (shared ownership)
-
- public:
-  explicit Model(const std::string& str) : cstring_{str} {}
-
-  // Helper functions
-  std::string c_str() const  // accessor
-  {
-    return cstring_;
-  }
-
-  void set_first_char(char ch) { cstring_.at(0) = ch; }
-};
-
-void run() {
-  {
-    std::cout << "\n\nRole of Zero\n";
-    Model str1{"str1"};
-    Model str2 = str1;  // shallow copy  with "assigment = "
-    std::cout << "Before change:\n";
-    std::cout << "  str1 = " << str1.c_str() << "\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    str2.set_first_char('X');
-    std::cout << "\nAfter modifying str2.set_first_char('X'):\n";
-    std::cout << "  str1 = " << str1.c_str() << "   <-- not changed!\n";
-    std::cout << "  str2 = " << str2.c_str() << "\n";
-
-    Model str{"there"};
-    Model str_move = std::move(str);
-    std::cout << "\nAfter moving str into str_move:\n";
-    std::cout << "  str.c_str()      = " << str.c_str() << "\n";
-    std::cout << "  str_move.c_str() = " << str_move.c_str() << "\n";
-  }
-}
-}  // namespace role_of_zero
-}  // namespace
-
-#include "ExampleRegistry.h"
-
-class RoleOfThreeFiveZero : public IExample {
- public:
-  std::string group() const override { return "core/class"; }
-  std::string name() const override { return "RoleOfThreeFiveZero"; }
-  std::string description() const override { return ""; }
-  void execute() override {
-    problem::run();
-    role_of_three::run();
-    role_of_five::run();
-    role_of_zero::run();
-  }
-};
-
-REGISTER_EXAMPLE(RoleOfThreeFiveZero);
\ No newline at end of file
diff --git a/src/core/class/RuleOfThreeFiveZero.cpp b/src/core/class/RuleOfThreeFiveZero.cpp
new file mode 100644
index 0000000..ffe0bcc
--- /dev/null
+++ b/src/core/class/RuleOfThreeFiveZero.cpp
@@ -0,0 +1,236 @@
+// -----------------------------------------------------------------------------
+// Rule of Three / Five / Zero
+//
+// A class that manages a resource by hand (new/delete, file handles, ...)
+// must decide what copying, moving and destroying mean:
+//
+//   Rule of Three : destructor + copy constructor + copy assignment
+//   Rule of Five  : ... + move constructor + move assignment (C++11)
+//   Rule of Zero  : use members that already manage themselves (std::string,
+//                   std::vector, std::unique_ptr) and write none of them.
+//
+// Prefer the Rule of Zero. Write the five only for low-level resource wrappers.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/rule_of_three
+// -----------------------------------------------------------------------------
+
+#include <cstring>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+char* duplicate(const char* text) {
+  const std::size_t size = std::strlen(text) + 1;
+  auto* copy = new char[size];
+  std::memcpy(copy, text, size);
+  return copy;
+}
+
+namespace problem {
+
+/// Owns a heap buffer but relies on the compiler-generated copy operations.
+class Text {
+ public:
+  explicit Text(const char* text) : data_{duplicate(text)} {}
+
+  // The destructor SHOULD release the buffer with `delete[] data_;`. Because
+  // the implicit copy constructor copies only the pointer (a shallow copy),
+  // two objects would then delete the same buffer: a double free. To keep the
+  // lab running, the destructor does nothing and run() frees the buffer once.
+  ~Text() = default;
+
+  const char* c_str() const { return data_; }
+  void setFirstChar(char c) { data_[0] = c; }
+  void releaseForDemo() {
+    delete[] data_;
+    data_ = nullptr;
+  }
+
+ private:
+  char* data_;
+};
+
+void run() {
+  LOG_SECTION("Problem: owning raw pointer + implicit copy");
+  Text first{"hello"};
+  Text second = first;  // copies the POINTER, not the characters
+
+  second.setFirstChar('J');
+  LOG_S("first  = " << first.c_str() << "   <- changed through `second`!");
+  LOG_S("second = " << second.c_str());
+  LOG_S("both point to " << static_cast<const void*>(first.c_str()));
+
+  first
+      .releaseForDemo();  // manual cleanup; `second` now dangles - never use it
+}
+
+}  // namespace problem
+
+namespace rule_of_three {
+
+class Text {
+ public:
+  explicit Text(const char* text) : data_{duplicate(text)} {}
+
+  // 1. Destructor: releases the resource.
+  ~Text() { delete[] data_; }
+
+  // 2. Copy constructor: deep copy.
+  Text(const Text& other) : data_{duplicate(other.data_)} {
+    LOG_S("  Text(const Text&)   deep copy of \"" << other.data_ << "\"");
+  }
+
+  // 3. Copy assignment, written with the copy-and-swap idiom: it is safe for
+  //    self-assignment and leaves *this untouched if the copy throws.
+  Text& operator=(const Text& other) {
+    LOG("  operator=(const Text&)");
+    Text copy(other);
+    std::swap(data_, copy.data_);
+    return *this;  // `copy` now holds the old buffer and deletes it
+  }
+
+  const char* c_str() const { return data_; }
+  void setFirstChar(char c) { data_[0] = c; }
+
+ private:
+  char* data_;
+};
+
+void run() {
+  LOG_SECTION("Rule of Three");
+  Text first{"hello"};
+  Text second = first;
+  second.setFirstChar('J');
+  LOG_S("first = " << first.c_str() << ", second = " << second.c_str()
+                   << "   <- independent copies");
+
+  LOG("Text moved = std::move(first);   <- no move constructor: falls back to "
+      "COPY");
+  const Text moved = std::move(first);
+  LOG_S("first still holds \"" << first.c_str()
+                               << "\" (the move was really a copy)");
+  LOG_S("moved = " << moved.c_str());
+}
+
+}  // namespace rule_of_three
+
+namespace rule_of_five {
+
+class Text {
+ public:
+  explicit Text(const char* text) : data_{duplicate(text)} {}
+  ~Text() { delete[] data_; }
+
+  Text(const Text& other) : data_{duplicate(other.data_)} {
+    LOG("  Text(const Text&)");
+  }
+
+  Text& operator=(const Text& other) {
+    LOG("  operator=(const Text&)");
+    Text copy(other);
+    std::swap(data_, copy.data_);
+    return *this;
+  }
+
+  // 4. Move constructor: steal the pointer, leave the source empty.
+  //    noexcept matters: std::vector only moves elements when it cannot throw.
+  Text(Text&& other) noexcept : data_{std::exchange(other.data_, nullptr)} {
+    LOG("  Text(Text&&)        steals the buffer");
+  }
+
+  // 5. Move assignment.
+  Text& operator=(Text&& other) noexcept {
+    LOG("  operator=(Text&&)");
+    std::swap(data_, other.data_);  // `other` deletes our old buffer later
+    return *this;
+  }
+
+  const char* c_str() const { return data_ != nullptr ? data_ : "(null)"; }
+
+ private:
+  char* data_;
+};
+
+void run() {
+  LOG_SECTION("Rule of Five");
+  Text first{"hello"};
+  LOG("Text moved = std::move(first);");
+  const Text moved = std::move(first);
+  LOG_S("first = " << first.c_str() << ", moved = " << moved.c_str());
+
+  Text target{"old"};
+  LOG("target = Text{\"temporary\"};");
+  target = Text{"temporary"};
+  LOG_S("target = " << target.c_str());
+}
+
+}  // namespace rule_of_five
+
+namespace rule_of_zero {
+
+/// std::string manages the memory: the compiler-generated destructor, copy
+/// and move operations are all correct. Nothing to write!
+class Text {
+ public:
+  explicit Text(std::string text) : data_{std::move(text)} {}
+  const std::string& str() const { return data_; }
+  void setFirstChar(char c) { data_.at(0) = c; }
+
+ private:
+  std::string data_;
+};
+
+/// Polymorphic base classes are the exception: they need a virtual destructor,
+/// which suppresses the implicit move operations, so all five are defaulted.
+class Shape {
+ public:
+  Shape() = default;
+  virtual ~Shape() = default;
+  Shape(const Shape&) = default;
+  Shape& operator=(const Shape&) = default;
+  Shape(Shape&&) = default;
+  Shape& operator=(Shape&&) = default;
+
+  virtual double area() const = 0;
+};
+
+class Square final : public Shape {  // Rule of Zero again
+ public:
+  explicit Square(double side) : side_{side} {}
+  double area() const override { return side_ * side_; }
+
+ private:
+  double side_;
+};
+
+void run() {
+  LOG_SECTION("Rule of Zero");
+  Text first{"hello"};
+  Text second = first;
+  second.setFirstChar('J');
+  LOG_S("first = " << first.str() << ", second = " << second.str());
+
+  Text moved = std::move(first);
+  LOG_S("moved = " << moved.str() << ", first after move = \"" << first.str()
+                   << "\" (valid but unspecified, here empty)");
+
+  const std::unique_ptr<Shape> shape = std::make_unique<Square>(3.0);
+  LOG_S("Square(3).area() = " << shape->area());
+}
+
+}  // namespace rule_of_zero
+
+}  // namespace
+
+LAB_EXAMPLE("RuleOfThreeFiveZero",
+            "which special member functions to write, and when to write none") {
+  problem::run();
+  rule_of_three::run();
+  rule_of_five::run();
+  rule_of_zero::run();
+}
diff --git a/src/core/class/SallowDeepCopying.cpp b/src/core/class/SallowDeepCopying.cpp
deleted file mode 100644
index eefdfb5..0000000
--- a/src/core/class/SallowDeepCopying.cpp
+++ /dev/null
@@ -1,167 +0,0 @@
-// cppcheck-suppress-file [noCopyConstructor, noOperatorEq, unsafeClassCanLeak]
-
-#include <iostream>
-
-namespace {
-namespace shallow {
-class Model {
- private:
-  int x_{0}, y_{1};
-  int* ptr_{};
-
- public:
-  // Default constructor: Model a = Model(1,2)
-  explicit Model(int x, int y, int z) : x_{x}, y_{y} {
-    ptr_ = new int;
-    *ptr_ = z;
-  }
-
-  ~Model() {
-    // [P1]
-    // Shallow copying makes both objects use the same pointer.
-    // If one object deletes the pointer, the other object now
-    // points to invalid memory.
-    // delete ptr_;   // Commented out on purpose for demo
-  }
-
-  void changePtr(int value) {
-    if (ptr_ != nullptr) {
-      *ptr_ = value;
-    }
-  }
-
-  int getPtr() const {
-    if (ptr_ != nullptr) {
-      return *ptr_;
-    }
-    return 0;
-  }
-
-  // Implicit copy constructor: Model a{b};
-  // Model(const Model &f) : x_{f.x_}, y_{f.y_} {}
-
-  // Implicit assignment operator (like the way compiler gen this function):
-  // Model a = b; Model &operator=(const Model &f)
-  // {
-  //     // self-assignment guard
-  //     if (this == &f)
-  //     {
-  //         return *this;
-  //     }
-
-  //     // do the copy
-  //     x_ = f.x_;
-  //     y_ = f.y_;
-
-  //     //  return the existing object so we can chain this operator
-  //     return *this;
-  // }
-};
-
-void run() {
-  Model obj1 = Model(1, 2, 3);
-  Model obj2 = obj1;
-  obj2.changePtr(30);
-  // [P2]
-  std::cout << "\n=== Shallow Copy Demo ===\n";
-  std::cout << "obj1.ptr_ = " << obj1.getPtr() << "\n";
-  std::cout << "obj2.ptr_ = " << obj2.getPtr() << "\n";
-}
-
-}  // namespace shallow
-
-// To do a deep copy on any non-null pointers being copied
-// Requires that we write our own `copy constructors` and `overloaded assignment
-// operators`.
-namespace deep_copying {
-class Model {
- private:
-  int x_{0}, y_{1};
-  int* ptr_{};
-
-  void deepCopy(const Model& source) {
-    // sallow copy the normal fields
-    x_ = source.x_;
-    y_ = source.y_;
-
-    // deep copy the ptr_ field
-    // m_data is a pointer, so we need to deep copy it if it is non-null
-    // first we need to deallocate any value that this Model is holding!
-    delete ptr_;
-    if (source.ptr_ != nullptr) {
-      // allocate memory for our copy
-      ptr_ = new int;
-      // do the copy
-      *ptr_ = *source.ptr_;
-    } else {
-      ptr_ = nullptr;
-    }
-  }
-
- public:
-  // Constructor
-  explicit Model(int x, int y, int z) : x_{x}, y_{y} {
-    ptr_ = new int;
-    *ptr_ = z;
-  }
-
-  // Destructor
-  ~Model() { delete ptr_; }
-
-  // Copy constructor
-  // no need to check self-copy [if (this != &source)]
-  // because it cannot happen a(a);
-  Model(const Model& source) { this->deepCopy(source); }
-
-  // Assignment operator
-  // need to check self-copy [if (this != &source)]
-  // because it posible a = a;
-  Model& operator=(const Model& source) {
-    if (this != &source) {
-      // now do the deep copy
-      this->deepCopy(source);
-    }
-    return *this;
-  }
-
-  void changePtr(int value) {
-    if (ptr_ != nullptr) {
-      *ptr_ = value;
-    }
-  }
-
-  int getPtr() const {
-    if (ptr_ != nullptr) {
-      return *ptr_;
-    }
-    return 0;
-  }
-};
-
-void run() {
-  Model obj1 = Model(1, 2, 3);
-  Model obj2 = obj1;
-  obj2.changePtr(30);
-
-  std::cout << "\n=== Deep Copy Demo ===\n";
-  std::cout << "obj1.ptr_ = " << obj1.getPtr() << "\n";
-  std::cout << "obj2.ptr_ = " << obj2.getPtr() << "\n";
-}
-
-}  // namespace deep_copying
-}  // namespace
-
-#include "ExampleRegistry.h"
-
-class ShallowDeepCopying : public IExample {
- public:
-  std::string group() const override { return "core"; }
-  std::string name() const override { return "ShallowDeepCopying"; }
-  std::string description() const override { return ""; }
-  void execute() override {
-    shallow::run();
-    deep_copying::run();
-  }
-};
-
-REGISTER_EXAMPLE(ShallowDeepCopying);
\ No newline at end of file
diff --git a/src/core/class/ShallowDeepCopying.cpp b/src/core/class/ShallowDeepCopying.cpp
new file mode 100644
index 0000000..86ed859
--- /dev/null
+++ b/src/core/class/ShallowDeepCopying.cpp
@@ -0,0 +1,151 @@
+// -----------------------------------------------------------------------------
+// Shallow copy vs deep copy
+//
+//   Shallow copy : copies member values as they are. For a pointer member that
+//                  means both objects point to the SAME memory.
+//                  This is what the compiler-generated copy operations do.
+//   Deep copy    : allocates new memory and copies what the pointer points to,
+//                  so each object owns its own data.
+//
+// Pointer members that own memory need a user-written copy constructor and
+// copy assignment (see RuleOfThreeFiveZero) - or better, a smart pointer or
+// container that already copies correctly.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/shallow-vs-deep-copying/
+// -----------------------------------------------------------------------------
+
+#include <memory>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+namespace shallow {
+
+class Model {
+ public:
+  explicit Model(int value) : value_{new int{value}} {}
+
+  // No user-defined copy operations: copying duplicates the pointer only.
+  // A destructor with `delete value_;` would free the shared int twice, so it
+  // is intentionally left out and run() frees the memory once by hand.
+
+  void set(int value) { *value_ = value; }
+  int get() const { return *value_; }
+  const int* address() const { return value_; }
+  void releaseForDemo() {
+    delete value_;
+    value_ = nullptr;
+  }
+
+ private:
+  int* value_;
+};
+
+void run() {
+  LOG_SECTION("Shallow copy");
+  Model original{3};
+  Model copy = original;  // compiler-generated copy: pointer copied
+  copy.set(30);
+
+  LOG_S("original.get() = " << original.get()
+                            << "  <- changed through the copy");
+  LOG_S("copy.get()     = " << copy.get());
+  LOG_S("same address?    " << std::boolalpha
+                            << (original.address() == copy.address()));
+
+  original.releaseForDemo();  // `copy` now holds a dangling pointer
+}
+
+}  // namespace shallow
+
+namespace deep {
+
+class Model {
+ public:
+  explicit Model(int value) : value_{new int{value}} {}
+  ~Model() { delete value_; }
+
+  // Copy constructor: allocate our own int and copy the pointed-to value.
+  // No self-copy check is needed: an object cannot be constructed from itself.
+  Model(const Model& other) : value_{new int{*other.value_}} {}
+
+  // Copy assignment: `a = a` is possible, so guard against self-assignment.
+  Model& operator=(const Model& other) {
+    if (this != &other) {
+      *value_ =
+          *other.value_;  // both objects own an int already: copy the value
+    }
+    return *this;
+  }
+
+  void set(int value) { *value_ = value; }
+  int get() const { return *value_; }
+  const int* address() const { return value_; }
+
+ private:
+  int* value_;
+};
+
+void run() {
+  LOG_SECTION("Deep copy");
+  const Model original{3};
+  Model copy = original;
+  copy.set(30);
+
+  LOG_S("original.get() = " << original.get() << "   <- unchanged");
+  LOG_S("copy.get()     = " << copy.get());
+  LOG_S("same address?    " << std::boolalpha
+                            << (original.address() == copy.address()));
+
+  Model assigned{0};
+  assigned = original;
+  LOG_S("assigned.get() = " << assigned.get()
+                            << " after `assigned = original`");
+}
+
+}  // namespace deep
+
+namespace modern {
+
+/// Rule of Zero alternative: std::unique_ptr cannot be copied by accident, and
+/// the explicit copy constructor states what a copy means.
+class Model {
+ public:
+  explicit Model(int value) : value_{std::make_unique<int>(value)} {}
+  Model(const Model& other) : value_{std::make_unique<int>(*other.value_)} {}
+  Model& operator=(const Model& other) {
+    *value_ = *other.value_;
+    return *this;
+  }
+  Model(Model&&) noexcept = default;
+  Model& operator=(Model&&) noexcept = default;
+  ~Model() = default;
+
+  void set(int value) { *value_ = value; }
+  int get() const { return *value_; }
+
+ private:
+  std::unique_ptr<int> value_;  // frees itself, never double-deletes
+};
+
+void run() {
+  LOG_SECTION("Deep copy with std::unique_ptr");
+  const Model original{3};
+  Model copy = original;
+  copy.set(30);
+  LOG_S("original.get() = " << original.get()
+                            << ", copy.get() = " << copy.get());
+}
+
+}  // namespace modern
+
+}  // namespace
+
+LAB_EXAMPLE("ShallowDeepCopying",
+            "why copying a pointer member is not copying the data") {
+  shallow::run();
+  deep::run();
+  modern::run();
+}
diff --git a/src/core/class/VirtualBase.cpp b/src/core/class/VirtualBase.cpp
index 199123d..32a1c60 100644
--- a/src/core/class/VirtualBase.cpp
+++ b/src/core/class/VirtualBase.cpp
@@ -1,127 +1,112 @@
-// cppcheck-suppress-file [functionStatic]
-#include <iostream>
-#include "ExampleRegistry.h"
+// -----------------------------------------------------------------------------
+// Virtual base classes and the diamond problem
+//
+//          PoweredDevice
+//           ^         ^
+//           |         |
+//       Scanner     Printer
+//           ^         ^
+//           |         |
+//             Copier
+//
+// With plain inheritance a Copier contains TWO PoweredDevice sub-objects, so
+// the base is constructed twice and `PoweredDevice&` conversions are ambiguous.
+// `virtual` inheritance shares one PoweredDevice sub-object. The MOST DERIVED
+// class (Copier) is then responsible for constructing it.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/virtual-base-classes/
+// -----------------------------------------------------------------------------
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
 namespace {
 
 namespace problem {
+
 class PoweredDevice {
  public:
-  PoweredDevice() { std::cout << "Powered Device created\n"; }
-  ~PoweredDevice() { std::cout << "Powered Device destroyed\n"; }
+  explicit PoweredDevice(int watts) {
+    LOG_S("  PoweredDevice(" << watts << " W)");
+  }
 };
 
 class Scanner : public PoweredDevice {
  public:
-  Scanner() { std::cout << "Scanner created\n"; }
-  ~Scanner() { std::cout << "Scanner destroyed\n"; }
-
-  void start() { std::cout << "Scanner started\n"; }
+  Scanner() : PoweredDevice{10} { LOG("  Scanner()"); }
+  void start() const { LOG("  Scanner::start"); }
 };
 
 class Printer : public PoweredDevice {
  public:
-  Printer() { std::cout << "Printer created\n"; }
-  ~Printer() { std::cout << "Printer destroyed\n"; }
-
-  void start() { std::cout << "Printer started\n"; }
+  Printer() : PoweredDevice{20} { LOG("  Printer()"); }
+  void start() const { LOG("  Printer::start"); }
 };
 
 class Copier : public Scanner, public Printer {
  public:
-  Copier() { std::cout << "Copier created\n"; }
-  ~Copier() { std::cout << "Copier destroyed\n"; }
+  Copier() { LOG("  Copier()"); }
 };
 
 void run() {
-  std::cout << "\n---Problem---\n";
-  Copier c{};
-  std::cout << "\n";
-  c.Scanner::start();
-  c.Printer::start();
-  std::cout << "\n";
-  // Output:
-  // Powered Device created <-- multiple "instances" of the Powered Device appearing in an inheritance hierarchy
-  // Scanner created
-  // Powered Device created <--
-  // Printer created
-  // Copier created
-
-  // Scanner started
-  // Printer started
-  // Copier destroyed
-  // Printer destroyed
-  // Powered Device destroyed
-  // Scanner destroyed
-  // Powered Device destroyed
+  LOG_SECTION("Problem: plain multiple inheritance");
+  const Copier copier;
+  LOG("  -> PoweredDevice was constructed TWICE");
+
+  // copier.start();                          // error: ambiguous
+  // PoweredDevice& device = copier;          // error: ambiguous base
+  copier.Scanner::start();  // must name the path explicitly
+  copier.Printer::start();
+  LOG_S("  sizeof(Copier) = " << sizeof(Copier));
 }
 
 }  // namespace problem
 
-namespace virtual_base_classes {
+namespace virtual_inheritance {
+
 class PoweredDevice {
  public:
-  PoweredDevice() { std::cout << "Powered Device created\n"; }
-  ~PoweredDevice() { std::cout << "Powered Device destroyed\n"; }
+  explicit PoweredDevice(int watts) {
+    LOG_S("  PoweredDevice(" << watts << " W)");
+  }
 };
 
 class Scanner : public virtual PoweredDevice {
  public:
-  Scanner() { std::cout << "Scanner created\n"; }
-  ~Scanner() { std::cout << "Scanner destroyed\n"; }
-
-  void start() { std::cout << "Scanner started\n"; }
+  // This initializer is ignored when a Scanner is part of a Copier.
+  Scanner() : PoweredDevice{10} { LOG("  Scanner()"); }
+  void start() const { LOG("  Scanner::start"); }
 };
 
 class Printer : public virtual PoweredDevice {
  public:
-  Printer() { std::cout << "Printer created\n"; }
-  ~Printer() { std::cout << "Printer destroyed\n"; }
-
-  void start() { std::cout << "Printer started\n"; }
+  Printer() : PoweredDevice{20} { LOG("  Printer()"); }
+  void start() const { LOG("  Printer::start"); }
 };
 
 class Copier : public Scanner, public Printer {
  public:
-  Copier() { std::cout << "Copier created\n"; }
-  ~Copier() { std::cout << "Copier destroyed\n"; }
+  // The most derived class constructs the shared virtual base.
+  Copier() : PoweredDevice{30} { LOG("  Copier()"); }
 };
 
 void run() {
-  std::cout << "\n---Solved by Virtual Base Class---\n";
-  // The most derived class is responsible for constructing the virtual base class (Copier)
-  Copier c{};
-  std::cout << "\n";
-  c.Scanner::start();
-  c.Printer::start();
-  std::cout << "\n";
-  // Output:
-  // Powered Device created <-- there is only one base object
-  // Scanner created
-  // Printer created
-  // Copier created
-
-  // Scanner started
-  // Printer started
-
-  // Copier destroyed
-  // Printer destroyed
-  // Scanner destroyed
-  // Powered Device destroyed
+  LOG_SECTION("Solution: virtual inheritance");
+  const Copier copier;
+  LOG("  -> ONE PoweredDevice, constructed by Copier with 30 W");
+
+  [[maybe_unused]] const PoweredDevice& device = copier;  // no longer ambiguous
+  copier.Scanner::start();
+  copier.Printer::start();
+  LOG_S("  sizeof(Copier) = " << sizeof(Copier)
+                              << " (virtual bases add hidden pointers)");
 }
-}  // namespace virtual_base_classes
-}  // namespace
-
-class VirtualBase : public IExample {
- public:
-  std::string group() const override { return "core/class"; };
 
-  std::string name() const override { return "VirtualBase"; };
-  std::string description() const override { return "VirtualBase examples"; };
+}  // namespace virtual_inheritance
 
-  void execute() override {
-    problem::run();
-    virtual_base_classes::run();
-  };
-};
+}  // namespace
 
-REGISTER_EXAMPLE(VirtualBase);
\ No newline at end of file
+LAB_EXAMPLE("VirtualBase", "the diamond problem and virtual inheritance") {
+  problem::run();
+  virtual_inheritance::run();
+}
diff --git a/src/core/concurrency/ConditionVariable.cpp b/src/core/concurrency/ConditionVariable.cpp
index 05cfe3d..07adc7d 100644
--- a/src/core/concurrency/ConditionVariable.cpp
+++ b/src/core/concurrency/ConditionVariable.cpp
@@ -1,75 +1,157 @@
-#include <string>
+// -----------------------------------------------------------------------------
+// std::condition_variable
+//
+// Lets a thread sleep until another thread signals that some condition has
+// become true, without busy-waiting.
+//
+//   std::unique_lock lock(mutex);
+//   cv.wait(lock, [] { return ready; });   // sleep until ready == true
+//
+// Rules:
+//   - Always wait with a predicate: wake-ups can be spurious, and a notify
+//     sent before the wait started would otherwise be lost.
+//   - Change the shared state while holding the mutex, then notify.
+//   - wait() needs std::unique_lock because it unlocks/relocks the mutex.
+//
+// Reference: https://en.cppreference.com/w/cpp/thread/condition_variable
+// -----------------------------------------------------------------------------
 
 #include <condition_variable>
+#include <deque>
+#include <functional>
 #include <mutex>
+#include <optional>
+#include <string>
 #include <thread>
+#include <vector>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-std::mutex mutex;
-std::condition_variable cv;
-
-std::string data;
-bool ready = false;
-bool finish = false;
 
-void worker_thread() {
-  std::unique_lock lock(mutex);
+namespace handshake {
 
-  LOG("Waiting for data");
+/// Everything both threads share, protected by `mutex`.
+struct Channel {
+  std::mutex mutex;
+  std::condition_variable cv;
+  std::string data;
+  bool ready{false};
+  bool processed{false};
+};
 
-  // wait() temporarily unlocks the mutex and puts the thread to sleep, allowing other threads to modify 'ready'.
-  // When notified, it wakes up, re-locks the mutex, and re-checks the condition.
-  // The thread continues only when 'ready' becomes true.
-  cv.wait(lock, []() { return ready; });
+void worker(Channel& channel) {
+  std::unique_lock<std::mutex> lock(channel.mutex);
+  LOG("worker: waiting for data");
 
-  LOG("Processing data");
+  // wait() atomically unlocks the mutex and sleeps. When woken up it locks the
+  // mutex again and re-checks the predicate before returning.
+  channel.cv.wait(lock, [&channel] { return channel.ready; });
 
-  data += " after processing";
-  finish = true;
+  LOG("worker: processing data");
+  channel.data += " -> processed";
+  channel.processed = true;
 
-  LOG("cv.notify_one");
-  cv.notify_one();
+  lock.unlock();  // unlock first so the woken thread can take the mutex at once
+  channel.cv.notify_one();
 }
 
 void run() {
-  LOG("Condition Example Begin");
-  std::thread w_thread(worker_thread);
+  LOG_SECTION("Handshake between two threads");
+  Channel channel;
+  std::thread worker_thread(worker, std::ref(channel));
 
-  // send data
-  LOG("Signals data ready for processing");
   {
-    std::lock_guard<std::mutex> lock(mutex);
-    data = "THIS IS A PRIVATE KEY: ABCxyz123";
-    ready = true;
+    const std::lock_guard<std::mutex> lock(channel.mutex);
+    channel.data = "request";
+    channel.ready = true;
   }
-
-  LOG("cv.notify_one");
-  cv.notify_one();  // wake up one thread waiting on this cv
+  LOG("main: data is ready, notify_one()");
+  channel.cv.notify_one();
 
   {
-    std::unique_lock g_mutex(mutex);
-    LOG("Waiting for finishing");
-    cv.wait(g_mutex, []() { return finish; });
+    std::unique_lock<std::mutex> lock(channel.mutex);
+    channel.cv.wait(lock, [&channel] { return channel.processed; });
+    LOG_S("main: received '" << channel.data << "'");
   }
-  LOG("data: " + data);
-  w_thread.join();
-
-  LOG("Condition Example End");
+  worker_thread.join();
 }
-}  // namespace
 
-class ConditionVariable : public IExample {
+}  // namespace handshake
+
+namespace producer_consumer {
+
+/// A minimal thread-safe queue: pop() blocks until an item arrives or the
+/// queue is closed.
+class BlockingQueue {
  public:
-  std::string group() const override { return "core/concurrency"; }
-  std::string name() const override { return "ConditionVariable"; }
-  std::string description() const override {
-    return "The examples for <thread> condition variable";
+  void push(int value) {
+    {
+      const std::lock_guard<std::mutex> lock(mutex_);
+      items_.push_back(value);
+    }
+    cv_.notify_one();  // wake one waiting consumer
   }
 
-  void execute() override { run(); }
+  void close() {
+    {
+      const std::lock_guard<std::mutex> lock(mutex_);
+      closed_ = true;
+    }
+    cv_.notify_all();  // wake every consumer so they can finish
+  }
+
+  /// Returns std::nullopt once the queue is closed and empty.
+  std::optional<int> pop() {
+    std::unique_lock<std::mutex> lock(mutex_);
+    cv_.wait(lock, [this] { return closed_ || !items_.empty(); });
+    if (items_.empty()) {
+      return std::nullopt;
+    }
+    const int value = items_.front();
+    items_.pop_front();
+    return value;
+  }
+
+ private:
+  std::mutex mutex_;
+  std::condition_variable cv_;
+  std::deque<int> items_;
+  bool closed_{false};
 };
 
-REGISTER_EXAMPLE(ConditionVariable);
\ No newline at end of file
+void run() {
+  LOG_SECTION("Producer / consumer with a blocking queue");
+  BlockingQueue queue;
+
+  auto consume = [&queue](int id) {
+    while (const std::optional<int> item = queue.pop()) {
+      LOG_S("consumer " << id << " got item " << *item);
+    }
+    LOG_S("consumer " << id << " sees a closed queue and stops");
+  };
+
+  std::vector<std::thread> consumers;
+  consumers.emplace_back(consume, 1);
+  consumers.emplace_back(consume, 2);
+
+  for (int item = 1; item <= 6; ++item) {
+    queue.push(item);
+  }
+  queue.close();
+
+  for (std::thread& consumer : consumers) {
+    consumer.join();
+  }
+}
+
+}  // namespace producer_consumer
+
+}  // namespace
+
+LAB_EXAMPLE("ConditionVariable",
+            "wait/notify handshake and a blocking producer/consumer queue") {
+  handshake::run();
+  producer_consumer::run();
+}
diff --git a/src/core/concurrency/FuturePromise.cpp b/src/core/concurrency/FuturePromise.cpp
index fb316dd..8d2adc4 100644
--- a/src/core/concurrency/FuturePromise.cpp
+++ b/src/core/concurrency/FuturePromise.cpp
@@ -1,121 +1,115 @@
+// -----------------------------------------------------------------------------
+// std::future, std::async, std::promise, std::packaged_task
+//
+// A future is a handle to a value (or exception) that will be available later.
+//
+//   std::async          : "run this function and give me the result later".
+//                         The simplest option - prefer it.
+//   std::promise        : manually set the value from any thread.
+//   std::packaged_task  : wraps a callable so its result goes into a future.
+//
+// Notes:
+//   - future.get() blocks until the result is ready and can be called once.
+//   - An exception thrown by the task is re-thrown by get().
+//   - std::launch::async forces a new thread; the default policy may defer
+//     the call until get() is invoked.
+//
+// Reference: https://en.cppreference.com/w/cpp/thread/future
+// -----------------------------------------------------------------------------
+
 #include <chrono>
 #include <future>
-#include <string>
+#include <stdexcept>
 #include <thread>
+#include <utility>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-// Simulated heavy work
-int heavy_work() {
-  LOG("Begin (2s)");
-  std::this_thread::sleep_for(std::chrono::seconds(2));
-  LOG("End");
+using std::chrono::milliseconds;
+using std::chrono::steady_clock;
+
+/// Simulates a slow computation.
+int heavyWork() {
+  LOG("heavyWork: started (300 ms)");
+  std::this_thread::sleep_for(milliseconds(300));
+  LOG("heavyWork: done");
   return 1000;
 }
 
-// Shared helper to simulate main thread work
-void do_other_work(std::chrono::steady_clock::time_point start) {
-  for (int i = 1; i <= 4; ++i) {
-    std::this_thread::sleep_for(std::chrono::milliseconds(400));
-    auto now = std::chrono::steady_clock::now();
-    auto elapsed =
-        std::chrono::duration_cast<std::chrono::milliseconds>(now - start)
-            .count();
-    LOG("doing other work... " + std::to_string(elapsed) + " ms");
+/// Simulates the caller doing something useful while it waits.
+void doOtherWork(steady_clock::time_point start) {
+  for (int step = 1; step <= 3; ++step) {
+    std::this_thread::sleep_for(milliseconds(80));
+    const auto elapsed =
+        std::chrono::duration_cast<milliseconds>(steady_clock::now() - start);
+    LOG_S("caller: other work, step " << step << " at " << elapsed.count()
+                                      << " ms");
   }
 }
 
-}  // namespace
+void asyncExample() {
+  LOG_SECTION("std::async");
+  const auto start = steady_clock::now();
 
-/**
- * @brief std::async example (high-level async)
- * Prefer to implement this - run a task and give me the result later
- */
-namespace async_example {
+  std::future<int> future = std::async(std::launch::async, heavyWork);
+  doOtherWork(start);
 
-void run() {
-  LOG("Begin");
-  auto start = std::chrono::steady_clock::now();
-
-  // Launch async task (guaranteed new thread)
-  std::future<int> fut = std::async(std::launch::async, heavy_work);
+  const int result = future.get();  // waits for heavyWork to finish
+  const auto total =
+      std::chrono::duration_cast<milliseconds>(steady_clock::now() - start);
+  LOG_S("result = " << result << ", total " << total.count()
+                    << " ms (work ran in parallel, not 300 + 240 ms)");
+}
 
-  LOG("launched");
-  do_other_work(start);
+void promiseExample() {
+  LOG_SECTION("std::promise + std::thread");
 
-  // Wait and get result
-  int result = fut.get();
+  std::promise<int> promise;
+  std::future<int> future = promise.get_future();
 
-  auto end = std::chrono::steady_clock::now();
-  auto total =
-      std::chrono::duration_cast<std::chrono::milliseconds>(end - start)
-          .count();
+  // The promise is moved into the thread; the future stays with the caller.
+  std::thread worker(
+      [p = std::move(promise)]() mutable { p.set_value(heavyWork()); });
 
-  LOG("result = " + std::to_string(result));
-  LOG("total time = " + std::to_string(total) + " ms");
-  LOG("End");
+  LOG_S("main: waiting, result = " << future.get());
+  worker.join();
 }
 
-}  // namespace async_example
+void packagedTaskExample() {
+  LOG_SECTION("std::packaged_task");
 
-/**
- * @brief std::promise + std::thread example (manual control)
- */
-namespace promise_example {
+  std::packaged_task<int(int, int)> task([](int a, int b) { return a * b; });
+  std::future<int> future = task.get_future();
 
-void worker(std::promise<int> prom) {
-  int result = heavy_work();
-  prom.set_value(result);
+  std::thread worker(std::move(task), 6, 7);
+  LOG_S("6 * 7 = " << future.get());
+  worker.join();
 }
 
-void run() {
-  LOG("Begin");
-  auto start = std::chrono::steady_clock::now();
-
-  // Create promise/future pair
-  std::promise<int> prom;
-  std::future<int> fut = prom.get_future();
-
-  // Launch thread manually
-  std::thread t(worker, std::move(prom));
-
-  LOG("launched");
-
-  do_other_work(start);
-
-  // Wait and get result
-  int result = fut.get();
+void exceptionExample() {
+  LOG_SECTION("Exceptions travel through the future");
 
-  auto end = std::chrono::steady_clock::now();
-  auto total =
-      std::chrono::duration_cast<std::chrono::milliseconds>(end - start)
-          .count();
+  std::future<int> future = std::async(std::launch::async, []() -> int {
+    throw std::runtime_error("failure inside the task");
+  });
 
-  LOG("result = " + std::to_string(result));
-  LOG("total time = " + std::to_string(total) + " ms");
-
-  t.join();
-
-  LOG("End");
-}
-
-}  // namespace promise_example
-
-class FuturePromise : public IExample {
- public:
-  std::string group() const override { return "core/concurrency"; }
-  std::string name() const override { return "FuturePromise"; }
-  std::string description() const override {
-    return "The examples for <future>";
+  try {
+    const int value = future.get();  // re-throws the task's exception here
+    LOG_S("unexpected value " << value);
+  } catch (const std::exception& e) {
+    LOG_S("caught in the caller: " << e.what());
   }
+}
 
-  void execute() override {
-    async_example::run();
-    promise_example::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(FuturePromise);
\ No newline at end of file
+LAB_EXAMPLE("FuturePromise",
+            "std::async, std::promise, std::packaged_task and exceptions") {
+  asyncExample();
+  promiseExample();
+  packagedTaskExample();
+  exceptionExample();
+}
diff --git a/src/core/concurrency/README.md b/src/core/concurrency/README.md
new file mode 100644
index 0000000..85a8920
--- /dev/null
+++ b/src/core/concurrency/README.md
@@ -0,0 +1,44 @@
+# Concurrency
+
+| Example             | Topic                                                          |
+|---------------------|----------------------------------------------------------------|
+| `ThreadManagement`  | `join`, `detach`, `joinable`, RAII thread guards, `std::jthread` |
+| `SharingData`       | passing arguments to threads, `std::ref`, lambda captures, `thread_local` |
+| `RaceCondition`     | data races and lost updates, `std::mutex`, `std::atomic`        |
+| `ConditionVariable` | waiting for a condition, producer/consumer queue               |
+| `FuturePromise`     | `std::async`, `std::promise`, `std::packaged_task`, exceptions across threads |
+| `Timing`            | `<chrono>` clocks and durations, measuring elapsed time        |
+
+## 1. Threads
+
+```cpp
+std::thread worker(function, arguments...);   // starts immediately
+worker.join();                                // wait for it to finish
+```
+
+- A `std::thread` that is still joinable when it is destroyed calls `std::terminate()`. Join it on
+  every path, or use `std::jthread` (C++20), which joins automatically.
+- Arguments are **copied** into the thread. Use `std::ref(x)` to pass a reference.
+- `detach()` is rarely right: nobody can wait for the thread anymore.
+
+## 2. Synchronization
+
+| Tool                        | Use it for                                          |
+|-----------------------------|-----------------------------------------------------|
+| `std::mutex` + `std::lock_guard` / `std::scoped_lock` | protecting shared data (a critical section) |
+| `std::unique_lock`          | a lock that can be released early; needed by condition variables |
+| `std::atomic<T>`            | single counters and flags without a lock           |
+| `std::condition_variable`   | sleeping until another thread signals a change      |
+| `std::future` / `std::promise` | handing one result (or exception) to another thread |
+
+A **data race** happens when two threads access the same memory, at least one of them writes, and
+nothing synchronizes them. A data race is undefined behavior, not just a wrong result. Build with
+`-fsanitize=thread` (ThreadSanitizer) to find races.
+
+## 3. Deadlocks
+
+A deadlock happens when two threads each hold a lock and wait for the other's. To avoid them:
+
+- lock several mutexes at once with `std::scoped_lock lock(a, b);`
+- always lock mutexes in the same order
+- never call unknown code (callbacks) while holding a lock
diff --git a/src/core/concurrency/RaceCondition.cpp b/src/core/concurrency/RaceCondition.cpp
index 0c7edb5..4023edd 100644
--- a/src/core/concurrency/RaceCondition.cpp
+++ b/src/core/concurrency/RaceCondition.cpp
@@ -1,96 +1,109 @@
+// -----------------------------------------------------------------------------
+// Race conditions, std::mutex and std::atomic
+//
+// `++counter` is not one step: the CPU reads the value, adds one and writes it
+// back. When two threads do this at the same time, increments get lost.
+// Unsynchronized access to shared data is a DATA RACE, which is undefined
+// behavior - the wrong total below is just one possible symptom.
+//
+// Fixes:
+//   - std::mutex + std::lock_guard : only one thread at a time in the section
+//   - std::atomic<int>             : the increment itself is indivisible
+//
+// Tip: build with -fsanitize=thread (ThreadSanitizer) to detect data races.
+// Reference: https://en.cppreference.com/w/cpp/thread/mutex
+// -----------------------------------------------------------------------------
+
 #include <atomic>
 #include <mutex>
+#include <string_view>
 #include <thread>
-#include "ExampleRegistry.h"
-#include "Logger.h"
 
-template <typename F, typename T>
-void run_case(const std::string& name, F work, T& global) {
-  global = 0;
-  LOG(name + "Begin");
-  std::cout << "global_variable: " << global << '\n';
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
 
-  std::thread thread1(work);
-  std::thread thread2(work);
+constexpr int kIncrementsPerThread = 1'000'000;
+constexpr int kExpected = 2 * kIncrementsPerThread;
 
-  thread1.join();
-  thread2.join();
+/// Runs `work` on two threads and reports the final counter.
+template <typename Work, typename Counter>
+void runCase(std::string_view title, Work work, const Counter& counter) {
+  LOG_SECTION(title);
+  std::thread first(work);
+  std::thread second(work);
+  first.join();
+  second.join();
 
-  std::cout << "global_variable: " << global << '\n';
-  LOG(name + "End");
+  const int total = counter;
+  LOG_S("expected " << kExpected << ", got " << total
+                    << (total == kExpected ? "  (correct)"
+                                           : "  <- lost updates!"));
 }
 
-/**
- * @brief Race Condition Problem
- */
 namespace problem {
-int global_variable = 0;
+
+int counter = 0;
 
 void run() {
-  auto work = []() {
-    for (int i = 0; i < 100000; ++i) {
-      global_variable++;
+  auto work = [] {
+    for (int i = 0; i < kIncrementsPerThread; ++i) {
+      ++counter;  // DATA RACE: read-modify-write without synchronization
     }
   };
-  run_case("Problem", work, global_variable);
+  runCase("Problem: unsynchronized ++counter", work, counter);
 }
+
 }  // namespace problem
 
-/**
- * @brief Mutex Example
- */
-namespace mutex {
-int global_variable = 0;
-std::mutex g_mutex;
+namespace with_mutex {
+
+int counter = 0;
+std::mutex counter_mutex;
 
 void run() {
-  auto work = []() {
-    for (int i = 0; i < 100000; ++i) {
-      // // anti pattern
-      // g_mutex.lock();
-      // global_variable += 1;
-      // g_mutex.unlock();
-
-      // a RAII lock for mutex
-      std::lock_guard<std::mutex> log(g_mutex);
-      global_variable++;
+  auto work = [] {
+    for (int i = 0; i < kIncrementsPerThread; ++i) {
+      // Anti-pattern: counter_mutex.lock(); ++counter; counter_mutex.unlock();
+      // If anything between lock and unlock throws, the mutex stays locked.
+      const std::lock_guard<std::mutex> lock(
+          counter_mutex);  // RAII: always unlocks
+      ++counter;
     }
   };
-
-  run_case("Mutex", work, global_variable);
+  runCase("Fix 1: std::mutex + std::lock_guard", work, counter);
 }
-}  // namespace mutex
 
-/**
- * @brief Atomic Example 
- */
-namespace atomic {
-std::atomic<int> global_variable = 0;
+}  // namespace with_mutex
+
+namespace with_atomic {
+
+std::atomic<int> counter{0};
 
 void run() {
-  auto work = []() {
-    for (int i = 0; i < 100000; ++i) {
-      global_variable++;
+  auto work = [] {
+    for (int i = 0; i < kIncrementsPerThread; ++i) {
+      ++counter;  // atomic increment, no lock needed
     }
   };
+  runCase("Fix 2: std::atomic<int>", work, counter);
+  LOG("atomic is faster than a mutex for a single variable; use a mutex when");
+  LOG("several variables must change together.");
+}
+
+}  // namespace with_atomic
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "RaceCondition",
+    "lost updates from a data race, fixed with std::mutex or std::atomic") {
+  problem::counter = 0;
+  with_mutex::counter = 0;
+  with_atomic::counter = 0;
 
-  run_case("Atomic", work, global_variable);
+  problem::run();
+  with_mutex::run();
+  with_atomic::run();
 }
-}  // namespace atomic
-
-class RaceCondition : public IExample {
- public:
-  std::string group() const override { return "core/concurrency"; }
-  std::string name() const override { return "RaceCondition"; }
-  std::string description() const override {
-    return "The examples for <thread> race condition";
-  }
-
-  void execute() override {
-    problem::run();
-    atomic::run();
-    mutex::run();
-  }
-};
-
-REGISTER_EXAMPLE(RaceCondition);
\ No newline at end of file
diff --git a/src/core/concurrency/SharingData.cpp b/src/core/concurrency/SharingData.cpp
index be6ae21..b1f7e10 100644
--- a/src/core/concurrency/SharingData.cpp
+++ b/src/core/concurrency/SharingData.cpp
@@ -1,51 +1,90 @@
+// -----------------------------------------------------------------------------
+// Passing data to threads
+//
+//   - std::thread COPIES (or moves) its arguments into the new thread, even if
+//     the function takes a reference.
+//   - Use std::ref(x) to really pass a reference. The caller must then make
+//     sure `x` outlives the thread.
+//   - Lambdas choose explicitly: [x] copies, [&x] references.
+//   - thread_local gives every thread its own instance of a variable.
+//
+// Reference: https://en.cppreference.com/w/cpp/thread/thread/thread
+// -----------------------------------------------------------------------------
+
+#include <functional>
+#include <string>
 #include <thread>
-#include "ExampleRegistry.h"
-#include "Logger.h"
 
-namespace {
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-int global_variable = 9;
+namespace {
 
-// Pass-by-value
-void set_global(int arg) {
-  LOG("arg: " + std::to_string(arg));
-  global_variable = 100;
-  LOG("global_variable: " + std::to_string(global_variable));
+void incrementByValue(int value) {
+  ++value;  // changes the thread's own copy
+  LOG_S("  inside thread: value = " << value);
 }
 
-void set_local(int& arg) {
-  //   thread_local int thread_local_variable = 1;
-  LOG("arg: " + std::to_string(arg));
-  arg = 100;
-  LOG("arg: " + std::to_string(arg));
+void incrementByReference(int& value) {
+  ++value;  // changes the caller's variable
+  LOG_S("  inside thread: value = " << value);
 }
 
-void run() {
-  int local_variable = 10;
-  std::cout << "local: " << local_variable << '\n';
-  std::cout << "global: " << global_variable << '\n';
+void arguments() {
+  LOG_SECTION("Arguments are copied unless wrapped in std::ref");
+  int number = 10;
 
-  std::thread thread1(set_global, local_variable);
-  thread1.join();
+  std::thread by_value(incrementByValue, number);
+  by_value.join();
+  LOG_S("after incrementByValue:     number = " << number << "  (unchanged)");
 
-  std::cout << "local: " << local_variable << '\n';
-  std::cout << "global: " << global_variable << '\n';
+  // std::thread by_ref(incrementByReference, number);  // does not compile:
+  //   a copied int (an rvalue) cannot bind to `int&`
+  std::thread by_ref(incrementByReference, std::ref(number));
+  by_ref.join();
+  LOG_S("after incrementByReference: number = " << number << "  (changed)");
+}
 
-  std::thread thread2(set_local, std::ref(local_variable));
-  thread2.join();
-  std::cout << "local: " << local_variable << '\n';
+void lambdas() {
+  LOG_SECTION("Lambda captures");
+  std::string message = "hello";
+
+  std::thread copies([message]() mutable {  // own copy of message
+    message += " (modified copy)";
+    LOG_S("  copy in thread: " << message);
+  });
+  copies.join();
+  LOG_S("after capture by value:     message = " << message);
+
+  std::thread references([&message] { message += " world"; });
+  references.join();
+  LOG_S("after capture by reference: message = " << message);
 }
-}  // namespace
 
-class SharingData : public IExample {
- public:
-  std::string group() const override { return "core/concurrency"; }
-  std::string name() const override { return "SharingData"; }
-  std::string description() const override {
-    return "The examples for <thread> sharing data";
+thread_local int t_calls = 0;  // one independent counter per thread
+
+void countCalls(const char* name) {
+  for (int i = 0; i < 3; ++i) {
+    ++t_calls;
   }
+  LOG_S("  " << name << " sees t_calls = " << t_calls);
+}
+
+void threadLocalStorage() {
+  LOG_SECTION("thread_local");
+  std::thread a(countCalls, "thread A");
+  std::thread b(countCalls, "thread B");
+  a.join();
+  b.join();
+  LOG_S("main thread sees t_calls = " << t_calls << "  (never touched here)");
+}
 
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(SharingData);
\ No newline at end of file
+LAB_EXAMPLE(
+    "SharingData",
+    "passing arguments to threads: copies, std::ref, captures, thread_local") {
+  arguments();
+  lambdas();
+  threadLocalStorage();
+}
diff --git a/src/core/concurrency/ThreadManagement.cpp b/src/core/concurrency/ThreadManagement.cpp
index e116a83..991ae3c 100644
--- a/src/core/concurrency/ThreadManagement.cpp
+++ b/src/core/concurrency/ThreadManagement.cpp
@@ -1,164 +1,157 @@
-#include <chrono>  // chrono::millisecond()
+// -----------------------------------------------------------------------------
+// Managing std::thread
+//
+//   join()       : wait for the thread to finish
+//   detach()     : let it run on its own; you can no longer wait for it
+//   joinable()   : true while the std::thread still owns a thread of execution
+//
+// A std::thread that is still joinable when destroyed calls std::terminate().
+// Protect against early returns and exceptions with RAII:
+//   - a small guard class that joins in its destructor, or
+//   - std::jthread (C++20), which joins automatically and supports stop requests.
+//
+// Reference: https://en.cppreference.com/w/cpp/thread/thread
+// -----------------------------------------------------------------------------
+
+#include <chrono>
+#include <future>
 #include <stdexcept>
+#include <stop_token>
 #include <thread>
-#include "ExampleRegistry.h"
-#include "Logger.h"
 
-namespace {
-
-/**
-   * @brief Check whether the thread is joinable
-   * joinable() tells you whether a std::thread is still owned and needs to be handled (joined or detached).
-   * @param thread 
-   */
-void checkJoinable(std::thread& thread) {
-  if (thread.joinable()) {
-    LOG("Thread Object is joinable.");
-  } else {
-    LOG("Thread Object is not joinable.");
-  }
-}
-}  // namespace
-
-/**
- * @brief Thread Exception Example
- */
-namespace exception_before_join {
-class ThreadGuard {
- public:
-  explicit ThreadGuard(std::thread& thread);
-  ~ThreadGuard();
-
-  // no copy & move
-  ThreadGuard operator=(const ThreadGuard& other) = delete;
-  ThreadGuard(const ThreadGuard& other) = delete;
-  ThreadGuard& operator=(ThreadGuard&& other) noexcept = delete;
-  ThreadGuard(ThreadGuard&& other) noexcept = delete;
-
- private:
-  std::thread& thread_;
-};
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-ThreadGuard::ThreadGuard(std::thread& thread) : thread_{thread} {}
+namespace {
 
-ThreadGuard::~ThreadGuard() {
-  if (thread_.joinable()) {
-    thread_.join();
-  }
-}
+using std::chrono::milliseconds;
 
-void callable() {
-  LOG("begin");
-  std::this_thread::sleep_for(std::chrono::milliseconds(5000));
-  LOG("end");
+void logJoinable(const std::thread& thread) {
+  LOG_S("  joinable() = " << std::boolalpha << thread.joinable());
 }
 
-void exceptionThrow() {
-  throw std::runtime_error("callable runtime exception");
-}
+namespace join {
 
 void run() {
-  LOG("Thread Exception Example Begin");
-  std::thread thread(callable);
-
-  // try {
-  //   exceptionThrow();
-  //   thread.join();
-  // } catch (...) {
-  //   thread.join();
-  // }
+  LOG_SECTION("join()");
+  LOG_S("hardware threads available: " << std::thread::hardware_concurrency());
+
+  std::thread worker;  // default-constructed: no thread yet
+  logJoinable(worker);
+
+  worker = std::thread([] {
+    for (int i = 0; i < 3; ++i) {
+      LOG_S("  worker step " << i << " on thread "
+                             << std::this_thread::get_id());
+      std::this_thread::sleep_for(milliseconds(5));
+    }
+  });
+  logJoinable(worker);
+
+  for (int i = 0; i < 3; ++i) {
+    LOG_S("  main step " << i << " on thread " << std::this_thread::get_id());
+    std::this_thread::sleep_for(milliseconds(5));
+  }
 
-  ThreadGuard tg(thread);
-  try {
-    exceptionThrow();
-  } catch (...) {}
-  LOG("Thread Exception Example End");
+  worker.join();  // blocks until the worker has finished
+  logJoinable(worker);
 }
 
-}  // namespace exception_before_join
+}  // namespace join
 
-/**
- * @brief Thread Detach Example
- */
 namespace detach {
-void foo() {
-  LOG("begin");
-  std::this_thread::sleep_for(std::chrono::microseconds(1000));
-  LOG("end");
-}
 
-void bar() {
-  LOG("begin");
-  std::this_thread::sleep_for(std::chrono::microseconds(2000));
-  LOG("end");
+void run() {
+  LOG_SECTION("detach()");
+  std::promise<void> finished;
+  std::future<void> finished_future = finished.get_future();
+
+  std::thread background([done = std::move(finished)]() mutable {
+    std::this_thread::sleep_for(milliseconds(20));
+    LOG("  detached thread: finished its work");
+    done.set_value();
+  });
+  background.detach();
+  logJoinable(background);
+
+  // After detach() nobody can join the thread. Something else must tell us
+  // when it is done - here a promise. A detached thread still running when
+  // main() returns is killed abruptly, so detach rarely is the right tool.
+  finished_future.wait();
+  LOG("  main: got the 'finished' signal");
 }
 
-void run() {
-  LOG("Thread Detach Example Begin");
+}  // namespace detach
 
-  std::thread foo_thread(foo);
-  std::thread bar_thread(bar);
+namespace exception_safety {
 
-  bar_thread
-      .detach();  // https://stackoverflow.com/questions/22803600/when-should-i-use-stdthreaddetach
-  foo_thread.join();  // wait until foo_thread finishes
+/// Joins the thread when the guard goes out of scope - also during stack
+/// unwinding after an exception.
+class ThreadGuard {
+ public:
+  explicit ThreadGuard(std::thread& thread) : thread_{thread} {}
+  ~ThreadGuard() {
+    if (thread_.joinable()) {
+      LOG("  ThreadGuard: joining in the destructor");
+      thread_.join();
+    }
+  }
+  ThreadGuard(const ThreadGuard&) = delete;
+  ThreadGuard& operator=(const ThreadGuard&) = delete;
 
-  LOG("Thread Detach Example End");
-}
-}  // namespace detach
+ private:
+  std::thread& thread_;
+};
 
-/**
- * @brief Thread Join Example
- */
-namespace join {
-void callable() {
-  LOG("begin");
-  for (size_t i = 0; i < 10; ++i) {
-    LOG(std::to_string(i));
-    std::this_thread::sleep_for(std::chrono::milliseconds(5));  // sleep for 5ms
-  }
-  LOG("end");
+void mayThrow() {
+  throw std::runtime_error("error while the worker is running");
 }
 
 void run() {
-  unsigned int threads_num = std::thread::hardware_concurrency();
-  std::cout << "The number of hardware thread contexts: " << threads_num
-            << '\n';
+  LOG_SECTION("Exceptions and RAII (ThreadGuard)");
+  try {
+    std::thread worker([] {
+      std::this_thread::sleep_for(milliseconds(50));
+      LOG("  worker: done");
+    });
+    const ThreadGuard guard(worker);
+    // Without the guard, this throw would destroy a joinable std::thread and
+    // call std::terminate().
+    mayThrow();
+  } catch (const std::exception& e) {
+    LOG_S("  caught: " << e.what());
+  }
+}
 
-  LOG("Thread Join Example Begin");
+}  // namespace exception_safety
 
-  // thread object
-  std::thread user_thread;
-  checkJoinable(user_thread);
-  user_thread = std::thread(callable);
-  checkJoinable(user_thread);
+namespace jthread {
 
-  for (size_t i = 0; i < 10; ++i) {
-    LOG(std::to_string(i));
-    std::this_thread::sleep_for(std::chrono::milliseconds(5));  // sleep for 5ms
+void run() {
+  LOG_SECTION("std::jthread (C++20): auto-join and cooperative stop");
+  {
+    std::jthread ticker([](const std::stop_token& token) {
+      int tick = 0;
+      while (
+          !token.stop_requested()) {  // the thread checks the stop flag itself
+        LOG_S("  tick " << ++tick);
+        std::this_thread::sleep_for(milliseconds(10));
+      }
+      LOG("  stop requested, ticker exits");
+    });
+    std::this_thread::sleep_for(milliseconds(35));
+    LOG("  leaving scope: ~jthread calls request_stop() and join()");
   }
-
-  // sync point, block the execution of the caller until the thread executation(callable) finished
-  user_thread.join();
-  checkJoinable(user_thread);
-
-  LOG("Thread Join Example End");
 }
-}  // namespace join
 
-class ThreadManagement : public IExample {
- public:
-  std::string group() const override { return "core/concurrency"; }
-  std::string name() const override { return "ThreadManagement"; }
-  std::string description() const override {
-    return "The examples for <thread>";
-  }
+}  // namespace jthread
 
-  void execute() override {
-    join::run();
-    detach::run();
-    exception_before_join::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(ThreadManagement);
\ No newline at end of file
+LAB_EXAMPLE("ThreadManagement",
+            "join, detach, joinable, RAII thread guards and std::jthread") {
+  join::run();
+  detach::run();
+  exception_safety::run();
+  jthread::run();
+}
diff --git a/src/core/concurrency/Timing.cpp b/src/core/concurrency/Timing.cpp
index f8b6582..6bdbbc0 100644
--- a/src/core/concurrency/Timing.cpp
+++ b/src/core/concurrency/Timing.cpp
@@ -1,28 +1,75 @@
-#include <thread>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+// -----------------------------------------------------------------------------
+// Measuring time with <chrono>
+//
+//   clocks     : steady_clock (never goes backwards - use it to measure),
+//                system_clock (wall-clock time, can jump when adjusted)
+//   durations  : std::chrono::milliseconds, seconds, ... (type-safe units)
+//   literals   : using namespace std::chrono_literals;  -> 100ms, 2s
+//
+// Measure elapsed time as `steady_clock::now() - start` and convert the
+// result with duration_cast or a floating-point duration.
+//
+// Reference: https://en.cppreference.com/w/cpp/chrono
+// -----------------------------------------------------------------------------
 
 #include <chrono>
+#include <cstdint>
+#include <thread>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
 
-void run() {
+using namespace std::chrono_literals;
+
+void durations() {
+  LOG_SECTION("Durations and literals");
+  const std::chrono::milliseconds timeout = 1500ms;
+  const auto in_seconds =
+      std::chrono::duration_cast<std::chrono::seconds>(timeout);
+  const std::chrono::duration<double> precise =
+      timeout;  // implicit: no precision lost
+
+  LOG_S("1500ms = " << timeout.count() << " ms");
+  LOG_S("duration_cast<seconds>(1500ms) = " << in_seconds.count()
+                                            << " s (truncated)");
+  LOG_S("duration<double>(1500ms)       = " << precise.count() << " s");
+  LOG_S("2s + 250ms = " << (2s +
+                            250ms));  // mixed units: result in the finer unit
+}
+
+void measureSleep() {
+  LOG_SECTION("Measuring a sleep with steady_clock");
   const auto start = std::chrono::steady_clock::now();
-  std::this_thread::sleep_for(std::chrono::seconds(5));
-  const auto finished = std::chrono::steady_clock::now();
+  std::this_thread::sleep_for(100ms);
+  const auto elapsed = std::chrono::steady_clock::now() - start;
 
-  const std::chrono::duration<double> elapsed =
-      finished - start;  // default unit is second
-  LOG_S("Elapsed time: " << elapsed);
+  const std::chrono::duration<double, std::milli> elapsed_ms = elapsed;
+  LOG_S("sleep_for(100ms) took " << elapsed_ms.count()
+                                 << " ms (at least 100 ms, never less)");
 }
 
-class Timing : public IExample {
- public:
-  std::string group() const override { return "core/concurrency"; }
-  std::string name() const override { return "Timing"; }
-  std::string description() const override {
-    return "The examples for <chrono> code timing";
+void measureWork() {
+  LOG_SECTION("Measuring a computation");
+  const auto start = std::chrono::steady_clock::now();
+
+  std::uint64_t sum = 0;
+  for (std::uint64_t i = 0; i < 10'000'000; ++i) {
+    sum += i;
   }
 
-  void execute() override { run(); }
-};
+  const auto elapsed = std::chrono::duration_cast<std::chrono::microseconds>(
+      std::chrono::steady_clock::now() - start);
+  LOG_S("sum = " << sum << " computed in " << elapsed);  // C++20 operator<<
+}
+
+}  // namespace
 
-REGISTER_EXAMPLE(Timing);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Timing",
+    "std::chrono clocks, durations, literals and measuring elapsed time") {
+  durations();
+  measureSleep();
+  measureWork();
+}
diff --git a/src/core/container/README.md b/src/core/container/README.md
index ad52251..8221d77 100644
--- a/src/core/container/README.md
+++ b/src/core/container/README.md
@@ -1,3 +1,30 @@
+# Containers
+
+| Example | Container |
+|---|---|
+| `sequence/Array` | `std::array` - fixed size, on the stack |
+| `sequence/Vector` | `std::vector` - dynamic array, growth and invalidation |
+| `sequence/Deque` | `std::deque` - fast at both ends, stable references |
+| `associative/Set` | `std::set` - sorted unique keys, ranges, `std::multiset` |
+| `unordered/UnorderedMap` | `std::unordered_map` - hash table, lookup pitfalls |
+| `adapter/Stack` | `std::stack` - LIFO |
+| `adapter/Queue` | `std::queue` - FIFO |
+| `adapter/PriorityQueue` | `std::priority_queue` - heap, custom priority |
+
+Choosing a container:
+
+```
+Need key -> value?          no  -> order matters and you insert/erase in the middle? -> std::list
+                                   only at the ends?                                 -> std::deque
+                                   otherwise                                         -> std::vector
+                            yes -> need sorted iteration? -> std::map / std::set
+                                   only fast lookup?      -> std::unordered_map / _set
+```
+
+`std::vector` is the default: contiguous memory keeps the CPU cache happy, which usually beats the
+theoretical advantages of other containers.
+
+---
 # Containers library
 - The Containers library is a generic collection of class templates and algorithms that allow programmers to easilly implement common data structures.
 - All container functions can be called concurrently by different threads on different containers
diff --git a/src/core/container/adapter/PriorityQueue.cpp b/src/core/container/adapter/PriorityQueue.cpp
new file mode 100644
index 0000000..3a30bdc
--- /dev/null
+++ b/src/core/container/adapter/PriorityQueue.cpp
@@ -0,0 +1,78 @@
+// -----------------------------------------------------------------------------
+// std::priority_queue - always pop the "largest" element first
+//
+//   template<class T, class Container = std::vector<T>,
+//            class Compare = std::less<typename Container::value_type>>
+//   class priority_queue;
+//
+// A container ADAPTER implemented as a binary heap on top of std::vector:
+// push() and pop() are O(log n), top() is O(1).
+//
+//   - Default (std::less)  : max-heap, top() is the largest element.
+//   - std::greater<T>      : min-heap, top() is the smallest element.
+//   - Custom comparator    : "a < b" means a has LOWER priority than b.
+//
+// Reference: https://en.cppreference.com/w/cpp/container/priority_queue
+// -----------------------------------------------------------------------------
+
+#include <functional>
+#include <queue>
+#include <string>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+void maxAndMinHeap() {
+  LOG_SECTION("Max-heap and min-heap");
+  const std::vector<int> values{5, 1, 8, 3, 9, 2};
+
+  std::priority_queue<int> max_heap(values.begin(), values.end());
+  std::priority_queue<int, std::vector<int>, std::greater<>> min_heap(values.begin(),
+                                                                      values.end());
+
+  std::string max_order;
+  std::string min_order;
+  while (!max_heap.empty()) {
+    max_order += std::to_string(max_heap.top()) + " ";
+    max_heap.pop();
+    min_order += std::to_string(min_heap.top()) + " ";
+    min_heap.pop();
+  }
+  LOG_S("max-heap pops: " << max_order);
+  LOG_S("min-heap pops: " << min_order);
+}
+
+struct Task {
+  std::string name;
+  int priority;
+};
+
+void customComparator() {
+  LOG_SECTION("Custom comparator: a task scheduler");
+
+  // Returns true when `a` should be served AFTER `b`.
+  auto lower_priority = [](const Task& a, const Task& b) {
+    return a.priority < b.priority;
+  };
+  std::priority_queue<Task, std::vector<Task>, decltype(lower_priority)> tasks(
+      lower_priority);
+
+  tasks.push({"write docs", 1});
+  tasks.push({"fix crash", 10});
+  tasks.push({"code review", 5});
+
+  while (!tasks.empty()) {
+    LOG_S("serve '" << tasks.top().name << "' (priority " << tasks.top().priority << ")");
+    tasks.pop();
+  }
+}
+
+}  // namespace
+
+LAB_EXAMPLE("PriorityQueue", "std::priority_queue: max-heap, min-heap, custom priority") {
+  maxAndMinHeap();
+  customComparator();
+}
diff --git a/src/core/container/adapter/Queue.cpp b/src/core/container/adapter/Queue.cpp
index 72c7b1f..783ea9f 100644
--- a/src/core/container/adapter/Queue.cpp
+++ b/src/core/container/adapter/Queue.cpp
@@ -1,55 +1,64 @@
-// cppcheck-suppress-file []
-
-/**
- * std::queue
- * template<
- *    class T,
- *    class Container = std::deque<T>
- * > class queue;
- *
- * Queue acts as a wrapper to the underlying container (sequence container e.g. std::deque, std::list)
- *  but only a specific 
- * set of functions is provided.
- * It pushs the elements on the back of the underlying container and pops them from the front
- * 
- */
-#include <iostream>
-#include <queue>  // for std::queue
+// -----------------------------------------------------------------------------
+// std::queue - first in, first out (FIFO)
+//
+//   template<class T, class Container = std::deque<T>> class queue;
+//
+// A container ADAPTER: it wraps a sequence container (std::deque by default,
+// or std::list) and only exposes queue operations:
+//   push() adds at the back, pop() removes from the front,
+//   front() / back() access the ends. There are no iterators.
+//
+// Note: pop() returns void. Read front() first, then pop().
+//
+// Reference: https://en.cppreference.com/w/cpp/container/queue
+// -----------------------------------------------------------------------------
+
+#include <list>
+#include <queue>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  // 1. Init
-  std::queue<int> m_queue{};
-
-  // 2. Modifiers
-  m_queue.push(0);  // inserts elements at the end
-  m_queue.push(1);  // q = 0 1
-  m_queue.push(2);  // q = 0 1 2
-  m_queue.push(3);  // q = 0 1 2 3
-
-  m_queue.pop();  // removes the 1st element q = 1 2 3
-
-  // 3. Element access
-  std::cout << "fisrt ele: " << m_queue.front() << "\n";
-  std::cout << "last ele: " << m_queue.back() << "\n";
-
-  // 4. Get all elements and remove
-  std::cout << "all ele: \n";
-  for (; !m_queue.empty(); m_queue.pop()) {
-    std::cout << m_queue.front() << " ";
+
+void basics() {
+  LOG_SECTION("push / pop / front / back");
+  std::queue<int> queue;
+
+  for (int value = 0; value < 4; ++value) {
+    queue.push(value);  // queue: 0 1 2 3
+  }
+  LOG_S("size = " << queue.size() << ", front = " << queue.front()
+                  << ", back = " << queue.back());
+
+  queue.pop();  // removes 0 -> queue: 1 2 3
+  LOG_S("after pop(): front = " << queue.front());
+
+  std::string drained;
+  while (!queue.empty()) {
+    drained += std::to_string(queue.front()) + " ";
+    queue.pop();
   }
-  std::cout << "\n";
+  LOG_S("drained in FIFO order: " << drained);
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void otherContainer() {
+  LOG_SECTION("A queue on top of std::list");
+  std::queue<std::string, std::list<std::string>> tasks;
+  tasks.emplace("compile");  // emplace constructs the element in place
+  tasks.emplace("test");
+  tasks.emplace("deploy");
+
+  while (!tasks.empty()) {
+    LOG_S("next task: " << tasks.front());
+    tasks.pop();
+  }
+}
 
-class Queue : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "Queue"; }
-  std::string description() const override { return "std::queue Example"; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Queue);
\ No newline at end of file
+LAB_EXAMPLE("Queue", "std::queue: FIFO container adapter") {
+  basics();
+  otherContainer();
+}
diff --git a/src/core/container/adapter/Stack.cpp b/src/core/container/adapter/Stack.cpp
index 61ffcaa..b60a3fe 100644
--- a/src/core/container/adapter/Stack.cpp
+++ b/src/core/container/adapter/Stack.cpp
@@ -1,55 +1,73 @@
-// cppcheck-suppress-file []
-
-/**
- * std::stack
- * template<
- *    class T,
- *    class Container = std::deque<T>
- * > class stack;
- *
- * Queue acts as a wrapper to the underlying container (sequence container e.g. std::deque, std::list)
- *  but only a specific 
- * set of functions is provided.
- * It pushs and pops the element from the back of the underlying container, a.k.a the top of the stack
- * 
- */
-#include <iostream>
-#include <stack>  // for std::queue
+// -----------------------------------------------------------------------------
+// std::stack - last in, first out (LIFO)
+//
+//   template<class T, class Container = std::deque<T>> class stack;
+//
+// A container ADAPTER over std::deque (default), std::vector or std::list.
+// push() and pop() work on the "top" (the back of the underlying container),
+// top() reads it. There are no iterators.
+//
+// Typical uses: undo history, expression evaluation, depth-first search.
+//
+// Reference: https://en.cppreference.com/w/cpp/container/stack
+// -----------------------------------------------------------------------------
+
+#include <stack>
+#include <string>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  // 1. Init
-  std::stack<int> m_stack{};
-
-  // 2. Modifiers
-  m_stack.push(0);  // inserts elements at the end
-  m_stack.push(1);  // q = 0 1
-  m_stack.push(2);  // q = 0 1 2
-  m_stack.push(3);  // q = 0 1 2 3
-  m_stack.pop();    // removes the top element q = 0 1 2
-
-  // 3. Element access
-  std::cout << "top ele: " << m_stack.top()
-            << "\n";  // access the top of the stack
-
-  // 4. Get all elements and remove
-  std::cout << "all ele (reverse): \n";
-  for (; !m_stack.empty(); m_stack.pop()) {
-    std::cout << m_stack.top() << " ";
+
+void basics() {
+  LOG_SECTION("push / pop / top");
+  std::stack<int> stack;
+
+  for (int value = 0; value < 4; ++value) {
+    stack.push(value);  // bottom -> top: 0 1 2 3
   }
-  std::cout << "\n";
+  LOG_S("size = " << stack.size() << ", top = " << stack.top());
+
+  stack.pop();  // removes 3
+  LOG_S("after pop(): top = " << stack.top());
+
+  std::string drained;
+  while (!stack.empty()) {
+    drained += std::to_string(stack.top()) + " ";
+    stack.pop();
+  }
+  LOG_S("drained in LIFO order: " << drained);
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
-#include "IExample.h"
+/// Classic stack use case: are the brackets balanced?
+bool isBalanced(const std::string& text) {
+  std::stack<char, std::vector<char>> open;  // stack on top of std::vector
+  for (const char c : text) {
+    if (c == '(' || c == '[' || c == '{') {
+      open.push(c);
+    } else if (c == ')' || c == ']' || c == '}') {
+      const char expected = c == ')' ? '(' : (c == ']' ? '[' : '{');
+      if (open.empty() || open.top() != expected) {
+        return false;
+      }
+      open.pop();
+    }
+  }
+  return open.empty();
+}
 
-class Stack : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "Stack"; }
-  std::string description() const override { return "std::stack Example"; }
-  void execute() override { run(); }
-};
+void balancedBrackets() {
+  LOG_SECTION("Use case: balanced brackets");
+  for (const std::string text : {"{[()()]}", "([)]", "((())"}) {
+    LOG_S(text << " -> " << (isBalanced(text) ? "balanced" : "not balanced"));
+  }
+}
 
-REGISTER_EXAMPLE(Stack);
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE("Stack", "std::stack: LIFO container adapter") {
+  basics();
+  balancedBrackets();
+}
diff --git a/src/core/container/associative/Set.cpp b/src/core/container/associative/Set.cpp
index dffd6cd..bd2345e 100644
--- a/src/core/container/associative/Set.cpp
+++ b/src/core/container/associative/Set.cpp
@@ -1,33 +1,84 @@
+// -----------------------------------------------------------------------------
+// std::set - sorted collection of unique keys
+//
+//   template<class Key, class Compare = std::less<Key>, ...> class set;
+//
+// Usually a red-black tree: insert, erase and find are O(log n), and
+// iteration visits the keys in sorted order.
+//
+//   - insert() returns {iterator, bool}: false if the key already existed.
+//   - contains() (C++20) is the readable way to test membership.
+//   - lower_bound / upper_bound find ranges of keys.
+//   - std::multiset allows duplicate keys; std::unordered_set is hashed and
+//     unsorted (O(1) on average).
+//
+// Reference: https://en.cppreference.com/w/cpp/container/set
+// -----------------------------------------------------------------------------
 
-// cppcheck-suppress-file []
-#include <iostream>
+#include <functional>
 #include <set>
-#include "ExampleRegistry.h"
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  // 1. Init
-  std::set<int> m_set{3, 4, 5, 1, 2};
 
-  // 2. Modifiers
-  m_set.insert(-1);
+template <typename Set>
+std::string join(const Set& set) {
+  std::string text;
+  for (const auto& key : set) {
+    text += std::to_string(key) + " ";
+  }
+  return text;
+}
+
+void basics() {
+  LOG_SECTION("Unique and sorted");
+  std::set<int> numbers{3, 4, 5, 1, 2, 3, 3};  // duplicates are dropped
+  LOG_S("{3, 4, 5, 1, 2, 3, 3} -> " << join(numbers));
+
+  const auto [position, inserted] = numbers.insert(-1);  // structured bindings
+  LOG_S("insert(-1): inserted = " << std::boolalpha << inserted
+                                  << ", *position = " << *position);
+  const bool inserted_again = numbers.insert(-1).second;
+  LOG_S("insert(-1) again: inserted = " << std::boolalpha << inserted_again);
 
-  m_set.insert(99);
-  m_set.erase(99);
+  numbers.erase(5);
+  LOG_S("erase(5) -> " << join(numbers));
+  LOG_S("contains(4) = " << std::boolalpha << numbers.contains(4)
+                         << ", contains(5) = " << numbers.contains(5));
+}
 
-  for (const auto k : m_set) {
-    std::cout << k << " ";
+void ranges() {
+  LOG_SECTION("Range queries");
+  const std::set<int> scores{10, 25, 40, 55, 70, 85};
+  // [lower_bound(30), upper_bound(70)) -> every key in 30..70
+  auto first = scores.lower_bound(30);       // first key >= 30
+  const auto last = scores.upper_bound(70);  // first key > 70
+  std::string in_range;
+  for (; first != last; ++first) {
+    in_range += std::to_string(*first) + " ";
   }
-  std::cout << std::endl;
+  LOG_S("scores between 30 and 70: " << in_range);
+}
+
+void customOrder() {
+  LOG_SECTION("Custom comparator and std::multiset");
+  const std::set<int, std::greater<>> descending{3, 1, 4, 1, 5};
+  LOG_S("std::set<int, std::greater<>>: " << join(descending));
+
+  const std::multiset<int> with_duplicates{3, 1, 4, 1, 5};
+  LOG_S("std::multiset<int>:            "
+        << join(with_duplicates) << "(count(1) = " << with_duplicates.count(1)
+        << ")");
 }
-}  // namespace
 
-class Set : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "Set"; }
-  std::string description() const override { return "std::set Example"; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Set);
\ No newline at end of file
+LAB_EXAMPLE("Set",
+            "std::set: unique sorted keys, insert result, ranges, multiset") {
+  basics();
+  ranges();
+  customOrder();
+}
diff --git a/src/core/container/sequence/Array.cpp b/src/core/container/sequence/Array.cpp
index 82f435b..976288d 100644
--- a/src/core/container/sequence/Array.cpp
+++ b/src/core/container/sequence/Array.cpp
@@ -1,90 +1,138 @@
-// cppcheck-suppress-file [unreadVariable,unusedVariable]
+// -----------------------------------------------------------------------------
+// std::array - a fixed-size array with a container interface
+//
+//   template<class T, std::size_t N> struct array;
+//
+//   - The size is part of the type and fixed at compile time; the elements are
+//     stored inline (no heap allocation).
+//   - Unlike a C array it never decays to a pointer, knows its size(), and can
+//     be copied, compared, and returned from functions.
+//   - operator[] is unchecked; at() throws std::out_of_range.
+//
+// Reference: https://en.cppreference.com/w/cpp/container/array
+// -----------------------------------------------------------------------------
 
-/**
- * std::array
- *  
- * <array>
- *  template< class T, std::size_t N > struct array;
- */
-#include <array>  // for std::array
-#include <iostream>
+#include <algorithm>
+#include <array>
+#include <numeric>
+#include <stdexcept>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  std::cout << "\n--- std::array Example ---\n";
-  // 1) Init
-  std::array<int, 3> m_array = {9, 100, 0};
-  // m_array = {1,2,3,5,6}; // ERROR
-
-  std::array<int, 3> a2{3, 4, 5};
-  std::array<int, 3> a3;     // garbage values for a3[0]-> a4[]
-  std::array<int, 3> a4{};   // all elements have value 0
-  std::array<int, 3> a5{1};  // a5[0] = 0, others elements have value 0
-
-  // 2) Element access
-  std::cout << m_array.front() << std::endl;
-  std::cout << m_array.back() << std::endl;
-
-  int* ptr_arr = m_array.data();
-  std::cout << *(ptr_arr++) << " ";
-  std::cout << *(ptr_arr++) << " ";
-  std::cout << *(ptr_arr++) << " ";
-  std::cout << std::endl;
-
-  // raw for loop
-  for (std::size_t i = 0; i < m_array.size(); ++i) {
-    std::cout << m_array.at(i) << " ";
+
+template <typename Range>
+std::string join(const Range& range) {
+  std::string text;
+  for (const auto& element : range) {
+    text += std::to_string(element) + " ";
   }
+  return text;
+}
+
+void initialization() {
+  LOG_SECTION("Initialization");
+  const std::array<int, 3> values{9, 100, 0};
+  const std::array<int, 3> zeros{};  // every element value-initialized: 0 0 0
+  const std::array<int, 3> partial{1};  // missing elements are zero: 1 0 0
+  [[maybe_unused]] std::array<int, 3>
+      garbage;  // ints are NOT initialized - don't read
+  const auto deduced =
+      std::array{1.5, 2.5};  // C++17 deduction: std::array<double, 2>
+  // std::array<int, 3> too_many{1, 2, 3, 4};   // error: too many initializers
+
+  LOG_S("values{9, 100, 0} -> " << join(values));
+  LOG_S("zeros{}           -> " << join(zeros));
+  LOG_S("partial{1}        -> " << join(partial));
+  LOG_S("std::array{1.5, 2.5} has size " << deduced.size());
+}
 
-  std::cout << std::endl;
+void elementAccess() {
+  LOG_SECTION("Element access");
+  std::array<int, 3> values{9, 100, 0};
+  LOG_S("front() = " << values.front() << ", back() = " << values.back()
+                     << ", values[1] = " << values[1]);
 
-  // for range
-  for (const int& e : m_array) {
-    std::cout << e << " ";
+  const int* raw = values.data();  // pointer to the first element (C interop)
+  LOG_S("data()[2] = " << raw[2]);
+
+  try {
+    values.at(3) = 1;  // bounds-checked
+  } catch (const std::out_of_range& e) {
+    LOG_S("at(3) threw std::out_of_range: " << e.what());
   }
-  std::cout << std::endl;
+  // values[3] = 1;  // NOT checked: undefined behavior
+}
+
+void iteration() {
+  LOG_SECTION("Iteration");
+  const std::array<int, 4> values{1, 2, 3, 4};
 
-  // 3) Iterators
-  std::array<int, 3>::iterator it = m_array.begin();
-  std::array<int, 3>::iterator itEnd = m_array.end();
-  for (; it != itEnd; ++it) {
-    std::cout << *it << " ";
+  std::string by_index;
+  for (std::size_t i = 0; i < values.size(); ++i) {
+    by_index += std::to_string(values[i]) + " ";
   }
-  std::cout << std::endl;
+  LOG_S("index loop   : " << by_index);
+  LOG_S("range-for    : " << join(values));
 
-  auto r_it = m_array.rbegin();
-  auto r_it_end = m_array.rend();
-  for (; r_it != r_it_end; r_it++) {
-    std::cout << *r_it << " ";
+  std::string reversed;
+  for (auto it = values.rbegin(); it != values.rend(); ++it) {
+    reversed += std::to_string(*it) + " ";
   }
-  std::cout << std::endl;
-
-  // 4) Capacity
-  std::cout << m_array.max_size()
-            << std::endl;  // fixed-size => max_size = size
-  std::cout << m_array.size() << std::endl;
-  bool is_empty = m_array.empty();
-
-  // 5) Operation
-  constexpr std::size_t kXy = 4;
-  using Cell = std::array<unsigned char, 8>;
-  std::array<Cell, kXy * kXy> board;
-  board.fill({0xE2, 0x96, 0x84, 0xE2, 0x96, 0x80, 0,
-              0});  // "▄▀"; // fill means fill all 16 Cell with "▄▀"
-  //   board = {Cell{0xE2, 0x96, 0x84, 0xE2, 0x96, 0x80, 0, 0},Cell{0xE2, 0x96, 0x84, 0xE2, 0x96, 0x80, 0, 0}};
-  for (size_t count{}; Cell c : board)
-    std::cout << c.data() << ((++count % kXy) ? "" : "\n");
+  LOG_S("rbegin..rend : " << reversed);
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void operations() {
+  LOG_SECTION("Operations");
+  std::array<int, 5> values{5, 3, 9, 1, 7};
+  std::sort(values.begin(), values.end());
+  LOG_S("sorted        : " << join(values));
+  LOG_S("sum           : " << std::accumulate(values.begin(), values.end(), 0));
+
+  const std::array<int, 5> copy = values;  // arrays copy like any value type
+  LOG_S("copy == values: " << std::boolalpha << (copy == values));
 
-class Array : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "Array"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+  const auto [first, second, third, fourth, fifth] =
+      values;  // structured bindings
+  LOG_S("structured bindings: first = " << first << ", fifth = " << fifth
+                                        << " (" << second + third + fourth
+                                        << " in between)");
 
-REGISTER_EXAMPLE(Array);
\ No newline at end of file
+  values.fill(0);
+  LOG_S("after fill(0) : " << join(values));
+  LOG_S("size() = max_size() = " << values.max_size()
+                                 << " (fixed at compile time)");
+}
+
+void board() {
+  LOG_SECTION("A 2D board: std::array of std::array");
+  constexpr std::size_t kSide = 4;
+  using Row = std::array<const char*, kSide>;
+  std::array<Row, kSide> cells{};
+
+  for (std::size_t row = 0; row < kSide; ++row) {
+    for (std::size_t col = 0; col < kSide; ++col) {
+      cells[row][col] = (row + col) % 2 == 0 ? "##" : "  ";
+    }
+  }
+  for (const Row& row : cells) {
+    std::string line;
+    for (const char* cell : row) {
+      line += cell;
+    }
+    LOG(line);
+  }
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Array",
+            "std::array: fixed-size container, access, iteration, algorithms") {
+  initialization();
+  elementAccess();
+  iteration();
+  operations();
+  board();
+}
diff --git a/src/core/container/sequence/Deque.cpp b/src/core/container/sequence/Deque.cpp
index af9aac6..369f77a 100644
--- a/src/core/container/sequence/Deque.cpp
+++ b/src/core/container/sequence/Deque.cpp
@@ -1,48 +1,68 @@
-// cppcheck-suppress-file []
+// -----------------------------------------------------------------------------
+// std::deque - double-ended queue
+//
+//   - O(1) insertion and removal at BOTH ends, O(1) random access.
+//   - Elements live in fixed-size blocks, not in one contiguous buffer: there
+//     is no data(), and indexing is a little slower than std::vector.
+//   - push_front / push_back never move existing elements, so references and
+//     pointers to them stay valid (iterators do not).
+//   - Insertion or removal in the middle is O(n).
+//
+// Reference: https://en.cppreference.com/w/cpp/container/deque
+// -----------------------------------------------------------------------------
 
-/**
- *  Double-ended queue is an indexed sequence container that allows fast insertion and deletion
- *  and never invalidates pointers or references to the rest of the elements because it use two pointer for 1 elem.
-=> Indexing and iterating performance  < vector
- *  The elements of a deque are not stored contiguously
-
- *  Insertion or removal of elements - linear O(n)
- *  Random access - constant O(1)
- */
 #include <deque>
-#include <iostream>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  // 1) Init
-  std::deque<int> m_deque = {9, 100, 0};
-
-  // 2) Modifiers
-  m_deque.clear();
-
-  m_deque.push_back(1);
-  m_deque.push_back(2);
-  m_deque.push_back(3);
-  m_deque.push_back(4);
-  m_deque.pop_back();
-  m_deque.pop_front();
-  m_deque.push_front(99);
-
-  for (const auto& e : m_deque) {
-    std::cout << e << " ";
+
+std::string join(const std::deque<int>& deque) {
+  std::string text;
+  for (const int element : deque) {
+    text += std::to_string(element) + " ";
   }
-  std::cout << std::endl;
+  return text;
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void bothEnds() {
+  LOG_SECTION("Adding and removing at both ends");
+  std::deque<int> deque{1, 2, 3};
+  LOG_S("start          : " << join(deque));
+
+  deque.push_front(0);
+  deque.push_back(4);
+  LOG_S("push_front(0), push_back(4): " << join(deque));
+
+  deque.pop_front();
+  deque.pop_back();
+  LOG_S("pop_front(), pop_back()    : " << join(deque));
+
+  deque.insert(deque.begin() + 1, 99);  // O(n) in the middle
+  LOG_S("insert at index 1          : " << join(deque));
+  LOG_S("random access deque[2]     = " << deque[2]);
+}
+
+void referenceStability() {
+  LOG_SECTION("References survive push_back / push_front");
+  std::deque<int> deque{42};
+  const int& first = deque.front();
 
-class Deque : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "Deque"; }
-  std::string description() const override { return "std::deque Example"; }
-  void execute() override { run(); }
-};
+  for (int i = 0; i < 10'000; ++i) {
+    deque.push_back(i);
+    deque.push_front(-i);
+  }
+  // With std::vector, growing would reallocate and `first` would dangle.
+  LOG_S("after 20000 insertions, `first` still reads "
+        << first << ", size = " << deque.size());
+}
 
-REGISTER_EXAMPLE(Deque);
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE("Deque",
+            "std::deque: fast insertion at both ends, stable references") {
+  bothEnds();
+  referenceStability();
+}
diff --git a/src/core/container/sequence/Vector.cpp b/src/core/container/sequence/Vector.cpp
index 92cfe69..f51d2a8 100644
--- a/src/core/container/sequence/Vector.cpp
+++ b/src/core/container/sequence/Vector.cpp
@@ -1,60 +1,126 @@
-// cppcheck-suppress-file [unreadVariable,unusedVariable,redundantInitialization]
+// -----------------------------------------------------------------------------
+// std::vector - dynamic contiguous array (the default container)
+//
+//   - size() is the number of elements, capacity() the allocated room.
+//   - When size would exceed capacity, the vector allocates a bigger buffer
+//     and moves every element into it.
+//   - reserve() allocates up front when the final size is known.
+//   - Reallocation invalidates ALL pointers, references and iterators.
+//   - emplace_back constructs in place; push_back copies/moves an object.
+//   - C++20 std::erase / std::erase_if replace the erase-remove idiom.
+//
+// Reference: https://en.cppreference.com/w/cpp/container/vector
+// -----------------------------------------------------------------------------
 
-// ArrayList
-/**
- * std::vector
- *  
- * <vector>
- */
-#include <iostream>
-#include <vector>  // for std::vector
+#include <cstdint>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  std::cout << "\n--- std::vector Example ---\n";
-  // 1) Init
-  std::vector<int> m_vec = {9, 100, 0};
-  m_vec = {1, 2, 3, 5, 6};  // OK
-
-  std::vector<int> m_vec1{9, 100, 0};
-  std::vector<int> m_vec2;
-  std::vector<int> m_vec3{};
-  std::vector<int> m_vec4();
-
-  m_vec.assign({1, 1, 3});
-
-  // 2) Modifiers
-  m_vec.clear();
-
-  auto pos = m_vec.begin();
-  m_vec.insert(pos, 99);
-  pos = m_vec.begin();  // pos may be no longer valid, get a new one
-  m_vec.insert(pos, 9);
-  pos = m_vec.begin();
-  m_vec.erase(pos);
-
-  m_vec.push_back(1);
-  m_vec.push_back(2);
-  m_vec.push_back(3);
-  m_vec.push_back(4);
-
-  m_vec.pop_back();
-
-  for (const auto& e : m_vec) {
-    std::cout << e << " ";
+
+template <typename T>
+std::string join(const std::vector<T>& vector) {
+  std::string text;
+  for (const T& element : vector) {
+    text += std::to_string(element) + " ";
   }
-  std::cout << std::endl;
+  return text;
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void initialization() {
+  LOG_SECTION("Initialization");
+  const std::vector<int> listed{9, 100, 0};  // initializer list
+  const std::vector<int> repeated(3, 7);     // 3 elements with value 7
+  const std::vector<int> empty;
+  std::vector<int> assigned;
+  assigned = {1, 2, 3, 5, 6};  // unlike std::array the size can change
+  // std::vector<int> oops();  // most vexing parse: declares a function!
+
+  LOG_S("listed{9, 100, 0} -> " << join(listed));
+  LOG_S("repeated(3, 7)    -> " << join(repeated));
+  LOG_S("empty.size()      =  " << empty.size());
+  LOG_S("assigned          -> " << join(assigned));
+}
+
+void growth() {
+  LOG_SECTION("size() vs capacity()");
+  std::vector<int> numbers;
+  std::size_t last_capacity = numbers.capacity();
+  for (int i = 0; i < 20; ++i) {
+    numbers.push_back(i);
+    if (numbers.capacity() != last_capacity) {
+      LOG_S("size " << numbers.size() << ": reallocated, capacity "
+                    << last_capacity << " -> " << numbers.capacity());
+      last_capacity = numbers.capacity();
+    }
+  }
+
+  std::vector<int> reserved;
+  reserved.reserve(20);  // one allocation, no reallocation below
+  const auto before = reinterpret_cast<std::uintptr_t>(reserved.data());
+  for (int i = 0; i < 20; ++i) {
+    reserved.push_back(i);
+  }
+  LOG_S("with reserve(20): buffer unchanged = "
+        << std::boolalpha
+        << (before == reinterpret_cast<std::uintptr_t>(reserved.data())));
+
+  numbers.shrink_to_fit();  // non-binding request to release unused capacity
+  LOG_S("after shrink_to_fit: size " << numbers.size() << ", capacity "
+                                     << numbers.capacity());
+}
+
+void modifiers() {
+  LOG_SECTION("Modifiers");
+  std::vector<int> numbers{1, 2, 3};
+
+  numbers.insert(numbers.begin(), 0);  // O(n): shifts every element
+  numbers.push_back(4);
+  numbers.emplace_back(5);
+  LOG_S("insert front, push_back, emplace_back -> " << join(numbers));
+
+  numbers.erase(numbers.begin() + 2);  // removes the element at index 2
+  numbers.pop_back();
+  LOG_S("erase index 2, pop_back              -> " << join(numbers));
+
+  std::vector<int> mixed{1, 2, 3, 4, 5, 6, 7, 8};
+  std::erase_if(mixed, [](int value) { return value % 2 == 0; });  // C++20
+  LOG_S("std::erase_if(even)                  -> " << join(mixed));
+
+  std::vector<std::pair<std::string, int>> people;
+  people.emplace_back("Alice",
+                      30);  // pair constructed directly inside the vector
+  LOG_S("emplace_back(\"Alice\", 30) -> " << people.front().first << ", "
+                                          << people.front().second);
+}
 
-class Vector : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "Vector"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+void invalidation() {
+  LOG_SECTION("Iterator invalidation");
+  std::vector<int> numbers{1, 2, 3};
+  numbers.shrink_to_fit();
+  // Kept as an integer: after the reallocation the old POINTER value must not
+  // be used any more, not even for a comparison.
+  const auto old_address = reinterpret_cast<std::uintptr_t>(numbers.data());
 
-REGISTER_EXAMPLE(Vector);
\ No newline at end of file
+  numbers.push_back(4);  // capacity was full -> reallocation
+  LOG_S("buffer moved after push_back: "
+        << std::boolalpha
+        << (old_address != reinterpret_cast<std::uintptr_t>(numbers.data())));
+  LOG("Any pointer, reference or iterator taken before is now dangling.");
+  LOG("Take new ones after modifying, or reserve() enough capacity first.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Vector",
+    "std::vector: growth and capacity, modifiers, erase_if, invalidation") {
+  initialization();
+  growth();
+  modifiers();
+  invalidation();
+}
diff --git a/src/core/container/unordered/UnorderedMap.cpp b/src/core/container/unordered/UnorderedMap.cpp
index 34e6274..edf8bbb 100644
--- a/src/core/container/unordered/UnorderedMap.cpp
+++ b/src/core/container/unordered/UnorderedMap.cpp
@@ -1,83 +1,117 @@
-// cppcheck-suppress-file [unreadVariable,unusedVariable,redundantInitialization]
-
-// HashMap: Collection of key-value pairs that are hashed by their keys where no two pairs have same keys.
-/**
- * std::unordered_map
- *  
- * <vector>
- */
-#include <iostream>
+// -----------------------------------------------------------------------------
+// std::unordered_map - hash table of unique keys to values
+//
+//   - Average O(1) insert, find and erase (O(n) worst case).
+//   - Iteration order is unspecified and can change after a rehash.
+//   - operator[] INSERTS a default value when the key is missing, so it is not
+//     available on a const map. Use find() / contains() to only look.
+//   - insert / emplace / try_emplace keep an existing value;
+//     insert_or_assign and operator[] overwrite it.
+//
+// Reference: https://en.cppreference.com/w/cpp/container/unordered_map
+// -----------------------------------------------------------------------------
+
+#include <algorithm>
+#include <sstream>
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <vector>
 
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
 namespace {
-void run() {
-  std::cout << "\n--- std::unordered_map Example ---\n";
-  // 1) Init
-  std::unordered_map<std::string, int> m_map{
-      {"k_1", 1}, {"k_2", 2}, {"k_3", 3}};
-
-  // 2) Modifiers
-  m_map.insert({"k_4", 4});
-
-  std::pair<std::string, int> new_elem1 = {"k_5", 0};
-  m_map.insert(new_elem1);
-
-  std::string m_key = "k_6";
-  int m_value = 99;
-  auto new_elem2 = std::make_pair(m_key, m_value);
-  m_map.insert(new_elem2);
-
-  auto m_map2 = m_map;
-  for (auto it = m_map.begin(); it != m_map.end();) {
-    it = m_map.erase(it);
-  }
-  for (const std::pair<const std::string, int>& e : m_map) {
-    std::cout << "[" << e.first << "," << e.second << "]" << " ";
-  }
-  std::cout << std::endl;
 
-  m_map2.insert_or_assign("k_6", 8888);  // WORK
+using Inventory = std::unordered_map<std::string, int>;
 
-  auto pos = m_map2.find("k_6");
-  if (pos != nullptr) {
-    m_map2.insert(std::make_pair(
-        "k_6", 9999));  // cannot reassign if this pair already existed
+/// Prints the map sorted by key, because iteration order is unspecified.
+std::string sorted(const Inventory& inventory) {
+  std::vector<std::pair<std::string, int>> entries(inventory.begin(),
+                                                   inventory.end());
+  std::sort(entries.begin(), entries.end());
+  std::string text;
+  for (const auto& [key, value] : entries) {  // structured bindings
+    text += "[" + key + ": " + std::to_string(value) + "] ";
   }
+  return text;
+}
 
-  // 3) Lookup
-  pos = m_map.find("k_1");
-  std::cout << (pos != nullptr ? "true" : "false") << std::endl;
+void insertion() {
+  LOG_SECTION("Inserting");
+  Inventory inventory{{"apple", 5}, {"banana", 2}};
+  inventory.insert({"cherry", 7});
+  inventory.emplace("date", 1);
+  inventory["elderberry"] = 3;
+  LOG_S("inventory: " << sorted(inventory));
+
+  const bool inserted = inventory.insert({"apple", 100}).second;
+  LOG_S("insert(apple, 100)            -> inserted = "
+        << std::boolalpha << inserted << ", apple = " << inventory["apple"]);
+
+  inventory.try_emplace("apple", 200);  // also keeps the existing value
+  LOG_S("try_emplace(apple, 200)       -> apple = " << inventory["apple"]);
+
+  inventory.insert_or_assign("apple", 300);  // overwrites
+  LOG_S("insert_or_assign(apple, 300)  -> apple = " << inventory["apple"]);
+}
 
-  for (auto const& [k, v] : m_map2) {
-    std::cout << "[" << k << "," << v << "]" << " ";
+void lookup() {
+  LOG_SECTION("Looking up without inserting");
+  Inventory inventory{{"apple", 5}};
+
+  if (const auto it = inventory.find("apple"); it != inventory.end()) {
+    LOG_S("find(apple)     -> " << it->second);
   }
-  std::cout << std::endl;
+  LOG_S("contains(kiwi)  -> " << std::boolalpha << inventory.contains("kiwi"));
 
-  // 4) Make fun
-  std::vector<std::string> keys{};
-  keys.reserve(m_map2.size());
-  for (auto const& [k, v] : m_map2) {
-    keys.push_back(k);
+  try {
+    const Inventory& read_only = inventory;
+    LOG_S("at(kiwi)        -> " << read_only.at("kiwi"));
+  } catch (const std::out_of_range&) {
+    LOG("at(kiwi)        -> throws std::out_of_range");
   }
 
-  std::cout << "Keys: " << std::endl;
-  for (auto const& k : keys) {
-    std::cout << k << " ";
+  LOG_S("operator[](kiwi) -> " << inventory["kiwi"]
+                               << "  <- pitfall: silently inserted kiwi = 0");
+  LOG_S("size is now " << inventory.size());
+}
+
+void erasing() {
+  LOG_SECTION("Erasing while iterating");
+  Inventory inventory{{"apple", 0}, {"banana", 2}, {"cherry", 0}, {"date", 4}};
+  for (auto it = inventory.begin(); it != inventory.end();) {
+    if (it->second == 0) {
+      it = inventory.erase(it);  // erase returns the next valid iterator
+    } else {
+      ++it;
+    }
   }
-  std::cout << std::endl;
+  LOG_S("removed empty items: " << sorted(inventory));
+  // C++20 shortcut: std::erase_if(inventory, [](const auto& e) { return e.second == 0; });
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void wordCount() {
+  LOG_SECTION("Use case: counting words");
+  std::istringstream text(
+      "the quick brown fox jumps over the lazy dog the end");
+  Inventory counts;
+  std::string word;
+  while (text >> word) {
+    ++counts[word];  // here operator[] inserting 0 is exactly what we want
+  }
+  LOG_S("counts: " << sorted(counts));
+  LOG_S("buckets = " << counts.bucket_count()
+                     << ", load factor = " << counts.load_factor());
+}
 
-class UnorderedMap : public IExample {
- public:
-  std::string group() const override { return "core/container"; }
-  std::string name() const override { return "UnorderedMap"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(UnorderedMap);
\ No newline at end of file
+LAB_EXAMPLE(
+    "UnorderedMap",
+    "std::unordered_map: insert vs assign, lookup pitfalls, erase, buckets") {
+  insertion();
+  lookup();
+  erasing();
+  wordCount();
+}
diff --git a/src/core/datatype/Array.cpp b/src/core/datatype/Array.cpp
index 48f022e..4a39a8c 100644
--- a/src/core/datatype/Array.cpp
+++ b/src/core/datatype/Array.cpp
@@ -1,30 +1,92 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// C-style arrays
+//
+//   - `int values[5]` has a size fixed at compile time; elements are contiguous.
+//   - Array-to-pointer decay: in most expressions (and when passed to a
+//     function) an array turns into a pointer to its first element and the
+//     size is lost.
+//   - No bounds checking: values[5] on a 5-element array is undefined behavior.
+//   - std::size(values) (C++17) gives the element count while no decay happened.
+//   - In C++ prefer std::array (fixed) or std::vector (dynamic); use std::span
+//     (C++20) to pass "pointer + size" safely.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/array
+// -----------------------------------------------------------------------------
 
-#include "ExampleRegistry.h"
+#include <iterator>
+#include <span>
+#include <string>
 
-void arrayExamples() {
-  std::cout << "\n--- Array Examples ---\n";
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-  const int arr[5] = {1, 2, 3, 4, 5};
-  for (int i = 0; i < 5; ++i) {
-    std::cout << "arr[" << i << "] = " << arr[i] << "\n";
+namespace {
+
+void initialization() {
+  LOG_SECTION("Initialization");
+  const int numbers[5] = {1, 2, 3};  // remaining elements become 0
+  const int deduced[] = {4, 5, 6};   // size deduced: 3
+  const char text[] = "hi";          // 3 chars: 'h', 'i', '\0'
+
+  std::string listed;
+  for (const int value : numbers) {
+    listed += std::to_string(value) + " ";
+  }
+  LOG_S("int numbers[5] = {1, 2, 3}  -> " << listed);
+  LOG_S("std::size(deduced) = " << std::size(deduced));
+  LOG_S("sizeof(\"hi\") = " << sizeof(text)
+                            << " (includes the terminating '\\0')");
+}
+
+// Looks like it takes an array, but the parameter really is `const int*`.
+// (GCC even warns when you write sizeof(values) here: -Wsizeof-array-argument.)
+void decayed(const int values[]) {
+  LOG_S("inside the function the parameter type has sizeof "
+        << sizeof(decltype(values))
+        << " -> the size of a POINTER, first element " << values[0]);
+}
+
+// std::span keeps pointer and size together (C++20).
+int sum(std::span<const int> values) {
+  int total = 0;
+  for (const int value : values) {
+    total += value;
   }
+  return total;
+}
+
+void decay() {
+  LOG_SECTION("Array-to-pointer decay");
+  const int values[5] = {10, 20, 30, 40, 50};
+  LOG_S("sizeof(values) = " << sizeof(values) << ", element count = "
+                            << sizeof(values) / sizeof(values[0]));
+  decayed(values);
 
-  double matrix[2][3] = {{1.1, 2.2, 3.3}, {4.4, 5.5, 6.6}};
-  for (int i = 0; i < 2; ++i) {
-    for (int j = 0; j < 3; ++j) {
-      std::cout << "matrix[" << i << "][" << j << "] = " << matrix[i][j]
-                << "\n";
+  const int* first = values;  // decay: pointer to values[0]
+  LOG_S("*(first + 2) = " << *(first + 2) << " (same as values[2])");
+  LOG_S("sum(std::span) = " << sum(values) << " (span knows the size is "
+                            << std::span<const int>(values).size() << ")");
+}
+
+void multidimensional() {
+  LOG_SECTION("Multidimensional array");
+  const double matrix[2][3] = {{1.1, 2.2, 3.3}, {4.4, 5.5, 6.6}};
+  for (const auto& row : matrix) {  // each row is a `const double[3]`
+    std::string line;
+    for (const double cell : row) {
+      line += std::to_string(cell).substr(0, 3) + " ";
     }
+    LOG(line);
   }
+  LOG_S("sizeof(matrix) = " << sizeof(matrix) << " = 2 * 3 * sizeof(double)");
 }
 
-class CArray : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Array"; }
-  std::string description() const override { return ""; }
-  void execute() override { arrayExamples(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(CArray);
+LAB_EXAMPLE(
+    "Array",
+    "C arrays: initialization, decay to pointers, std::size, std::span") {
+  initialization();
+  decay();
+  multidimensional();
+}
diff --git a/src/core/datatype/Enum.cpp b/src/core/datatype/Enum.cpp
index a1d136e..dc25a4c 100644
--- a/src/core/datatype/Enum.cpp
+++ b/src/core/datatype/Enum.cpp
@@ -1,53 +1,123 @@
-// cppcheck-suppress-file [unreadVariable]
+// -----------------------------------------------------------------------------
+// Enumerations
+//
+//   enum Color { kRed, kGreen };          unscoped: names leak into the
+//                                         enclosing scope, converts to int
+//   enum class Fruit { kApple, kPear };   scoped (C++11): names stay inside,
+//                                         no implicit conversion - prefer it
+//   enum class Status : std::uint8_t {}   fixed underlying type (size, protocols)
+//   using enum Fruit;                     (C++20) bring enumerators into scope
+//
+// There is no built-in enum -> string conversion; a switch is the usual way.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/enum
+// -----------------------------------------------------------------------------
 
-#include <cstdint>  // for uint8_t
-#include <iostream>
+#include <cstdint>
+#include <string_view>
+#include <type_traits>
 
-// A type defined in terms of other types
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-// *0. Define some enums
-// Unscope enum
-enum BasicEnum { kEnumratorA, kEnumratorB, kEnumratorC };
+namespace {
 
-// Scoped enum - enumrators are inside enum's scope
-enum class ScopeEnumClass { kEnumratorA, kEnumratorB, kEnumratorC };
+enum Color {
+  kRed,
+  kGreen,
+  kBlue
+};  // unscoped: kRed is visible everywhere here
 
-// Scoped enum inside a namespace
-namespace enum_name_space {
-enum class ScopeEnumClass { kEnumratorA, kEnumratorB, kEnumratorC };
-}
+enum class Fruit { kApple, kPear, kCherry };  // scoped
+
+enum class Status : std::uint8_t {  // one byte, explicit values
+  kOk = 0,
+  kWarning = 1,
+  kError = 2,
+};
 
-//  Scoped enum with explicit base type
-enum class ScopeEnumClassB : uint8_t {
-  kEnumratorA = 0,
-  kEnumratorB = 1,
-  kEnumratorC = 2
+/// Bit flags with a scoped enum need their own operators.
+enum class Permission : unsigned {
+  kNone = 0,
+  kRead = 1U << 0U,
+  kWrite = 1U << 1U,
+  kExecute = 1U << 2U,
 };
 
-void enums() {
-  std::cout << "\n--- Enum Type Examples ---\n";
-  // *1. Using unscope enum
-  BasicEnum unscope_e = kEnumratorA;
+constexpr Permission operator|(Permission a, Permission b) {
+  return static_cast<Permission>(static_cast<unsigned>(a) |
+                                 static_cast<unsigned>(b));
+}
 
-  // *2. Using scoped enum
-  ScopeEnumClass scope_e_c = ScopeEnumClass::kEnumratorA;
+constexpr bool has(Permission set, Permission flag) {
+  return (static_cast<unsigned>(set) & static_cast<unsigned>(flag)) != 0U;
+}
 
-  // *3. Using scoped enum namespace
-  enum_name_space::ScopeEnumClass scope_e_c_n =
-      enum_name_space::ScopeEnumClass::kEnumratorA;
+std::string_view toString(Fruit fruit) {
+  switch (fruit) {  // -Wswitch warns if an enumerator is not handled
+    case Fruit::kApple:
+      return "apple";
+    case Fruit::kPear:
+      return "pear";
+    case Fruit::kCherry:
+      return "cherry";
+  }
+  return "unknown";
+}
 
-  // *4. Using scoped enum with base type
-  ScopeEnumClassB st = ScopeEnumClassB::kEnumratorA;
+/// Converts any enum to its underlying integer (std::to_underlying in C++23).
+template <typename Enum>
+constexpr auto toUnderlying(Enum value) {
+  return static_cast<std::underlying_type_t<Enum>>(value);
 }
 
-#include "ExampleRegistry.h"
+void unscoped() {
+  LOG_SECTION("Unscoped enum");
+  const Color color = kGreen;
+  const int as_int = color;  // implicit conversion to int
+  LOG_S("kGreen converts to " << as_int << ", and kBlue + 1 = " << kBlue + 1
+                              << " (compiles, but is rarely meaningful)");
+}
 
-class CEnum : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Enum"; }
-  std::string description() const override { return "Compound type: Enum"; }
-  void execute() override { enums(); }
-};
+void scoped() {
+  LOG_SECTION("Scoped enum (enum class)");
+  const Fruit fruit = Fruit::kPear;
+  // const int bad = fruit;  // error: no implicit conversion
+  LOG_S("Fruit::kPear -> \"" << toString(fruit) << "\", underlying value "
+                             << toUnderlying(fruit));
 
-REGISTER_EXAMPLE(CEnum);
+  using enum Fruit;  // C++20: kCherry can be used without the Fruit:: prefix
+  LOG_S("using enum Fruit; toString(kCherry) = " << toString(kCherry));
+}
+
+void underlyingType() {
+  LOG_SECTION("Underlying type");
+  LOG_S("sizeof(Color)  = " << sizeof(Color)
+                            << " (implementation-defined for unscoped)");
+  LOG_S("sizeof(Fruit)  = " << sizeof(Fruit)
+                            << " (enum class defaults to int)");
+  LOG_S("sizeof(Status) = " << sizeof(Status) << " (: std::uint8_t)");
+  LOG_S("Status::kError = "
+        << static_cast<int>(Status::kError)
+        << "  (cast uint8_t to int, or it prints as a char)");
+}
+
+void flags() {
+  LOG_SECTION("Bit flags");
+  const Permission permissions = Permission::kRead | Permission::kWrite;
+  LOG_S(std::boolalpha << "read: " << has(permissions, Permission::kRead)
+                       << ", write: " << has(permissions, Permission::kWrite)
+                       << ", execute: "
+                       << has(permissions, Permission::kExecute));
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Enum",
+    "unscoped vs scoped enums, underlying types, using enum, bit flags") {
+  unscoped();
+  scoped();
+  underlyingType();
+  flags();
+}
diff --git a/src/core/datatype/Fundamental.cpp b/src/core/datatype/Fundamental.cpp
index f4ec4d3..fb20fd5 100644
--- a/src/core/datatype/Fundamental.cpp
+++ b/src/core/datatype/Fundamental.cpp
@@ -1,62 +1,123 @@
-#include <iostream>
-
-// 	A basic type built into the core C++ language
-void primative() {
-  std::cout << "\n--- Primative Type Examples ---\n";
-  // Boolean
-  bool is_ready = true;
-  std::cout << "bool: " << is_ready << "\n";
-
-  // Character
-  char c = 'A';
-  unsigned char uc = 200;
-  wchar_t wc = L'Ω';  // Greek Omega
-  // char8_t c8 = u8'A';   // UTF-8
-  char16_t c16 = u'ß';   // UTF-16
-  char32_t c32 = U'中';  // UTF-32
-  std::cout << "char: " << c << "\n";
-  std::cout << "unsigned char: " << static_cast<int>(uc) << "\n";
-  std::wcout << L"wchar_t: " << wc << L"\n";
-  // std::cout << "char8_t: " << static_cast<char>(c8) << "\n";
-  std::cout << "char16_t: (UTF-16 code) " << static_cast<int>(c16) << "\n";
-  std::cout << "char32_t: (UTF-32 code) " << static_cast<int>(c32) << "\n";
-
-  // Integer
-  short s = -10;
-  int i = 42;
-  unsigned int ui = 100;
-  long l = 123456L;
-  long long ll = 9876543210LL;
-  std::cout << "short: " << s << "\n";
-  std::cout << "int: " << i << "\n";
-  std::cout << "unsigned int: " << ui << "\n";
-  std::cout << "long: " << l << "\n";
-  std::cout << "long long: " << ll << "\n";
-
-  // Floating Point
-  float f = 3.14F;
-  double d = 2.718281828;
-  long double ld = 1.6180339887L;
-  std::cout << "float: " << f << "\n";
-  std::cout << "double: " << d << "\n";
-  std::cout << "long double: " << ld << "\n";
-
-  // Void
-  std::cout << "void: (no data type, used for functions)\n";
-
-  // pointer
-  int const* ptr = nullptr;
-  std::cout << "nullptr_t: " << ptr << "\n";
+// -----------------------------------------------------------------------------
+// Fundamental types
+//
+//   bool, char types, integers, floating point, void, std::nullptr_t
+//
+//   - The standard only guarantees MINIMUM sizes (e.g. int >= 16 bits, long
+//     >= 32 bits). Use <cstdint> (std::int32_t, std::uint8_t, ...) when the
+//     exact width matters.
+//   - std::numeric_limits<T> describes the range of a type.
+//   - Floating-point numbers are approximations: 0.1 + 0.2 != 0.3.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/types
+// -----------------------------------------------------------------------------
+
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <iomanip>
+#include <limits>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+void booleans() {
+  LOG_SECTION("bool");
+  const bool is_ready = true;
+  LOG_S("is_ready = " << is_ready << " (printed as an int), with boolalpha: "
+                      << std::boolalpha << is_ready);
+  LOG_S("sizeof(bool) = " << sizeof(bool));
+}
+
+void characters() {
+  LOG_SECTION("Character types");
+  const char c = 'A';
+  const unsigned char byte = 200;
+  const wchar_t wide = L'Ω';     // Greek capital omega
+  const char8_t utf8 = u8'A';    // C++20
+  const char16_t utf16 = u'ß';   // German sharp s
+  const char32_t utf32 = U'中';  // CJK "middle"
+
+  LOG_S("char           'A' = " << c << " (code " << static_cast<int>(c)
+                                << ")");
+  LOG_S("unsigned char  200 printed as a number: " << static_cast<int>(byte));
+  // Mixing std::wcout with std::cout on the same stream is not allowed,
+  // so the wide characters are printed as code points.
+  LOG_S("wchar_t   U+" << std::hex << static_cast<unsigned long>(wide)
+                       << std::dec << ", sizeof = " << sizeof(wchar_t));
+  LOG_S("char8_t   U+" << std::hex << static_cast<unsigned>(utf8) << std::dec
+                       << ", sizeof = " << sizeof(char8_t));
+  LOG_S("char16_t  U+" << std::hex << static_cast<unsigned>(utf16) << std::dec
+                       << ", sizeof = " << sizeof(char16_t));
+  LOG_S("char32_t  U+" << std::hex << static_cast<unsigned long>(utf32)
+                       << std::dec << ", sizeof = " << sizeof(char32_t));
+}
+
+template <typename T>
+void describeInteger(const char* name) {
+  LOG_S(std::left << std::setw(14) << name << "sizeof = " << sizeof(T)
+                  << "  range [" << +std::numeric_limits<T>::min() << ", "
+                  << +std::numeric_limits<T>::max() << "]");
 }
 
-#include "ExampleRegistry.h"
+void integers() {
+  LOG_SECTION("Integer types");
+  describeInteger<short>("short");
+  describeInteger<int>("int");
+  describeInteger<unsigned int>("unsigned int");
+  describeInteger<long>("long");
+  describeInteger<long long>("long long");
 
-class Fundamental : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Fundamental"; }
-  std::string description() const override { return "Fundamental"; }
-  void execute() override { primative(); }
-};
+  LOG("Fixed-width types from <cstdint>:");
+  describeInteger<std::int8_t>(
+      "std::int8_t");  // unary + prints numbers, not chars
+  describeInteger<std::uint16_t>("std::uint16_t");
+  describeInteger<std::int32_t>("std::int32_t");
+  describeInteger<std::uint64_t>("std::uint64_t");
+  LOG_S("std::size_t   sizeof = " << sizeof(std::size_t)
+                                  << "  (type of sizeof and indices)");
 
-REGISTER_EXAMPLE(Fundamental);
+  const long long big = 9'876'543'210LL;  // suffixes: U, L, LL, UL, ULL
+  LOG_S("9'876'543'210LL = " << big);
+}
+
+void floatingPoint() {
+  LOG_SECTION("Floating-point types");
+  const float f = 3.14F;
+  const double d = 2.718281828;
+  const long double ld = 1.6180339887L;
+  LOG_S("float        " << f << "  sizeof = " << sizeof(float) << ", ~"
+                        << std::numeric_limits<float>::digits10 << " digits");
+  LOG_S("double       " << d << "  sizeof = " << sizeof(double) << ", ~"
+                        << std::numeric_limits<double>::digits10 << " digits");
+  LOG_S("long double  " << ld << "  sizeof = " << sizeof(long double));
+
+  const double sum = 0.1 + 0.2;
+  LOG_S(std::setprecision(17) << "0.1 + 0.2 = " << sum << " -> == 0.3 is "
+                              << std::boolalpha << (sum == 0.3));
+  LOG_S("compare with a tolerance instead: |sum - 0.3| < 1e-9 is "
+        << std::boolalpha << (std::abs(sum - 0.3) < 1e-9));
+}
+
+void voidAndNullptr() {
+  LOG_SECTION("void and std::nullptr_t");
+  LOG("void: \"no value\" - used as a return type and for void* pointers");
+  const std::nullptr_t null = nullptr;
+  const int* pointer = null;
+  LOG_S("nullptr converts to any pointer type: pointer == nullptr is "
+        << std::boolalpha << (pointer == nullptr));
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Fundamental",
+    "bool, character, integer and floating-point types, sizes and limits") {
+  booleans();
+  characters();
+  integers();
+  floatingPoint();
+  voidAndNullptr();
+}
diff --git a/src/core/datatype/Pointer.cpp b/src/core/datatype/Pointer.cpp
index 556e53c..f87cf76 100644
--- a/src/core/datatype/Pointer.cpp
+++ b/src/core/datatype/Pointer.cpp
@@ -1,116 +1,134 @@
-// cppcheck-suppress-file [unreadVariable]
+// -----------------------------------------------------------------------------
+// Pointers
+//
+//   int* p = &x;    p holds the ADDRESS of x;  *p reads/writes x itself
+//
+//   const int* p          pointer to const : *p cannot change, p can
+//   int* const p          const pointer    : p cannot change, *p can
+//   const int* const p    both are fixed
+//   (read right to left: "p is a const pointer to an int that is const")
+//
+// Pitfalls: dereferencing nullptr or a dangling pointer (to an object that no
+// longer exists) is undefined behavior. For ownership use smart pointers
+// (see core/smart_pointer); raw pointers should only observe.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/pointer
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+void basics() {
+  LOG_SECTION("Address-of & and dereference *");
+  int value = 10;
+  int* pointer = &value;
+  LOG_S("value = " << value << ", &value = " << &value
+                   << ", pointer = " << pointer);
+  LOG_S("*pointer = " << *pointer);
+
+  *pointer = 20;  // writes through the pointer
+  LOG_S("after *pointer = 20, value = " << value);
+
+  const int* nothing = nullptr;  // points to no object
+  LOG_S("nullptr pointer = " << nothing << " - check before dereferencing");
+}
+
+void constCombinations() {
+  LOG_SECTION("const and pointers");
+  int a = 1;
+  int b = 2;
+
+  const int* to_const = &a;  // pointer to const
+  // *to_const = 5;          // error: the pointee is read-only through this pointer
+  to_const = &b;  // OK: the pointer itself may change
+  LOG_S("const int* to_const       -> *to_const = " << *to_const);
 
-#include <iostream>
+  int* const const_pointer = &a;  // const pointer
+  *const_pointer = 5;             // OK: the pointee may change
+  // const_pointer = &b;          // error: the pointer is fixed
+  LOG_S("int* const const_pointer  -> a is now " << a);
 
-// Simple function to demonstrate function pointers
-int foo(int x) {
-  std::cout << "x = " << x << std::endl;
-  return x;
+  const int* const both = &b;  // nothing may change
+  LOG_S("const int* const both     -> *both = " << *both);
 }
 
-void byPtr(int* x) {
-  (*x)++;
-  std::cout << "x = " << *x << std::endl;
+void arithmetic() {
+  LOG_SECTION("Pointer arithmetic");
+  int values[] = {10, 20, 30, 40};
+  int* first = values;     // array decays to a pointer to its first element
+  int* third = first + 2;  // moves by 2 ELEMENTS, not 2 bytes
+  LOG_S("*(first + 2) = " << *third);
+  LOG_S("third - first = " << third - first << " elements ("
+                           << static_cast<std::ptrdiff_t>(sizeof(int)) *
+                                  (third - first)
+                           << " bytes)");
+  ++third;
+  LOG_S("after ++third: *third = " << *third);
+  // first + 4 may be computed (one past the end) but must not be dereferenced.
 }
 
-void byConstPtr(const int* const x) {
-  // *x++;   // error
-  std::cout << "x = " << *x << std::endl;
+void pointerToPointer() {
+  LOG_SECTION("Pointer to pointer");
+  int value = 7;
+  int* pointer = &value;
+  int** pointer_to_pointer = &pointer;
+  **pointer_to_pointer = 70;
+  LOG_S("**pointer_to_pointer = 70 -> value = " << value);
 }
 
-void byPtrConst(const int* x) {
-  // *x++; // error
-  std::cout << "x = " << *x << std::endl;
+void voidPointer() {
+  LOG_SECTION("void* (generic pointer)");
+  int value = 42;
+  void* generic = &value;  // any object pointer converts to void*
+  // *generic;             // error: cannot dereference void*
+  const int* back = static_cast<int*>(generic);  // you must know the real type
+  LOG_S("static_cast<int*>(generic) -> " << *back);
 }
 
-void byConstPtrConst(const int* const x) {
-  // *x++; // error
-  std::cout << "x = " << *x << std::endl;
+int twice(int x) {
+  return 2 * x;
 }
 
-static int global = 42;
-int* returnPtr() {
-  return &global;  // the object must outlive the reference.
+void increment(int* counter) {
+  if (counter != nullptr) {  // pointers can be null, references cannot
+    ++*counter;
+  }
 }
 
-void pointers() {
-  std::cout << "\n--- Pointers Type Examples ---\n";
-  int a = 10;
-  std::cout << "a = " << a << "\n";
-
-  // * 1. Basics
-  const int* null_ptr = nullptr;
-  std::cout << "Address of nullptr (null_ptr): " << null_ptr << "\n";
-
-  // '&' gives the address of a variable
-  int* ptr_a = &a;
-  std::cout << "Address of a (&a): " << &a << "\n";
-  std::cout << "Value stored in pointer (ptr_a): " << ptr_a << "\n";
-
-  // '*' dereferences a pointer (accesses the value at that address)
-  std::cout << "Value of a via *ptr_a: " << *ptr_a << "\n";
-
-  // Change value of a through its pointer
-  *ptr_a = 2;
-  std::cout << "Value of a after *ptr_a = 2: " << a << "\n";
-
-  // * 2. Pointer to const
-  const int const_var = 100;
-  const int* ptr_const_var = &const_var;
-  // *ptr_const_var = 10;     // cannot modify the value through pointer
-  std::cout << "Value of ptr_const_var " << *ptr_const_var << "\n";
-  ptr_const_var = &a;  // can point somewhere else
-  std::cout << "Value of ptr_const_var " << *ptr_const_var << "\n";
-
-  // * 3. Const pointer
-  int* const const_ptr_a = &a;
-  *const_ptr_a = 10;  // can change value
-  // const_ptr_a = nullptr;   //cannot point to another variable
-
-  // * 4. Const pointer to const
-  const int* const const_ptr_const_var = &a;
-  // *const_ptr_const_var = 10;  // cannot modify the value through pointer
-  // const_ptr_const_var = nullptr; //cannot point to another variable
-
-  // * 5. Pointer to pointer
-  int** ptr_ptr_a = new int*[10];  // dynamically allocate an array of 10 int*
-  ptr_ptr_a[0] = &a;
-  std::cout << "Value via pointer-to-pointer (*ptr_ptr_a[0]): " << *ptr_ptr_a[0]
-            << "\n";
-  delete[] ptr_ptr_a;  // always free heap memory
-
-  // * 6. Void pointer (generic pointer)
-  // void *void_ptr = static_cast<int*>(&a);
-  void* void_ptr = &a;  // C-style pointer casting [cstyleCast]
-
-  std::cout << "Value via void pointer (after casting): "
-            << *static_cast<int*>(void_ptr) << "\n";
-
-  // * 7. Function pointer
-  int (*fcn_ptr)(int) = &foo;
-  (*fcn_ptr)(5);  // call via dereference
-  fcn_ptr(10);    // call directly
-
-  // 8. Passing pointers
-  int in = 10;
-  byPtr(&in);
-  byConstPtr(&in);
-  byPtrConst(&in);
-  byConstPtrConst(&in);
-
-  // * 9. Return by ptr(address)
-  const int* b_ptr = returnPtr();
-  std::cout << "By ptr: " << *b_ptr << '\n';
+int* globalCounter() {
+  static int counter = 100;  // lives for the whole program
+  return &counter;           // never return the address of a local variable!
 }
 
-#include "ExampleRegistry.h"
+void functionsAndParameters() {
+  LOG_SECTION("Function pointers and pointer parameters");
+  int (*operation)(int) =
+      &twice;  // pointer to a function taking int, returning int
+  LOG_S("(*operation)(5) = " << (*operation)(5)
+                             << ", operation(6) = " << operation(6));
 
-class CPointers : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Pointer"; }
-  std::string description() const override { return "Compound type: Pointers"; }
-  void execute() override { pointers(); }
-};
+  int counter = 0;
+  increment(&counter);
+  increment(nullptr);  // safely ignored
+  LOG_S("increment(&counter) -> counter = " << counter);
 
-REGISTER_EXAMPLE(CPointers);
+  const int* global = globalCounter();
+  LOG_S("*globalCounter() = " << *global);
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Pointer",
+            "address-of, dereference, const pointers, arithmetic, void*, "
+            "function pointers") {
+  basics();
+  constCombinations();
+  arithmetic();
+  pointerToPointer();
+  voidPointer();
+  functionsAndParameters();
+}
diff --git a/src/core/datatype/README.md b/src/core/datatype/README.md
new file mode 100644
index 0000000..ea75d37
--- /dev/null
+++ b/src/core/datatype/README.md
@@ -0,0 +1,46 @@
+# Data types
+
+| Example           | Topic                                                           |
+|-------------------|-----------------------------------------------------------------|
+| `Fundamental`     | bool, character, integer, floating point; sizes and `std::numeric_limits` |
+| `Array`           | C arrays, array-to-pointer decay, `std::size`, `std::span`       |
+| `Pointer`         | address-of/dereference, const pointers, pointer arithmetic, `void*`, function pointers |
+| `Reference`       | lvalue/rvalue references, const& lifetime extension, `std::move` |
+| `Enum`            | unscoped vs `enum class`, underlying types, `using enum`, flags  |
+| `Struct`          | aggregates, designated initializers, padding and alignment      |
+| `Union`           | the active member rule, `std::bit_cast`, `std::variant`          |
+| `TypeConversions` | implicit conversions, the four casts, slicing, `auto`/`decltype` |
+
+## 1. Fundamental types
+
+The standard only fixes minimum sizes (`int` has at least 16 bits, `long` at least 32). When the
+exact width matters, use `<cstdint>`: `std::int32_t`, `std::uint8_t`, and so on.
+
+## 2. Pointers vs references
+
+|                     | Pointer `T*`          | Reference `T&`        |
+|---------------------|-----------------------|-----------------------|
+| can be null         | yes                   | no                    |
+| can be re-seated    | yes                   | no (bound once)       |
+| must be initialized | no                    | yes                   |
+| arithmetic          | yes                   | no                    |
+
+Read `const` declarations from right to left:
+`const int* p` means "p is a pointer to a const int", and `int* const p` means "p is a const
+pointer to an int".
+
+## 3. Casts
+
+| Cast               | Use for                                                   |
+|--------------------|-----------------------------------------------------------|
+| `static_cast`      | well-defined conversions between related types            |
+| `dynamic_cast`     | safe down-casts in polymorphic hierarchies (checked at run time) |
+| `const_cast`       | adding or removing `const` (writing to a truly const object is UB) |
+| `reinterpret_cast` | low-level reinterpretation of bits and addresses          |
+| `(T)x` C-style     | avoid it: it silently picks any of the above              |
+
+## 4. Unions and variants
+
+Only the member written last may be read. Reading another member is fine in C but undefined
+behavior in C++. To inspect the bytes of a value, use `std::bit_cast` or `std::memcpy`. For a
+type-safe "one of several types", use `std::variant`.
diff --git a/src/core/datatype/Reference.cpp b/src/core/datatype/Reference.cpp
index 7bbb498..91f57b9 100644
--- a/src/core/datatype/Reference.cpp
+++ b/src/core/datatype/Reference.cpp
@@ -1,103 +1,110 @@
-// cppcheck-suppress-file [unreadVariable]
-
-#include <iostream>
-
-// A type defined in terms of other types
-
-void increment(int& x) {
-  x += 1;
+// -----------------------------------------------------------------------------
+// References
+//
+//   int& ref = x;          lvalue reference: another name (alias) for x
+//   const int& cref = 42;  const reference: can bind to temporaries
+//   int&& rref = 42;       rvalue reference: binds to temporaries / std::move
+//
+//   - A reference must be initialized and can never be re-bound.
+//   - Unlike a pointer it cannot be null.
+//   - Pass `const T&` to avoid copies of large objects; `T&` for out-params.
+//   - Never return a reference to a local variable (it dangles).
+//
+// Reference: https://en.cppreference.com/w/cpp/language/reference
+// -----------------------------------------------------------------------------
+
+#include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+void basics() {
+  LOG_SECTION("lvalue references");
+  int value = 10;
+  int& alias = value;  // alias IS value
+  // int& unbound;     // error: references must be initialized
+
+  alias = 20;
+  LOG_S("alias = 20 -> value = " << value);
+  LOG_S("&alias == &value: " << std::boolalpha << (&alias == &value));
+
+  int other = 99;
+  alias = other;  // assigns 99 to value, does NOT re-bind alias to other
+  LOG_S("alias = other -> value = " << value
+                                    << " (alias still refers to value)");
 }
 
-void incrementConst(const int& x) {
-  // s cannot be modified here
-  // x += 1;
+void increment(int& number) {
+  ++number;  // modifies the caller's variable
 }
 
-static int global = 42;
-int& returnRef() {
-  return global;  // the object must outlive the reference.
+std::size_t length(const std::string& text) {  // no copy, cannot modify
+  return text.size();
 }
 
-void references() {
-  std::cout << "\n--- References Type Examples ---\n";
-  int a = 10;
-  std::cout << "a = " << a << "\n";
-
-  // *1. Reference basics
-  // int &ref_error; // reference must be initialized
-  int& ref_a = a;
-
-  ref_a = 20;  // modifies 'a', since ref is just an alias
-  std::cout << "ref_a =20, a = " << a << "\n";  // prints 20
-
-  // Cannot reseat: once 'ref' is bound to 'a', it cannot be bound to another
-  // variable int b = 30; ref = &b;   invalid, would assign value instead of
-  // rebinding
+const std::string& greeting() {
+  static const std::string kGreeting = "hello";  // outlives the function
+  return kGreeting;
+  // Returning a reference to a local std::string would dangle.
+}
 
-  // *2. Pass by reference
-  increment(a);                                      // avoids making a copy
-  std::cout << "a after increment = " << a << "\n";  // prints 21
+void parameters() {
+  LOG_SECTION("Passing and returning references");
+  int counter = 0;
+  increment(counter);
+  LOG_S("increment(counter) -> counter = " << counter);
 
-  // *3. Pass by const reference
-  incrementConst(a);
+  LOG_S("length(\"temporary\") = "
+        << length("temporary")
+        << "  <- const& binds to a temporary std::string");
+  LOG_S("greeting() = " << greeting());
 
-  // *4. Return by reference
-  int const& b = returnRef();
-  std::cout << "By reference: " << b << '\n';
+  const std::string& extended = std::string("lifetime ") + "extended";
+  LOG_S("const& to a temporary keeps it alive: " << extended);
 }
 
-/**
- *
-  a (lvalue)
-  |
-  | std::move(a) (rvalue reference)
-  V
-source (rvalue reference parameter, but it's the lvalue inside the function)
-  |
-  | steal data
-  V
-  b
- */
-namespace rvalue_reference {
-
-// Move-like function taking an rvalue reference as parameter
-int copyConstructor(int&& x) {
-  // Inside the function, x is a named lvalue that refers to the original object
-  // passed in (here, 'a')
-  int result = x * 10;  // compute result based on x
-  x = 0;                // reset the original object to 0
-  return result;        // return the computed result
+void take(int& /*value*/) {
+  LOG("  take(int&)       <- modifiable lvalue");
 }
-
-void run() {
-  int a{10};  // original value
-
-  // Call function with an rvalue reference using std::move
-  // std::move(a) casts a (lvalue) into an rvalue reference (int&&)
-  int b = copyConstructor(std::move(a));
-
-  std::cout << b << std::endl;  // prints 100
-  std::cout
-      << a
-      << std::endl;  // prints 0, because x in the function referred to a and
-                     // was reset
+void take(const int& /*value*/) {
+  LOG("  take(const int&) <- const lvalue");
+}
+void take(int&& /*value*/) {
+  LOG("  take(int&&)      <- rvalue (temporary or std::move)");
 }
 
-}  // namespace rvalue_reference
+/// Takes an rvalue reference, i.e. it is allowed to "consume" its argument.
+std::string consume(std::string&& text) {
+  // Inside the function `text` has a name, so it is an lvalue again.
+  // std::move marks it as an rvalue once more to move it into the result.
+  std::string result = std::move(text);
+  return result + " (consumed)";
+}
 
-#include "ExampleRegistry.h"
+void rvalueReferences() {
+  LOG_SECTION("rvalue references and overload resolution");
+  int number = 1;
+  const int constant = 2;
+  take(number);
+  take(constant);
+  take(3);
+  take(std::move(number));  // std::move is only a cast to int&&
+
+  std::string message = "a long message";
+  const std::string result = consume(std::move(message));
+  LOG_S("result  = " << result);
+  LOG_S("message = \"" << message << "\" (moved-from: valid but unspecified)");
+}
 
-class CReferences : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Reference"; }
-  std::string description() const override {
-    return "Compound type: References";
-  }
-  void execute() override {
-    references();
-    rvalue_reference::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(CReferences);
+LAB_EXAMPLE(
+    "Reference",
+    "lvalue and rvalue references, const& lifetime extension, std::move") {
+  basics();
+  parameters();
+  rvalueReferences();
+}
diff --git a/src/core/datatype/Struct.cpp b/src/core/datatype/Struct.cpp
index 6bec744..c034c14 100644
--- a/src/core/datatype/Struct.cpp
+++ b/src/core/datatype/Struct.cpp
@@ -1,74 +1,113 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Structs
+//
+//   - A struct groups related data. In C++ it can also have member functions;
+//     the only difference to `class` is that members are public by default.
+//   - Default member initializers give every field a sane starting value.
+//   - Padding: the compiler inserts unused bytes so each member sits at an
+//     address matching its alignment. Ordering members from largest to
+//     smallest often reduces the size.
+//   - C++20: designated initializers and `= default` comparison operators.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/class
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
+#include <cstdint>
 #include <string>
 
-// A type defined in terms of other types
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
 
-// *0. Define a struct:
-// structure alignment, padding, decreasing order of size
-// public access
-// In C, structs can only hold data members, not functions.
-struct StructDataType {
-  /* data */
-  double voltage{0.0};  // Default initialization
+struct Sensor {
+  double voltage{0.0};  // default member initializers
   int id{0};
   char status{'N'};
-  std::string label{"Unknown"};
+  std::string label{"unknown"};
 
-  /* function */
   void print() const {
-    std::cout << "Size of struct = " << sizeof(StructDataType) << " bytes"
-              << std::endl;
-    std::cout << "Sensor " << id << " [" << label << "] "
-              << "Voltage: " << voltage << " Status: " << status << std::endl;
+    LOG_S("  Sensor " << id << " [" << label << "] voltage " << voltage
+                      << " V, status " << status);
   }
+
+  bool operator==(const Sensor&) const = default;  // C++20: member-wise ==
 };
 
-void updateVoltageRef(StructDataType& data, double newV) {
-  data.voltage = newV;
+void setVoltage(Sensor& sensor,
+                double volts) {  // by reference: modifies the caller's object
+  sensor.voltage = volts;
 }
 
-void updateVoltagePtr(StructDataType* data, double newV) {
-  // (*data).voltage = newV;
-  if (data)
-    data->voltage = newV;
+void setVoltage(Sensor* sensor, double volts) {  // by pointer: may be null
+  if (sensor != nullptr) {
+    sensor->voltage = volts;  // same as (*sensor).voltage
+  }
 }
 
-StructDataType makeSensor(int id, double v, const std::string& label) {
-  return {v, id, 'N', label};
+Sensor makeSensor(int id, double volts, const std::string& label) {
+  return {volts, id, 'N', label};  // returned by value, no copy (RVO)
 }
 
-void structs() {
-  std::cout << "\n--- Struct Type Examples ---\n";
-  // *1. Using struct
-  [[maybe_unused]] StructDataType data0;  // default init
-  StructDataType data1{3.3, 1, 'N', "Temp1"};
-  StructDataType data2 = {6.3, 2, 'N', "Temp2"};
-
-  // *2. Access members
-  data1.print();
-  const StructDataType* ptr_data1 = &data1;
-  ptr_data1->print();
-
-  // *3. Passing by reference
-  updateVoltageRef(data2, 100);
-  data2.print();
-  // *4. Passing by pointer
-  updateVoltagePtr(&data2, 200);
-  data2.print();
-
-  // *5. Return a temporary struct
-  StructDataType s2 = makeSensor(2, 5.0, "Pressure");
-  s2.print();
+void usage() {
+  LOG_SECTION("Creating and using structs");
+  const Sensor defaults;                    // every member uses its initializer
+  Sensor temperature{3.3, 1, 'N', "temp"};  // aggregate initialization
+  const Sensor pressure{.voltage = 5.0, .id = 2, .label = "pressure"};  // C++20
+
+  defaults.print();
+  temperature.print();
+  pressure.print();
+
+  setVoltage(temperature, 4.2);
+  temperature.print();
+  setVoltage(&temperature, 4.8);
+  temperature.print();
+
+  const Sensor made = makeSensor(3, 1.5, "humidity");
+  made.print();
+
+  const auto& [volts, id, status, label] = made;  // structured bindings
+  LOG_S("  structured bindings: id = " << id << ", label = " << label
+                                       << ", volts = " << volts
+                                       << ", status = " << status);
+  LOG_S("  made == made copy: " << std::boolalpha << (made == Sensor{made}));
 }
 
-#include "ExampleRegistry.h"
+struct Unordered {  // members in "random" order
+  char a;
+  std::int32_t b;
+  char c;
+  std::int64_t d;
+};
 
-class CStruct : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Struct"; }
-  std::string description() const override { return "Compound type: Struct"; }
-  void execute() override { structs(); }
+struct Ordered {  // same members, largest first
+  std::int64_t d;
+  std::int32_t b;
+  char a;
+  char c;
 };
 
-REGISTER_EXAMPLE(CStruct);
+void padding() {
+  LOG_SECTION("Padding and alignment");
+  LOG_S("Unordered {char, int32, char, int64}: sizeof = " << sizeof(Unordered));
+  LOG_S("  offsets: a " << offsetof(Unordered, a) << ", b "
+                        << offsetof(Unordered, b) << ", c "
+                        << offsetof(Unordered, c) << ", d "
+                        << offsetof(Unordered, d));
+  LOG_S("Ordered   {int64, int32, char, char}: sizeof = " << sizeof(Ordered));
+  LOG_S("  offsets: d " << offsetof(Ordered, d) << ", b "
+                        << offsetof(Ordered, b) << ", a "
+                        << offsetof(Ordered, a) << ", c "
+                        << offsetof(Ordered, c));
+  LOG_S("alignof(std::int64_t) = " << alignof(std::int64_t));
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Struct",
+            "structs: initialization, passing, structured bindings, padding") {
+  usage();
+  padding();
+}
diff --git a/src/core/datatype/TypeConVersions.cpp b/src/core/datatype/TypeConVersions.cpp
deleted file mode 100644
index 6dc68b8..0000000
--- a/src/core/datatype/TypeConVersions.cpp
+++ /dev/null
@@ -1,180 +0,0 @@
-// cppcheck-suppress-file [unreadVariable]
-#include <iostream>
-
-class Base {
- public:
-  virtual void show() { std::cout << "Base class\n"; }
-  virtual ~Base() = default;
-};
-
-class Derived : public Base {
- public:
-  void show() override { std::cout << "Derived class\n"; }
-};
-
-class DerivedX : public Base {
- public:
-  void show() override { std::cout << "DerivedX class\n"; }
-};
-
-void implicitConversion() {
-  std::cout << "\n--- Implicit Type Conversion ---\n";
-  // *1. Numeric promotion (safe, no data loss)
-  char c = 'A';
-  int i = c;  // char -> int
-  float f = 3.5F;
-  double d = f;  // float → double
-  bool b = true;
-  int b_to_int = b;  // bool -> int (true=1)
-
-  std::cout << "char to int: " << i << "\n";
-  std::cout << "float to double: " << d << "\n";
-  std::cout << "bool to int: " << b_to_int << "\n";
-
-  // *2. Numeric conversion
-  float pi = 3.14159;
-  double pi_double = pi;  // Widening conversions
-  int pi_int = pi;        // narrowing, may lose fractional part
-  std::cout << "float to double (didening): " << pi_double << "\n";
-  std::cout << "float to int (narrowing): " << pi_int << "\n";
-}
-
-void explicitConversion() {
-  std::cout << "\n--- Explicit Type Conversion ---\n";
-
-  double pi = 3.14159;
-
-  // *1. C-style cast - not safe
-  int pi_c = (int)pi;
-  std::cout << "C-style cast: " << pi_c << "\n";
-
-  // **2. static_cast - type-safe relationship + compile-time type checking**
-  int pi_static = static_cast<int>(pi);
-  std::cout << "static_cast: " << pi_static << "\n";
-
-  //    object -> object
-  Derived derived{};
-  Base base_obj = static_cast<Derived>(derived);
-  // DerivedX derivedx =static_cast<Derived>(derived); // ERROR
-
-  //    object -> reference
-  const Base& base_ref = static_cast<Derived&>(derived);
-  // object -> ptr
-  const Base* base_ptr = static_cast<Derived*>(&derived);
-
-  // **3. const_cast: const_cast adds or removes the const qualifier**
-  const double c_pi = 2.71828;
-  const double* p_const = &c_pi;
-  const double* p_non_const = const_cast<double*>(p_const);  // remove const
-  std::cout << "const_cast: " << *p_non_const << " (removed const)\n";
-
-  // **4. reinterpret_cast: reinterpret memory (unssafe)**
-  // It is used to convert a pointer of some data type into a pointer of another data type,
-  // even if the data types before and after conversion are different. (#static,dynamic)
-  // It does not check if the pointer type and data pointed by the pointer is same or not.
-  const void* p_void = reinterpret_cast<const void*>(&pi);
-  std::cout << "reinterpret_cast: address of pi = " << p_void << "\n";
-
-  // ******************** Use case: Memory-Mapped I/O ******************************
-  // C ===============================================
-  // #define REG_ADDR 0x000fff01
-  //   volatile uint8_t* reg = reinterpret_cast<volatile uint8_t*>(REG_ADDR);
-  //   *reg = 0xF;
-  //   *reg = 0x1;
-
-  // C++ ===============================================
-  // #include <cstdint>
-  // constexpr std::uintptr_t REG_ADDR = 0x000fff02;
-  // auto* const reg = reinterpret_cast<volatile uint8_t*>(REG_ADDR);
-  // *reg = 0xF;
-  // *reg = 0x1;
-  // ********************************************************************************
-
-  // **5. dynamic_cast: safe cast between related classes - type-safe relationship + run-time type checking**
-  // RTTI (RunTime Type Information) check
-  // #include <typeinfor>
-  // if(typeid(*basePtr) == typeid(Derived)){
-  // Derived* derivedPtr = dynamic_cast<Derived*>(basePtr)
-  // }
-
-  Base* base_ptr_2 = new Derived();
-  const Derived* derived_ptr = dynamic_cast<Derived*>(base_ptr_2);
-  if (derived_ptr) {
-    std::cout << "dynamic_cast: Success (Base* -> Derived*)\n";
-  } else {
-    std::cout << "dynamic_cast: Failed\n";
-  }
-
-  Base* another_base = new Base();
-  const Derived* wrong_cast = dynamic_cast<Derived*>(another_base);
-  if (!wrong_cast) {
-    std::cout << "dynamic_cast: nullptr (invalid downcast)\n";
-  }
-  delete base_ptr_2;
-  delete another_base;
-}
-
-void typeAliases() {
-  std::cout << "\n--- Type Aliases ---\n";
-
-  // *1. using - preferred
-  using MyDouble = double;
-  const MyDouble a = 3.14;
-
-  // *2. typedef - old style
-  typedef double OldDouble;
-  OldDouble b = 2.718;
-
-  // *3. Function pointer alias
-  using FuncType = int (*)(double, char);
-  auto func = [](double x, char c) {
-    return static_cast<int>(x) + c;
-  };
-  FuncType fptr = func;
-  std::cout << "Function pointer alias result: " << fptr(2.5, 'A') << "\n";
-}
-
-int add(int x, int y) {
-  return (x + y);
-}
-
-auto add_auto(int a, int b) -> int {
-  return a + b;
-}
-
-void typeDeduction() {
-  std::cout << "\n--- Type Deduction ---\n";
-
-  // *1. auto deduces type
-  auto x = 42;           // int
-  auto y = 3.14;         // double
-  const auto z = x + y;  // double, const ignored in type deduction
-
-  std::cout << "auto x: " << x << ", y: " << y << ", z: " << z << "\n";
-
-  // *2. Trailing return type
-  std::cout << "add(3,4) = " << add(3, 4) << "\n";
-  std::cout << "add_auto(3,4) = " << add_auto(3, 4) << "\n";
-
-  // *3. std::common_type
-  std::common_type_t<int, double> val = x + y;
-  std::cout << "common_type<int,double>: " << val << "\n";
-}
-
-#include "ExampleRegistry.h"
-
-class CTypeConversion : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "TypeConversion"; }
-  std::string description() const override { return ""; }
-  void execute() override {
-    implicitConversion();
-    explicitConversion();
-
-    typeAliases();
-    typeDeduction();
-  }
-};
-
-REGISTER_EXAMPLE(CTypeConversion);
\ No newline at end of file
diff --git a/src/core/datatype/TypeConversions.cpp b/src/core/datatype/TypeConversions.cpp
new file mode 100644
index 0000000..c7baff1
--- /dev/null
+++ b/src/core/datatype/TypeConversions.cpp
@@ -0,0 +1,178 @@
+// -----------------------------------------------------------------------------
+// Type conversions, casts, aliases and type deduction
+//
+// Implicit conversions happen automatically:
+//   - promotions (char -> int, float -> double) never lose information
+//   - conversions (double -> int, int -> unsigned) may lose or change values
+//
+// Explicit casts, from safest to most dangerous:
+//   static_cast       related types, checked at compile time
+//   dynamic_cast      down-casts in polymorphic hierarchies, checked at run time
+//   const_cast        adds/removes const (modifying a truly const object is UB)
+//   reinterpret_cast  treat the bits as another type (pointers, addresses)
+//   (T)value          C-style cast: tries all of the above - avoid it
+//
+// Reference: https://en.cppreference.com/w/cpp/language/expressions#Conversions
+// -----------------------------------------------------------------------------
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <type_traits>
+#include <typeinfo>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+class Base {
+ public:
+  virtual ~Base() = default;
+  virtual std::string name() const { return "Base"; }
+};
+
+class Derived : public Base {
+ public:
+  std::string name() const override { return "Derived"; }
+  std::string onlyInDerived() const { return "Derived::onlyInDerived"; }
+};
+
+class Other : public Base {
+ public:
+  std::string name() const override { return "Other"; }
+};
+
+void implicitConversions() {
+  LOG_SECTION("Implicit conversions");
+  const char letter = 'A';
+  const int promoted = letter;  // promotion: char -> int
+  const float f = 3.5F;
+  const double widened = f;  // promotion: float -> double
+  const bool flag = true;
+  const int from_bool = flag;  // true -> 1
+  LOG_S("'A' -> " << promoted << ", 3.5F -> " << widened << ", true -> "
+                  << from_bool);
+
+  const double pi = 3.14159;
+  const int truncated =
+      static_cast<int>(pi);  // implicitly `int t = pi;` compiles too
+  LOG_S("double 3.14159 -> int " << truncated << " (fraction lost)");
+
+  // Signed/unsigned mixing: -1 is converted to a huge unsigned value first.
+  const int minus_one = -1;
+  const unsigned int one = 1;
+  const bool surprising = static_cast<unsigned int>(minus_one) < one;
+  LOG_S("-1 < 1U evaluates as " << std::boolalpha << surprising
+                                << " (-1 becomes "
+                                << static_cast<unsigned int>(minus_one)
+                                << "); -Wsign-compare warns about it");
+}
+
+void staticAndConstCast() {
+  LOG_SECTION("static_cast and const_cast");
+  const double pi = 3.14159;
+  LOG_S("static_cast<int>(3.14159) = " << static_cast<int>(pi));
+
+  const Derived derived;
+  const Base& as_base =
+      static_cast<const Base&>(derived);  // up-cast: always safe
+  LOG_S("static_cast to Base& keeps the dynamic type: " << as_base.name());
+
+  const Base sliced = derived;  // OBJECT SLICING: only the Base part is copied
+  LOG_S("copying a Derived into a Base object slices it: " << sliced.name());
+
+  int mutable_value = 1;
+  const int* read_only = &mutable_value;
+  int* writable =
+      const_cast<int*>(read_only);  // OK: the object itself is not const
+  *writable = 2;
+  LOG_S("const_cast removed const from a pointer to a non-const int: "
+        << mutable_value);
+  // Doing the same with `const int x = 1;` and writing through it is UB.
+}
+
+void reinterpretCast() {
+  LOG_SECTION("reinterpret_cast");
+  const std::uint32_t value = 0x11223344;
+  const auto* bytes = reinterpret_cast<const unsigned char*>(
+      &value);  // char may alias anything
+  LOG_S("0x11223344 as bytes: "
+        << std::hex << static_cast<int>(bytes[0]) << ' '
+        << static_cast<int>(bytes[1]) << ' ' << static_cast<int>(bytes[2])
+        << ' ' << static_cast<int>(bytes[3]) << std::dec
+        << (bytes[0] == 0x44 ? "  (little-endian)" : "  (big-endian)"));
+
+  // Embedded use case: memory-mapped I/O (only valid on real hardware)
+  //   constexpr std::uintptr_t kRegisterAddress = 0x4001'3800;
+  //   auto* const reg = reinterpret_cast<volatile std::uint32_t*>(kRegisterAddress);
+  //   *reg = 0xF;
+}
+
+void dynamicCast() {
+  LOG_SECTION("dynamic_cast (needs a polymorphic base)");
+  const std::unique_ptr<Base> derived = std::make_unique<Derived>();
+  const std::unique_ptr<Base> other = std::make_unique<Other>();
+
+  if (const auto* as_derived = dynamic_cast<const Derived*>(derived.get())) {
+    LOG_S("Base* -> Derived* succeeded: " << as_derived->onlyInDerived());
+  }
+  if (dynamic_cast<const Derived*>(other.get()) == nullptr) {
+    LOG("Base* -> Derived* on an Other returns nullptr");
+  }
+
+  try {
+    const Base& reference = *other;
+    [[maybe_unused]] const Derived& wrong =
+        dynamic_cast<const Derived&>(reference);
+  } catch (const std::bad_cast& e) {
+    LOG_S("failed reference cast throws std::bad_cast: " << e.what());
+  }
+}
+
+int add(int x, int y) {
+  return x + y;
+}
+
+auto multiply(int x, int y) -> int {  // trailing return type
+  return x * y;
+}
+
+void aliasesAndDeduction() {
+  LOG_SECTION("Type aliases and type deduction");
+  using Celsius = double;     // modern alias
+  typedef double Fahrenheit;  // C-style alias, same meaning
+  using BinaryOperation = int (*)(int, int);
+
+  const Celsius room = 21.5;
+  const Fahrenheit converted = room * 9 / 5 + 32;
+  BinaryOperation operation = add;
+  LOG_S("21.5 C = " << converted
+                    << " F, operation(3, 4) = " << operation(3, 4));
+  operation = multiply;
+  LOG_S("after operation = multiply: operation(3, 4) = " << operation(3, 4));
+
+  auto integer = 42;                           // int
+  auto real = 3.14;                            // double
+  const auto sum = integer + real;             // double
+  decltype(integer) same_type_as_integer = 7;  // int, taken from an expression
+  std::common_type_t<int, double> common = integer;  // double
+  LOG_S("auto sum = int + double -> double: " << sum);
+  LOG_S("decltype(integer) is int: "
+        << std::boolalpha
+        << std::is_same_v<decltype(same_type_as_integer), int>);
+  LOG_S("std::common_type_t<int, double> is double: "
+        << std::boolalpha << std::is_same_v<decltype(common), double>);
+}
+
+}  // namespace
+
+LAB_EXAMPLE("TypeConversions",
+            "implicit conversions, the four C++ casts, slicing, aliases, "
+            "auto/decltype") {
+  implicitConversions();
+  staticAndConstCast();
+  reinterpretCast();
+  dynamicCast();
+  aliasesAndDeduction();
+}
diff --git a/src/core/datatype/Union.cpp b/src/core/datatype/Union.cpp
index 19308fe..513d0cb 100644
--- a/src/core/datatype/Union.cpp
+++ b/src/core/datatype/Union.cpp
@@ -1,50 +1,128 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Unions and std::variant
+//
+//   - All members of a union share the same memory; its size is that of the
+//     largest member (plus padding).
+//   - Only the member written last is "active". Reading another member is
+//     allowed in C but UNDEFINED BEHAVIOR in C++.
+//   - To reinterpret bytes, use std::memcpy or std::bit_cast (C++20).
+//   - A union does not know which member is active. A "tagged union" stores
+//     that separately - std::variant (C++17) does it safely for you.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/union
+// -----------------------------------------------------------------------------
+
+#include <bit>
+#include <cstdint>
 #include <string>
+#include <type_traits>
+#include <variant>
 
-// --- Union Definition ---
-// All members share the same memory
-union UnionDataType {
-  int intValue;
-  float floatValue;
-  char charValue;
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-  void printAll() const {
-    std::cout << "intValue = " << intValue << ", floatValue = " << floatValue
-              << ", charValue = " << charValue << "\n";
-  }
+namespace {
+
+union Number {
+  std::int32_t integer;
+  float real;
+  char letter;
 };
 
-// --- Demonstrate unique property ---
-void unionDemo() {
-  std::cout << "\n--- Union Unique Behavior ---\n";
+void rawUnion() {
+  LOG_SECTION("A plain union");
+  Number number{};
+  number.integer = 65;  // `integer` is now the active member
+  LOG_S("integer = " << number.integer);
 
-  UnionDataType u;
+  number.real = 3.14F;  // switches the active member to `real`
+  LOG_S("real    = " << number.real);
+  // Reading number.integer now would be undefined behavior in C++.
 
-  u.intValue = 65;
-  std::cout << "After assigning intValue = 65:\n";
-  u.printAll();  // Only intValue is meaningful; others show overwritten memory
+  LOG_S("sizeof(Number) = " << sizeof(Number) << " (largest member)");
+}
 
-  u.floatValue = 3.14F;
-  std::cout << "After assigning floatValue = 3.14:\n";
-  u.printAll();  // Writing floatValue overwrites intValue
+void typePunning() {
+  LOG_SECTION("Reading the bits of a float correctly");
+  const float real = 1.0F;
+  const auto bits = std::bit_cast<std::uint32_t>(real);  // C++20, well-defined
+  LOG_S("std::bit_cast<std::uint32_t>(1.0F) = 0x" << std::hex << bits
+                                                  << std::dec << " (IEEE-754)");
+}
 
-  u.charValue = 'A';
-  std::cout << "After assigning charValue = 'A':\n";
-  u.printAll();  // Writing charValue overwrites both intValue and floatValue
+/// A hand-written tagged union: the tag says which member is active.
+struct TaggedNumber {
+  enum class Kind { kInteger, kReal } kind;
+  union {
+    std::int32_t integer;
+    float real;
+  };
+};
 
-  std::cout << "Size of union = " << sizeof(UnionDataType) << " bytes\n";
-  std::cout << "Notice: Only one value is valid at a time.\n";
+void describe(const TaggedNumber& number) {
+  if (number.kind == TaggedNumber::Kind::kInteger) {
+    LOG_S("  tagged: integer " << number.integer);
+  } else {
+    LOG_S("  tagged: real " << number.real);
+  }
 }
 
-// --- Auto-run struct ---
-#include "ExampleRegistry.h"
+using Value = std::variant<int, double, std::string>;
 
-class CUnion : public IExample {
- public:
-  std::string group() const override { return "core/datatype"; }
-  std::string name() const override { return "Union"; }
-  std::string description() const override { return "Compound type: Union"; }
-  void execute() override { unionDemo(); }
-};
+void describe(const Value& value) {
+  // std::visit calls the lambda with the currently held alternative.
+  std::visit(
+      [](const auto& held) {
+        using T = std::decay_t<decltype(held)>;
+        if (std::is_same_v<T, int>) {
+          LOG_S("  variant holds int " << held);
+        } else if (std::is_same_v<T, double>) {
+          LOG_S("  variant holds double " << held);
+        } else {
+          LOG_S("  variant holds std::string \"" << held << "\"");
+        }
+      },
+      value);
+}
 
-REGISTER_EXAMPLE(CUnion);
\ No newline at end of file
+void taggedUnions() {
+  LOG_SECTION("Tagged union vs std::variant");
+  TaggedNumber tagged{};
+  tagged.kind = TaggedNumber::Kind::kInteger;
+  tagged.integer = 7;
+  describe(tagged);
+  tagged.kind =
+      TaggedNumber::Kind::kReal;  // forgetting this line would be a bug
+  tagged.real = 2.5F;
+  describe(tagged);
+
+  Value value = 42;
+  describe(value);
+  value = 3.5;
+  describe(value);
+  value =
+      std::string("hello");  // std::string would not even fit in a plain union
+  describe(value);
+
+  if (const auto* text = std::get_if<std::string>(&value)) {
+    LOG_S("  std::get_if<std::string> -> " << *text);
+  }
+  try {
+    [[maybe_unused]] const int wrong = std::get<int>(value);
+  } catch (const std::bad_variant_access&) {
+    LOG("  std::get<int> on a string alternative throws "
+        "std::bad_variant_access");
+  }
+  LOG_S("  sizeof(Value) = " << sizeof(Value)
+                             << " (largest alternative + index)");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Union",
+            "unions, the active member rule, std::bit_cast, tagged unions and "
+            "std::variant") {
+  rawUnion();
+  typePunning();
+  taggedUnions();
+}
diff --git a/src/core/datetime/README.md b/src/core/datetime/README.md
index 7fec4c5..bfe94c5 100644
--- a/src/core/datetime/README.md
+++ b/src/core/datetime/README.md
@@ -1,3 +1,12 @@
+# Date and time
+
+| Example | Topic |
+|---|---|
+| `Time` | `<ctime>` timestamps and `strftime`, `<chrono>` calendar dates |
+
+See also `core/concurrency/Timing` for measuring elapsed time with `<chrono>`.
+
+---
 # Date and Time
 - <ctime> : provides functions and types to work with date and time values including parsing and formatting (inherited from C)
 
diff --git a/src/core/datetime/Time.cpp b/src/core/datetime/Time.cpp
index 69da59c..35e4339 100644
--- a/src/core/datetime/Time.cpp
+++ b/src/core/datetime/Time.cpp
@@ -1,39 +1,85 @@
-#include <iostream>
-#include "ExampleRegistry.h"
+// -----------------------------------------------------------------------------
+// Date and time (see README.md in this folder for the strftime format codes)
+//
+//   <ctime>   (from C)  std::time_t timestamps, std::tm broken-down time,
+//                       localtime / gmtime / mktime, strftime formatting
+//   <chrono>  (C++11)   type-safe clocks and durations
+//                       (C++20) calendar types such as year_month_day
+//
+// Pitfall: std::localtime and std::gmtime return a pointer to shared static
+// storage and are not thread-safe; POSIX localtime_r / gmtime_r are.
+//
+// Reference: https://en.cppreference.com/w/cpp/chrono/c
+// -----------------------------------------------------------------------------
 
+#include <chrono>
 #include <ctime>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  // **1. Get the current timestamp**
-  std::time_t now = time(nullptr);
-  const auto* ts = ctime(&now);
-  std::cout << "Current time: " << ts << '\n';
-
-  // **2. Create the dt structure**
-  struct tm datetime = *localtime(&now);
-  std::cout << "Year: " << datetime.tm_year + 1900 << '\n';
-  std::cout << "Current time stamp: " << mktime(&datetime) << '\n';
-
-  // **3. Formatting**
-  char output[50];
-  strftime(output, 50, "%B %e, %Y", &datetime);
-  std::cout << output << "\n";
-  strftime(output, 50, "%I:%M:%S %p", &datetime);
-  std::cout << output << "\n";
-  strftime(output, 50, "%m/%d/%y", &datetime);
-  std::cout << output << "\n";
-  strftime(output, 50, "%a %b %e %H:%M:%S %Y", &datetime);
-  std::cout << output << "\n";
+
+std::string format(const std::tm& time, const char* pattern) {
+  char buffer[64]{};
+  const std::size_t length =
+      std::strftime(buffer, sizeof(buffer), pattern, &time);
+  return std::string(buffer, length);
+}
+
+void cTime() {
+  LOG_SECTION("<ctime>");
+  const std::time_t now = std::time(nullptr);  // seconds since 1970-01-01 UTC
+  LOG_S("std::time(nullptr) = " << now);
+
+  std::tm local{};
+  localtime_r(&now, &local);  // thread-safe version of std::localtime
+  std::tm utc{};
+  gmtime_r(&now, &utc);
+
+  LOG_S("year " << local.tm_year + 1900 << ", month " << local.tm_mon + 1
+                << ", day " << local.tm_mday
+                << "  (tm_year counts from 1900, tm_mon from 0)");
+  LOG_S("local : " << format(local, "%Y-%m-%d %H:%M:%S"));
+  LOG_S("UTC   : " << format(utc, "%Y-%m-%d %H:%M:%S"));
+  LOG_S("%B %e, %Y     -> " << format(local, "%B %e, %Y"));
+  LOG_S("%I:%M:%S %p   -> " << format(local, "%I:%M:%S %p"));
+  LOG_S("%a %b %e %H:%M -> " << format(local, "%a %b %e %H:%M"));
+
+  std::tm tomorrow = local;
+  tomorrow.tm_mday += 1;  // may overflow the month...
+  const std::time_t tomorrow_time =
+      std::mktime(&tomorrow);  // ...mktime normalizes it
+  LOG_S("tomorrow: " << format(tomorrow, "%Y-%m-%d") << " ("
+                     << std::difftime(tomorrow_time, now) << " seconds later)");
 }
-}  // namespace
 
-class CTime : public IExample {
- public:
-  std::string group() const override { return "core/datetime"; }
-  std::string name() const override { return "Time"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+void chronoCalendar() {
+  LOG_SECTION("<chrono> calendar (C++20)");
+  const auto now = std::chrono::system_clock::now();
+  const auto today = std::chrono::floor<std::chrono::days>(now);
+  const std::chrono::year_month_day date{today};
 
-REGISTER_EXAMPLE(CTime);
\ No newline at end of file
+  LOG_S("year_month_day: " << static_cast<int>(date.year()) << '-'
+                           << static_cast<unsigned>(date.month()) << '-'
+                           << static_cast<unsigned>(date.day()) << " (UTC)");
+
+  using namespace std::chrono;  // for the calendar literals below
+  const year_month_day new_year = 2026y / January / 1d;
+  const auto days_since = (today - sys_days{new_year}).count();
+  LOG_S("days since 2026-01-01: " << days_since);
+  LOG_S("2024 is a leap year: " << std::boolalpha << year{2024}.is_leap());
+
+  const std::time_t as_time_t =
+      system_clock::to_time_t(now);  // chrono -> C API
+  LOG_S("system_clock::to_time_t(now) = " << as_time_t);
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Time",
+            "<ctime> timestamps and strftime, <chrono> calendar dates") {
+  cTime();
+  chronoCalendar();
+}
diff --git a/src/core/exception/BasicHandle.cpp b/src/core/exception/BasicHandle.cpp
index b5039ae..4d5ca5d 100644
--- a/src/core/exception/BasicHandle.cpp
+++ b/src/core/exception/BasicHandle.cpp
@@ -1,39 +1,114 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Exception handling basics
+//
+//   throw   : report an error; the stack unwinds until a matching catch
+//   try     : a block whose exceptions you want to handle
+//   catch   : handler, tried in order - put the most derived types first
+//
+// Guidelines:
+//   - Throw by value, catch by (const) reference: avoids copies and slicing.
+//   - Derive custom exceptions from std::exception (usually std::runtime_error).
+//   - `throw;` rethrows the CURRENT exception unchanged; `throw e;` would
+//     throw a copy of the caught (possibly sliced) object.
+//   - std::throw_with_nested adds context without losing the original error.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/exceptions
+// -----------------------------------------------------------------------------
+
+#include <exception>
 #include <stdexcept>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void errorFnc() {
-  throw std::runtime_error("[L] error fnc\n");
+
+/// A custom exception carrying extra data.
+class ConfigError : public std::runtime_error {
+ public:
+  ConfigError(const std::string& key, const std::string& message)
+      : std::runtime_error("config key '" + key + "': " + message), key_{key} {}
+  const std::string& key() const { return key_; }
+
+ private:
+  std::string key_;
+};
+
+int parsePort(const std::string& text) {
+  const int port =
+      std::stoi(text);  // throws std::invalid_argument / out_of_range
+  if (port <= 0 || port > 65535) {
+    throw ConfigError("port", "value " + text + " is out of range");
+  }
+  return port;
 }
 
-void run() {
+void catchOrder() {
+  LOG_SECTION("Catch clauses are tried in order");
+  for (const std::string input : {"8080", "99999", "abc"}) {
+    try {
+      LOG_S("parsePort(\"" << input << "\") = " << parsePort(input));
+    } catch (const ConfigError& e) {  // most specific first
+      LOG_S("ConfigError for key '" << e.key() << "': " << e.what());
+    } catch (const std::invalid_argument& e) {
+      LOG_S("std::invalid_argument: " << e.what());
+    } catch (
+        const std::exception& e) {  // everything derived from std::exception
+      LOG_S("std::exception: " << e.what());
+    } catch (...) {  // anything else, even `throw 42;`
+      LOG("unknown exception");
+    }
+  }
+}
+
+void rethrow() {
+  LOG_SECTION("Rethrowing with throw;");
   try {
     try {
-      errorFnc();
-    } catch (std::exception& e) {
-      std::cout << e.what();
-      throw std::runtime_error(
-          "[M] Middle error \n");  // use as custom exception
-      //   throw;   // rethrow
+      throw ConfigError("timeout", "missing");
+    } catch (const std::exception& e) {
+      LOG_S("inner handler logs and rethrows: " << e.what());
+      throw;  // rethrows the original ConfigError, not a std::exception copy
     }
-  } catch (std::exception& e) {
-    std::cout << "[H] " << e.what();
-    std::cout << "Caught an exception of type: " << typeid(e).name()
-              << std::endl;
+  } catch (const ConfigError& e) {
+    LOG_S("outer handler still sees a ConfigError (key '" << e.key() << "')");
   }
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void loadConfiguration() {
+  try {
+    parsePort("0");
+  } catch (...) {
+    std::throw_with_nested(std::runtime_error("failed to load configuration"));
+  }
+}
 
-class BasicHandle : public IExample {
- public:
-  std::string group() const override { return "core/exception"; }
-  std::string name() const override { return "BasicHandle"; }
-  std::string description() const override {
-    return "Basic Expception Handle Example";
+void printNested(const std::exception& e, int depth = 0) {
+  LOG_S(std::string(static_cast<std::size_t>(depth) * 2, ' ')
+        << "- " << e.what());
+  try {
+    std::rethrow_if_nested(e);
+  } catch (const std::exception& nested) {
+    printNested(nested, depth + 1);
   }
-  void execute() override { run(); }
-};
+}
 
-REGISTER_EXAMPLE(BasicHandle);
\ No newline at end of file
+void nestedExceptions() {
+  LOG_SECTION("Nested exceptions keep the cause");
+  try {
+    loadConfiguration();
+  } catch (const std::exception& e) {
+    printNested(e);
+  }
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "BasicHandle",
+    "try/catch/throw, custom exceptions, catch order, rethrow, nesting") {
+  catchOrder();
+  rethrow();
+  nestedExceptions();
+}
diff --git a/src/core/exception/README.md b/src/core/exception/README.md
new file mode 100644
index 0000000..9e3ec51
--- /dev/null
+++ b/src/core/exception/README.md
@@ -0,0 +1,44 @@
+# Exceptions
+
+| Example         | Topic                                                            |
+|-----------------|------------------------------------------------------------------|
+| `BasicHandle`   | try/catch/throw, custom exceptions, catch order, rethrow, nested exceptions |
+| `ThrowNoexcept` | `noexcept` specifier and operator, `std::terminate`, `noexcept` moves in `std::vector` |
+
+## 1. The mechanism
+
+```cpp
+try {
+  mightThrow();
+} catch (const MyError& e) {      // most specific first
+  ...
+} catch (const std::exception& e) {
+  ...
+} catch (...) {                   // anything else
+  throw;                          // rethrow the current exception unchanged
+}
+```
+
+When an exception is thrown, the stack **unwinds**: destructors of all fully constructed local
+objects run until a matching `catch` is found. This makes RAII the foundation of exception
+safety.
+
+## 2. Guidelines
+
+- Throw by value, catch by `const&`. This avoids copies and object slicing.
+- Derive your exceptions from `std::exception`, usually `std::runtime_error` or
+  `std::logic_error`.
+- Use exceptions for exceptional situations. For an expected "no result", `std::optional` is often
+  clearer (see `core/utils/Optional`).
+- Never let an exception escape a destructor. Destructors are `noexcept` by default.
+- Mark move constructors and move assignment `noexcept`; containers rely on it (see the
+  `ThrowNoexcept` example).
+
+## 3. Exception safety guarantees
+
+| Guarantee | Meaning                                                             |
+|-----------|---------------------------------------------------------------------|
+| no-throw  | the operation never throws (`noexcept`)                              |
+| strong    | on failure the state is unchanged ("commit or rollback", e.g. copy-and-swap) |
+| basic     | on failure no resources leak and objects stay valid, but may have changed |
+| none      | anything can happen - avoid                                          |
diff --git a/src/core/exception/ThrowNoexcept.cpp b/src/core/exception/ThrowNoexcept.cpp
index 9693c42..90512f1 100644
--- a/src/core/exception/ThrowNoexcept.cpp
+++ b/src/core/exception/ThrowNoexcept.cpp
@@ -1,49 +1,119 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// noexcept
+//
+//   void f() noexcept;          promise: f never lets an exception escape
+//   void g() noexcept(false);   may throw (the default for most functions)
+//   noexcept(expression)        compile-time operator: can this expression throw?
+//
+//   - If an exception tries to leave a noexcept function, std::terminate() is
+//     called immediately - there is no unwinding to the caller.
+//   - Destructors are noexcept by default.
+//   - Mark move constructors noexcept: std::vector only MOVES its elements
+//     during reallocation when that cannot throw; otherwise it copies them.
+//   - `throw()` is the old spelling, removed in C++20.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/noexcept_spec
+// -----------------------------------------------------------------------------
+
+#include <exception>
 #include <stdexcept>
+#include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-void errorFnc() {
-  throw std::runtime_error("errorFnc\n");
+void mayThrow() {
+  throw std::runtime_error("mayThrow failed");
 }
 
-// void noExpectExcpt() throw() { // deprecated
-void noExpectExcpt() noexcept {
+/// Handles everything inside, so it can honestly promise noexcept.
+void neverThrows() noexcept {
   try {
-    errorFnc();
-  } catch (std::exception& e) {
-    std::cout << typeid(e).name() << " " << e.what();
+    mayThrow();
+  } catch (const std::exception& e) {
+    LOG_S("neverThrows handled the error internally: " << e.what());
   }
 }
 
-// void expectExcpt() noexcept(false) {
-//   try {
-//     errorFnc();
-//   } catch (std::exception& e) {
-//     std::cout << typeid(e).name() << " " << e.what();
-//     throw;
-//   }
-// }
-
-void run() {
-  noExpectExcpt();
-
-  std::set_terminate([]() { exit(-1); });
+void noexceptOperator() {
+  LOG_SECTION("noexcept specifier and operator");
+  neverThrows();
+  LOG_S(std::boolalpha << "noexcept(neverThrows()) = "
+                       << noexcept(neverThrows()));
+  LOG_S(std::boolalpha << "noexcept(mayThrow())    = " << noexcept(mayThrow()));
+  LOG_S(std::boolalpha << "noexcept(1 + 1)         = " << noexcept(1 + 1));
+}
 
-  // expectExcpt(); terminated program when got unhandle exception
+void terminateHandler() {
+  LOG_SECTION("What happens when noexcept is broken");
+  // If mayThrow() were called without try/catch inside a noexcept function,
+  // the program would call std::terminate(). A terminate handler can log
+  // before the process ends, but it must not return.
+  const std::terminate_handler previous = std::set_terminate([] {
+    // would run on terminate, e.g. log and std::abort()
+  });
+  LOG("installed a terminate handler (not triggered here, it would end the "
+      "lab)");
+  std::set_terminate(previous);  // restore: handlers are process-wide state
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+/// Counts how a std::vector treats its elements when it reallocates.
+struct Counters {
+  int copies = 0;
+  int moves = 0;
+};
 
-class ThrowNoexcept : public IExample {
+template <bool kNoexceptMove>
+class Element {
  public:
-  std::string group() const override { return "core/exception"; }
-  std::string name() const override { return "ThrowNoexcept"; }
-  std::string description() const override {
-    return "Exception throw/noexcept Example";
+  explicit Element(Counters& counters) : counters_{&counters} {}
+  Element(const Element& other) : counters_{other.counters_} {
+    ++counters_->copies;
   }
-  void execute() override { run(); }
+  Element(Element&& other) noexcept(kNoexceptMove)
+      : counters_{other.counters_} {
+    ++counters_->moves;
+  }
+  Element& operator=(const Element&) = default;
+  Element& operator=(Element&&) = default;
+  ~Element() = default;
+
+ private:
+  Counters* counters_;
 };
 
-REGISTER_EXAMPLE(ThrowNoexcept);
\ No newline at end of file
+template <bool kNoexceptMove>
+Counters growVector() {
+  Counters counters;
+  std::vector<Element<kNoexceptMove>> elements;
+  for (int i = 0; i < 100; ++i) {
+    elements.emplace_back(counters);  // reallocates several times
+  }
+  return counters;
+}
+
+void moveIfNoexcept() {
+  LOG_SECTION("Why move constructors should be noexcept");
+  const Counters with_noexcept = growVector<true>();
+  const Counters without_noexcept = growVector<false>();
+  LOG_S("move ctor noexcept    : " << with_noexcept.moves << " moves, "
+                                   << with_noexcept.copies << " copies");
+  LOG_S("move ctor may throw   : " << without_noexcept.moves << " moves, "
+                                   << without_noexcept.copies
+                                   << " copies  <- slower!");
+  LOG("std::vector copies to keep its strong exception guarantee when a move "
+      "could throw.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("ThrowNoexcept",
+            "noexcept specifier/operator, std::terminate, noexcept moves in "
+            "std::vector") {
+  noexceptOperator();
+  terminateHandler();
+  moveIfNoexcept();
+}
diff --git a/src/core/filehandle/BinaryFileHandling.cpp b/src/core/filehandle/BinaryFileHandling.cpp
index 02959ae..fc6c371 100644
--- a/src/core/filehandle/BinaryFileHandling.cpp
+++ b/src/core/filehandle/BinaryFileHandling.cpp
@@ -1,121 +1,132 @@
-//cppcheck-suppress-file [invalidPointerCast]
+// -----------------------------------------------------------------------------
+// Binary file I/O
+//
+//   std::ofstream out(path, std::ios::binary);   write raw bytes with write()
+//   std::ifstream in(path, std::ios::binary);    read raw bytes with read()
+//   tellp()/tellg() report and seekp()/seekg() move the write/read position
+//
+// Pitfalls:
+//   - Never dump an object with write(this, sizeof(*this)) if it contains
+//     pointers or owning members such as std::string: only the pointer value
+//     is written, not the characters. Serialize each field instead
+//     (strings as length + bytes).
+//   - Raw binary data depends on type sizes and endianness, so the file is only
+//     portable between identical platforms.
+//
+// Reference: https://en.cppreference.com/w/cpp/io/basic_fstream
+// -----------------------------------------------------------------------------
+
+#include <cstdint>
+#include <filesystem>
 #include <fstream>
-#include <iostream>
 #include <string>
-#include "ExampleRegistry.h"
+#include <utility>
+#include <vector>
 
-namespace {
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-// Important: Do not use sizeof() to dump the raw memory of an object if it contains std::string.
-class Account {
-  friend std::ostream& operator<<(std::ostream&, const Account&);
+namespace {
 
- private:
-  int code_;
-  std::string name_;
-  double balance_;
+namespace fs = std::filesystem;
 
+class Account {
  public:
-  explicit Account(int c = 0, std::string n = "", double b = 0.0)
-      : code_(c), name_(std::move(n)), balance_(b) {}
-
-  int getCode() const { return code_; }
-
-  std::ostream& write(std::ostream&) const;
-  std::istream& read(std::istream&);
-};
-
-std::ostream& Account::write(std::ostream& os) const {
-  os.write(reinterpret_cast<const char*>(&code_), sizeof(code_));
-  os.write(reinterpret_cast<const char*>(&balance_), sizeof(balance_));
-
-  std::size_t length = name_.size();
-  os.write(reinterpret_cast<const char*>(&length), sizeof(length));
-  os.write(name_.data(), length);
-
-  return os;
-}
-
-std::istream& Account::read(std::istream& is) {
-  is.read(reinterpret_cast<char*>(&code_), sizeof(code_));
-  is.read(reinterpret_cast<char*>(&balance_), sizeof(balance_));
-
-  std::size_t length = 0;
-  is.read(reinterpret_cast<char*>(&length), sizeof(length));
-
-  name_.resize(length);
-  is.read(name_.data(), length);
-
-  return is;
-}
-
-std::ostream& operator<<(std::ostream& os, const Account& acc) {
-  os << "Code   : " << acc.code_ << "\n";
-  os << "Name   : " << acc.name_ << "\n";
-  os << "Balance: " << acc.balance_ << "\n";
-  return os;
-}
-
-void run() {
-
-  // ====== WRITE ======
-  Account* accounts[2];
-  accounts[0] = new Account(1, "Whitney Elizabeth Houston", 2500);
-  accounts[1] = new Account(2, "Michael Jackson", 5000);
-
-  std::ofstream outf("data.bin", std::ios::binary | std::ios::trunc);
-
-  if (!outf) {
-    std::cerr << "Cannot open file for writing\n";
-    return;
+  Account() = default;
+  Account(std::int32_t code, std::string name, double balance)
+      : code_{code}, name_{std::move(name)}, balance_{balance} {}
+
+  std::int32_t code() const { return code_; }
+
+  /// Writes code, balance, name length and name characters.
+  void write(std::ostream& out) const {
+    const auto length = static_cast<std::uint32_t>(name_.size());
+    out.write(reinterpret_cast<const char*>(&code_), sizeof(code_));
+    out.write(reinterpret_cast<const char*>(&balance_), sizeof(balance_));
+    out.write(reinterpret_cast<const char*>(&length), sizeof(length));
+    out.write(name_.data(), static_cast<std::streamsize>(length));
   }
 
-  for (int i = 0; i < 2; ++i) {
-    if (!accounts[i]->write(outf))
-      std::cerr << "Error writing account " << i << "\n";
+  /// Reads the fields back in the same order. Returns false on failure.
+  bool read(std::istream& in) {
+    constexpr std::uint32_t kMaxNameLength =
+        1024;  // protects against corrupt files
+    std::uint32_t length = 0;
+    in.read(reinterpret_cast<char*>(&code_), sizeof(code_));
+    in.read(reinterpret_cast<char*>(&balance_), sizeof(balance_));
+    in.read(reinterpret_cast<char*>(&length), sizeof(length));
+    if (!in || length > kMaxNameLength) {
+      return false;
+    }
+    name_.resize(length);
+    in.read(name_.data(), static_cast<std::streamsize>(length));
+    return static_cast<bool>(in);
   }
 
-  outf.close();
-  std::cout << "Finish writing.\n";
-
-  // ====== READ ACCOUNT #2 ======
-  std::ifstream inf("data.bin", std::ios::binary);
-
-  if (!inf) {
-    std::cerr << "Cannot open file for reading\n";
-  } else {
-
-    auto* temp = new Account();
+  std::string describe() const {
+    return "#" + std::to_string(code_) + " " + name_ + ", balance " +
+           std::to_string(balance_);
+  }
 
-    while (inf.peek() != EOF) {
-      temp->read(inf);
+ private:
+  std::int32_t code_{0};
+  std::string name_;
+  double balance_{0.0};
+};
 
-      if (temp->getCode() == 2) {
-        std::cout << "\nAccount #2\n";
-        std::cout << *temp << std::endl;
-        break;
-      }
+void run() {
+  const fs::path path = fs::temp_directory_path() / "cpplab_accounts.bin";
+  const std::vector<Account> accounts{
+      {1, "Whitney Houston", 2500.0},
+      {2, "Michael Jackson", 5000.0},
+      {3, "Freddie Mercury", 4200.0},
+  };
+
+  LOG_SECTION("Writing");
+  std::vector<std::streampos> offsets;  // where each record starts
+  {
+    std::ofstream out(path, std::ios::binary | std::ios::trunc);
+    if (!out) {
+      LOG_S("cannot open " << path << " for writing");
+      return;
+    }
+    for (const Account& account : accounts) {
+      offsets.push_back(out.tellp());
+      account.write(out);
+    }
+  }  // the stream is flushed and closed here (RAII)
+  LOG_S("wrote " << accounts.size() << " accounts, " << fs::file_size(path)
+                 << " bytes to " << path.string());
+  LOG_S("sizeof(Account) = " << sizeof(Account)
+                             << " - the object size is NOT what we store");
+
+  LOG_SECTION("Reading sequentially");
+  {
+    std::ifstream in(path, std::ios::binary);
+    Account account;
+    while (account.read(in)) {
+      LOG_S("  " << account.describe());
     }
-
-    delete temp;
   }
 
-  inf.close();
-
-  // ====== CLEAN MEMORY ======
-  delete accounts[0];
-  delete accounts[1];
+  LOG_SECTION("Random access with seekg");
+  {
+    std::ifstream in(path, std::ios::binary);
+    in.seekg(offsets.at(2));  // jump straight to the third record
+    Account third;
+    if (third.read(in)) {
+      LOG_S("  record 3: " << third.describe());
+    }
+  }
 
-  std::cout << "Finish reading.\n";
+  fs::remove(path);
+  LOG_S("removed " << path.filename().string());
 }
-}  // namespace
 
-class BinaryFileHandling : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "BinaryFileHandling"; }
-  std::string description() const override { return "Binary file handling"; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(BinaryFileHandling);
\ No newline at end of file
+LAB_EXAMPLE(
+    "BinaryFileHandling",
+    "write/read binary records, serialize strings, seekg random access") {
+  run();
+}
diff --git a/src/core/filehandle/Directory.cpp b/src/core/filehandle/Directory.cpp
index 1e05383..3b8039d 100644
--- a/src/core/filehandle/Directory.cpp
+++ b/src/core/filehandle/Directory.cpp
@@ -1,52 +1,94 @@
-#include <filesystem>  // for creating dir
-#include <iostream>
+// -----------------------------------------------------------------------------
+// std::filesystem (C++17)
+//
+//   std::filesystem::path    portable path manipulation (operator/, filename,
+//                            extension, parent_path, ...)
+//   create_directory         creates ONE directory, parent must exist
+//   create_directories       creates the whole chain, like `mkdir -p`
+//   directory_iterator       lists a directory (recursive_directory_iterator
+//                            walks the whole tree)
+//   remove / remove_all      delete a file or empty dir / a whole tree
+//
+// Most functions have two forms: one throws std::filesystem::filesystem_error,
+// the other takes a std::error_code& and never throws.
+//
+// Reference: https://en.cppreference.com/w/cpp/filesystem
+// -----------------------------------------------------------------------------
+
+#include <filesystem>
+#include <fstream>
 #include <string>
+#include <system_error>
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  std::filesystem::path path1{"p1"};
-  std::filesystem::path path2{"p1/p2"};
 
-  std::cout << "[1] Try create_directory(p1/p2)\n";
-  try {
-    if (!std::filesystem::create_directory(path2)) {
-      std::cout << "    Failed: parent directory does not exist\n";
-    }
-  } catch (const std::filesystem::filesystem_error& e) {
-    std::cout << "    Exception: " << e.what() << '\n';
-  }
+namespace fs = std::filesystem;
 
-  std::cout << "[2] Create parent directories: p1\n";
-  std::filesystem::create_directories(path1);
+void paths() {
+  LOG_SECTION("Working with paths");
+  const fs::path file = fs::path("projects") / "cpp-lab" / "src" / "main.cpp";
+  LOG_S("path        : " << file.string());
+  LOG_S("filename    : " << file.filename().string());
+  LOG_S("stem        : " << file.stem().string());
+  LOG_S("extension   : " << file.extension().string());
+  LOG_S("parent_path : " << file.parent_path().string());
+  LOG_S("replace_extension(\".h\") : "
+        << fs::path(file).replace_extension(".h").string());
+}
+
+void directories(const fs::path& root) {
+  LOG_SECTION("Creating directories");
+  const fs::path nested = root / "p1" / "p2";
 
-  std::cout << "[3] Try create_directory(p1/p2) again\n";
-  if (std::filesystem::create_directory(path2)) {
-    std::cout << "    Success\n";
-  } else {
-    std::cout << "    Failed: directory already exists\n";
+  std::error_code error;
+  if (!fs::create_directory(nested, error)) {  // non-throwing overload
+    LOG_S("create_directory(p1/p2) failed: "
+          << error.message() << " (the parent p1 does not exist)");
   }
 
-  std::cout << "[4] Cleanup\n";
-  if (std::filesystem::exists(path2)) {
-    std::filesystem::remove(path2);
-    std::cout << "    Removed p1/p2\n";
+  fs::create_directories(nested);  // creates p1 and p2
+  LOG_S("create_directories(p1/p2) -> exists: " << std::boolalpha
+                                                << fs::exists(nested));
+
+  std::ofstream(nested / "notes.txt") << "hello filesystem\n";
+  std::ofstream(root / "p1" / "readme.md") << "# readme\n";
+
+  LOG_SECTION("Listing directories");
+  for (const fs::directory_entry& entry :
+       fs::recursive_directory_iterator(root)) {
+    const std::string relative = fs::relative(entry.path(), root).string();
+    if (entry.is_directory()) {
+      LOG_S("  [dir]  " << relative);
+    } else {
+      LOG_S("  [file] " << relative << " (" << entry.file_size() << " bytes)");
+    }
   }
+}
 
-  if (std::filesystem::exists(path1)) {
-    std::filesystem::remove(path1);
-    std::cout << "    Removed p1\n";
+void run() {
+  const fs::path root = fs::temp_directory_path() / "cpplab_directory_demo";
+  fs::remove_all(root);  // start from a clean state
+  fs::create_directory(root);
+
+  paths();
+  try {
+    directories(root);
+  } catch (const fs::filesystem_error& e) {
+    LOG_S("filesystem error: " << e.what());
   }
+
+  LOG_SECTION("Cleaning up");
+  const std::uintmax_t removed = fs::remove_all(root);
+  LOG_S("remove_all removed " << removed << " files and directories");
 }
-}  // namespace
 
-class Directory : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "Directory"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Directory);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Directory",
+    "std::filesystem paths, create_directories, iterating and removing") {
+  run();
+}
diff --git a/src/core/filehandle/FileIO.cpp b/src/core/filehandle/FileIO.cpp
index 2e9fdd5..3b1aa86 100644
--- a/src/core/filehandle/FileIO.cpp
+++ b/src/core/filehandle/FileIO.cpp
@@ -1,119 +1,100 @@
+// -----------------------------------------------------------------------------
+// Text file I/O with <fstream>
+//
+//   std::ofstream   output file stream (creates/truncates the file by default)
+//   std::ifstream   input file stream
+//   std::fstream    both directions
+//
+// Steps: open (constructor or open()), check the stream, read/write with
+// << >> getline put get, close (close() or simply let it go out of scope).
+//
+// Open modes: std::ios::app (append), ate (start at the end), trunc (erase),
+// binary, in, out - combine with |.
+//
+// Reference: https://en.cppreference.com/w/cpp/io/basic_ifstream
+// -----------------------------------------------------------------------------
+
+#include <filesystem>
 #include <fstream>
-#include <iostream>
+#include <string>
 
-namespace {
-
-constexpr inline std::string_view kTestFileName = "fileio_test.csv";
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-void fileInput() {
-  std::ifstream in_file{std::string{kTestFileName}};
-  if (!in_file.is_open()) {
-    std::cerr << "Cannot open file: " << kTestFileName << " \n";
-  }
-
-  std::string input_str{};
-  std::cout << "====skip while space content====" << std::endl;
-  while (
-      in_file >>
-      input_str) {  //  Note that ifstream returns a 0 if we’ve reached the end of the file (EOF)
-    std::cout << input_str;
-  }
-  std::cout << "========" << std::endl;
-  std::cout << "====full content====" << std::endl;
+namespace {
 
-  // not skip whitespace
-  in_file.close();
-  in_file.open(std::string{kTestFileName});  // explicitly call open()
-  // The otherway to do this
-  /**
-   * inFile.clear();                 // clear eof/fail flags
-   * inFile.seekg(0);                // rewind
-   */
+namespace fs = std::filesystem;
 
-  input_str.clear();
-  while (std::getline(in_file, input_str)) {
-    std::cout << input_str << std::endl;
+void writeFile(const fs::path& path) {
+  LOG_SECTION("Writing");
+  std::ofstream out(path);  // text mode, truncates an existing file
+  if (!out) {
+    LOG_S("cannot open " << path << " for writing");
+    return;
   }
-  std::cout << "========" << std::endl;
-
-  in_file.close();
+  out << "time_s,gsr_value\n";
+  out << "0.000,45.27\n";
+  out << "0.005,41.69\n";
+  out.put('#');  // a single character
+  out << " end of data\n";
+  LOG_S("wrote 4 lines to " << path.filename().string());
+}  // `out` is closed by its destructor
+
+void appendToFile(const fs::path& path) {
+  LOG_SECTION("Appending");
+  std::ofstream out(path, std::ios::app);  // keep the content, write at the end
+  out << "0.010,38.13\n";
+  LOG("appended one line with std::ios::app");
 }
 
-void fileOutput() {
-  std::ofstream outfile{std::string{
-      kTestFileName}};  // only output stream creates new file if not exist
-  if (!outfile || !outfile.is_open()) {
-    std::cerr << "Cannot open file: " << kTestFileName << " \n";
-    return;
+void readWordByWord(const fs::path& path) {
+  LOG_SECTION("Reading with >> (skips whitespace)");
+  std::ifstream in(path);
+  std::string word;
+  int words = 0;
+  while (in >> word) {  // the stream converts to false at end of file or error
+    ++words;
   }
-
-  // Put bytes data to the file
-  // put string
-  std::string elf_bytes{
-      R"""(
-        time_s,
-        gsr_value 0.0, 45.27761157741693 0.005, 41.69912812397066 0.01,
-        38.13110177547114 0.015, 35.32162785580394 0.02,
-        31.75617843363382 0.025, 28.352875321528607 0.03,
-        25.23210282654006 0.035, 21.769688905641132 0.04,
-        17.99031153059391 0.045, 15.073732055666543 0.05,
-        15.13550182371759 0.055, 14.69547985289048 0.06,
-        14.867397107985468 0.065, 14.982082556093832 0.07,
-        14.893751010484861 0.075, 14.877034044202343 0.08,
-        14.820590581790071 0.085, 15.1065350504897 0.09,
-        15.152287796727098 0.095, 14.764395300078201 0.1,
-        15.118189654760348 0.105, 15.473255351586635 0.11,
-        14.913896402347113
-    \n )"""};
-  outfile << elf_bytes;
-
-  elf_bytes =
-      "0x0 0x0"
-      "0x0 0x0"
-      "0x0 0x0";
-  outfile << elf_bytes;
-
-  elf_bytes =
-      "0xF 0xA \
-              0xE 0xB \
-              0x0 0x0";
-  outfile << elf_bytes;
-
-  outfile.put('E');  // put char
-  outfile.close();
+  LOG_S("operator>> read " << words << " whitespace-separated words");
 }
 
-void fileRemove() {
-  std::remove(std::string{kTestFileName}.c_str());
-  std::ifstream ifile{std::string{kTestFileName}};
-  if (ifile) {
-    std::cerr << "Cannot delete file: " << kTestFileName << " \n";
-    return;
+void readLineByLine(const fs::path& path) {
+  LOG_SECTION("Reading with std::getline (keeps whitespace)");
+  std::ifstream in(path);
+  std::string line;
+  int number = 0;
+  while (std::getline(in, line)) {
+    LOG_S("  line " << ++number << ": " << line);
   }
 
-  std::cout << "Delete file: " << kTestFileName << " \n";
+  // After reaching the end the stream is in the eof/fail state. To read the
+  // file again, clear the flags and rewind (or close and reopen it).
+  in.clear();
+  in.seekg(0);
+  std::getline(in, line);
+  LOG_S("after clear() + seekg(0), the first line again: " << line);
 }
 
 void run() {
-  // Create and produce data to a file
-  fileOutput();
-
-  // Load the created file as input and display its content
-  fileInput();
-
-  // remove the file
-  fileRemove();
+  const fs::path path = fs::temp_directory_path() / "cpplab_fileio_test.csv";
+  writeFile(path);
+  appendToFile(path);
+  readWordByWord(path);
+  readLineByLine(path);
+
+  LOG_SECTION("Removing");
+  const bool removed =
+      fs::remove(path);  // or std::remove(path.c_str()) from <cstdio>
+  LOG_S("removed " << path.filename().string() << ": " << std::boolalpha
+                   << removed);
+
+  std::ifstream missing(path);
+  LOG_S("opening a missing file -> is_open() = " << std::boolalpha
+                                                 << missing.is_open());
 }
-}  // namespace
-
-#include "ExampleRegistry.h"
 
-class FileIO : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "FileIO"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(FileIO);
\ No newline at end of file
+LAB_EXAMPLE("FileIO", "write, append and read text files with fstream") {
+  run();
+}
diff --git a/src/core/filehandle/IOStream.cpp b/src/core/filehandle/IOStream.cpp
index 3e45848..9519e1d 100644
--- a/src/core/filehandle/IOStream.cpp
+++ b/src/core/filehandle/IOStream.cpp
@@ -1,41 +1,84 @@
+// -----------------------------------------------------------------------------
+// Standard streams and stream states
+//
+//   std::cin   standard input  (std::istream)
+//   std::cout  standard output (std::ostream, buffered)
+//   std::cerr  standard error  (unbuffered: appears immediately)
+//   std::clog  standard error  (buffered)
+//
+// Every stream has state flags: good(), eof(), fail(), bad(). A failed
+// extraction sets failbit and all further reads do nothing until clear().
+// Validate input with `if (stream >> value)`.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/stream-states-and-input-validation/
+// -----------------------------------------------------------------------------
+
 #include <iostream>
+#include <limits>
 #include <sstream>
 #include <string>
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  std::cout << "\n--- IO Streams Example ---\n";
-  // 1) input stream
 
-  // input source using std::stringstream
-  std::string input_str{};
-  std::stringstream input("input aa aa");
+void standardStreams() {
+  LOG_SECTION("cout, cerr and clog");
+  std::cout << "[cout] regular output\n";
+  std::cerr << "[cerr] errors, unbuffered\n";
+  std::clog << "[clog] diagnostics, buffered\n";
+  std::cout.flush();
+}
+
+void redirectCin() {
+  LOG_SECTION("Reading std::cin from a string");
+  // Every stream reads through a stream buffer (rdbuf). Swapping the buffer
+  // makes std::cin read from a string - handy for tests.
+  std::istringstream fake_input("Ada Lovelace\n36\n");
+  std::streambuf* original = std::cin.rdbuf(fake_input.rdbuf());
 
-  // save and redirect std::cin
-  auto* old_buf = std::cin.rdbuf(input.rdbuf());
+  std::string name;
+  int age = 0;
+  std::getline(std::cin, name);  // whole line, including the space
+  std::cin >> age;
+
+  std::cin.rdbuf(original);  // always restore the original buffer
+  LOG_S("read name = \"" << name << "\", age = " << age);
+}
 
-  // input from keyboard,
-  // std::cin >> inputStr; // skip whitespace
-  std::getline(std::cin, input_str);  // get all
+void validation() {
+  LOG_SECTION("Stream states and input validation");
+  std::istringstream input("42 abc 7");
+  int value = 0;
 
-  // have to restore std::cin
-  std::cin.rdbuf(old_buf);
+  input >> value;
+  LOG_S("read 42  -> value = " << value << ", good() = " << std::boolalpha
+                               << input.good());
 
-  // 2) output stream
-  std::cout << "[cout] " << input_str << '\n';
-  std::cerr << "[cerr] " << input_str << '\n';  // unbuffered
-  std::clog << "[clog] " << input_str << '\n';  // buffered
+  if (!(input >> value)) {  // "abc" is not a number
+    LOG_S("read abc -> fail() = " << std::boolalpha << input.fail()
+                                  << ", value = " << value
+                                  << " (a failed read stores 0)");
+    input.clear();  // reset the flags...
+    input.ignore(std::numeric_limits<std::streamsize>::max(),
+                 ' ');  // ...skip the bad token
+  }
+
+  if (input >> value) {
+    LOG_S("read 7   -> value = " << value);
+  }
+  input >> value;
+  LOG_S("read past the end -> eof() = " << std::boolalpha << input.eof()
+                                        << ", fail() = " << input.fail());
 }
-}  // namespace
 
-class IOStream : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "IOStream"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(IOStream);
\ No newline at end of file
+LAB_EXAMPLE(
+    "IOStream",
+    "cout/cerr/clog, redirecting cin, stream states and input validation") {
+  standardStreams();
+  redirectCin();
+  validation();
+}
diff --git a/src/core/filehandle/OutputFormatting.cpp b/src/core/filehandle/OutputFormatting.cpp
index 638cfe9..89245aa 100644
--- a/src/core/filehandle/OutputFormatting.cpp
+++ b/src/core/filehandle/OutputFormatting.cpp
@@ -1,74 +1,118 @@
+// -----------------------------------------------------------------------------
+// Output formatting with <iomanip> and std::format
+//
+// Two ways to change how a stream formats values:
+//   - flags        : stream.setf(std::ios::showpos), unsetf(...)
+//   - manipulators : stream << std::hex << std::setw(8) << std::setfill('0')
+//
+// Most settings are STICKY (they stay until changed); std::setw only applies
+// to the next output. Save/restore the state with copyfmt when a function
+// must not leave its settings behind.
+//
+// C++20 std::format("{:>8.2f}", x) formats without touching any stream state.
+//
+// This example formats into std::ostringstream objects, so the settings do
+// not leak into the rest of the program.
+//
+// Reference: https://en.cppreference.com/w/cpp/io/manip
+// -----------------------------------------------------------------------------
+
+#include <format>
 #include <iomanip>
-#include <iostream>
-#include "ExampleRegistry.h"
+#include <sstream>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  std::ios old_state(nullptr);
-  old_state.copyfmt(std::cout);  // Save state
-
-  // std::ios::boolalpha / noboolanpha
-  std::cout << "[boolalpha]\n";
-  std::cout << true << ' ' << false << '\n';  // 0
-  std::cout.setf(std::ios::boolalpha);
-  std::cout << false << ' ' << true << '\n';  // true false
-
-  // std::ios::showpos / noshowpos
-  std::cout << "\n[showpos]\n";
-  std::cout << 5 << ' ' << -5 << '\n';  // 5 -5
-  std::cout.setf(std::ios::boolalpha);
-  std::cout << 5 << ' ' << -5 << '\n';  // +5 -5
-
-  // std::ios::upercase / no
-  std::cout << "\n[uppercase]\n";
-  std::cout << 12345678.9 << '\n';  // 1.23457e+07
-  std::cout.setf(std::ios::uppercase);
-  std::cout << 12345678.9 << '\n';  // 1.23457E+07
-
-  // std::ios::basefield
-  // std::ios::dec
-  // std::ios::hex
-  // std::ios::oct
-  std::cout << "\n[base: dec / hex / oct]\n";
-  std::cout << 11 << '\n';  // 11
-  std::cout.setf(std::ios::hex, std::ios::basefield);
-  std::cout << 11 << '\n';  // B
-
-  // std::fixed - use dec notation
-  std::cout << "\n[fixed vs scientific]\n";
-  std::cout << std::fixed << '\n';
-  std::cout << std::setprecision(5) << 123.456 << '\n';  // 123.45600
-
-  // std::scientific
-  std::cout << std::scientific << '\n';
-  std::cout << std::setprecision(5) << 123.456 << '\n';  // 1.23456e+002
-
-  // reset ========================================================
-  std::cout.copyfmt(old_state);  // Restore state
-
-  // std::setw() - set the filed width for input and output
-  // std::left/right/internal - left/right justifies - Left-justifies the sign of the number, and right-justifies the value
-  std::cout << "\n[width & alignment]\n";
-  std::cout << "|" << -12345 << "|\n";
-  std::cout << "|" << std::setw(10) << -12345 << "|\n";               // right
-  std::cout << "|" << std::setw(10) << std::left << -12345 << "|\n";  // left
-  std::cout << "|" << std::setw(10) << std::internal << -12345 << "|\n";  // internal
-
-  // std::fill(char) set the fill char
-  std::cout << "\n[fill]\n";
-  std::cout.fill('*');
-  std::cout << std::setw(10) << std::internal << -12345 << '\n';
-
-  std::cout.copyfmt(old_state);  // Restore state
+
+void flags() {
+  LOG_SECTION("Flags: boolalpha, showpos, uppercase");
+  std::ostringstream out;
+
+  out << true << ' ' << false;
+  LOG_S("default        : " << out.str());
+
+  out.str("");
+  out.setf(std::ios::boolalpha);
+  out << true << ' ' << false;
+  LOG_S("boolalpha      : " << out.str());
+
+  out.str("");
+  out.setf(std::ios::showpos);
+  out << 5 << ' ' << -5;
+  LOG_S("showpos        : " << out.str());
+  out.unsetf(std::ios::showpos);
+
+  out.str("");
+  out.setf(std::ios::uppercase);
+  out << 12345678.9 << ' ' << std::hex << 255;
+  LOG_S("uppercase      : " << out.str());
 }
-}  // namespace
 
-class OutputFormatting : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "OutputFormatting"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+void numberBases() {
+  LOG_SECTION("Number bases");
+  std::ostringstream out;
+  out << std::showbase << "dec " << std::dec << 255 << ", hex " << std::hex
+      << 255 << ", oct " << std::oct << 255;
+  LOG(out.str());
+}
+
+void floatingPoint() {
+  LOG_SECTION("Floating point: precision, fixed, scientific");
+  const double value = 123.456789;
+  std::ostringstream out;
+
+  out << value << " | " << std::setprecision(4) << value;
+  LOG_S("default, setprecision(4) : " << out.str() << "  (significant digits)");
 
-REGISTER_EXAMPLE(OutputFormatting);
\ No newline at end of file
+  out.str("");
+  out << std::fixed << std::setprecision(2) << value;
+  LOG_S("fixed + setprecision(2)  : " << out.str()
+                                      << "  (digits after the point)");
+
+  out.str("");
+  out << std::scientific << std::setprecision(3) << value;
+  LOG_S("scientific               : " << out.str());
+}
+
+void widthAndAlignment() {
+  LOG_SECTION("Width, alignment and fill");
+  std::ostringstream out;
+  out << '|' << std::setw(10) << -12345 << "|  right (default)\n"
+      << '|' << std::setw(10) << std::left << -12345 << "|  left\n"
+      << '|' << std::setw(10) << std::internal << -12345 << "|  internal\n"
+      << '|' << std::setfill('*') << std::setw(10) << std::right << -12345
+      << "|  setfill('*')\n"
+      << '|' << -12345 << "|  setw applies to one output only";
+  LOG(out.str());
+
+  LOG_SECTION("Saving and restoring the stream state");
+  std::ostringstream stream;
+  std::ios saved(nullptr);
+  saved.copyfmt(stream);  // remember the current settings
+  stream << std::hex << std::uppercase << 3054;
+  stream.copyfmt(saved);  // back to the defaults
+  stream << ' ' << 3054;
+  LOG_S("hex then restored: " << stream.str());
+}
+
+void stdFormat() {
+  LOG_SECTION("C++20 std::format");
+  LOG(std::format("|{:>10}|{:<10}|{:^10}|", "right", "left", "center"));
+  LOG(std::format("pi = {:.3f}, hex = {:#x}, padded = {:08.2f}", 3.14159, 255,
+                  3.14159));
+  LOG(std::format("{0} + {0} = {1}", 21, 42));  // positional arguments
+}
+
+}  // namespace
+
+LAB_EXAMPLE("OutputFormatting",
+            "iomanip flags and manipulators, sticky state, std::format") {
+  flags();
+  numberBases();
+  floatingPoint();
+  widthAndAlignment();
+  stdFormat();
+}
diff --git a/src/core/filehandle/README.md b/src/core/filehandle/README.md
index 07dcf86..3ff7f7d 100644
--- a/src/core/filehandle/README.md
+++ b/src/core/filehandle/README.md
@@ -1,3 +1,16 @@
+# Streams and files
+
+| Example | Topic |
+|---|---|
+| `IOStream` | `cout`/`cerr`/`clog`, redirecting `cin`, stream states, input validation |
+| `StringStream` | building and parsing strings with `<sstream>` |
+| `OutputFormatting` | `<iomanip>` flags and manipulators, sticky state, `std::format` |
+| `FileIO` | writing, appending and reading text files |
+| `BinaryFileHandling` | binary records, serializing strings, random access |
+| `Directory` | `std::filesystem`: paths, creating, listing, removing |
+| `TerminalColor` | ANSI escape codes for colors and text effects |
+
+---
 ## 1. I/O Streams
 - It is a part of the STL.
 - I/O is implemented with `streams`.
diff --git a/src/core/filehandle/StringStream.cpp b/src/core/filehandle/StringStream.cpp
index 1576e6c..ccad36e 100644
--- a/src/core/filehandle/StringStream.cpp
+++ b/src/core/filehandle/StringStream.cpp
@@ -1,48 +1,89 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// String streams (<sstream>)
+//
+//   std::ostringstream  build a string with <<
+//   std::istringstream  parse a string with >> or std::getline
+//   std::stringstream   both directions
+//
+// Pitfalls:
+//   - str("") replaces the CONTENT; clear() resets the error FLAGS.
+//     Reusing a stream usually needs both.
+//   - Since C++17 std::to_string / std::stoi or std::from_chars are simpler
+//     and faster for single number conversions.
+//
+// Reference: https://en.cppreference.com/w/cpp/io/basic_stringstream
+// -----------------------------------------------------------------------------
+
 #include <sstream>
 #include <string>
+#include <vector>
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void runStringStreamExample() {
-  std::cout << "\n--- String Stream Example ---\n";
-
-  std::stringstream os{};
-
-  // input:   std::istringstream iss;
-  os << "0xF";
-  std::cout << os.str();
-
-  // Note: After changing .str(), always call .clear() before reading.
-  os.str("0x1 0x2");
-  os.clear();
-  std::cout << os.str();
-
-  // output: std::ostringstream oss;
-  std::string bytes_str = os.str();
-  std::cout << bytes_str;
-
-  os.str("0x0 0xF 0xE 0x2");
-  os.clear();
-  os >> bytes_str;
-  std::cout << bytes_str;
-
-  // conversions
-  int byte_low = 0xFFF;
-  int byte_high = 0x001;
-  os.clear();
-  os << byte_low << ' ' << byte_high;
-  std::cout << os.str();
+
+void building() {
+  LOG_SECTION("Building strings with std::ostringstream");
+  std::ostringstream out;
+  out << "sensor " << 7 << " reads " << 21.5 << " C";
+  LOG_S("result: \"" << out.str() << "\"");
 }
-}  // namespace
 
-class StringStream : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "StringStream"; }
-  std::string description() const override { return ""; }
-  void execute() override { runStringStreamExample(); }
-};
+void parsing() {
+  LOG_SECTION("Parsing with std::istringstream");
+  std::istringstream in("0x1F 42 3.14 hello");
+  int hex_value = 0;
+  int number = 0;
+  double real = 0.0;
+  std::string word;
+  in >> std::hex >> hex_value >> std::dec >> number >> real >> word;
+  LOG_S("0x1F -> " << hex_value << ", 42 -> " << number << ", 3.14 -> " << real
+                   << ", word -> " << word);
+
+  std::istringstream csv("red,green,,blue");
+  std::vector<std::string> fields;
+  for (std::string field;
+       std::getline(csv, field, ',');) {  // ',' as the delimiter
+    fields.push_back(field);
+  }
+  LOG_S("\"red,green,,blue\" split on ',' -> "
+        << fields.size() << " fields (one of them empty)");
+}
+
+void reuse() {
+  LOG_SECTION("Reusing a stream: str() vs clear()");
+  std::stringstream stream("12");
+  int value = 0;
+  stream >> value;  // reads 12 and hits the end: eofbit is set
+  LOG_S("read " << value << ", eof() = " << std::boolalpha << stream.eof());
+
+  stream.str("34");  // new content, but the eof flag is still set...
+  stream >> value;
+  LOG_S("after str(\"34\") only: value still "
+        << value << ", fail() = " << std::boolalpha << stream.fail());
 
-REGISTER_EXAMPLE(StringStream);
\ No newline at end of file
+  stream.clear();  // ...so reset the flags as well
+  stream.str("56");
+  stream >> value;
+  LOG_S("after clear() + str(\"56\"): value = " << value);
+}
+
+void conversions() {
+  LOG_SECTION("Number <-> string");
+  std::ostringstream out;
+  out << 0xFFF << ' ' << 0x001;
+  LOG_S("stream: \"" << out.str() << "\", std::to_string(3.5) = \""
+                     << std::to_string(3.5)
+                     << "\", std::stoi(\"123\") = " << std::stoi("123"));
+}
+
+}  // namespace
+
+LAB_EXAMPLE("StringStream",
+            "build and parse strings with ostringstream/istringstream") {
+  building();
+  parsing();
+  reuse();
+  conversions();
+}
diff --git a/src/core/filehandle/TerminalColor.cpp b/src/core/filehandle/TerminalColor.cpp
index 4b0949a..6c78cb0 100644
--- a/src/core/filehandle/TerminalColor.cpp
+++ b/src/core/filehandle/TerminalColor.cpp
@@ -1,123 +1,93 @@
-#include <ostream>
-#include <sstream>
+// -----------------------------------------------------------------------------
+// Colors in the terminal (ANSI escape codes)
+//
+//   "\033[<code>m" changes the style of the text that follows,
+//   "\033[0m" resets everything.
+//
+//   30-37 foreground   40-47 background   90-97 bright foreground
+//   1 bold   2 dim   3 italic   4 underline   7 reverse
+//   Codes combine with ';', e.g. "\033[1;31m" is bold red.
+//
+// Only terminals understand these codes. When output goes to a file or a pipe
+// (check with isatty) or NO_COLOR is set, print plain text - lab::Logger does.
+//
+// Reference: https://en.wikipedia.org/wiki/ANSI_escape_code
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <iostream>
 #include <string>
-#include "Logger.h"
+#include <string_view>
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-namespace terminal_color_code {
+namespace ansi {
+inline constexpr std::string_view kReset = "\033[0m";
+}  // namespace ansi
 
-inline constexpr const char* kReset = "\033[0m";
-inline constexpr const char* kBlack = "\033[30m";
-inline constexpr const char* kRed = "\033[31m";
-inline constexpr const char* kGreen = "\033[32m";
-inline constexpr const char* kYellow = "\033[33m";
-inline constexpr const char* kBlue = "\033[34m";
-inline constexpr const char* kMagenta = "\033[35m";
-inline constexpr const char* kCyan = "\033[36m";
-inline constexpr const char* kWhite = "\033[37m";
+struct Style {
+  std::string_view name;
+  std::string_view code;
+};
 
-// Bold variants
-inline constexpr const char* kBoldBlack = "\033[1m\033[30m";
-inline constexpr const char* kBoldRed = "\033[1m\033[31m";
-inline constexpr const char* kBoldGreen = "\033[1m\033[32m";
-inline constexpr const char* kBoldYellow = "\033[1m\033[33m";
-inline constexpr const char* kBoldBlue = "\033[1m\033[34m";
-inline constexpr const char* kBoldMagenta = "\033[1m\033[35m";
-inline constexpr const char* kBoldCyan = "\033[1m\033[36m";
-inline constexpr const char* kBoldWhite = "\033[1m\033[37m";
-}  // namespace terminal_color_code
+constexpr std::array<Style, 8> kColors{{
+    {"black", "30"},
+    {"red", "31"},
+    {"green", "32"},
+    {"yellow", "33"},
+    {"blue", "34"},
+    {"magenta", "35"},
+    {"cyan", "36"},
+    {"white", "37"},
+}};
+
+constexpr std::array<Style, 5> kEffects{{
+    {"bold", "1"},
+    {"dim", "2"},
+    {"italic", "3"},
+    {"underline", "4"},
+    {"reverse", "7"},
+}};
+
+std::string styled(std::string_view text, std::string_view code) {
+  return "\033[" + std::string(code) + "m" + std::string(text) +
+         std::string(ansi::kReset);
+}
 
 void run() {
-  LOG("Terminal Color Example");
-
-  std::ostringstream oss;
-
-  oss.str("");
-  oss << terminal_color_code::kRed << "RED" << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBlack << "BLACK" << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kGreen << "GREEN" << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kYellow << "YELLOW"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBlue << "BLUE" << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kMagenta << "MAGENTA"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kCyan << "CYAN" << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kWhite << "WHITE" << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  // Bold variants
-  oss.str("");
-  oss << terminal_color_code::kBoldRed << "BOLD RED"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldGreen << "BOLD GREEN"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldBlue << "BOLD BLUE"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldCyan << "BOLD CYAN"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldMagenta << "BOLD MAGENTA"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldWhite << "BOLD WHITE"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldYellow << "BOLD YELLOW"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
-
-  oss.str("");
-  oss << terminal_color_code::kBoldBlack << "BOLD BLACK"
-      << terminal_color_code::kReset;
-  LOG(oss.str());
+  // Plain std::cout keeps the color table free of log prefixes.
+  LOG_SECTION("Foreground colors: normal, bold and bright");
+  for (const Style& color : kColors) {
+    const std::string bold = "1;" + std::string(color.code);
+    const std::string bright =
+        std::to_string(std::stoi(std::string(color.code)) + 60);
+    std::cout << "  " << styled(color.name, color.code) << "  "
+              << styled(color.name, bold) << "  " << styled(color.name, bright)
+              << '\n';
+  }
+
+  LOG_SECTION("Background colors");
+  for (const Style& color : kColors) {
+    const std::string background =
+        std::to_string(std::stoi(std::string(color.code)) + 10);
+    std::cout << "  "
+              << styled("  " + std::string(color.name) + "  ", background)
+              << '\n';
+  }
+
+  LOG_SECTION("Text effects (support varies by terminal)");
+  for (const Style& effect : kEffects) {
+    std::cout << "  " << styled(effect.name, effect.code) << '\n';
+  }
+  std::cout.flush();
 }
-}  // namespace
 
-class TerminalColor : public IExample {
- public:
-  std::string group() const override { return "core/filehandle"; }
-  std::string name() const override { return "TerminalColor"; }
-  std::string description() const override { return ""; }
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(TerminalColor);
\ No newline at end of file
+LAB_EXAMPLE("TerminalColor",
+            "ANSI escape codes: colors, backgrounds and text effects") {
+  run();
+}
diff --git a/src/core/function/FunctionPointer.cpp b/src/core/function/FunctionPointer.cpp
index c50b6b6..8d5e518 100644
--- a/src/core/function/FunctionPointer.cpp
+++ b/src/core/function/FunctionPointer.cpp
@@ -1,69 +1,132 @@
+// -----------------------------------------------------------------------------
+// Function pointers
+//
+//   int (*operation)(int, int) = &add;   pointer to "function taking two ints
+//                                        and returning int"
+//   using Operation = int (*)(int, int); an alias makes the syntax readable
+//
+//   - A function name converts to a pointer automatically (&add == add).
+//   - Call through the pointer with operation(1, 2) or (*operation)(1, 2).
+//   - Function pointers cannot hold lambdas WITH captures; use std::function
+//     or templates for that (see Functional.cpp).
+//   - Pointers to member functions need an object: (object.*member)().
+//
+// Reference: https://en.cppreference.com/w/cpp/language/pointer#Pointers_to_functions
+// -----------------------------------------------------------------------------
+
 #include <algorithm>
+#include <array>
+#include <cstdlib>
+#include <string>
 #include <vector>
-#include "Logger.h"
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-int increase(int a, int b) {
-  LOG("");
-  return static_cast<int>(a > b);
+std::string join(const std::vector<int>& values) {
+  std::string text;
+  for (const int value : values) {
+    text += std::to_string(value) + " ";
+  }
+  return text;
 }
 
-int decrease(int a, int b) {
-  LOG("");
-  return static_cast<int>(a < b);
+bool ascending(int a, int b) {
+  return a < b;
 }
 
-// // Function
-// // Declaring
-// return_type (*FuncPtr) (parameter type, ....);
-// typedef int (*SortFcn)(int a, int b);
-
-/// @brief Function Pointer
-using sort_function_ptr = int (*)(int, int);
-
-void run() {
-  std::vector<int> vect{-1, -6, 4, 2, 0, 6, 3, 9, -5};
-  auto f_print = [](const std::vector<int>& vec) {
-    std::ostringstream oss;
-    for (const auto& e : vec) {
-      oss << e << " ";
-    }
-    LOG(oss.str());
-  };
+bool descending(int a, int b) {
+  return a > b;
+}
+
+bool byAbsoluteValue(int a, int b) {
+  return std::abs(a) < std::abs(b);
+}
 
-  LOG("Before sorting : ");
-  f_print(vect);
+using Comparator = bool (*)(int, int);
 
-  LOG("Sorting in descending order");
-  // Use auto
-  auto sort_type_auto = increase;
-  std::sort(vect.begin(), vect.end(), sort_type_auto);
+void sortWith(std::vector<int> values, Comparator compare, const char* label) {
+  std::sort(values.begin(), values.end(), compare);
+  LOG_S(label << join(values));
+}
 
-  // Use pointer
-  sort_function_ptr sort_type_ptr = decrease;
-  f_print(vect);
+void comparators() {
+  LOG_SECTION("Passing functions to std::sort");
+  const std::vector<int> values{-1, -6, 4, 2, 0, 6, 3, 9, -5};
+  LOG_S("input             : " << join(values));
 
-  LOG("Sorting with absolute value as parameter");
-  std::sort(vect.begin(), vect.end(), sort_type_ptr);
+  sortWith(values, ascending, "ascending         : ");
+  sortWith(values, &descending, "descending        : ");  // & is optional
+  sortWith(values, byAbsoluteValue, "by absolute value : ");
 
-  std::ostringstream oss;
-  for (auto i : vect)
-    oss << i << " ";
-  LOG(oss.str());
+  Comparator chosen = descending;
+  LOG_S("chosen(1, 2) = " << std::boolalpha << chosen(1, 2)
+                          << ", (*chosen)(2, 1) = " << (*chosen)(2, 1));
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+int add(int a, int b) {
+  return a + b;
+}
+int subtract(int a, int b) {
+  return a - b;
+}
+int multiply(int a, int b) {
+  return a * b;
+}
 
-class FunctionPointer : public IExample {
- public:
-  std::string group() const override { return "core/function"; }
-  std::string name() const override { return "FunctionPointer"; }
-  std::string description() const override {
-    return "Function Pointer Example";
+void dispatchTable() {
+  LOG_SECTION("A dispatch table: array of function pointers");
+  struct Entry {
+    char symbol;
+    int (*function)(int, int);
+  };
+  constexpr std::array<Entry, 3> kOperations{
+      {{'+', add}, {'-', subtract}, {'*', multiply}}};
+
+  for (const Entry& entry : kOperations) {
+    LOG_S("8 " << entry.symbol << " 2 = " << entry.function(8, 2));
   }
-  void execute() override { run(); }
+
+  // A capture-less lambda converts to a function pointer too.
+  int (*modulo)(int, int) = [](int a, int b) {
+    return a % b;
+  };
+  LOG_S("8 % 3 = " << modulo(8, 3)
+                   << " (capture-less lambda as a function pointer)");
+}
+
+class Counter {
+ public:
+  void increment() { ++value_; }
+  void reset() { value_ = 0; }
+  int value() const { return value_; }
+
+ private:
+  int value_{0};
 };
 
-REGISTER_EXAMPLE(FunctionPointer);
+void memberFunctionPointers() {
+  LOG_SECTION("Pointers to member functions");
+  void (Counter::*action)() = &Counter::increment;  // & is required here
+  Counter counter;
+  (counter.*action)();
+  (counter.*action)();
+  LOG_S("after calling increment twice: " << counter.value());
+
+  action = &Counter::reset;
+  Counter* pointer = &counter;
+  (pointer->*action)();
+  LOG_S("after reset through a pointer: " << counter.value());
+}
+
+}  // namespace
+
+LAB_EXAMPLE("FunctionPointer",
+            "function pointers, comparators, dispatch tables, member function "
+            "pointers") {
+  comparators();
+  dispatchTable();
+  memberFunctionPointers();
+}
diff --git a/src/core/function/Functional.cpp b/src/core/function/Functional.cpp
index 1c59db8..be38ad4 100644
--- a/src/core/function/Functional.cpp
+++ b/src/core/function/Functional.cpp
@@ -1,52 +1,127 @@
+// -----------------------------------------------------------------------------
+// std::function, std::bind and std::invoke (<functional>)
+//
+//   std::function<int(int, int)> f;   holds ANY callable with that signature:
+//                                     free functions, lambdas (with captures),
+//                                     function objects, bound member functions
+//
+//   - Calling an empty std::function throws std::bad_function_call.
+//   - It has a small run-time cost (type erasure, possible allocation); inside
+//     hot code or generic code prefer templates / auto parameters.
+//   - std::bind is mostly replaced by lambdas, which are easier to read.
+//   - std::invoke calls anything callable, including member pointers.
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/functional/function
+// -----------------------------------------------------------------------------
+
 #include <functional>
-#include "Logger.h"
+#include <map>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-// Functions for simple math operations
+
 int add(int a, int b) {
-  LOG("");
   return a + b;
 }
-int sub(int a, int b) {
-  LOG("");
-  return a - b;
-}
-int mul(int a, int b) {
-  LOG("");
-  return a * b;
-}
-int divs(int a, int b) {
-  LOG("");
-  return a / b;
-}
 
-void func(int a, int b, const std::function<int(int, int)>& calc) {
-  if (!calc) {
-    LOG("No function provided");
+/// A function object (functor): a class with operator().
+struct Multiply {
+  int operator()(int a, int b) const { return a * b; }
+};
+
+class Calculator {
+ public:
+  int power(int base, int exponent) const {
+    int result = 1;
+    for (int i = 0; i < exponent; ++i) {
+      result *= base;
+    }
+    return result;
+  }
+};
+
+void apply(int a, int b, const std::function<int(int, int)>& operation,
+           const char* name) {
+  if (!operation) {  // std::function can be empty
+    LOG_S(name << ": no function provided");
     return;
   }
+  LOG_S(name << "(" << a << ", " << b << ") = " << operation(a, b));
+}
 
-  int result = calc(a, b);
-  LOG_S(result);
+void holdingCallables() {
+  LOG_SECTION("One type for many kinds of callables");
+  int offset = 100;
+  const Calculator calculator;
+
+  apply(8, 2, add, "free function");
+  apply(8, 2, Multiply{}, "function object");
+  apply(8, 2, [](int a, int b) { return a % b; }, "lambda");
+  apply(
+      8, 2, [offset](int a, int b) { return a - b + offset; },
+      "capturing lambda");
+  apply(
+      8, 2, [&calculator](int a, int b) { return calculator.power(a, b); },
+      "member function via lambda");
+  apply(8, 2, nullptr, "empty");
+
+  const std::function<int(int, int)> empty;
+  try {
+    empty(1, 2);
+  } catch (const std::bad_function_call& e) {
+    LOG_S("calling an empty std::function throws: " << e.what());
+  }
 }
 
-void run() {
-  func(8, 2, add);
-  func(8, 2, sub);
-  func(8, 2, mul);
-  func(8, 2, divs);
-  func(8, 2, [](int a, int b) { return a % b; });  // 0
+void bindAndInvoke() {
+  LOG_SECTION("std::bind vs lambda, std::invoke");
+  using std::placeholders::_1;
+
+  const std::function<int(int)> add_ten_bind = std::bind(add, _1, 10);
+  const std::function<int(int)> add_ten_lambda = [](int value) {
+    return add(value, 10);
+  };
+  LOG_S("std::bind(add, _1, 10)(5) = " << add_ten_bind(5) << ", lambda(5) = "
+                                       << add_ten_lambda(5));
+
+  const Calculator calculator;
+  LOG_S("std::invoke(&Calculator::power, calculator, 2, 10) = " << std::invoke(
+            &Calculator::power, calculator, 2, 10));
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void callbackRegistry() {
+  LOG_SECTION("Use case: a command registry");
+  std::map<std::string, std::function<void()>> commands;
+  int counter = 0;
+  commands["increment"] = [&counter] {
+    ++counter;
+  };
+  commands["reset"] = [&counter] {
+    counter = 0;
+  };
+  commands["show"] = [&counter] {
+    LOG_S("  counter = " << counter);
+  };
 
-class Functional : public IExample {
- public:
-  std::string group() const override { return "core/function"; }
-  std::string name() const override { return "Functional"; }
-  std::string description() const override { return "Functional Example"; }
-  void execute() override { run(); }
-};
+  for (const std::string name :
+       {"increment", "increment", "show", "reset", "show", "unknown"}) {
+    if (const auto it = commands.find(name); it != commands.end()) {
+      it->second();
+    } else {
+      LOG_S("  unknown command '" << name << "'");
+    }
+  }
+}
 
-REGISTER_EXAMPLE(Functional);
+}  // namespace
+
+LAB_EXAMPLE(
+    "Functional",
+    "std::function, function objects, std::bind, std::invoke, callbacks") {
+  holdingCallables();
+  bindAndInvoke();
+  callbackRegistry();
+}
diff --git a/src/core/function/Lambda.cpp b/src/core/function/Lambda.cpp
index 63aee7e..141f8dd 100644
--- a/src/core/function/Lambda.cpp
+++ b/src/core/function/Lambda.cpp
@@ -1,53 +1,146 @@
-#include <algorithm>  // for std::sort
-// std::sort
-// default (1)
-// template <class RandomAccessIterator>  void sort (RandomAccessIterator first, RandomAccessIterator last);
-// custom (2)
-// template <class RandomAccessIterator, class Compare>  void sort (RandomAccessIterator first, RandomAccessIterator last, Compare comp);
-
-#include <sstream>
+// -----------------------------------------------------------------------------
+// Lambda expressions
+//
+//   [captures](parameters) mutable -> return_type { body }
+//
+//   Captures:  [x]  copy of x         [&x]    reference to x
+//              [=]  copy everything   [&]     reference everything used
+//              [y = expr] init capture (C++14), e.g. [p = std::move(ptr)]
+//              [this] the current object
+//
+//   - The compiler turns a lambda into an unnamed class with operator().
+//   - Captured copies are const inside the body unless the lambda is `mutable`.
+//   - `auto` parameters make a generic lambda (a template operator()).
+//   - Pitfall: capturing by reference and using the lambda after the captured
+//     variables are gone gives a dangling reference.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/lambda
+// -----------------------------------------------------------------------------
+
+#include <algorithm>
+#include <cstdlib>
+#include <functional>
+#include <memory>
+#include <string>
+#include <utility>
 #include <vector>
-#include "Logger.h"
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  std::vector<int> vect{-1, -6, 4, 2, 0, 6, 3, 9, -5};
-  auto f_print = [](const std::vector<int>& vec) {
-    std::ostringstream oss;
-    for (const auto& e : vec) {
-      oss << e << " ";
-    }
-    LOG(oss.str());
-  };
 
-  LOG("Before sorting : ");
-  f_print(vect);
+std::string join(const std::vector<int>& values) {
+  std::string text;
+  for (const int value : values) {
+    text += std::to_string(value) + " ";
+  }
+  return text;
+}
 
-  LOG("Sorting in descending order");
-  std::sort(vect.begin(), vect.end(), [](int a, int b) { return a > b; });
+void withAlgorithms() {
+  LOG_SECTION("Lambdas with standard algorithms");
+  std::vector<int> values{-1, -6, 4, 2, 0, 6, 3, 9, -5};
+  LOG_S("input             : " << join(values));
 
-  f_print(vect);
+  std::sort(values.begin(), values.end(), [](int a, int b) { return a > b; });
+  LOG_S("descending        : " << join(values));
 
-  LOG("Sorting with absolute value as parameter");
-  std::sort(vect.begin(), vect.end(), [](int a, int b) { return a < b; });
+  std::sort(values.begin(), values.end(),
+            [](int a, int b) { return std::abs(a) < std::abs(b); });
+  LOG_S("by absolute value : " << join(values));
 
-  std::ostringstream oss;
-  for (auto i : vect)
-    oss << i << " ";
-  LOG(oss.str());
+  const auto negatives =
+      std::count_if(values.begin(), values.end(), [](int v) { return v < 0; });
+  LOG_S("negative values   : " << negatives);
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void captures() {
+  LOG_SECTION("Capture by value, by reference, mutable, init capture");
+  int counter = 0;
 
-class Lambda : public IExample {
+  auto by_value = [counter]() {
+    return counter + 1;
+  };  // copies counter NOW
+  auto by_reference = [&counter]() {
+    ++counter;
+  };  // refers to counter
+  counter = 10;
+  by_reference();
+  LOG_S("by_value() = " << by_value()
+                        << " (saw counter = 0), counter = " << counter);
+
+  auto generator = [next = 0]() mutable {
+    return next++;
+  };  // init capture + mutable
+  const int first = generator();
+  const int second = generator();
+  const int third = generator();
+  LOG_S("mutable generator: " << first << ' ' << second << ' ' << third);
+
+  auto owned = std::make_unique<std::string>("moved into the lambda");
+  auto uses_owned = [text = std::move(owned)]() {
+    return *text;
+  };  // move-only capture
+  LOG_S("init capture with std::move: " << uses_owned());
+}
+
+class Button {
  public:
-  std::string group() const override { return "core/function"; }
-  std::string name() const override { return "Lambda"; }
-  std::string description() const override {
-    return "Lambda Expression Example";
+  explicit Button(std::string label) : label_{std::move(label)} {}
+
+  std::function<void()> onClick() const {
+    return [this] {
+      LOG_S("clicked '" << label_ << "' (captured this)");
+    };
   }
-  void execute() override { run(); }
+
+ private:
+  std::string label_;
 };
 
-REGISTER_EXAMPLE(Lambda);
+void thisCapture() {
+  LOG_SECTION("Capturing this");
+  Button button{"OK"};
+  const std::function<void()> handler = button.onClick();
+  handler();  // fine: button is still alive
+  // Storing `handler` beyond the lifetime of `button` would dangle.
+}
+
+std::function<int(int)> makeMultiplier(int factor) {
+  return [factor](int value) {
+    return value * factor;
+  };  // copy: safe to return
+  // [&factor] would refer to a parameter that dies when this function returns!
+}
+
+void genericAndClosures() {
+  LOG_SECTION("Generic lambdas, closures, immediately invoked lambdas");
+  auto print_twice = [](const auto& value) {
+    LOG_S("  " << value << ' ' << value);
+  };
+  print_twice(42);
+  print_twice(std::string("hi"));
+
+  const auto triple = makeMultiplier(3);
+  LOG_S("makeMultiplier(3)(7) = " << triple(7));
+
+  // Immediately invoked lambda: initialize a const variable with complex logic.
+  const std::string level = [](int errors) {
+    if (errors == 0) {
+      return "ok";
+    }
+    return errors < 5 ? "warning" : "error";
+  }(3);
+  LOG_S("const level computed by an immediately invoked lambda: " << level);
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Lambda",
+            "lambda syntax, captures, mutable, generic lambdas and closures") {
+  withAlgorithms();
+  captures();
+  thisCapture();
+  genericAndClosures();
+}
diff --git a/src/core/function/README.md b/src/core/function/README.md
new file mode 100644
index 0000000..f0153ff
--- /dev/null
+++ b/src/core/function/README.md
@@ -0,0 +1,52 @@
+# Functions and callables
+
+| Example           | Topic                                                          |
+|-------------------|----------------------------------------------------------------|
+| `FunctionPointer` | function pointer syntax, comparators, dispatch tables, member function pointers |
+| `Lambda`          | captures, `mutable`, init captures, generic lambdas, closures  |
+| `Functional`      | `std::function`, function objects, `std::bind`, `std::invoke`   |
+
+Operator overloading is in the [operator_overloading](operator_overloading) folder.
+
+## 1. Kinds of callables
+
+| Callable                   | Can hold state | Type                         |
+|----------------------------|----------------|------------------------------|
+| free function              | no             | `int (*)(int)`               |
+| capture-less lambda        | no             | unique type, converts to a function pointer |
+| lambda with captures       | yes            | unique closure type          |
+| function object (functor)  | yes            | a class with `operator()`    |
+| `std::function<int(int)>`  | yes            | type-erased wrapper for all of the above |
+
+Use templates or `auto` parameters to accept callables with zero overhead. Use `std::function`
+when you need to store callables of different types in one place, such as callbacks or command
+maps.
+
+## 2. Lambda captures
+
+```cpp
+[x]        // copy of x (const inside the body unless the lambda is mutable)
+[&x]       // reference to x - must not outlive x!
+[=], [&]   // capture everything used, by copy / by reference
+[y = f()]  // init capture (C++14), e.g. [p = std::move(ptr)]
+[this]     // the current object (by pointer)
+```
+
+## 3. Operator overloading
+
+| Operator            | Canonical form                                             | Example |
+|---------------------|------------------------------------------------------------|---------|
+| `+ - * /`           | non-member, implemented with the member `+= -= *= /=`       | `ArithmeticOperator` |
+| `= `                | member, returns `T&`, handles self-assignment              | `AssignmentOperator` |
+| `<=> ==`            | `auto operator<=>(const T&) const = default;` (C++20)      | `ComparisonOperator` |
+| `<< >>` on streams  | non-member (the stream is the left operand)                | `StreamOperator` |
+| `[]`                | member, const and non-const overloads                      | `SubscriptOperator` |
+| `()`                | member, turns an object into a function object             | `FunctionCallOperator` |
+| `++ --`             | prefix returns `T&`, postfix `T operator++(int)` returns the old value | `InDecOperator` |
+| `-> *`              | member, used by smart pointers and iterators               | `ClassMemberAccessOperator` |
+| `operator T()`      | conversion operator, prefer `explicit`                     | `TypeCast` |
+| `new delete`        | class-specific allocation                                  | `AllocationOperator` |
+| `- + ! ~`           | member, returns a new value                                | `UnaryOperator` |
+
+Rule of thumb: an overloaded operator should do what the built-in operator would do. Anything
+surprising belongs in a named function.
diff --git a/src/core/function/operator_overloading/AllocationOperator.cpp b/src/core/function/operator_overloading/AllocationOperator.cpp
index d2c44e3..353d8a8 100644
--- a/src/core/function/operator_overloading/AllocationOperator.cpp
+++ b/src/core/function/operator_overloading/AllocationOperator.cpp
@@ -1,99 +1,106 @@
-// cppcheck-suppress-file [functionConst]
+// -----------------------------------------------------------------------------
+// Overloading operator new and operator delete
+//
+// `new T` does two things: calls `operator new(sizeof(T))` to get raw memory,
+// then runs T's constructor in it. `delete p` runs the destructor, then calls
+// `operator delete(p)`. Only the memory part can be customized.
+//
+//   - Class-specific overloads (static members) affect only that class:
+//     logging, memory pools, alignment, debugging leaks.
+//   - Overload new/delete AND new[]/delete[] together.
+//   - operator new must throw std::bad_alloc on failure (or be nothrow).
+//   - Placement new `new (buffer) T` constructs in memory you already own.
+//
+// Reference: https://en.cppreference.com/w/cpp/memory/new/operator_new
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
+#include <memory>
+#include <new>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-// Overloading operator new, delete
-// Debug
-
-#include <iostream>
-#include "ExampleRegistry.h"
 namespace {
 
-class IntCollection {
- private:
-  int m_data_[3]{10, 20, 30};
-
+class Tracked {
  public:
-  class Iterator {
-   private:
-    int* m_ptr_;
-
-   public:
-    explicit Iterator(int* ptr) : m_ptr_(ptr) {}
-
-    int& operator*() { return *m_ptr_; }
-
-    int* operator->() { return m_ptr_; }
-
-    Iterator& operator++() {
-      ++m_ptr_;
-      return *this;
-    }
-
-    bool operator!=(const Iterator& other) const {
-      return m_ptr_ != other.m_ptr_;
-    }
-  };
-
-  Iterator begin() { return Iterator(m_data_); }
-  Iterator end() { return Iterator(m_data_ + 3); }
-
-  // int* a = new int;
-  void* operator new(size_t size) {
-    std::cout << "void* operator new(size_t size)\n";
-    // void* p = ::operator new(size);
-    void* p = malloc(size);
-    if (!p)
-      throw std::bad_alloc();
-    return p;
+  Tracked() { LOG("    Tracked()   constructor"); }
+  ~Tracked() { LOG("    ~Tracked()  destructor"); }
+  Tracked(const Tracked&) = delete;
+  Tracked& operator=(const Tracked&) = delete;
+
+  static void* operator new(std::size_t size) {
+    LOG_S("    operator new(" << size << ")");
+    return ::operator new(size);  // delegate to the global allocator
   }
 
-  // delete a
-  void operator delete(void* p) {
-    std::cout << "void operator delete(void* p)\n";
-    free(p);
+  static void operator delete(void* memory) noexcept {
+    LOG("    operator delete");
+    ::operator delete(memory);
   }
 
-  // int* as = new int[100]
-  void* operator new[](size_t size) {
-    std::cout << "void* operator new[](size_t size)\n";
-    void* p = malloc(size);
-    if (!p)
-      throw std::bad_alloc();
-    return p;
+  static void* operator new[](std::size_t size) {
+    LOG_S("    operator new[](" << size
+                                << ")  (may include bookkeeping bytes)");
+    return ::operator new[](size);
   }
 
-  // delete []as;
-  void operator delete[](void* p) {
-    std::cout << "void operator delete[](void* p)\n";
-    free(p);
+  static void operator delete[](void* memory) noexcept {
+    LOG("    operator delete[]");
+    ::operator delete[](memory);
   }
+
+ private:
+  int data_[3]{10, 20, 30};
 };
 
-void run() {
-  auto* col = new IntCollection;
+void singleObject() {
+  LOG_SECTION("new / delete: memory first, then constructor");
+  LOG("  new Tracked:");
+  auto* object = new Tracked;
+  LOG("  delete object:");
+  delete object;
 
-  for (auto it = col->begin(); it != col->end(); ++it) {
-    std::cout << *it << '\n';
-  }
+  LOG("  std::make_unique uses the class operator new as well:");
+  auto owned = std::make_unique<Tracked>();
+  owned.reset();
+}
 
-  delete col;
+void arrays() {
+  LOG_SECTION("new[] / delete[]");
+  LOG_S("  sizeof(Tracked) = " << sizeof(Tracked) << ", allocating 3:");
+  auto* objects = new Tracked[3];
+  LOG("  delete[] objects:");
+  delete[] objects;  // mixing new[] with delete (or new with delete[]) is UB
+}
 
-  auto* cols = new IntCollection[10];
-  for (int i = 0; i < 10; ++i) {
-    for (auto it = cols[i].begin(); it != cols[i].end(); ++it) {
-      std::cout << *it << '\n';
-    }
-  }
-  delete[] cols;
+void placementNew() {
+  LOG_SECTION("Placement new: construct in existing memory");
+  alignas(Tracked) std::byte buffer[sizeof(Tracked)];
+  LOG("  new (buffer) Tracked  -> no allocation, only the constructor runs:");
+  Tracked* object =
+      ::new (buffer) Tracked;  // ::new bypasses the class overload
+  LOG("  object->~Tracked()     -> call the destructor manually, never "
+      "delete:");
+  object->~Tracked();
 }
-}  // namespace
 
-class AllocationOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "AllocationOperator"; }
-  std::string description() const override { return ""; }
+void nothrowNew() {
+  LOG_SECTION("std::nothrow");
+  // The nothrow form returns nullptr instead of throwing std::bad_alloc.
+  const std::unique_ptr<int[]> numbers(new (std::nothrow) int[16]);
+  LOG_S("  new (std::nothrow) int[16] -> "
+        << (numbers ? "allocated" : "nullptr"));
+}
 
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(AllocationOperator);
\ No newline at end of file
+LAB_EXAMPLE(
+    "AllocationOperator",
+    "class-specific operator new/delete, new[]/delete[], placement new") {
+  singleObject();
+  arrays();
+  placementNew();
+  nothrowNew();
+}
diff --git a/src/core/function/operator_overloading/ArithmeticOperator.cpp b/src/core/function/operator_overloading/ArithmeticOperator.cpp
index dd5080d..ac241b4 100644
--- a/src/core/function/operator_overloading/ArithmeticOperator.cpp
+++ b/src/core/function/operator_overloading/ArithmeticOperator.cpp
@@ -1,82 +1,107 @@
-// cppcheck-suppress-file[]
-// + - * /
-#include <iostream>
-#include "ExampleRegistry.h"
+// -----------------------------------------------------------------------------
+// Overloading arithmetic operators: + - * / and += -= *= /=
+//
+// Canonical pattern:
+//   - Implement the compound operator (+=) as a MEMBER returning *this.
+//   - Implement the binary operator (+) as a NON-MEMBER in terms of +=.
+//     A non-member works when the left operand is not our class: 5 + cents.
+//   - Take operands by const reference (or by value when cheap) and return a
+//     new object by value.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operators#Binary_arithmetic_operators
+// -----------------------------------------------------------------------------
+
+#include <stdexcept>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Cents {
- private:
-  int m_cents_{};
 
+class Cents {
  public:
-  explicit Cents(int cents) : m_cents_{cents} {}
-  int getCents() const { return m_cents_; }
-
-  // Problem: A member operator only works when the left-hand operand is an object of the class (e.g., Cents).
-  // Cents sum = 5 + s1;
-  // int.operator+(5)
-  // => error
-  //   Cents operator+(const Cents& other) {
-  //     return Cents{this->getCents() + other.getCents()};
-  //   }
-
-  // For operands of different types
-  friend Cents operator+(int v1, const Cents& c2) {
-    return Cents{v1 + c2.getCents()};
+  explicit Cents(int cents) : cents_{cents} {}
+  int value() const { return cents_; }
+
+  // Compound assignment operators modify *this and return it by reference,
+  // so they can be chained like built-in types.
+  Cents& operator+=(const Cents& other) {
+    cents_ += other.cents_;
+    return *this;
   }
-
-  friend Cents operator+(const Cents& c1, int v2) {
-    return Cents{v2 + c1.getCents()};
+  Cents& operator-=(const Cents& other) {
+    cents_ -= other.cents_;
+    return *this;
   }
-
-  // ArithmeticOperator operators
-  friend Cents operator+(const Cents& c1, const Cents& c2) {
-    return Cents{c1.getCents() + c2.getCents()};
+  Cents& operator*=(int factor) {
+    cents_ *= factor;
+    return *this;
   }
-
-  friend Cents operator-(const Cents& c1, const Cents& c2) {
-    return Cents{c1.getCents() - c2.getCents()};
+  Cents& operator/=(int divisor) {
+    if (divisor == 0) {
+      throw std::invalid_argument("division of Cents by zero");
+    }
+    cents_ /= divisor;
+    return *this;
   }
 
-  friend Cents operator*(const Cents& c1, const Cents& c2) {
-    return Cents{c1.getCents() * c2.getCents()};
-  }
-
-  friend Cents operator/(const Cents& c1, const Cents& c2) {
-    return Cents{c1.getCents() / c2.getCents()};
-  }
+ private:
+  int cents_;
 };
 
-void run() {
-  Cents c1{25};
-  Cents c2{75};
-
-  // Sum
-  Cents sum = c1 + c2;
-  Cents sum2 = operator+(125, c2);
-  std::cout << "Sum: " << sum.getCents() << " " << sum2.getCents() << std::endl;
-
-  // Sub
-  Cents sub = c1 - c2;
-  std::cout << "Sub: " << sub.getCents() << std::endl;
-
-  // Div
-  Cents div = c1 / c2;
-  std::cout << "Div: " << div.getCents() << std::endl;
+// Non-members built on the compound operators. `lhs` is taken by value: it is
+// the copy we modify and return.
+Cents operator+(Cents lhs, const Cents& rhs) {
+  return lhs += rhs;
+}
+Cents operator-(Cents lhs, const Cents& rhs) {
+  return lhs -= rhs;
+}
+Cents operator*(Cents lhs, int factor) {
+  return lhs *= factor;
+}
+Cents operator*(int factor, Cents rhs) {  // allows 3 * cents
+  return rhs *= factor;
+}
+Cents operator/(Cents lhs, int divisor) {
+  return lhs /= divisor;
+}
 
-  // Mul
-  Cents mul = c1 * c2;
-  std::cout << "Mul: " << mul.getCents() << std::endl;
+// Mixed operands: with a member operator+ only `cents + 5` could work,
+// never `5 + cents`, because the left operand of a member is always *this.
+Cents operator+(const Cents& lhs, int rhs) {
+  return Cents{lhs.value() + rhs};
+}
+Cents operator+(int lhs, const Cents& rhs) {
+  return Cents{lhs + rhs.value()};
 }
-}  // namespace
 
-class ArithmeticOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "ArithmeticOperator"; }
-  std::string description() const override { return ""; }
+void run() {
+  LOG_SECTION("Binary operators");
+  const Cents a{25};
+  const Cents b{75};
+  LOG_S("a + b    = " << (a + b).value());
+  LOG_S("a - b    = " << (a - b).value());
+  LOG_S("a * 3    = " << (a * 3).value() << ", 3 * a = " << (3 * a).value());
+  LOG_S("b / 2    = " << (b / 2).value());
+  LOG_S("a + 5    = " << (a + 5).value() << ", 5 + a = " << (5 + a).value());
+
+  LOG_SECTION("Compound assignment and chaining");
+  Cents total{0};
+  total += a;
+  (total += b) += Cents{100};  // returns Cents&, so it can be chained
+  LOG_S("total    = " << total.value());
+
+  try {
+    total /= 0;
+  } catch (const std::invalid_argument& e) {
+    LOG_S("total /= 0 throws: " << e.what());
+  }
+}
 
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(ArithmeticOperator);
\ No newline at end of file
+LAB_EXAMPLE("ArithmeticOperator",
+            "overload + - * / via += -= *= /=, mixed operand types") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/AssignmentOperator.cpp b/src/core/function/operator_overloading/AssignmentOperator.cpp
index 65f85f5..d1bd8e4 100644
--- a/src/core/function/operator_overloading/AssignmentOperator.cpp
+++ b/src/core/function/operator_overloading/AssignmentOperator.cpp
@@ -1,52 +1,94 @@
-// cppcheck-suppress-file [unreadVariable]
+// -----------------------------------------------------------------------------
+// Overloading the assignment operators
+//
+//   T& operator=(const T& other);      copy assignment
+//   T& operator=(T&& other) noexcept;  move assignment
+//
+//   - Assignment changes an EXISTING object; `T b = a;` is not assignment but
+//     copy construction.
+//   - Return *this by reference so `a = b = c` works like for built-in types.
+//   - Handle self-assignment (a = a). The copy-and-swap idiom does it for free.
+//   - Usually the compiler-generated versions are right (Rule of Zero).
+//
+// Reference: https://en.cppreference.com/w/cpp/language/copy_assignment
+// -----------------------------------------------------------------------------
 
-// Overloading operator=
+#include <string>
+#include <utility>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Cents {
+
+class Document {
  public:
-  explicit Cents(int cents = 0) : cent_{cents} {}
+  explicit Document(std::string title = "untitled")
+      : title_{std::move(title)} {}
+
+  Document(const Document& other) : title_{other.title_} {
+    LOG_S("  copy constructor      <- " << title_);
+  }
+
+  Document(Document&& other) noexcept : title_{std::move(other.title_)} {
+    LOG_S("  move constructor      <- " << title_);
+  }
 
-  /// @brief Copy constructor
-  Cents(const Cents& other) {
-    LOG("");
-    cent_ = other.cent_;
+  Document& operator=(const Document& other) {
+    LOG_S("  copy assignment       <- " << other.title_);
+    if (this != &other) {  // self-assignment guard
+      title_ = other.title_;
+    }
+    return *this;
   }
 
-  /// @brief Copy assignment
-  Cents& operator=(const Cents& cents) {
-    // do the copy
-    LOG("");
-    cent_ = cents.cent_;
+  Document& operator=(Document&& other) noexcept {
+    LOG_S("  move assignment       <- " << other.title_);
+    if (this != &other) {
+      title_ = std::move(other.title_);
+    }
     return *this;
   }
 
+  ~Document() = default;
+
+  const std::string& title() const { return title_; }
+
  private:
-  int cent_;
+  std::string title_;
 };
 
 void run() {
-  Cents c1(100);  
-  Cents c2;
-  
-  LOG("c2 = c1;");
-  c2 = c1;        // c2.operator=(c1)
-
-  LOG("Cents c3 = c1;");
-  Cents c3 = c1;  // c3(c1)
-}
-}  // namespace
+  LOG_SECTION("Construction vs assignment");
+  const Document report{"report"};
 
-class AssignmentOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "Assignment Operator"; }
-  std::string description() const override { return ""; }
+  LOG("Document copy = report;   (construction, not assignment)");
+  const Document copy = report;
 
-  void execute() override { run(); }
-};
+  LOG("target = report;          (assignment to an existing object)");
+  Document target;
+  target = report;
+
+  LOG("target = Document{\"draft\"};  (a temporary: move assignment)");
+  target = Document{"draft"};
 
-REGISTER_EXAMPLE(AssignmentOperator);
\ No newline at end of file
+  LOG_SECTION("Chaining and self-assignment");
+  Document a;
+  Document b;
+  LOG("a = b = report;");
+  a = b = report;  // b = report runs first and returns b
+  LOG_S("a.title() = " << a.title() << ", copy.title() = " << copy.title());
+
+  LOG("a = a;   (the operator runs, but the self-assignment guard skips the "
+      "copy)");
+  const Document& same = a;
+  a = same;
+  LOG_S("a.title() is still " << a.title());
+}
+
+}  // namespace
+
+LAB_EXAMPLE("AssignmentOperator",
+            "copy/move assignment, chaining, self-assignment") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/ClassMemberAccessOperator.cpp b/src/core/function/operator_overloading/ClassMemberAccessOperator.cpp
index 6147732..0a5cc14 100644
--- a/src/core/function/operator_overloading/ClassMemberAccessOperator.cpp
+++ b/src/core/function/operator_overloading/ClassMemberAccessOperator.cpp
@@ -1,64 +1,97 @@
-// cppcheck-suppress-file []
+// -----------------------------------------------------------------------------
+// Overloading operator-> and operator*
+//
+//   T& operator*()   dereference: returns the pointed-to object
+//   T* operator->()  member access: returns a pointer (or another object with
+//                    operator->, which is then applied again - "drill-down")
+//
+// These are how smart pointers and iterators look like pointers.
+// Overloads usually come in const and non-const pairs.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operator_member_access
+// -----------------------------------------------------------------------------
 
-// Overloading operator-> *.
-// Collection item
+#include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-#include <iostream>
-#include "ExampleRegistry.h"
 namespace {
 
-class IntCollection {
- private:
-  int m_data_[3]{10, 20, 30};
+struct Person {
+  std::string name;
+  int age;
+  void greet() const { LOG_S("  Hi, I am " << name << " (" << age << ")"); }
+};
 
+/// A tiny owning pointer, similar in spirit to std::unique_ptr.
+template <typename T>
+class Owner {
  public:
-  class Iterator {
-   private:
-    int* m_ptr_;
+  explicit Owner(T* pointer) : pointer_{pointer} {}
+  ~Owner() { delete pointer_; }
+  Owner(const Owner&) = delete;
+  Owner& operator=(const Owner&) = delete;
+
+  T& operator*() {
+    LOG("  Owner::operator*");
+    return *pointer_;
+  }
+  const T& operator*() const { return *pointer_; }
 
+  T* operator->() {
+    LOG("  Owner::operator->");
+    return pointer_;  // the compiler then applies the built-in -> to this pointer
+  }
+  const T* operator->() const { return pointer_; }
+
+ private:
+  T* pointer_;
+};
+
+/// operator-> may return an object that itself has operator->; the compiler
+/// keeps applying -> until it gets a raw pointer. Here that is used to lock
+/// around every member call: operator-> returns a temporary "guard".
+class Monitor {
+ public:
+  class Guard {
    public:
-    explicit Iterator(int* ptr) : m_ptr_(ptr) {}
-
-    int& operator*() {
-      std::cout << "int& operator*()\n";
-      return *m_ptr_;
-    }
-
-    int* operator->() {
-      std::cout << "int* operator->()\n";
-      return m_ptr_;
-    }
-
-    Iterator& operator++() {
-      ++m_ptr_;
-      return *this;
-    }
-
-    bool operator!=(const Iterator& other) const {
-      return m_ptr_ != other.m_ptr_;
-    }
+    explicit Guard(Person& person) : person_{person} { LOG("  [lock]"); }
+    ~Guard() { LOG("  [unlock]"); }
+    Guard(const Guard&) = delete;
+    Guard& operator=(const Guard&) = delete;
+    Person* operator->() { return &person_; }
+
+   private:
+    Person& person_;
   };
 
-  Iterator begin() { return Iterator(m_data_); }
-  Iterator end() { return Iterator(m_data_ + 3); }
+  explicit Monitor(Person person) : person_{std::move(person)} {}
+  Guard operator->() {
+    return Guard{person_};
+  }  // chained: Guard::operator-> follows
+
+ private:
+  Person person_;
 };
 
 void run() {
-  IntCollection col;
+  LOG_SECTION("A smart-pointer-like class");
+  Owner<Person> owner{new Person{"Alice", 30}};
+  owner->greet();     // owner.operator->()->greet()
+  (*owner).age += 1;  // owner.operator*().age
+  LOG_S("  age after (*owner).age += 1: " << owner->age);
 
-  for (auto it = col.begin(); it != col.end(); ++it) {
-    std::cout << *it << '\n';
-  }
+  LOG_SECTION("Chained operator->: a monitor that locks per call");
+  Monitor monitor{Person{"Bob", 40}};
+  monitor
+      ->greet();  // Monitor::operator-> -> Guard -> Guard::operator-> -> Person*
 }
-}  // namespace
 
-class ClassMemberAccessOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "ClassMemberAccessOperator"; }
-  std::string description() const override { return ""; }
-
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(ClassMemberAccessOperator);
\ No newline at end of file
+LAB_EXAMPLE("ClassMemberAccessOperator",
+            "operator-> and operator* for smart pointers and proxies") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/ComparisonOperator.cpp b/src/core/function/operator_overloading/ComparisonOperator.cpp
index ac77598..7e480bf 100644
--- a/src/core/function/operator_overloading/ComparisonOperator.cpp
+++ b/src/core/function/operator_overloading/ComparisonOperator.cpp
@@ -1,47 +1,114 @@
-// cppcheck-suppress-file[]
+// -----------------------------------------------------------------------------
+// Comparison operators and the C++20 spaceship operator <=>
+//
+//   auto operator<=>(const T&) const = default;   member-wise three-way compare
+//   bool operator==(const T&) const = default;    member-wise equality
+//
+//   - From <=> the compiler rewrites  <  <=  >  >=  ; from == it rewrites  !=.
+//     Before C++20 all six operators had to be written by hand.
+//   - <=> returns an ordering category:
+//       std::strong_ordering  equal values are indistinguishable (int)
+//       std::weak_ordering    equivalent values may differ (case-insensitive text)
+//       std::partial_ordering some values are unordered (NaN for double)
+//   - A defaulted <=> also implies a defaulted ==.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/default_comparisons
+// -----------------------------------------------------------------------------
 
-#include <iostream>
-#include "ExampleRegistry.h"
+#include <algorithm>
+#include <cctype>
+#include <compare>
+#include <string>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
+
 class Cents {
+ public:
+  explicit Cents(int cents) : cents_{cents} {}
+  int value() const { return cents_; }
+
+  auto operator<=>(const Cents&) const =
+      default;  // also gives ==, !=, <, <=, >, >=
+
  private:
-  int m_cents_{};
+  int cents_;
+};
 
- public:
-  explicit Cents(int cents) : m_cents_{cents} {}
-  int getCents() const { return m_cents_; }
+struct Version {
+  int major;
+  int minor;
+  int patch;
+  // Compares major first, then minor, then patch - in declaration order.
+  auto operator<=>(const Version&) const = default;
+};
 
-  auto operator<=> (const Cents&) const = default;  // std 20
-  // friend bool operator== (const Cents& c1, const Cents& c2) { return c1.m_cents == c2.m_cents; }
-  // friend bool operator!= (const Cents& c1, const Cents& c2) { return !(operator==(c1, c2)); }
+/// Case-insensitive name: "Alice" and "alice" are equivalent but not identical.
+class Name {
+ public:
+  explicit Name(std::string text) : text_{std::move(text)} {}
+  const std::string& text() const { return text_; }
 
-  // friend bool operator< (const Cents& c1, const Cents& c2) { return c1.m_cents < c2.m_cents; }
-  // friend bool operator> (const Cents& c1, const Cents& c2) { return operator<(c2, c1); }
+  std::weak_ordering operator<=>(const Name& other) const {
+    const auto lower = [](unsigned char c) {
+      return std::tolower(c);
+    };
+    return std::lexicographical_compare_three_way(
+        text_.begin(), text_.end(), other.text_.begin(), other.text_.end(),
+        [&lower](unsigned char a, unsigned char b) {
+          return lower(a) <=> lower(b);
+        });
+  }
+  bool operator==(const Name& other) const { return (*this <=> other) == 0; }
 
-  // friend bool operator<= (const Cents& c1, const Cents& c2) { return !(operator>(c1, c2)); }
-  // friend bool operator>= (const Cents& c1, const Cents& c2) { return !(operator<(c1, c2)); }
+ private:
+  std::string text_;
 };
 
-void run() {
-  Cents pt1{25};
-  Cents pt2{30};
-  std::cout << std::boolalpha << (pt1 == pt2) << ' '  // false
-            << (pt1 != pt2) << ' '                    // true
-            << (pt1 < pt2) << ' '                     // true
-            << (pt1 <= pt2) << ' '                    // true
-            << (pt1 > pt2) << ' '                     // false
-            << (pt1 >= pt2) << ' ';                   // false
+const char* describe(std::strong_ordering order) {
+  if (order < 0) {
+    return "less";
+  }
+  return order > 0 ? "greater" : "equal";
 }
-}  // namespace
 
-class ComparisonOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "ComparisonOperator"; }
-  std::string description() const override { return ""; }
+void run() {
+  LOG_SECTION("Defaulted <=> on a single member");
+  const Cents a{25};
+  const Cents b{30};
+  LOG_S(std::boolalpha << "a == b " << (a == b) << ", a != b " << (a != b)
+                       << ", a < b " << (a < b) << ", a <= b " << (a <= b)
+                       << ", a > b " << (a > b) << ", a >= b " << (a >= b));
+  LOG_S("a <=> b is " << describe(a <=> b));
 
-  void execute() override { run(); }
-};
+  LOG_SECTION("Member-wise ordering");
+  std::vector<Version> versions{{1, 10, 0}, {1, 2, 3}, {0, 9, 9}, {1, 2, 10}};
+  std::sort(versions.begin(),
+            versions.end());  // uses the synthesized operator<
+  std::string sorted;
+  for (const Version& v : versions) {
+    sorted += std::to_string(v.major) + "." + std::to_string(v.minor) + "." +
+              std::to_string(v.patch) + "  ";
+  }
+  LOG_S("sorted versions: " << sorted);
 
-REGISTER_EXAMPLE(ComparisonOperator);
\ No newline at end of file
+  LOG_SECTION("Custom weak ordering");
+  const Name alice{"Alice"};
+  const Name lower_alice{"alice"};
+  const Name bob{"bob"};
+  LOG_S(std::boolalpha << "\"Alice\" == \"alice\": " << (alice == lower_alice)
+                       << ", \"alice\" < \"bob\": " << (lower_alice < bob)
+                       << ", identical text: "
+                       << (alice.text() == lower_alice.text()));
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "ComparisonOperator",
+    "C++20 operator<=> and ==, rewritten comparisons, ordering categories") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/FunctionCallOperator.cpp b/src/core/function/operator_overloading/FunctionCallOperator.cpp
index fe3b4d0..5a69996 100644
--- a/src/core/function/operator_overloading/FunctionCallOperator.cpp
+++ b/src/core/function/operator_overloading/FunctionCallOperator.cpp
@@ -1,37 +1,103 @@
-// cppcheck-suppress-file []
+// -----------------------------------------------------------------------------
+// Overloading operator() - function objects (functors)
+//
+//   struct Linear { double operator()(double x) const { return a * x + b; } };
+//
+//   - An object with operator() can be called like a function, but it can
+//     also carry STATE (parameters, counters, caches).
+//   - Standard algorithms accept functors, e.g. std::sort comparators.
+//   - A lambda is a compiler-generated functor; write a class when the object
+//     needs a name, several overloads or to be reused in many places.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operators#Function_call_operator
+// -----------------------------------------------------------------------------
 
-// operator()
+#include <algorithm>
+#include <string>
+#include <vector>
 
-#include <iostream>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-#include <cassert>  // for assert()
 
+/// Represents the function f(x) = a * x + b.
 struct Linear {
-  double a, b;
+  double a;
+  double b;
+  double operator()(double x) const { return a * x + b; }
+};
 
-  double operator()(double x) const {
-    LOG("");
-    return a * x + b;
+/// A stateful functor: counts how often it is called.
+class CallCounter {
+ public:
+  void operator()(int value) {
+    ++calls_;
+    sum_ += value;
   }
-};
+  int calls() const { return calls_; }
+  int sum() const { return sum_; }
 
-void run() {
-  Linear f{2, 1};  // Represents function 2x + 1.
-  double f_0 = f(0);
-  LOG_S(f_0);
-}
-}  // namespace
+ private:
+  int calls_{0};
+  int sum_{0};
+};
 
-class FunctionCallOperator : public IExample {
+/// Comparator functor with a parameter: sort by distance to a target.
+class CloserTo {
  public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "FunctionCallOperator"; }
-  std::string description() const override { return ""; }
+  explicit CloserTo(int target) : target_{target} {}
+  bool operator()(int lhs, int rhs) const {
+    return distance(lhs) < distance(rhs);
+  }
 
-  void execute() override { run(); }
+ private:
+  int distance(int value) const {
+    return value > target_ ? value - target_ : target_ - value;
+  }
+  int target_;
 };
 
-REGISTER_EXAMPLE(FunctionCallOperator);
\ No newline at end of file
+/// Several overloads in one object.
+struct Describe {
+  std::string operator()(int value) const {
+    return "int " + std::to_string(value);
+  }
+  std::string operator()(const std::string& value) const {
+    return "string \"" + value + "\"";
+  }
+};
+
+void run() {
+  LOG_SECTION("A function with parameters");
+  const Linear f{2.0, 1.0};  // f(x) = 2x + 1
+  LOG_S("f(0) = " << f(0) << ", f(3) = " << f(3));
+
+  LOG_SECTION("A functor that keeps state");
+  const std::vector<int> values{4, 8, 15, 16, 23, 42};
+  // std::for_each returns (a copy of) the functor, including its state.
+  const CallCounter counter =
+      std::for_each(values.begin(), values.end(), CallCounter{});
+  LOG_S("called " << counter.calls() << " times, sum = " << counter.sum());
+
+  LOG_SECTION("A functor as a comparator");
+  std::vector<int> numbers{1, 9, 14, 20, 11, 7};
+  std::sort(numbers.begin(), numbers.end(), CloserTo{10});
+  std::string sorted;
+  for (const int n : numbers) {
+    sorted += std::to_string(n) + " ";
+  }
+  LOG_S("sorted by distance to 10: " << sorted);
+
+  LOG_SECTION("Overloaded operator()");
+  const Describe describe;
+  LOG_S(describe(42) << ", " << describe(std::string("hello")));
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "FunctionCallOperator",
+    "operator(): function objects with parameters, state and overloads") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/InDecOperator.cpp b/src/core/function/operator_overloading/InDecOperator.cpp
index f5f284e..f386353 100644
--- a/src/core/function/operator_overloading/InDecOperator.cpp
+++ b/src/core/function/operator_overloading/InDecOperator.cpp
@@ -1,74 +1,80 @@
-// cppcheck-suppress-file [postfixOperator]
+// -----------------------------------------------------------------------------
+// Overloading ++ and -- (prefix and postfix)
+//
+//   T& operator++();     prefix  ++x : increment, return the object itself
+//   T  operator++(int);  postfix x++ : copy, increment, return the OLD copy
+//
+// The unused `int` parameter only tells the compiler which one is postfix.
+// Postfix must create a copy, so prefer ++it in loops over iterators and other
+// objects that are expensive to copy.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operator_incdec
+// -----------------------------------------------------------------------------
 
-// prefix/posfix
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Cents {
+
+class Counter {
  public:
-  explicit Cents(int cents) : cents_{cents} {}
-  int getCents() const { return cents_; }
+  explicit Counter(int value) : value_{value} {}
+  int value() const { return value_; }
+
+  Counter& operator++() {  // prefix
+    LOG_FUNC();
+    ++value_;
+    return *this;
+  }
 
-  // pre: inc -> return new
-  Cents& operator++();
-  Cents& operator--();
+  Counter& operator--() {  // prefix
+    LOG_FUNC();
+    --value_;
+    return *this;
+  }
 
-  // return old -> inc
-  Cents operator++(int);
-  Cents operator--(int);
+  Counter operator++(int) {  // postfix
+    LOG_FUNC();
+    Counter old{*this};  // 1. remember the old value
+    ++(*this);           // 2. reuse the prefix version
+    return old;          // 3. return the old value
+  }
+
+  Counter operator--(int) {  // postfix
+    LOG_FUNC();
+    Counter old{*this};
+    --(*this);
+    return old;
+  }
 
  private:
-  int cents_{};
+  int value_;
 };
 
-/// @brief pre ++x
-Cents& Cents::operator++() {
-  LOG("");
-  ++cents_;
-  return *this;
-}
+void run() {
+  LOG_SECTION("Prefix vs postfix");
+  Counter counter{25};
 
-/// @brief pre ++x
-Cents& Cents::operator--() {
-  LOG("");
-  --cents_;
-  return *this;
-}
+  const int prefix_result = (++counter).value();
+  LOG_S("++counter returned " << prefix_result << ", counter is "
+                              << counter.value());
 
-/// @brief pos x++
-Cents Cents::operator++(int) {
-  LOG("");
-  Cents temp{*this};  // create copy
-  ++(*this);          // increase origin
-  return temp;        // return old
-}
+  const int postfix_result = (counter++).value();
+  LOG_S("counter++ returned " << postfix_result << ", counter is "
+                              << counter.value());
 
-/// @brief pos x--
-Cents Cents::operator--(int) {
-  LOG("");
-  Cents temp{*this};
-  --(*this);
-  return temp;
-}
+  --counter;
+  counter--;
+  LOG_S("after --counter and counter--: " << counter.value());
 
-void run() {
-  Cents cent{25};
-  cent++;
-  ++cent;
-  cent--;
-  --cent;
-  LOG_S(cent.getCents());
+  LOG_SECTION("Prefix can be chained, postfix returns a temporary");
+  ++ ++counter;  // both increments apply to `counter`
+  LOG_S("++ ++counter -> " << counter.value());
 }
-}  // namespace
-
-class InDecOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "InDecOperator"; }
-  std::string description() const override { return ""; }
 
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(InDecOperator);
\ No newline at end of file
+LAB_EXAMPLE("InDecOperator",
+            "prefix and postfix ++/--, why ++it is preferred") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/StreamOperator.cpp b/src/core/function/operator_overloading/StreamOperator.cpp
index 905dd31..15ed23d 100644
--- a/src/core/function/operator_overloading/StreamOperator.cpp
+++ b/src/core/function/operator_overloading/StreamOperator.cpp
@@ -1,66 +1,86 @@
-// cppcheck-suppress-file[]
+// -----------------------------------------------------------------------------
+// Overloading operator<< and operator>> for streams
+//
+//   std::ostream& operator<<(std::ostream& out, const T& value);
+//   std::istream& operator>>(std::istream& in, T& value);
+//
+//   - They must be NON-members: the left operand is the stream, a class we
+//     cannot modify. Make them friends if they need private members.
+//   - Return the stream so calls chain: std::cout << a << b.
+//   - operator>> should set failbit on malformed input and leave the target
+//     unchanged, so `if (in >> value)` works like for built-in types.
+//
+// The same operators work with std::cout/std::cin, files and string streams;
+// string streams are used below so the example needs no keyboard input.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operators#Stream_extraction_and_insertion
+// -----------------------------------------------------------------------------
 
-// operator>> and operator<<
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include <istream>
+#include <ostream>
+#include <sstream>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Cents {
+
+class Point {
  public:
-  explicit Cents(int cents) : cents_{cents} {}
-  int getCents() const { return cents_; }
+  Point() = default;
+  Point(int x, int y) : x_{x}, y_{y} {}
 
-  //   // We won’t be able to use a member overload if the left operand is either not a class (e.g. int),
-  //   // or it is a class that we can’t modify (e.g. std::ostream).
-  //   // _cents << std::cout; work
-  //   // std::cout << _cents; error
-  //   std::ostream& operator<<(std::ostream& out) {
-  //     out << m_cents;
-  //     return out;
-  //   }
+  friend std::ostream& operator<<(std::ostream& out, const Point& point);
+  friend std::istream& operator>>(std::istream& in, Point& point);
 
  private:
-  int cents_{};
+  int x_{0};
+  int y_{0};
 };
 
-/// @brief Write obj to stream
-std::ostream& operator<<(std::ostream& out, const Cents& c) {
-  LOG("");
-  out << c.getCents();
-  return out;
+/// Writes "(x, y)".
+std::ostream& operator<<(std::ostream& out, const Point& point) {
+  return out << '(' << point.x_ << ", " << point.y_ << ')';
 }
 
-/// @brief Read obj from stream
-std::istream& operator>>(std::istream& in, Cents& c) {
-  LOG("");
-  int cents{};
-  in >> cents;
-  c = in ? Cents{cents} : Cents{0};
+/// Reads "(x, y)". On malformed input sets failbit and keeps `point` unchanged.
+std::istream& operator>>(std::istream& in, Point& point) {
+  char open = 0;
+  char comma = 0;
+  char close = 0;
+  int x = 0;
+  int y = 0;
+  if (in >> open >> x >> comma >> y >> close && open == '(' && comma == ',' &&
+      close == ')') {
+    point = Point{x, y};
+  } else {
+    in.setstate(std::ios::failbit);
+  }
   return in;
 }
 
 void run() {
-  Cents c1{25};
-  // out >>
-  std::cout << c1 << "\n";
-
-  // in >>
-  std::cin >> c1;
-  std::cout << c1 << "\n";
+  LOG_SECTION("operator<<");
+  const Point origin;
+  const Point target{3, -4};
+  std::ostringstream out;
+  out << "origin " << origin << " -> target " << target;  // chained calls
+  LOG(out.str());
 
-  // clearing lefover newline
-  std::string line;
-  std::getline(std::cin, line);
+  LOG_SECTION("operator>>");
+  std::istringstream input("(10, 20) (7,8) (oops)");
+  Point point;
+  while (input >> point) {
+    LOG_S("parsed " << point);
+  }
+  LOG_S("stopped at malformed input, fail() = "
+        << std::boolalpha << input.fail() << ", point kept its last value "
+        << point);
 }
-}  // namespace
 
-class StreamOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "StreamOperator"; }
-  std::string description() const override { return ""; }
-
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(StreamOperator);
\ No newline at end of file
+LAB_EXAMPLE("StreamOperator",
+            "operator<< and operator>> for a custom type, input validation") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/SubscriptOperator.cpp b/src/core/function/operator_overloading/SubscriptOperator.cpp
index 06e74a8..cc47723 100644
--- a/src/core/function/operator_overloading/SubscriptOperator.cpp
+++ b/src/core/function/operator_overloading/SubscriptOperator.cpp
@@ -1,44 +1,97 @@
-// cppcheck-suppress-file[]
+// -----------------------------------------------------------------------------
+// Overloading operator[] (and operator() for 2D access)
+//
+//   T&       operator[](std::size_t index);        read/write for non-const objects
+//   const T& operator[](std::size_t index) const;  read-only for const objects
+//
+//   - Provide both overloads; the compiler picks one by the constness of the
+//     object.
+//   - Like std::vector, operator[] is usually unchecked (fast) and a separate
+//     at() checks the bounds and throws.
+//   - Before C++23 operator[] takes exactly one argument, so matrices often
+//     use operator()(row, column) instead.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operators#Array_subscript_operator
+// -----------------------------------------------------------------------------
 
-// >> <<
-#include <iostream>
-#include "ExampleRegistry.h"
+#include <array>
+#include <cassert>
+#include <cstddef>
+#include <stdexcept>
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
 class IntList {
+ public:
+  int& operator[](std::size_t index) {
+    assert(index < values_.size() &&
+           "index out of range");  // checked in Debug only
+    return values_[index];
+  }
+
+  const int& operator[](std::size_t index) const {
+    assert(index < values_.size() && "index out of range");
+    return values_[index];
+  }
+
+  int& at(std::size_t index) {
+    if (index >= values_.size()) {
+      throw std::out_of_range("IntList::at: index " + std::to_string(index));
+    }
+    return values_[index];
+  }
+
+  std::size_t size() const { return values_.size(); }
+
  private:
-  int m_list_[10]{
-      0, 1, 2, 3, 4,
-      5, 6, 7, 8, 9};  // give this class some initial state for this example
+  std::array<int, 10> values_{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+};
 
+class Matrix {
  public:
-  // For non-const objects: can be used for assignment
-  int& operator[](int index) { return m_list_[index]; }
+  double& operator()(std::size_t row, std::size_t column) {
+    return cells_[row * kColumns + column];
+  }
+  double operator()(std::size_t row, std::size_t column) const {
+    return cells_[row * kColumns + column];
+  }
 
-  // For const objects: can only be used for access
-  // This function could also return by value if the type is cheap to copy
-  const int& operator[](int index) const { return m_list_[index]; }
+ private:
+  static constexpr std::size_t kColumns = 3;
+  std::array<double, 2 * kColumns> cells_{};
 };
 
 void run() {
-  IntList list{};
-  list[2] = 3;  // okay: calls non-const version of operator[]
-  std::cout << list[2] << '\n';
+  LOG_SECTION("const and non-const operator[]");
+  IntList list;
+  list[2] = 30;  // non-const overload returns int&
+  LOG_S("list[2] = " << list[2]);
 
-  const IntList clist{};
-  // clist[2] = 3; // compile error: clist[2] returns const reference, which we can't assign to
-  std::cout << clist[2] << '\n';
-}
-}  // namespace
+  const IntList read_only;
+  // read_only[2] = 3;  // error: const overload returns const int&
+  LOG_S("read_only[2] = " << read_only[2]);
 
-class SubscriptOperator : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "SubscriptOperator"; }
-  std::string description() const override { return ""; }
+  try {
+    list.at(10) = 1;
+  } catch (const std::out_of_range& e) {
+    LOG_S("list.at(10) throws: " << e.what());
+  }
 
-  void execute() override { run(); }
-};
+  LOG_SECTION("operator() for two indices");
+  Matrix matrix;
+  matrix(1, 2) = 4.5;
+  const Matrix& view = matrix;
+  LOG_S("matrix(1, 2) = " << view(1, 2) << ", matrix(0, 0) = " << view(0, 0));
+}
+
+}  // namespace
 
-REGISTER_EXAMPLE(SubscriptOperator);
\ No newline at end of file
+LAB_EXAMPLE(
+    "SubscriptOperator",
+    "operator[] const/non-const overloads, bounds-checked at(), operator()") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/TypeCast.cpp b/src/core/function/operator_overloading/TypeCast.cpp
index 7ac3233..729ee13 100644
--- a/src/core/function/operator_overloading/TypeCast.cpp
+++ b/src/core/function/operator_overloading/TypeCast.cpp
@@ -1,61 +1,80 @@
-// cppcheck-suppress-file []
+// -----------------------------------------------------------------------------
+// Conversion operators (user-defined type casts)
+//
+//   operator Target() const;            implicit conversion to Target
+//   explicit operator Target() const;   only with static_cast<Target>(x)
+//   explicit operator bool() const;     still works in if/while/&&/!
+//
+//   - Implicit conversions are convenient but can kick in where you do not
+//     expect them; prefer `explicit` unless the conversion is obviously safe.
+//   - A converting constructor (Target(Source)) is the other way to define a
+//     conversion; avoid defining both directions implicitly.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/cast_operator
+// -----------------------------------------------------------------------------
 
-// Overloading typecast
-
-#include <iostream>
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Cents {
- private:
-  int m_cents_{};
 
+class Cents {
  public:
-  explicit Cents(int cents = 0) : m_cents_{cents} {}
+  explicit Cents(int cents = 0) : cents_{cents} {}
 
-  // note that there is a space between operator keyword and the type we are casting
-  // overloading explicit cast operator
-  explicit operator int() const {
-    std::cout << "explicit operator int() const\n";
-    return m_cents_;
+  explicit operator int() const {  // requires static_cast<int>(cents)
+    LOG_FUNC();
+    return cents_;
   }
 
-  int getCents() const { return m_cents_; }
-  void setCents(int cents) { m_cents_ = cents; }
-};
+  explicit operator bool() const {
+    return cents_ != 0;
+  }  // "is there any money?"
 
-class Dollars {
  private:
-  int m_dollars_{};
+  int cents_;
+};
 
+class Dollars {
  public:
-  // overloading non-explicit cast operator
-  operator Cents() const {
-    std::cout << "operator Cents() const\n";
-    return Cents{m_dollars_ * 1000};
+  explicit Dollars(int dollars = 0) : dollars_{dollars} {}
+
+  operator Cents()
+      const {  // NOLINT: implicit on purpose, Dollars -> Cents is lossless
+    LOG_FUNC();
+    return Cents{dollars_ * 100};
   }
 
-  explicit Dollars(int dollars = 0) : m_dollars_{dollars} {}
+ private:
+  int dollars_;
 };
 
-void printCents(Cents c) {
-  // we are using explicit for the overloading operator int()
-  std::cout << static_cast<int>(c);
+void printCents(const Cents& cents) {
+  LOG_S("printCents: " << static_cast<int>(cents) << " cents");
 }
 
 void run() {
-  Dollars d{100};
-  printCents(d);  // Dollars -> Cents
-}
-}  // namespace
+  LOG_SECTION("Implicit conversion operator");
+  const Dollars price{3};
+  printCents(price);  // Dollars -> Cents happens automatically
 
-class TypeCast : public IExample {
- public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "TypeCast"; }
-  std::string description() const override { return ""; }
+  LOG_SECTION("explicit conversion operators");
+  const Cents empty{0};
+  const Cents some{250};
+  // int raw = some;  // error: operator int is explicit
+  LOG_S("static_cast<int>(some) = " << static_cast<int>(some));
 
-  void execute() override { run(); }
-};
+  if (some && !empty) {  // explicit operator bool is allowed in conditions
+    LOG("`some` has money and `empty` has none");
+  }
+  // bool flag = some;  // error: explicit operator bool needs a cast here
+  // int sum = some + 1; // error: explicit prevents surprising arithmetic
+}
+
+}  // namespace
 
-REGISTER_EXAMPLE(TypeCast);
\ No newline at end of file
+LAB_EXAMPLE(
+    "TypeCast",
+    "implicit and explicit conversion operators, explicit operator bool") {
+  run();
+}
diff --git a/src/core/function/operator_overloading/UnaryOperator.cpp b/src/core/function/operator_overloading/UnaryOperator.cpp
index 020ccf4..298fe9c 100644
--- a/src/core/function/operator_overloading/UnaryOperator.cpp
+++ b/src/core/function/operator_overloading/UnaryOperator.cpp
@@ -1,41 +1,72 @@
-// cppcheck-suppress-file[]
+// -----------------------------------------------------------------------------
+// Overloading unary operators: - + ! ~
+//
+//   T    operator-() const;   negation, returns a new object
+//   T    operator+() const;   unary plus, usually returns a copy
+//   bool operator!() const;   logical not
+//   T    operator~() const;   bitwise not
+//
+// Unary operators take no parameters as members (or one as non-members) and
+// should not modify the operand.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/operators
+// -----------------------------------------------------------------------------
 
-// - + ! (-2, +3)
-#include <iostream>
-#include "ExampleRegistry.h"
+#include <bitset>
+#include <cstdint>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-class Cents {
- private:
-  int m_cents_{};
 
+class Vector2 {
  public:
-  explicit Cents(int cents) : m_cents_{cents} {}
-  int getCents() const { return m_cents_; }
+  Vector2(double x, double y) : x_{x}, y_{y} {}
 
-  Cents operator-() const { return Cents{-m_cents_}; }
+  Vector2 operator-() const { return {-x_, -y_}; }
+  Vector2 operator+() const { return *this; }
+  bool operator!() const {
+    return x_ == 0.0 && y_ == 0.0;
+  }  // "is it the zero vector?"
 
-  Cents operator+() const { return Cents{m_cents_}; }
+  double x() const { return x_; }
+  double y() const { return y_; }
 
-  bool operator!() const { return m_cents_ == 0; }
+ private:
+  double x_;
+  double y_;
 };
 
-void run() {
-  Cents c1{25};
-  if (!c1 == false) {
-    c1 = -c1;
-    std::cout << c1.getCents();
-  }
-}
-}  // namespace
-
-class UnaryOperator : public IExample {
+class Flags {
  public:
-  std::string group() const override { return "core/overloading_operator"; }
-  std::string name() const override { return "UnaryOperator"; }
-  std::string description() const override { return ""; }
+  explicit Flags(std::uint8_t bits) : bits_{bits} {}
+  Flags operator~() const { return Flags{static_cast<std::uint8_t>(~bits_)}; }
+  std::uint8_t bits() const { return bits_; }
 
-  void execute() override { run(); }
+ private:
+  std::uint8_t bits_;
 };
 
-REGISTER_EXAMPLE(UnaryOperator);
\ No newline at end of file
+void run() {
+  LOG_SECTION("- + ! on a 2D vector");
+  const Vector2 velocity{3.0, -1.5};
+  const Vector2 reversed = -velocity;
+  const Vector2 copy = +velocity;
+  LOG_S("velocity  = (" << velocity.x() << ", " << velocity.y() << ")");
+  LOG_S("-velocity = (" << reversed.x() << ", " << reversed.y() << ")");
+  LOG_S("+velocity = (" << copy.x() << ", " << copy.y() << ")");
+  LOG_S(std::boolalpha << "!velocity = " << !velocity
+                       << ", !Vector2{0, 0} = " << !Vector2{0.0, 0.0});
+
+  LOG_SECTION("~ on a set of flags");
+  const Flags flags{0b0000'1111};
+  LOG_S(" flags = " << std::bitset<8>(flags.bits()));
+  LOG_S("~flags = " << std::bitset<8>((~flags).bits()));
+}
+
+}  // namespace
+
+LAB_EXAMPLE("UnaryOperator", "overload unary -, +, ! and ~") {
+  run();
+}
diff --git a/src/core/linkage/External.cpp b/src/core/linkage/External.cpp
index f0122cd..7e8bea9 100644
--- a/src/core/linkage/External.cpp
+++ b/src/core/linkage/External.cpp
@@ -1,21 +1,26 @@
+// Definitions of the entities with EXTERNAL linkage used by Linkage.cpp.
+// They must be defined in the same namespace as their declarations in
+// External.h, otherwise the linker cannot match them.
+
 #include "External.h"
-#include <iostream>
 
-namespace external {  // We must define the variable inside the same namespace as its extern declaration;
-                      // otherwise the linker cannot find the correct symbol.
+#include "lab/Logger.h"
+
+namespace external {
 
-// 1. Non-Static global variable/ function
+// 1. Non-static global variables and functions have external linkage.
 int non_static_var{1};
+
 void nonStaticFnc() {
-  std::cout << "nonStaticFnc\n";
+  LOG("external::nonStaticFnc() defined in External.cpp");
 }
 
-// 2. Extern Const/constexpr
+// 2. const variables have INTERNAL linkage by default; `extern` makes them external.
 extern const int kExternConstVar{200};
 
-// 3. Namespaces
+// 3. Variables inside a named namespace behave like globals.
 namespace name {
 int namespace_var = 123;
-}
+}  // namespace name
 
-}  // namespace external
\ No newline at end of file
+}  // namespace external
diff --git a/src/core/linkage/External.h b/src/core/linkage/External.h
index 724ec61..f00643b 100644
--- a/src/core/linkage/External.h
+++ b/src/core/linkage/External.h
@@ -1,9 +1,23 @@
+#pragma once
+
+// Declarations shared between External.cpp (definitions) and Linkage.cpp (use).
+
 namespace external {
-// 3. Inline const/constexpr in header file
-inline const int kInlineConstVar{100};
-constexpr int kConstexprVar{500};
+
+// A header must only DECLARE non-inline variables (extern) - defining them here
+// would create one definition per including file and break the linker.
+extern int non_static_var;
+extern const int kExternConstVar;
+void nonStaticFnc();
 
 namespace name {
 extern int namespace_var;
-}
+}  // namespace name
+
+// Exceptions that may be defined in a header:
+inline const int kInlineConstVar{
+    100};  // inline variable (C++17): one shared definition
+constexpr int kConstexprVar{
+    500};  // constexpr implies internal linkage at namespace scope
+
 }  // namespace external
diff --git a/src/core/linkage/Internal.cpp b/src/core/linkage/Internal.cpp
index 5b298e5..9beccb8 100644
--- a/src/core/linkage/Internal.cpp
+++ b/src/core/linkage/Internal.cpp
@@ -1,21 +1,33 @@
-#include <iostream>
+// Entities with INTERNAL linkage: they are visible only inside this .cpp file
+// (this "translation unit"). Another file may even define entities with the
+// same names without any conflict.
 
-namespace internal {  // We must define the variable inside the same namespace as its extern declaration;
-                      // otherwise the linker cannot find the correct symbol.
+#include "lab/Logger.h"
 
-// 1. Static global variable/ function
+namespace internal {
+namespace {
+
+// 3. Everything in an anonymous namespace has internal linkage (preferred in C++).
+int ns_internal{300};
+
+}  // namespace
+
+// 1. `static` at namespace scope gives internal linkage (the C way).
 static int g_internal{42};
 static void func_internal() {
-  std::cout << "func_internal\n";
+  LOG("internal::func_internal() - only callable inside Internal.cpp");
 }
 
-// 2. Const/constexpr
+// 2. const and constexpr variables at namespace scope are internal by default.
 const int c_internal{100};
-constexpr int ce_internal{100};
+constexpr int ce_internal{200};
 
-// 3. Anonymous namepsace
-namespace {
-int ns_internal{100};
+/// External linkage on purpose: the one door into this file (see Linkage.cpp).
+void printInternals() {
+  func_internal();
+  LOG_S("g_internal = " << g_internal << ", c_internal = " << c_internal
+                        << ", ce_internal = " << ce_internal
+                        << ", ns_internal = " << ns_internal);
 }
 
-}  // namespace internal
\ No newline at end of file
+}  // namespace internal
diff --git a/src/core/linkage/Linkage.cpp b/src/core/linkage/Linkage.cpp
index ae5cf1f..8a0cc46 100644
--- a/src/core/linkage/Linkage.cpp
+++ b/src/core/linkage/Linkage.cpp
@@ -1,53 +1,59 @@
-// cppcheck-suppress-file [unreadVariable]
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Linkage: can a name be used from another .cpp file?
+//
+//   no linkage       local variables - only inside their block
+//   internal linkage static globals, const/constexpr globals, anonymous
+//                    namespaces - only inside their translation unit (.cpp)
+//   external linkage non-static globals and functions, extern variables,
+//                    inline variables - shared by the whole program
+//
+// Each .cpp is compiled separately; the LINKER then connects uses of external
+// names to their single definition (the One Definition Rule).
+//
+// Files: External.h / External.cpp (external names), Internal.cpp (internal
+// names), sharing/ (three ways to share global constants).
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/internal-linkage/
+// -----------------------------------------------------------------------------
+
 #include "External.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
+// Declaration of the only externally visible function of Internal.cpp.
 namespace internal {
-
-extern int g_internal;   //  ERROR: g_internal not visible outside Internal.cpp
-extern int ce_internal;  //  ERROR: g_internal not visible outside Internal.cpp
-extern int c_internal;   //  ERROR: g_internal not visible outside Internal.cpp
-extern int ns_internal;  //  ERROR: g_internal not visible outside Internal.cpp
-
-void func_internal();  //  ERROR: helper not visible outside Internal.cpp
-
-void run() {
-  // std::cout << g_internal;
-  // std::cout << ce_internal;
-  // std::cout << c_internal;
-  // std::cout << ns_internal;
-  // func_internal();
-}
+void printInternals();
 }  // namespace internal
 
-namespace external {
-// use extern without initliaizer/forward declaration to access the external global variable/function
-extern int non_static_var;
-void nonStaticFnc();
-extern const int kExternConstVar;
-
-void run() {
-  std::cout << non_static_var << "\n";
-  std::cout << kInlineConstVar << "\n";
-  std::cout << kExternConstVar << "\n";
-  std::cout << kConstexprVar << "\n";
-  std::cout << name::namespace_var << "\n";
-  nonStaticFnc();
+namespace {
+
+void internalLinkage() {
+  LOG_SECTION("Internal linkage");
+  // Declaring the internal names from Internal.cpp here would compile, but the
+  // linker would fail with "undefined reference" as soon as they are used:
+  //   namespace internal { extern int g_internal; void func_internal(); }
+  //   internal::func_internal();  // link error
+  LOG("internal names cannot be reached from this file; Internal.cpp prints "
+      "them:");
+  internal::printInternals();
 }
 
-}  // namespace external
-
-#include "ExampleRegistry.h"
+void externalLinkage() {
+  LOG_SECTION("External linkage");
+  LOG_S("non_static_var        = " << external::non_static_var);
+  LOG_S("kExternConstVar       = " << external::kExternConstVar);
+  LOG_S("name::namespace_var   = " << external::name::namespace_var);
+  LOG_S("kInlineConstVar       = " << external::kInlineConstVar
+                                   << " (inline variable in the header)");
+  LOG_S("kConstexprVar         = " << external::kConstexprVar
+                                   << " (constexpr in the header)");
+  external::nonStaticFnc();
+}
 
-class Linkage : public IExample {
- public:
-  std::string group() const override { return "core"; }
-  std::string name() const override { return "Linkage"; }
-  std::string description() const override { return "Linkage"; }
-  void execute() override {
-    internal::run();
-    external::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Linkage);
+LAB_EXAMPLE("Linkage",
+            "internal vs external linkage across translation units") {
+  internalLinkage();
+  externalLinkage();
+}
diff --git a/src/core/linkage/README.md b/src/core/linkage/README.md
new file mode 100644
index 0000000..7cc7eb4
--- /dev/null
+++ b/src/core/linkage/README.md
@@ -0,0 +1,39 @@
+# Linkage
+
+| Example                  | Files                                        |
+|--------------------------|----------------------------------------------|
+| `Linkage`                | `Linkage.cpp`, `External.h/.cpp`, `Internal.cpp` |
+| `sharing/Sharing`        | `sharing/Sharing.cpp` and the three `constants` variants |
+
+## 1. Translation units and the linker
+
+Each `.cpp` file is compiled on its own into an object file (a *translation unit*). The linker then
+combines the object files and connects every use of a name with its definition.
+
+| Linkage  | Visible                     | Typical entities                                  |
+|----------|-----------------------------|---------------------------------------------------|
+| none     | only in its block           | local variables                                   |
+| internal | only in its `.cpp` file     | `static` globals, `const`/`constexpr` globals, anything in an anonymous namespace |
+| external | in the whole program        | non-static functions and globals, `extern` variables, `inline` variables |
+
+**One Definition Rule (ODR):** an entity with external linkage must have exactly one definition in
+the whole program. Inline functions and variables are the exception: they may be defined in
+several files if every definition is identical.
+
+Common linker errors:
+
+- `undefined reference to ...`: something is declared but never defined, or its internal linkage
+  hides it from other files.
+- `multiple definition of ...`: a non-inline variable or function is defined in a header that is
+  included by several `.cpp` files.
+
+## 2. Sharing global constants
+
+| Approach                             | Copies     | Constant expression elsewhere | Recompile on change |
+|--------------------------------------|------------|-------------------------------|---------------------|
+| `inline constexpr` in a header (C++17) | one        | yes                           | all includers       |
+| `constexpr` in a header              | one per file | yes                         | all includers       |
+| `extern const` + definition in `.cpp` | one        | no                            | only that `.cpp`    |
+
+The `Sharing` example prints the address of each constant as seen from two different files. This
+shows that internal constants are copied into every file, while inline constants are shared.
diff --git a/src/core/linkage/sharing/Sharing.cpp b/src/core/linkage/sharing/Sharing.cpp
index d0279a0..055c741 100644
--- a/src/core/linkage/sharing/Sharing.cpp
+++ b/src/core/linkage/sharing/Sharing.cpp
@@ -1,42 +1,62 @@
-// cppcheck-suppress-file [unreadVariable]
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Sharing global constants across multiple files
+//
+//   1. inline constexpr in a header (C++17)   <- preferred
+//        one definition shared by every file, usable in constant expressions
+//   2. constexpr in a header (internal linkage)
+//        simple, but every .cpp that includes it gets its own copy
+//   3. extern const declared in a header, defined in one .cpp
+//        one copy, but not usable in constant expressions in other files and
+//        declaration/definition must be kept in sync
+//
+// This example proves the "copies" claim by comparing the ADDRESS of the same
+// constant as seen from this file and from external/constants.cpp.
+//
+// Reference: https://www.learncpp.com/cpp-tutorial/sharing-global-constants-across-multiple-files-using-inline-variables/
+// -----------------------------------------------------------------------------
 
 #include "external/constants.h"
 #include "inline/constants.h"
 #include "internal/constants.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-namespace internal_way {
-void run() {
-  std::cout << internal_constants::kAvogadro << "\n";
+// Defined in external/constants.cpp: addresses of the constants as that file sees them.
+namespace sharing_demo {
+const double* internalAvogadroAddress();
+const double* inlineAvogadroAddress();
+}  // namespace sharing_demo
+
+namespace {
+
+void compare(const char* label, const double* here, const double* there) {
+  LOG_S(label << "this file " << here << ", constants.cpp " << there
+              << (here == there ? "  -> the SAME object"
+                                : "  -> two different copies"));
 }
-}  // namespace internal_way
 
-namespace external_way {
 void run() {
-  std::cout << external_constants::kAvogadro << "\n";
+  LOG_SECTION("Values");
+  LOG_S("inline_constants::kAvogadro   = " << inline_constants::kAvogadro);
+  LOG_S("internal_constants::kAvogadro = " << internal_constants::kAvogadro);
+  LOG_S("external_constants::kAvogadro = " << external_constants::kAvogadro);
+
+  constexpr double kMoles =
+      2.0 * inline_constants::kAvogadro;  // OK: constant expression
+  // constexpr double bad = 2.0 * external_constants::kAvogadro; // error: value not known here
+  LOG_S("2 mol = " << kMoles << " particles (computed at compile time)");
+
+  LOG_SECTION("Addresses");
+  compare("inline   : ", &inline_constants::kAvogadro,
+          sharing_demo::inlineAvogadroAddress());
+  compare("internal : ", &internal_constants::kAvogadro,
+          sharing_demo::internalAvogadroAddress());
 }
-}  // namespace external_way
 
-namespace inline_way {
-void run() {
-  std::cout << inline_constants::kAvogadro << "\n";
+}  // namespace
+
+LAB_EXAMPLE(
+    "Sharing",
+    "inline, internal and extern global constants shared between files") {
+  run();
 }
-}  // namespace inline_way
-
-#include "ExampleRegistry.h"
-
-class Sharing : public IExample {
- public:
-  std::string group() const override { return "core"; }
-  std::string name() const override { return "Sharing"; }
-  std::string description() const override {
-    return "SharingGlobalConstantsAcrossMultipleFiles";
-  }
-  void execute() override {
-    internal_way::run();  // prefer 2
-    external_way::run();
-    inline_way::run();  // prefer 1
-  }
-};
-
-REGISTER_EXAMPLE(Sharing);
diff --git a/src/core/linkage/sharing/external/constants.cpp b/src/core/linkage/sharing/external/constants.cpp
index 6d17827..e224350 100644
--- a/src/core/linkage/sharing/external/constants.cpp
+++ b/src/core/linkage/sharing/external/constants.cpp
@@ -1,9 +1,25 @@
 #include "constants.h"
 
+#include "../inline/constants.h"
+#include "../internal/constants.h"
+
 namespace external_constants {
-// We use extern to ensure these have external linkage
+// The single definitions. `extern` keeps external linkage (const alone would
+// make them internal).
 extern constexpr double kPi{3.14159};
 extern constexpr double kAvogadro{6.0221413e23};
 extern constexpr double kMyGravity{
     9.2};  // m/s^2 -- gravity is light on this planet
 }  // namespace external_constants
+
+namespace sharing_demo {
+
+const double* internalAvogadroAddress() {
+  return &internal_constants::kAvogadro;  // this file's own copy
+}
+
+const double* inlineAvogadroAddress() {
+  return &inline_constants::kAvogadro;  // the one shared object
+}
+
+}  // namespace sharing_demo
diff --git a/src/core/linkage/sharing/external/constants.h b/src/core/linkage/sharing/external/constants.h
index 4c498e4..b59c9cf 100644
--- a/src/core/linkage/sharing/external/constants.h
+++ b/src/core/linkage/sharing/external/constants.h
@@ -1,22 +1,22 @@
-// global constants as external variables:
-
+// Global constants as external variables
+//
 // Advantages:
-//     Works prior to C++16.
-//     Only one copy of each variable is required.
-//     Only requires recompilation of one file if the value of a constant changes.
+//     Works before C++17.
+//     Only one copy of each variable exists.
+//     Changing a value only requires recompiling constants.cpp.
 // Downsides:
-//     Forward declarations and variable definitions are in separate files, and must be kept in sync.
-//     Variables not usable in constant expressions outside of the file in which they are defined.
+//     Declarations (here) and definitions (constants.cpp) must be kept in sync.
+//     Not usable in constant expressions outside constants.cpp.
 
-#ifndef ECONSTANTS_H
-#define ECONSTANTS_H
+#ifndef CPPLAB_EXTERNAL_CONSTANTS_H
+#define CPPLAB_EXTERNAL_CONSTANTS_H
 
 namespace external_constants {
-// Since the actual variables are inside a namespace, the forward declarations need to be inside a namespace as well
-// We can't forward declare variables as constexpr, but we can forward declare them as (runtime) const
+// The definitions live in a namespace, so the declarations must too.
+// A variable cannot be forward declared as constexpr, only as (run-time) const.
 extern const double kPi;
 extern const double kAvogadro;
 extern const double kMyGravity;
 }  // namespace external_constants
 
-#endif
\ No newline at end of file
+#endif  // CPPLAB_EXTERNAL_CONSTANTS_H
diff --git a/src/core/linkage/sharing/inline/constants.h b/src/core/linkage/sharing/inline/constants.h
index 0a27132..25bc2ce 100644
--- a/src/core/linkage/sharing/inline/constants.h
+++ b/src/core/linkage/sharing/inline/constants.h
@@ -1,22 +1,20 @@
-// global constants as inline variables:
-
-// If you need global constants and your compiler is C++17 capable, prefer defining inline constexpr global variables in a header file.
+// Global constants as inline variables (preferred since C++17)
+//
 // Advantages:
-//     Can be used in constant expressions in any translation unit that includes them.
-//     Only one copy of each variable is required.
+//     Usable in constant expressions in every file that includes the header.
+//     Only one copy of each variable exists (the linker merges them).
 // Downsides:
-//     Only works in C++17 onward.
-//     Changing anything in the header file requires recompiling files including the header.
+//     Requires C++17.
+//     Changing a value recompiles every file that includes the header.
 
-#ifndef ICONSTANTS_H
-#define ICONSTANTS_H
+#ifndef CPPLAB_INLINE_CONSTANTS_H
+#define CPPLAB_INLINE_CONSTANTS_H
 
-// define your own namespace to hold constants
 namespace inline_constants {
-inline constexpr double kPi{3.14159};  // note: now inline constexpr
+inline constexpr double kPi{3.14159};
 inline constexpr double kAvogadro{6.0221413e23};
 inline constexpr double kMyGravity{
     9.2};  // m/s^2 -- gravity is light on this planet
-           // ... other related constants
 }  // namespace inline_constants
-#endif
\ No newline at end of file
+
+#endif  // CPPLAB_INLINE_CONSTANTS_H
diff --git a/src/core/linkage/sharing/internal/constants.h b/src/core/linkage/sharing/internal/constants.h
index 41f5c62..36cf3d6 100644
--- a/src/core/linkage/sharing/internal/constants.h
+++ b/src/core/linkage/sharing/internal/constants.h
@@ -1,21 +1,20 @@
-
-// global constants as internal variables:
+// Global constants as internal variables
+//
 // Advantages:
-//     Works prior to C++16.
-//     Can be used in constant expressions in any translation unit that includes them.
+//     Works before C++17.
+//     Usable in constant expressions in every file that includes the header.
 // Downsides:
-//     Changing anything in the header file requires recompiling files including the header.
-//     Each translation unit including the header gets its own copy of the variable.
+//     Every file that includes the header gets its OWN copy of each constant.
+//     Changing a value recompiles every file that includes the header.
 
-#ifndef INCONSTANTS_H
-#define INCONSTANTS_H
+#ifndef CPPLAB_INTERNAL_CONSTANTS_H
+#define CPPLAB_INTERNAL_CONSTANTS_H
 
-// Define your own namespace to hold constants
 namespace internal_constants {
-// Global constants have internal linkage by default
+// const/constexpr variables at namespace scope have internal linkage by default.
 constexpr double kPi{3.14159};
 constexpr double kAvogadro{6.0221413e23};
 constexpr double kMyGravity{9.2};  // m/s^2 -- gravity is light on this planet
-                                   // ... other related constants
 }  // namespace internal_constants
-#endif
\ No newline at end of file
+
+#endif  // CPPLAB_INTERNAL_CONSTANTS_H
diff --git a/src/core/smart_pointer/README.md b/src/core/smart_pointer/README.md
new file mode 100644
index 0000000..aa7e7a3
--- /dev/null
+++ b/src/core/smart_pointer/README.md
@@ -0,0 +1,39 @@
+# Smart pointers
+
+| Example  | Topic                                                          |
+|----------|----------------------------------------------------------------|
+| `Unique` | exclusive ownership, moving, sink functions, arrays, custom deleters |
+| `Shared` | reference counting, `shared_ptr<const T>`, `enable_shared_from_this` |
+| `Weak`   | observing without owning, `lock()`, breaking reference cycles  |
+
+Smart pointers apply RAII to heap memory: the destructor releases the object, so there is no
+`delete` to forget and no leak when an exception is thrown.
+
+## 1. Which one?
+
+```
+Does anybody need to share ownership?
+├── no  -> std::unique_ptr<T>   (the default: zero overhead, move-only)
+└── yes -> std::shared_ptr<T>   (reference counted)
+             └── observers that must not keep it alive -> std::weak_ptr<T>
+```
+
+Raw pointers and references are still fine for **non-owning** access: `void draw(const Shape&)`.
+
+## 2. Function signatures express ownership
+
+| Parameter                     | Meaning                                    |
+|-------------------------------|--------------------------------------------|
+| `void f(T&)` / `void f(T*)`   | uses the object, does not own it           |
+| `void f(std::unique_ptr<T>)`  | takes ownership ("sink")                   |
+| `void f(std::shared_ptr<T>)`  | becomes one more owner                     |
+| `std::unique_ptr<T> make()`   | factory: hands ownership to the caller     |
+
+## 3. Pitfalls
+
+- Create smart pointers with `std::make_unique` / `std::make_shared`, never
+  `std::shared_ptr<T>(this)` (use `enable_shared_from_this`).
+- Two `shared_ptr`s that own each other form a **cycle** and are never freed. Make one direction
+  `weak_ptr`.
+- `shared_ptr` makes the *reference count* thread-safe, not the object it points to.
+- `unique_ptr::release()` gives up ownership without deleting. You usually want `reset()`.
diff --git a/src/core/smart_pointer/Shared.cpp b/src/core/smart_pointer/Shared.cpp
index 30e31ba..81b6c6b 100644
--- a/src/core/smart_pointer/Shared.cpp
+++ b/src/core/smart_pointer/Shared.cpp
@@ -1,93 +1,124 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// std::shared_ptr - shared ownership
+//
+//   auto p = std::make_shared<T>(args...);
+//
+//   - Several shared_ptrs own the same object; a reference count in a
+//     "control block" tracks them. The object is deleted with the last owner.
+//   - Copying increments the count (atomically - thread-safe count, NOT a
+//     thread-safe object). Moving transfers without touching the count.
+//   - make_shared allocates the object and control block together.
+//   - shared_ptr<const T> shares read-only access.
+//   - Pitfall: two objects owning each other form a cycle and are never freed
+//     (see Weak.cpp). Prefer unique_ptr unless ownership is really shared.
+//
+// Reference: https://en.cppreference.com/w/cpp/memory/shared_ptr
+// -----------------------------------------------------------------------------
+
 #include <memory>
 #include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
 namespace {
-// Shared resource rather than copy to optimize memory
+
 struct AppConfig {
   std::string server;
   int port;
 
-  AppConfig(std::string s, int p) : server(std::move(s)), port(p) {
-    std::cout << "Config loaded\n";
+  AppConfig(std::string server_name, int port_number)
+      : server{std::move(server_name)}, port{port_number} {
+    LOG("  AppConfig loaded");
   }
-
-  void setPort(int p) { port = p; }
-
-  ~AppConfig() { std::cout << "Config destroyed\n"; }
+  ~AppConfig() { LOG("  AppConfig destroyed (last owner gone)"); }
+  AppConfig(const AppConfig&) = delete;
+  AppConfig& operator=(const AppConfig&) = delete;
 };
 
-// Module A
+/// Module A: shares the configuration read-only.
 class NetworkManager {
  public:
-  explicit NetworkManager(std::shared_ptr<const AppConfig> cfg)
-      : config_(std::move(cfg)) {}
-
+  explicit NetworkManager(std::shared_ptr<const AppConfig> config)
+      : config_{std::move(config)} {}
   void connect() const {
-    std::cout << "Connecting to " << config_->server << ":" << config_->port
-              << "\n";
+    LOG_S("  connecting to " << config_->server << ':' << config_->port);
   }
 
  private:
-  // const means we cannot modify config at this point
-  std::shared_ptr<const AppConfig> config_;
+  std::shared_ptr<const AppConfig>
+      config_;  // cannot modify the config through this
 };
 
-// Module B
-class Logger {
+/// Module B: shares the same configuration.
+class RequestLogger {
  public:
-  explicit Logger(std::shared_ptr<const AppConfig> cfg)
-      : config_(std::move(cfg)) {}
-
-  void log_start() const {
-    std::cout << "Logging enabled for " << config_->server << "\n";
-  }
-
-  ~Logger() { std::cout << "Logger destroyed\n"; }
+  explicit RequestLogger(std::shared_ptr<const AppConfig> config)
+      : config_{std::move(config)} {}
+  void start() const { LOG_S("  logging requests for " << config_->server); }
 
  private:
   std::shared_ptr<const AppConfig> config_;
 };
 
-void run() {
+void sharedOwnership() {
+  LOG_SECTION("Several owners, one object");
+  auto config = std::make_shared<AppConfig>("test.server.com", 80);
+  LOG_S("  use_count after make_shared: " << config.use_count());
   {
-    // auto config = std::make_shared<AppConfig>("api.example.com", 443);
-    std::shared_ptr<AppConfig> config =
-        std::make_shared<AppConfig>("test.server.com", 80);
-
+    const NetworkManager network{config};
     {
-      NetworkManager net(config);
-
-      {
-        Logger logger(config);
+      const RequestLogger logger{config};
+      LOG_S("  use_count with two modules:  " << config.use_count());
+      network.connect();
+      logger.start();
 
-        net.connect();
-        logger.log_start();
-
-        std::cout << "The number of owners (shared_ptr) - use_count: "
-                  << config.use_count() << "\n";
-        config->setPort(8080);
-        net.connect();
-        logger.log_start();
-      }
-
-      std::cout << "The number of owners (shared_ptr) - use_count: "
-                << config.use_count() << "\n";
+      config->port = 8080;  // the owner with non-const access changes it...
+      network.connect();    // ...and every module sees the change
     }
-    std::cout << "The number of owners (shared_ptr) - use_count: "
-              << config.use_count() << "\n";
+    LOG_S("  logger gone, use_count:     " << config.use_count());
   }
+  LOG_S("  network gone, use_count:    " << config.use_count());
+
+  const std::shared_ptr<AppConfig> moved =
+      std::move(config);  // no count change
+  LOG_S("  after std::move: config is "
+        << (config ? "set" : "empty")
+        << ", moved.use_count() = " << moved.use_count());
+  LOG("  -- leaving the function --");
 }
 
-}  // namespace
-
-#include "ExampleRegistry.h"
-
-class Shared : public IExample {
+class Session : public std::enable_shared_from_this<Session> {
  public:
-  std::string group() const override { return "core/smart_pointer"; }
-  std::string name() const override { return "Shared"; }
-  std::string description() const override { return "Shared Pointer Example"; }
-  void execute() override { run(); }
+  /// Hands out another owner of *this. Never do std::shared_ptr<Session>(this):
+  /// that would create a second, independent control block (double delete).
+  std::shared_ptr<Session> self() { return shared_from_this(); }
+  ~Session() { LOG("  Session destroyed"); }
 };
 
-REGISTER_EXAMPLE(Shared);
\ No newline at end of file
+void sharedFromThis() {
+  LOG_SECTION("enable_shared_from_this");
+  const auto session = std::make_shared<Session>();
+  [[maybe_unused]] const std::shared_ptr<Session> another = session->self();
+  LOG_S("  use_count = " << session.use_count() << " (same control block)");
+}
+
+void customDeleter() {
+  LOG_SECTION("Custom deleter");
+  const std::shared_ptr<int> value(new int{42}, [](const int* pointer) {
+    LOG_S("  custom deleter frees " << *pointer);
+    delete pointer;
+  });
+  LOG_S("  *value = " << *value);
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Shared",
+    "std::shared_ptr: reference counting, const sharing, shared_from_this") {
+  sharedOwnership();
+  sharedFromThis();
+  customDeleter();
+}
diff --git a/src/core/smart_pointer/Unique.cpp b/src/core/smart_pointer/Unique.cpp
index 9f1f771..06e92f2 100644
--- a/src/core/smart_pointer/Unique.cpp
+++ b/src/core/smart_pointer/Unique.cpp
@@ -1,45 +1,126 @@
-#include <cstring>
+// -----------------------------------------------------------------------------
+// std::unique_ptr - exclusive ownership
+//
+//   auto p = std::make_unique<T>(args...);
+//
+//   - Exactly one unique_ptr owns the object; the object is deleted when that
+//     unique_ptr is destroyed or reset (RAII). No manual delete, no leaks.
+//   - It cannot be copied, only MOVED: ownership is transferred explicitly.
+//   - Zero overhead compared to a raw pointer (with the default deleter).
+//   - Function parameters express intent:
+//       f(std::unique_ptr<T>)  f takes ownership (a "sink")
+//       f(T&) / f(T*)          f only uses the object, ownership stays
+//   - A custom deleter releases non-memory resources (files, handles).
+//
+// Reference: https://en.cppreference.com/w/cpp/memory/unique_ptr
+// -----------------------------------------------------------------------------
+
+#include <cstdio>
 #include <memory>
-#include "Logger.h"
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
+
 class Resource {
  public:
-  Resource() { std::cout << "Resource acquired\n"; }
-  ~Resource() { std::cout << "Resource destroyed\n"; }
-
-  void use() {
-    std::cout << "Using resource\n";
-    dummy_++;
+  explicit Resource(std::string name) : name_{std::move(name)} {
+    LOG_S("  Resource(" << name_ << ") acquired");
   }
+  ~Resource() { LOG_S("  ~Resource(" << name_ << ") released"); }
+  Resource(const Resource&) = delete;
+  Resource& operator=(const Resource&) = delete;
+
+  const std::string& name() const { return name_; }
 
  private:
-  int dummy_{};
+  std::string name_;
 };
 
-void run() {
-  LOG("unique_ptr example");
+void basics() {
+  LOG_SECTION("Ownership and moving");
   {
-    auto p1 = std::make_unique<Resource>();
-    p1->use();
+    auto first = std::make_unique<Resource>("A");
+    // auto copy = first;  // error: unique_ptr cannot be copied
+    auto second = std::move(first);  // ownership moves, nothing is copied
+    LOG_S("  first is " << (first ? "set" : "empty") << ", second owns "
+                        << second->name());
+    LOG("  -- leaving scope --");
+  }  // second is destroyed here and deletes Resource A
 
-    // auto p2 = p1; // compile error -> copy not allow
-    auto p2 = std::move(p1);
-    std::cout << "p1 is " << (p1 ? "not null" : "null") << "\n";
-    p2->use();
-  }
-  LOG("End scope. RAII");  // automatically deletes the object uinique_ptr owns
+  LOG_SECTION("reset, release and get");
+  auto owner = std::make_unique<Resource>("B");
+  const Resource* observer = owner.get();  // non-owning raw pointer
+  LOG_S("  get() -> " << observer->name());
+
+  owner.reset(new Resource("C"));   // deletes B, now owns C
+  Resource* raw = owner.release();  // gives up ownership WITHOUT deleting
+  LOG_S("  after release(): owner is " << (owner ? "set" : "empty")
+                                       << ", raw points to " << raw->name());
+  delete raw;  // now it is our job - which is why release() is rarely used
 }
-}  // namespace
 
-#include "ExampleRegistry.h"
+void consume(std::unique_ptr<Resource> resource) {  // sink: takes ownership
+  LOG_S("  consume() owns " << resource->name() << " now");
+}  // deleted here
 
-class Unique : public IExample {
- public:
-  std::string group() const override { return "core/smart_pointer"; }
-  std::string name() const override { return "Unique"; }
-  std::string description() const override { return "Unique Pointer Example"; }
-  void execute() override { run(); }
-};
+void inspect(
+    const Resource& resource) {  // borrows, ownership stays with the caller
+  LOG_S("  inspect() looks at " << resource.name());
+}
+
+std::unique_ptr<Resource> makeResource(const std::string& name) {
+  return std::make_unique<Resource>(name);  // factory: returns ownership
+}
+
+void functions() {
+  LOG_SECTION("Passing ownership through functions");
+  auto resource = makeResource("D");
+  inspect(*resource);
+  consume(std::move(resource));
+  LOG_S("  after consume(): resource is " << (resource ? "set" : "empty"));
+}
+
+void containersAndArrays() {
+  LOG_SECTION("Containers and arrays");
+  std::vector<std::unique_ptr<Resource>> resources;
+  resources.push_back(std::make_unique<Resource>("E"));
+  resources.push_back(std::make_unique<Resource>("F"));
+  LOG_S("  vector holds " << resources.size() << " unique_ptrs");
+
+  const auto numbers = std::make_unique<int[]>(3);  // value-initialized: 0 0 0
+  numbers[1] = 42;
+  LOG_S("  unique_ptr<int[]>: numbers[1] = "
+        << numbers[1] << " (delete[] used automatically)");
+  LOG("  -- clearing the vector --");
+  resources.clear();
+}
 
-REGISTER_EXAMPLE(Unique);
\ No newline at end of file
+void customDeleter() {
+  LOG_SECTION("Custom deleter for a C resource");
+  auto close_file = [](std::FILE* file) {
+    LOG("  deleter: std::fclose");
+    std::fclose(file);
+  };
+  const std::unique_ptr<std::FILE, decltype(close_file)> file(std::tmpfile(),
+                                                              close_file);
+  if (file) {
+    std::fputs("temporary data", file.get());
+    LOG("  wrote to a temporary FILE*; it is closed automatically");
+  }
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Unique",
+    "std::unique_ptr: ownership, moves, sinks, arrays, custom deleters") {
+  basics();
+  functions();
+  containersAndArrays();
+  customDeleter();
+}
diff --git a/src/core/smart_pointer/Weak.cpp b/src/core/smart_pointer/Weak.cpp
index a2a7820..6dc4b04 100644
--- a/src/core/smart_pointer/Weak.cpp
+++ b/src/core/smart_pointer/Weak.cpp
@@ -1,63 +1,126 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// std::weak_ptr - observe without owning
+//
+//   std::weak_ptr<T> observer = shared;   does NOT increase the owner count
+//   if (auto locked = observer.lock())    temporary shared_ptr, empty if expired
+//
+// Uses:
+//   - Caches and observers that must not keep objects alive.
+//   - Breaking reference cycles: if A owns B and B owns A through shared_ptrs,
+//     neither count ever reaches zero and both leak. Make one side weak.
+//
+// In multithreaded code use lock() rather than expired(): the object can be
+// destroyed right after expired() returned false.
+//
+// Reference: https://en.cppreference.com/w/cpp/memory/weak_ptr
+// -----------------------------------------------------------------------------
+
 #include <memory>
 #include <string>
-#include "Logger.h"
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-// Shared resource rather than copy to optimize memory
+
 struct AppConfig {
   std::string server;
   int port;
 
-  AppConfig(std::string s, int p) : server(std::move(s)), port(p) {
-    std::cout << "Config loaded\n";
-  }
-
-  void setPort(int p) { port = p; }
-
-  ~AppConfig() { std::cout << "Config destroyed\n"; }
+  AppConfig(std::string server_name, int port_number)
+      : server{std::move(server_name)}, port{port_number} {}
+  ~AppConfig() { LOG("  AppConfig destroyed"); }
+  AppConfig(const AppConfig&) = delete;
+  AppConfig& operator=(const AppConfig&) = delete;
 };
 
-void validatePointer(const std::weak_ptr<AppConfig>& wp) {
-  if (auto tmp = wp.lock()) {
-    LOG("config value is: " + std::to_string(tmp->port) + " " + tmp->server);
+void useIfAlive(const std::weak_ptr<AppConfig>& observer) {
+  if (const std::shared_ptr<AppConfig> config = observer.lock()) {
+    LOG_S("  lock() succeeded: " << config->server << ':' << config->port);
   } else {
-    LOG("config is expired");
+    LOG("  lock() returned empty: the config is gone");
   }
 }
 
-/**
- * wp.expired() == false // at least one shared_ptr still owns it
- * wp.lock() != nullptr  // same condition
- */
-void run() {
+void observing() {
+  LOG_SECTION("lock() and expired()");
   std::weak_ptr<AppConfig> observer;
   {
-    std::shared_ptr<AppConfig> config =
-        std::make_shared<AppConfig>("test.server.com", 80);
-
-    // check lock() to determine if pointer is valid
+    const auto config = std::make_shared<AppConfig>("test.server.com", 80);
     observer = config;
-    std::cout << "use_count: " << config.use_count() << "\n";
-    std::cout << "expired? " << std::boolalpha << observer.expired() << "\n";
-    validatePointer(observer);
+    LOG_S("  use_count = " << config.use_count()
+                           << " (the weak_ptr does not count)");
+    LOG_S("  expired() = " << std::boolalpha << observer.expired());
+    useIfAlive(observer);
+    LOG("  -- last shared_ptr goes out of scope --");
   }
-
-  // now the config is expired
-  std::cout << "expired? " << std::boolalpha << observer.expired() << "\n";
-  validatePointer(observer);
+  LOG_S("  expired() = " << std::boolalpha << observer.expired());
+  useIfAlive(observer);
 }
 
-}  // namespace
+namespace cycle {
 
-#include "ExampleRegistry.h"
+struct Child;
+
+struct Parent {
+  std::shared_ptr<Child> child;
+  ~Parent() { LOG("  ~Parent"); }
+};
 
-class Weak : public IExample {
- public:
-  std::string group() const override { return "core/smart_pointer"; }
-  std::string name() const override { return "Weak"; }
-  std::string description() const override { return "Weak Pointer Example"; }
-  void execute() override { run(); }
+struct StrongChild {
+  std::shared_ptr<struct StrongParent> parent;
+  ~StrongChild() { LOG("  ~StrongChild"); }
 };
 
-REGISTER_EXAMPLE(Weak);
\ No newline at end of file
+struct StrongParent {
+  std::shared_ptr<StrongChild> child;
+  ~StrongParent() { LOG("  ~StrongParent"); }
+};
+
+struct Child {
+  std::weak_ptr<Parent> parent;  // weak back-reference breaks the cycle
+  ~Child() { LOG("  ~Child"); }
+};
+
+void run() {
+  LOG_SECTION("Reference cycle with shared_ptr on both sides");
+  {
+    auto parent = std::make_shared<StrongParent>();
+    parent->child = std::make_shared<StrongChild>();
+    parent->child->parent = parent;  // cycle: parent <-> child
+    LOG_S("  parent.use_count() = "
+          << parent.use_count() << " (local variable + the child's pointer)");
+    const std::weak_ptr<StrongParent> watch = parent;
+    parent.reset();  // drop our own reference
+    LOG_S("  after parent.reset() the parent is still alive: "
+          << std::boolalpha << !watch.expired());
+    LOG("  -> nothing will ever free these objects: a memory leak");
+
+    // Cut the loop by hand so this lab stays leak-free. Both destructors run:
+    watch.lock()->child->parent.reset();
+  }
+
+  LOG_SECTION("The same with a weak_ptr back-reference");
+  {
+    auto parent = std::make_shared<Parent>();
+    parent->child = std::make_shared<Child>();
+    parent->child->parent = parent;  // weak: does not count
+    LOG_S("  parent.use_count() = " << parent.use_count());
+    if (const auto locked = parent->child->parent.lock()) {
+      LOG("  the child can still reach its parent through lock()");
+    }
+    LOG("  -- leaving scope: both destructors run --");
+  }
+}
+
+}  // namespace cycle
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Weak",
+    "std::weak_ptr: lock/expired, observers and breaking shared_ptr cycles") {
+  observing();
+  cycle::run();
+}
diff --git a/src/core/string/CString.cpp b/src/core/string/CString.cpp
index 26ee4af..23076c0 100644
--- a/src/core/string/CString.cpp
+++ b/src/core/string/CString.cpp
@@ -1,224 +1,155 @@
-#include <string.h>  // C-String
-#include "Logger.h"
+// -----------------------------------------------------------------------------
+// C strings (<cstring>, <cstdio>, <cstdlib>)
+//
+// A C string is an array of char terminated by '\0'. The functions below
+// trust you to provide big enough buffers - a missing '\0' or a too-small
+// buffer is a buffer overflow (undefined behavior, security bugs).
+//
+//   length   strlen (counts until '\0') vs sizeof (size of the array/pointer)
+//   copy     strcpy, strncpy (may NOT add '\0'!), snprintf (always terminates)
+//   append   strcat, strncat
+//   compare  strcmp, strncmp, memcmp
+//   parse    strtok (not thread-safe), strtok_r (POSIX), strcspn
+//   convert  atoi/atof (no error reporting), strtol/strtod (report the end)
+//
+// In C++ prefer std::string and std::string_view; know these for C APIs.
+//
+// Reference: https://en.cppreference.com/w/cpp/string/byte
+// -----------------------------------------------------------------------------
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void log_string_info(const char* label, const char* str, size_t size) {
-  LOG_S(label << ": \"" << str << "\"" << " | size=" << size
-              << " | length=" << strlen(str));
-}
 
-namespace create {
-/// @brief Stack (modifiable array)
-// 0x7fffc000: str2[0] = 'H'
-// 0x7fffc001: str2[1] = 'e'
-// 0x7fffc002: str2[2] = 'l'
-// 0x7fffc003: str2[3] = 'l'
-// 0x7fffc004: str2[4] = 'o'
-// 0x7fffc005: str2[5] = '\0'
-// (str2 starts at 0x7fffc000)
-
-/// @brief String literal (Data / Read-only segment)
-// 0x00403000: 'H'
-// 0x00403001: 'e'
-// 0x00403002: 'l'
-// 0x00403003: 'l'
-// 0x00403004: 'o'
-// 0x00403005: '\0'
-// (str1 -> points to 0x00403000)
-
-// Pointer variable
-// 0x7fffbff0: str1 = 0x00403000   // str1 holds address of string literal
-void run() {
-  LOG("=== create ===");
-
-  /// @brief Create a string as a character array (modifiable)
-  char str_array[] = "this is a string array literal";
-  log_string_info("str_array", str_array, sizeof(str_array));
-  str_array[0] ^= ' ';  // modify first character
-  log_string_info("modified str_array", str_array, sizeof(str_array));
-
-  /// @brief Create a pointer to a string literal const (read-only)
-  const char* str_ptr = "this is a strPtr literal";
-  log_string_info("str_ptr", str_ptr, sizeof(str_ptr));
-  // str_ptr[0] ^= ' '; // ERROR
-
-  /// @brief Create a string using sprintf / snprintf
-  char str_formatted[50];
-  int num_var = 21;
-  const char text[] = "example";
-
-  sprintf(str_formatted, "sprintf: %d",
-          num_var);  // sprintf (unsafe if buffer too small)
-  log_string_info("sprintf", str_formatted, sizeof(str_formatted));
-
-  snprintf(str_formatted, sizeof(str_formatted), "snprintf %s %d", text,
-           num_var);  // snprintf (safer, limits buffer size)
-  log_string_info("snprintf", str_formatted, sizeof(str_formatted));
+void logString(const char* label, const char* text, std::size_t size) {
+  LOG_S(label << ": \"" << text << "\" | sizeof = " << size
+              << " | strlen = " << std::strlen(text));
 }
-}  // namespace create
-
-namespace copy {
-void run() {
-  LOG("=== copy ===");
-
-  const char src[] = "CopyStr";
-  char dst[50];
-
-  /// @brief Copy full string
-  strcpy(dst, src);
-  log_string_info("strcpy", dst, sizeof(dst));
 
-  /// @brief Copy first N characters
-  strncpy(dst, "Hello123", 5);
-  dst[5] = '\0';  // strncpy may not append '\0'
-  log_string_info("strncpy", dst, sizeof(dst));
+void create() {
+  LOG_SECTION("Creating C strings");
+  // A char array holds a modifiable COPY of the literal (on the stack):
+  //   0x7ffc...: 't' 'h' 'i' 's' ... '\0'
+  char array[] = "this is a char array";
+  logString("array", array, sizeof(array));
+  array[0] = 'T';  // allowed
+  logString("modified", array, sizeof(array));
+
+  // A pointer to a string literal points into read-only memory:
+  //   pointer (stack) -> 0x4030...: 't' 'h' 'i' 's' ... '\0' (read-only data)
+  const char* pointer = "this is a string literal";
+  logString("pointer", pointer,
+            sizeof(pointer));  // sizeof gives the POINTER size!
+  // pointer[0] = 'T';  // error (and undefined behavior without the const)
+
+  char formatted[50];
+  std::snprintf(formatted, sizeof(formatted), "snprintf %s %d", "example", 21);
+  logString("snprintf", formatted, sizeof(formatted));
 }
-}  // namespace copy
 
-namespace concat {
-void run() {
-  LOG("=== concat ===");
+void copy() {
+  LOG_SECTION("Copying");
+  const char source[] = "CopyStr";
+  char destination[50];
 
-  const char part1[] = "Hello";
-  const char part2[] = "World";
-  char dst[50] = "";
+  std::strcpy(destination, source);  // destination must be large enough
+  logString("strcpy", destination, sizeof(destination));
 
-  /// @brief Append full strings
-  strcat(dst, part1);
-  strcat(dst, part2);
-  strcat(dst, " !!");
-  log_string_info("strcat", dst, sizeof(dst));
-
-  /// @brief Append first N characters
-  strncat(dst, "1234", 3);
-  log_string_info("strncat", dst, sizeof(dst));
+  std::strncpy(destination, "Hello123",
+               5);        // copies 5 chars, NO '\0' added here
+  destination[5] = '\0';  // so terminate it yourself
+  logString("strncpy(5)", destination, sizeof(destination));
 }
-}  // namespace concat
-
-namespace compare {
-void run() {
-  LOG("=== compare ===");
-
-  const char str1[] = "abc";
-  const char str2[] = "abcde";
 
-  /// @brief Compare memory
-  // int memcmp(const void* ptr1, const void* ptr2, size_t num);
-  int result0 = memcmp(str1, str2, sizeof(str1));
-  LOG_S("memcmp(str1, str2, sizeof(str1)) = " << result0);
-
-  /// @brief Compare full string
-  int result1 = strcmp(str1, "abc");
-  int result2 = strcmp(str1, str2);
-  LOG_S("strcmp(str1, \"abc\") = " << result1);
-  LOG_S("strcmp(str1, str2) = " << result2);
-
-  /// @brief Compare first N characters
-  int result3 = strncmp(str1, str2, 3);
-  LOG_S("strncmp(str1, str2, 3) = " << result3);
+void concatenate() {
+  LOG_SECTION("Concatenating");
+  char destination[50] = "";
+  std::strcat(destination, "Hello");
+  std::strcat(destination, "World");
+  std::strcat(destination, " !!");
+  logString("strcat", destination, sizeof(destination));
+
+  std::strncat(destination, "1234",
+               3);  // appends at most 3 chars, always adds '\0'
+  logString("strncat(3)", destination, sizeof(destination));
 }
-}  // namespace compare
-
-namespace parse {
-void run() {
-  LOG("=== compare ===");
-
-  char str[] = "A,B,C,D,";
-  // char* str = "A,B,C,D,"; // ERROR - string literal is read-only
 
-  const char* delimiter = ",";
-
-  /// @brief strtok (NOT thread-safe)
-  LOG_S("=== strtok ===");
-  const char* token = strtok(str, delimiter);
-  while (token != nullptr) {
-    LOG_S("token = " << token);
-
-    token = strtok(nullptr, delimiter);
-  }
-
-  /// @brief strtok problem example
-  {
-    LOG_S("=== strtok problem example ===");
-
-    char str1[] = "a,b,c";
-    char str2[] = "1,2,3";
-
-    // Parse str1
-    const char* token1 = strtok(str1, delimiter);
-    LOG_S("str1 first token  = " << token1);
-
-    // Parse str2
-    const char* token2 = strtok(str2, delimiter);
-    LOG_S("str2 first token  = " << token2);
+void compare() {
+  LOG_SECTION("Comparing");
+  const char shorter[] = "abc";
+  const char longer[] = "abcde";
+  // Result < 0, 0 or > 0 - never compare C strings with == (that compares addresses).
+  LOG_S("strcmp(\"abc\", \"abc\")      = " << std::strcmp(shorter, "abc"));
+  LOG_S("strcmp(\"abc\", \"abcde\")    = " << std::strcmp(shorter, longer)
+                                           << " (< 0)");
+  LOG_S(
+      "strncmp(\"abc\", \"abcde\", 3) = " << std::strncmp(shorter, longer, 3));
+  LOG_S("memcmp over 4 bytes          = "
+        << std::memcmp(shorter, longer, sizeof(shorter)) << " ('\\0' vs 'd')");
+}
 
-    // Continue parsing str1
-    token1 = strtok(nullptr, delimiter);
-    LOG_S("str1 second token = " << token1 << " (unexpected)");
+void parse() {
+  LOG_SECTION("Tokenizing");
+  char list[] =
+      "A,B,C,D,";  // strtok MODIFIES the string: it must not be a literal
+  for (const char* token = std::strtok(list, ","); token != nullptr;
+       token = std::strtok(nullptr, ",")) {
+    LOG_S("strtok token: " << token);
   }
 
-  /// @brief strtok_r (thread-safe / reentrant)
-  LOG_S("=== strtok_r ===");
-
-  char str2[] = "one,two,three";
-  char* saveptr;
-  const char* token2 = strtok_r(str2, delimiter, &saveptr);
-
-  while (token2 != nullptr) {
-    LOG_S("token = " << token2);
-    token2 = strtok_r(nullptr, delimiter, &saveptr);
+  LOG("strtok keeps hidden global state - interleaving two strings breaks it:");
+  char first[] = "a,b,c";
+  char second[] = "1,2,3";
+  const char* token1 = std::strtok(first, ",");
+  const char* token2 = std::strtok(second, ",");  // resets the hidden state
+  LOG_S("  first token of each: " << token1 << ", " << token2);
+  token1 = std::strtok(nullptr, ",");
+  LOG_S("  'next token of first' is really from second: " << token1);
+
+  char reentrant[] = "one,two,three";
+  char* save = nullptr;  // strtok_r keeps the state in `save` instead
+  for (const char* token = strtok_r(reentrant, ",", &save); token != nullptr;
+       token = strtok_r(nullptr, ",", &save)) {
+    LOG_S("strtok_r token: " << token);
   }
 
-  /// @brief strcspn
-  // Find first occurrence of any character in reject set
-  LOG_S("=== strcspn ===");
-
   const char sample[] = "hello123world";
-  size_t pos = strcspn(sample, "0123456789");
-  LOG_S("sample = " << sample);
-  LOG_S("first digit index = " << pos);
-  LOG_S("digit = " << sample[pos]);
+  const std::size_t index = std::strcspn(sample, "0123456789");
+  LOG_S("strcspn: first digit of \"" << sample << "\" is '" << sample[index]
+                                     << "' at index " << index);
 }
-}  // namespace parse
-
-namespace number_conversion {
-void run() {
-  LOG_S("=== number_conversion ===");
-
-  /// @brief String to integer
-  const char str_num[] = "100";
-  int num = atoi(str_num);
-  LOG_S("atoi(\"100\") = " << num);
-
-  /// @brief String to double
-  const char str_num_d[] = "100.1234__123";
-  double num_d = atof(str_num_d);
-  LOG_S("atof(\"100.1234__123\") = " << num_d);
-
-  /// @brief strtod
-  char* end;
-  num_d = strtod(str_num_d, &end);
-  LOG_S("strtod = " << num_d);
-  LOG_S("remaining string = " << end);
+
+void convert() {
+  LOG_SECTION("Number conversions");
+  LOG_S("atoi(\"100\")          = " << std::atoi("100"));
+  LOG_S("atoi(\"abc\")          = " << std::atoi("abc")
+                                    << " (errors look like 0!)");
+
+  const char text[] = "100.1234__123";
+  char* end = nullptr;
+  const double value =
+      std::strtod(text, &end);  // reports where parsing stopped
+  LOG_S("strtod(\"" << text << "\") = " << value << ", remaining \"" << end
+                    << "\"");
+
+  const long hex = std::strtol("ff", nullptr, 16);
+  LOG_S("strtol(\"ff\", 16)     = " << hex);
 }
-}  // namespace number_conversion
-}  // namespace
 
-#include "ExampleRegistry.h"
-
-class CString : public IExample {
- public:
-  std::string group() const override { return "core/string"; }
-  std::string name() const override { return "C-String"; }
-  std::string description() const override { return "C-String Example"; }
-  void execute() override {
-    create::run();
-    copy::run();
-    concat::run();
-    compare::run();
-    parse::run();
-    number_conversion::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(CString);
+LAB_EXAMPLE(
+    "CString",
+    "C strings: strlen vs sizeof, copy, concatenate, compare, strtok, strtod") {
+  create();
+  copy();
+  concatenate();
+  compare();
+  parse();
+  convert();
+}
diff --git a/src/core/string/README.md b/src/core/string/README.md
new file mode 100644
index 0000000..4013020
--- /dev/null
+++ b/src/core/string/README.md
@@ -0,0 +1,41 @@
+# Strings
+
+| Example            | Topic                                                         |
+|--------------------|---------------------------------------------------------------|
+| `CString`          | `char` arrays, `strlen` vs `sizeof`, copy/concat/compare, `strtok`, `strtod` |
+| `StdString`        | `std::string` operations, searching, conversions, `std::string_view` |
+| `StringFormatting` | `std::format`, concatenation, `std::ostringstream`, `snprintf`, custom formatters |
+
+## 1. Three kinds of strings
+
+| Type                 | Owns the characters | Knows its length | Typical use                |
+|----------------------|---------------------|------------------|----------------------------|
+| `const char*`        | no                  | no (scans for `'\0'`) | C APIs, string literals |
+| `std::string`        | yes                 | yes              | storing and modifying text |
+| `std::string_view`   | no                  | yes              | read-only parameters (C++17) |
+
+```cpp
+void print(std::string_view text);  // accepts literals, std::string, substrings - without copies
+```
+
+A `std::string_view` must not outlive the characters it refers to:
+`std::string_view view = std::string("temporary");` dangles immediately.
+
+## 2. C string pitfalls
+
+- `sizeof(pointer)` is the size of the pointer, not the length of the text.
+- `strcpy`, `strcat` and `sprintf` do not check buffer sizes: prefer `snprintf`.
+- `strncpy` does **not** add `'\0'` when the source is too long.
+- Compare with `strcmp`, not `==`, which compares addresses.
+- `atoi` returns 0 on error. `strtol` and `strtod` report where parsing stopped.
+
+## 3. Formatting (C++20)
+
+```cpp
+std::format("{:>8}|{:<8}|{:^8}", "r", "l", "c");  // alignment
+std::format("{:.2f} {:#x} {:08.3f}", 3.14159, 255, 2.5);
+std::format("{1} {0}", "world", "hello");        // positional arguments
+```
+
+`std::format` is type-safe, and a format string that does not match the arguments fails at compile
+time.
diff --git a/src/core/string/StdString.cpp b/src/core/string/StdString.cpp
index 3f7281b..1ad5456 100644
--- a/src/core/string/StdString.cpp
+++ b/src/core/string/StdString.cpp
@@ -1,230 +1,165 @@
+// -----------------------------------------------------------------------------
+// std::string and std::string_view
+//
+//   std::string       owns and manages a dynamic array of char (always
+//                     '\0'-terminated, so c_str() works with C APIs)
+//   std::string_view  (C++17) a non-owning view: pointer + length. Cheap to
+//                     pass by value, but must not outlive the viewed text.
+//
+//   - find() returns std::string::npos when nothing is found.
+//   - Short strings are usually stored inside the object without allocating
+//     (Small String Optimization).
+//   - C++20: starts_with / ends_with; std::erase(str, ch).
+//
+// Reference: https://en.cppreference.com/w/cpp/string/basic_string
+// -----------------------------------------------------------------------------
+
 #include <algorithm>
 #include <cctype>
-#include <iomanip>
 #include <sstream>
 #include <string>
+#include <string_view>
+#include <vector>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-void log_string_info(const char* label, const std::string& str) {
-  LOG_S(label << ": \"" << str << "\"" << " | size=" << str.size()
-              << " | empty=" << std::boolalpha << str.empty());
+void logString(std::string_view label, const std::string& text) {
+  LOG_S(label << ": \"" << text << "\" (size " << text.size() << ")");
 }
 
-}  // namespace
-
-namespace create {
-
-void run() {
-  LOG("=== create ===");
-
-  /// @brief Direct initialization with literal
-  std::string s1 = "string 1";
-
-  /// @brief Constructor initialization
-  std::string s2("string 2");
-
-  /// @brief Repeat character constructor
-  std::string s3(5, 's');  // "sssss"
-
-  /// @brief Concatenated string literals (compile-time)
-  std::string s4 =
+void create() {
+  LOG_SECTION("Creating strings");
+  const std::string literal = "string 1";
+  const std::string constructed("string 2");
+  const std::string repeated(5, 's');
+  const std::string joined =
       "First "
-      "Second";
-
-  /// @brief Raw string literal (no escaping needed)
-  std::string s5 = R"(C:\folder\file.txt)";
-
-  log_string_info("s1", s1);
-  log_string_info("s2", s2);
-  log_string_info("s3", s3);
-  log_string_info("s4", s4);
-  log_string_info("s5", s5);
+      "Second";  // adjacent literals are joined at compile time
+  const std::string raw = R"(C:\folder\file.txt)";  // raw literal: no escaping
+  const std::string part(literal, 0, 6);            // substring constructor
+
+  logString("literal    ", literal);
+  logString("constructed", constructed);
+  logString("repeated   ", repeated);
+  logString("joined     ", joined);
+  logString("raw        ", raw);
+  logString("part       ", part);
 }
 
-}  // namespace create
-
-namespace modify {
-
-void run() {
-  LOG("=== modify ===");
-
-  std::string str = "xPhong";
-  log_string_info("init", str);
-
-  /// @brief Append
-  str.append("Nguyen");
-  log_string_info("append", str);
-
-  /// @brief Insert at position
-  str.insert(6, "Vanxx");
-  log_string_info("insert", str);
-
-  /// @brief Erase by position and length
-  str.erase(9, 2);
-  log_string_info("erase", str);
-
-  /// @brief Erase character using remove + erase idiom
-  auto new_end = std::remove(str.begin(), str.end(), 'O');
-  str.erase(new_end, str.end());
-  log_string_info("erase 'O'", str);
-
-  // C++20
-  // std::erase(str, 'O');
-
-  /// @brief Replace sub
-  str.replace(0, 1, "My name is ");
-  log_string_info("replace", str);
-
-  /// @brief Convert to lowercase
-  std::transform(str.begin(), str.end(), str.begin(),
-                 [](unsigned char c) { return std::tolower(c); });
-  log_string_info("tolower", str);
-
-  /// @brief Convert to uppercase
-  std::transform(str.begin(), str.end(), str.begin(),
-                 [](unsigned char c) { return std::toupper(c); });
-  log_string_info("toupper", str);
-
-  /// @brief Trim leading whitespace
-  str = "   Hello World   ";
-  log_string_info("before trim", str);
-
-  str.erase(0, str.find_first_not_of(" \t\n\r"));
-  log_string_info("trim first", str);
-
-  /// @brief Trim trailing whitespace
-  str.erase(str.find_last_not_of(" \t\n\r") + 1);
-  log_string_info("trim last", str);
-}
+void modify() {
+  LOG_SECTION("Modifying");
+  std::string name = "Phong";
+  name.append(" Nguyen");  // "Phong Nguyen"
+  name.insert(6, "Van ");  // "Phong Van Nguyen"
+  logString("append + insert", name);
 
-}  // namespace modify
+  name.erase(6, 4);  // erase(position, count) -> "Phong Nguyen"
+  logString("erase(6, 4)    ", name);
 
-namespace sub {
+  name.replace(0, 5, "Mr.");  // "Mr. Nguyen"
+  logString("replace(0, 5)  ", name);
 
-void run() {
-  LOG("=== sub ===");
+  std::erase(name, '.');  // C++20: remove every '.'
+  logString("std::erase('.')", name);
 
-  std::string str = "PhongNguyen";
-  log_string_info("init", str);
+  std::transform(name.begin(), name.end(), name.begin(), [](unsigned char c) {
+    return static_cast<char>(std::toupper(c));
+  });
+  logString("toupper        ", name);
 
-  /// @brief Extract sub
-  std::string first_name = str.substr(0, 5);
-  log_string_info("substr", first_name);
+  std::string padded = "   Hello World   ";
+  padded.erase(0, padded.find_first_not_of(" \t"));  // trim left
+  padded.erase(padded.find_last_not_of(" \t") + 1);  // trim right
+  logString("trimmed        ", padded);
 }
 
-}  // namespace sub
+void search() {
+  LOG_SECTION("Searching and substrings");
+  const std::string text = "PhongNguyen";
 
-namespace search {
-
-void run() {
-  LOG("=== search ===");
-
-  std::string str = "PhongNguyen";
-  log_string_info("init", str);
-
-  /// @brief Find character
-  size_t pos = str.find('N');
-  if (pos != std::string::npos) {
-    std::string last_name = str.substr(pos);
-
-    LOG_S("find('N')" << " | pos=" << pos << " | result=\"" << last_name
-                      << "\"");
+  if (const std::size_t position = text.find('N');
+      position != std::string::npos) {
+    LOG_S("find('N')        -> " << position << ", substr(" << position
+                                 << ") = \"" << text.substr(position) << "\"");
   }
+  LOG_S("find(\"ong\")      -> " << text.find("ong"));
+  LOG_S("rfind('n')       -> " << text.rfind('n') << " (search from the end)");
+  LOG_S("find('z') == npos -> " << std::boolalpha
+                                << (text.find('z') == std::string::npos));
+  LOG_S("starts_with(\"Phong\") = "
+        << std::boolalpha << text.starts_with("Phong")
+        << ", ends_with(\"yen\") = " << text.ends_with("yen"));
+}
 
-  /// @brief Find sub
-  pos = str.find("ong");
-  if (pos != std::string::npos) {
-    LOG_S("find(\"ong\")" << " | pos=" << pos);
+void compareAndConvert() {
+  LOG_SECTION("Comparing and converting");
+  const std::string a = "apple";
+  const std::string b = "banana";
+  LOG_S(std::boolalpha << "a == \"apple\" " << (a == "apple") << ", a < b "
+                       << (a < b) << ", a.compare(b) = " << a.compare(b));
+
+  LOG_S("std::stoi(\"42\") = "
+        << std::stoi("42") << ", std::stod(\"3.5\") = " << std::stod("3.5")
+        << ", std::to_string(999) = \"" << std::to_string(999) << "\"");
+  try {
+    [[maybe_unused]] const int parsed = std::stoi("not a number");
+  } catch (const std::invalid_argument&) {
+    LOG("std::stoi(\"not a number\") throws std::invalid_argument");
   }
+}
 
-  /// @brief Find last occurrence
-  pos = str.rfind('n');
-  if (pos != std::string::npos) {
-    LOG_S("rfind('n')" << " | pos=" << pos);
+void split() {
+  LOG_SECTION("Splitting on a delimiter");
+  std::istringstream stream("a,b,c");
+  std::vector<std::string> parts;
+  for (std::string item; std::getline(stream, item, ',');) {
+    parts.push_back(item);
   }
+  LOG_S("\"a,b,c\" -> " << parts.size() << " parts: " << parts[0] << " "
+                        << parts[1] << " " << parts[2]);
 }
 
-}  // namespace search
-
-namespace compare {
-
-void run() {
-  LOG("=== compare ===");
-
-  std::string str1 = "PhongNguyen";
-  std::string str2 = "PhongNguyen";
-
-  /// @brief Compare strings
-  int result = str1.compare(str2);
-  LOG_S("compare result = " << result);
-  LOG_S("equal = " << std::boolalpha << (result == 0));
+std::size_t countVowels(
+    std::string_view text) {  // accepts literals and strings without copies
+  return static_cast<std::size_t>(
+      std::count_if(text.begin(), text.end(), [](char c) {
+        return std::string_view("aeiouAEIOU").find(c) != std::string_view::npos;
+      }));
 }
 
-}  // namespace compare
-
-namespace convert {
-
-void run() {
-  LOG("=== convert ===");
-
-  /// @brief String to integer
-  std::string str_int = "3";
-  int ivalue = std::stoi(str_int);
-  LOG_S("stoi(\"3\") = " << ivalue);
-
-  /// @brief String to double
-  std::string str_double = "3.3";
-  double dvalue = std::stod(str_double);
-  LOG_S("stod(\"3.3\") = " << std::setprecision(4) << dvalue);
-
-  /// @brief Number to string
-  int value = 999;
-  std::string str_value = std::to_string(value);
-  log_string_info("to_string", str_value);
+void stringView() {
+  LOG_SECTION("std::string_view");
+  const std::string owned = "Hello, string_view";
+  const std::string_view view = owned;  // no copy
+  std::string_view word =
+      view.substr(0, 5);  // substr of a view is a view, still no copy
+
+  LOG_S("countVowels(owned) = " << countVowels(owned)
+                                << ", countVowels(\"literal\") = "
+                                << countVowels("literal"));
+  LOG_S("view.substr(0, 5) = " << word);
+  word.remove_prefix(1);
+  LOG_S("after remove_prefix(1): "
+        << word << " (the string itself is unchanged: " << owned << ")");
+
+  // Pitfall: std::string_view dangling = std::string("temporary");  // view of a dead string
+  const std::string small = "short";
+  LOG_S("sizeof(std::string) = "
+        << sizeof(std::string) << ", capacity of \"short\" = "
+        << small.capacity() << " (stored inline: SSO)");
 }
 
-}  // namespace convert
-
-namespace parsing {
-
-void run() {
-  LOG("=== parsing ===");
-
-  std::string line = "a,b,c";
-  log_string_info("init", line);
-
-  /// @brief Parse CSV-like string
-  char delimiter = ',';
-  std::stringstream ss(line);
-  std::string item;
+}  // namespace
 
-  LOG_S("Parsing with delimiter ','");
-  while (std::getline(ss, item, delimiter)) {
-    LOG_S("token = " << item);
-  }
+LAB_EXAMPLE("StdString",
+            "std::string create/modify/search/convert, std::string_view") {
+  create();
+  modify();
+  search();
+  compareAndConvert();
+  split();
+  stringView();
 }
-
-}  // namespace parsing
-
-class StdString : public IExample {
- public:
-  std::string group() const override { return "core/string"; }
-  std::string name() const override { return "StdString"; }
-  std::string description() const override { return "StdString Example"; }
-
-  void execute() override {
-    create::run();
-    modify::run();
-    sub::run();
-    search::run();
-    compare::run();
-    convert::run();
-    parsing::run();
-  }
-};
-
-REGISTER_EXAMPLE(StdString);
\ No newline at end of file
diff --git a/src/core/string/StringFormatting.cpp b/src/core/string/StringFormatting.cpp
index e82f132..234fc50 100644
--- a/src/core/string/StringFormatting.cpp
+++ b/src/core/string/StringFormatting.cpp
@@ -1,101 +1,105 @@
+// -----------------------------------------------------------------------------
+// Formatting text: four ways to build "User Phong has 100 points, Pi: 3.14"
+//
+//   1. std::format (C++20)   type-safe, Python-like "{:.2f}" syntax  <- preferred
+//   2. operator+             simple, but std::to_string has fixed precision
+//   3. std::ostringstream    flexible, verbose, sticky manipulators
+//   4. std::snprintf         C style, fast, not type-safe
+//
+// std::format specifiers: {[index]:[fill][align][width][.precision][type]}
+//   {:>8}  right-align in 8 columns     {:*^9}  center, fill with '*'
+//   {:.2f} two decimals                 {:#x}   hex with 0x prefix
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/format/format
+// -----------------------------------------------------------------------------
+
 #include <cstdio>
 #include <format>
 #include <iomanip>
+#include <iterator>
 #include <sstream>
 #include <string>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-void log_formatted(const char* method, const std::string& text) {
-  LOG_S(method << ": \"" << text << "\"" << " | size=" << text.size());
+const std::string kName = "Phong";
+constexpr int kScore = 100;
+constexpr double kPi = 3.14159;
+
+void stdFormat() {
+  LOG_SECTION("1. std::format");
+  LOG(std::format("User {} has {} points, Pi: {:.2f}", kName, kScore, kPi));
+  LOG(std::format("|{:>8}|{:<8}|{:*^9}|", "right", "left", "center"));
+  LOG(std::format("hex {:#x}, binary {:#b}, padded {:05}, sign {:+}", 255, 5,
+                  42, 7));
+  LOG(std::format("positional: {1} before {0}", "second", "first"));
+
+  std::string buffer;
+  std::format_to(std::back_inserter(buffer), "appended {} times",
+                 3);  // no temporary string
+  LOG(buffer);
 }
 
-}  // namespace
-
-namespace std_format {
-
-void run() {
-  LOG("=== std_format ===");
-
-  std::string name{"Phong"};
-  int score = 100;
-
-  /// @brief C++20 std::format
-  std::string str =
-      std::format("User {} has {} points, Pi: {:.2f}", name, score, 3.14159);
-  log_formatted("std::format", str);
+void concatenation() {
+  LOG_SECTION("2. operator+");
+  const std::string text = "User " + kName + " has " + std::to_string(kScore) +
+                           " points, Pi: " + std::to_string(kPi);
+  LOG(text + "   <- to_string always prints 6 decimals");
 }
 
-}  // namespace std_format
-
-namespace concatenation {
-
-void run() {
-  LOG("=== concatenation ===");
-
-  std::string name{"Phong"};
-  int score = 100;
-
-  /// @brief String concatenation using operator+
-  std::string str = "User " + name + " has " + std::to_string(score) +
-                    " points, Pi: " + std::to_string(3.14159);
-  log_formatted("concatenation", str);
+void stream() {
+  LOG_SECTION("3. std::ostringstream");
+  std::ostringstream out;
+  out << "User " << kName << " has " << kScore << " points, Pi: " << std::fixed
+      << std::setprecision(2) << kPi;
+  LOG(out.str());
 }
 
-}  // namespace concatenation
-
-namespace stream {
-
-void run() {
-  LOG("=== stream ===");
-
-  std::string name{"Phong"};
-  int score = 100;
-
-  /// @brief String formatting using stringstream
-  std::stringstream ss;
-  ss << "User " << name << " has " << score << " points, Pi: " << std::fixed
-     << std::setprecision(2) << 3.14159;
-  log_formatted("stringstream", ss.str());
+void cStyle() {
+  LOG_SECTION("4. std::snprintf");
+  char buffer[128];
+  const int written =
+      std::snprintf(buffer, sizeof(buffer), "User %s has %d points, Pi: %.2f",
+                    kName.c_str(), kScore, kPi);
+  LOG_S(buffer << "   (" << written << " characters)");
+  // A wrong specifier such as %d for a double compiles and is undefined behavior.
 }
 
-}  // namespace stream
+struct Point {
+  int x;
+  int y;
+};
 
-namespace c_style {
+}  // namespace
 
-void run() {
-  LOG("=== c_style ===");
+/// Teaching std::format about a custom type.
+template <>
+struct std::formatter<Point> : std::formatter<std::string> {
+  auto format(const Point& point, std::format_context& context) const {
+    return std::formatter<std::string>::format(
+        std::format("({}, {})", point.x, point.y), context);
+  }
+};
 
-  std::string name{"Phong"};
-  int score = 100;
+namespace {
 
-  /// @brief C-style formatting using snprintf
-  char buffer[128];
-  std::snprintf(buffer, sizeof(buffer), "User %s has %d points, Pi: %.2f",
-                name.c_str(), score, 3.14159);
-  log_formatted("snprintf", buffer);
+void customType() {
+  LOG_SECTION("std::formatter for a custom type");
+  const Point point{3, -4};
+  LOG(std::format("point = {}, right-aligned: [{:>10}]", point, point));
 }
 
-}  // namespace c_style
-
-class StringFormatting : public IExample {
- public:
-  std::string group() const override { return "core/string"; }
-  std::string name() const override { return "StringFormatting"; }
-  std::string description() const override {
-    return "String formatting examples "
-           "(std::format, concatenation, stringstream, C-style)";
-  }
-
-  void execute() override {
-    std_format::run();
-    concatenation::run();
-    stream::run();
-    c_style::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(StringFormatting);
\ No newline at end of file
+LAB_EXAMPLE(
+    "StringFormatting",
+    "std::format, concatenation, ostringstream, snprintf, custom formatters") {
+  stdFormat();
+  concatenation();
+  stream();
+  cStyle();
+  customType();
+}
diff --git a/src/core/utils/Algorithm.cpp b/src/core/utils/Algorithm.cpp
index bb5ec4c..d3634eb 100644
--- a/src/core/utils/Algorithm.cpp
+++ b/src/core/utils/Algorithm.cpp
@@ -1,38 +1,147 @@
+// -----------------------------------------------------------------------------
+// Standard algorithms (<algorithm>, <numeric>) and C++20 ranges
+//
+// Prefer a named algorithm over a raw loop: the name states the intent, the
+// implementation is tested, and it is often faster.
+//
+//   searching   find, find_if, any_of, all_of, none_of, count_if
+//   ordering    sort, stable_sort, partition, binary_search, lower_bound
+//   modifying   transform, remove_if + erase (or std::erase_if), unique, fill
+//   numeric     accumulate, reduce, iota, inner_product
+//   ranges      std::ranges::sort(v), v | std::views::filter(...) | ... (C++20)
+//
+// Reference: https://en.cppreference.com/w/cpp/algorithm
+// -----------------------------------------------------------------------------
+
 #include <algorithm>
-#include "ExampleRegistry.h"
-#include "Logger.h"
-
-namespace find_if_example {
-void run() {
-  LOG("std::find_if example");
-  std::vector<int> v{1, 2, 3, 4, 5};
-  auto it = std::find_if(v.begin(), v.end(), [](int i) { return i % 2 == 0; });
-  if (it != v.end()) {
-    LOG("First even number: " + std::to_string(*it));
-  } else {
-    LOG("No even number found");
+#include <numeric>
+#include <ranges>
+#include <string>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+std::string join(const std::vector<int>& values) {
+  std::string text;
+  for (const int value : values) {
+    text += std::to_string(value) + " ";
   }
+  return text;
+}
+
+bool isEven(int value) {
+  return value % 2 == 0;
+}
 
-  LOG("std::find_if_not example");
-  auto it_not =
-      std::find_if_not(v.begin(), v.end(), [](int i) { return i % 2 == 0; });
-  if (it_not != v.end()) {
-    LOG("First odd number: " + std::to_string(*it_not));
-  } else {
-    LOG("No odd number found");
+void searching() {
+  LOG_SECTION("Searching and counting");
+  const std::vector<int> values{1, 3, 4, 7, 8, 11};
+  LOG_S("values: " << join(values));
+
+  if (const auto it = std::find_if(values.begin(), values.end(), isEven);
+      it != values.end()) {
+    LOG_S("find_if(even)     -> " << *it << " at index "
+                                  << it - values.begin());
+  }
+  if (const auto it = std::find_if_not(values.begin(), values.end(),
+                                       [](int v) { return v < 5; });
+      it != values.end()) {
+    LOG_S("find_if_not(< 5)  -> " << *it);
   }
+  LOG_S("count_if(even)    -> "
+        << std::count_if(values.begin(), values.end(), isEven));
+  LOG_S(std::boolalpha << "any_of(> 10) "
+                       << std::any_of(values.begin(), values.end(),
+                                      [](int v) { return v > 10; })
+                       << ", all_of(> 0) "
+                       << std::all_of(values.begin(), values.end(),
+                                      [](int v) { return v > 0; })
+                       << ", none_of(< 0) "
+                       << std::none_of(values.begin(), values.end(),
+                                       [](int v) { return v < 0; }));
 }
-}  // namespace find_if_example
-
-class Algorithm : public IExample {
- public:
-  std::string group() const override { return "core/utils"; }
-  std::string name() const override { return "std::algorithm"; }
-  std::string description() const override {
-    return "The examples for <algorithm> header";
+
+void ordering() {
+  LOG_SECTION("Sorting and searching sorted data");
+  std::vector<int> values{5, 3, 9, 3, 1, 9, 7};
+  std::sort(values.begin(), values.end());
+  LOG_S("sort                 -> " << join(values));
+
+  values.erase(std::unique(values.begin(), values.end()), values.end());
+  LOG_S("unique + erase       -> " << join(values)
+                                   << "(removes adjacent duplicates)");
+
+  LOG_S(std::boolalpha << "binary_search(7)     -> "
+                       << std::binary_search(values.begin(), values.end(), 7));
+  const auto position = std::lower_bound(values.begin(), values.end(), 6);
+  LOG_S("lower_bound(6)       -> " << *position << " (first element >= 6)");
+
+  const auto [smallest, largest] =
+      std::minmax_element(values.begin(), values.end());
+  LOG_S("minmax_element       -> " << *smallest << " and " << *largest);
+
+  std::vector<int> mixed{1, 2, 3, 4, 5, 6};
+  std::partition(mixed.begin(), mixed.end(), isEven);
+  LOG_S("partition(even)      -> " << join(mixed)
+                                   << "(evens first, order not kept)");
+}
+
+void modifyingAndNumeric() {
+  LOG_SECTION("Transforming and numeric algorithms");
+  std::vector<int> values(5);
+  std::iota(values.begin(), values.end(), 1);  // 1 2 3 4 5
+  LOG_S("iota(1)               -> " << join(values));
+
+  std::vector<int> squares(values.size());
+  std::transform(values.begin(), values.end(), squares.begin(),
+                 [](int v) { return v * v; });
+  LOG_S("transform(square)     -> " << join(squares));
+
+  LOG_S("accumulate(+)         -> "
+        << std::accumulate(values.begin(), values.end(), 0));
+  LOG_S("accumulate(*)         -> " << std::accumulate(
+            values.begin(), values.end(), 1, std::multiplies<>{}));
+  LOG_S("inner_product         -> " << std::inner_product(
+            values.begin(), values.end(), squares.begin(), 0));
+
+  std::erase_if(squares, [](int v) {
+    return v > 10;
+  });  // C++20, replaces remove_if + erase
+  LOG_S("erase_if(> 10)        -> " << join(squares));
+}
+
+void ranges() {
+  LOG_SECTION("C++20 ranges and views");
+  std::vector<int> values{8, 3, 5, 1, 9, 2, 6};
+
+  std::ranges::sort(values);  // pass the container, not two iterators
+  LOG_S("ranges::sort          -> " << join(values));
+
+  // Views are lazy: nothing is computed until the loop pulls the elements.
+  auto pipeline = values | std::views::filter(isEven) |
+                  std::views::transform([](int v) { return v * 10; });
+  std::string result;
+  for (const int value : pipeline) {
+    result += std::to_string(value) + " ";
+  }
+  LOG_S("filter(even) | x10    -> " << result);
+
+  std::string first_three;
+  for (const int value : values | std::views::reverse | std::views::take(3)) {
+    first_three += std::to_string(value) + " ";
   }
+  LOG_S("reverse | take(3)     -> " << first_three);
+}
 
-  void execute() override { find_if_example::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Algorithm);
\ No newline at end of file
+LAB_EXAMPLE("Algorithm",
+            "find/count/sort/transform/accumulate and C++20 ranges pipelines") {
+  searching();
+  ordering();
+  modifyingAndNumeric();
+  ranges();
+}
diff --git a/src/core/utils/Optional.cpp b/src/core/utils/Optional.cpp
index 1a15fa9..ece61ac 100644
--- a/src/core/utils/Optional.cpp
+++ b/src/core/utils/Optional.cpp
@@ -1,120 +1,125 @@
-// cppcheck-suppress-file [knownConditionTrueFalse]
-
-#include <exception>
+// -----------------------------------------------------------------------------
+// std::optional (C++17) - a value that may be absent
+//
+// Older ways to say "no value" all have drawbacks:
+//   - magic values (-1, "")   : ambiguous, the caller may forget to check
+//   - nullptr                 : needs somewhere to point, unclear ownership
+//   - exceptions              : heavy for an expected situation
+//   - bool + out parameter    : clumsy call sites
+//
+// std::optional<T> stores the T inline (no allocation) plus a flag.
+//   if (opt) / opt.has_value()   check
+//   *opt / opt->member           access (undefined if empty!)
+//   opt.value()                  access, throws std::bad_optional_access if empty
+//   opt.value_or(fallback)       access with a default
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/optional
+// -----------------------------------------------------------------------------
+
+#include <charconv>
 #include <optional>
 #include <stdexcept>
 #include <string>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-int global = 21;
+// --- the old ways ------------------------------------------------------------
 
-/**
- * @brief ambiguous issue
- * 
- * @param condition 
- * @return int 
- */
-int bad_api_status(bool condition) {
-  return condition ? global : -1;
+/// Returns -1 when the input is invalid... but what if -1 is a valid number?
+int parseWithMagicValue(std::string_view text) {
+  int value = 0;
+  const auto [end, error] =
+      std::from_chars(text.data(), text.data() + text.size(), value);
+  return error == std::errc{} && end == text.data() + text.size() ? value : -1;
 }
 
-int bad_api_throw(bool condition) {
-  if (!condition) {
-    throw std::runtime_error("required value does not exist.");
+/// Throws for invalid input - exceptions for an everyday situation.
+int parseOrThrow(std::string_view text) {
+  const int value = parseWithMagicValue(text);
+  if (value == -1 && text != "-1") {
+    throw std::invalid_argument("not a number: " + std::string(text));
   }
-
-  return 0;
+  return value;
 }
 
-int* bad_api_ptr(bool condition) {
-  return condition ? &global : nullptr;
-}
+// --- the optional way -------------------------------------------------------
 
-std::optional<int> optional_api(bool condition) {
-  if (!condition) {
-    return std::nullopt;
+std::optional<int> parse(std::string_view text) {
+  int value = 0;
+  const auto [end, error] =
+      std::from_chars(text.data(), text.data() + text.size(), value);
+  if (error != std::errc{} || end != text.data() + text.size()) {
+    return std::nullopt;  // clearly "no value"
   }
-  return global;
+  return value;
 }
 
-void run() {
-  LOG("=== std::optional Example ===");
-
-  bool condition = false;
-
-  // Bad patterns
-  {
-    LOG("API (ambiguous):");
-    auto value = bad_api_status(condition);
-    LOG("value = " + std::to_string(value));
-
-    LOG("API (pointer):");
-    if (const auto* ptr = bad_api_ptr(condition)) {
-      LOG("value = " + std::to_string(*ptr));
-    } else {
-      LOG("null pointer");
-    }
+void oldWays() {
+  LOG_SECTION("Before std::optional");
+  LOG_S("parseWithMagicValue(\"42\")  = " << parseWithMagicValue("42"));
+  LOG_S("parseWithMagicValue(\"abc\") = " << parseWithMagicValue("abc")
+                                          << "  <- error?");
+  LOG_S("parseWithMagicValue(\"-1\")  = " << parseWithMagicValue("-1")
+                                          << "  <- or a real -1?");
+  try {
+    parseOrThrow("abc");
+  } catch (const std::invalid_argument& e) {
+    LOG_S("parseOrThrow(\"abc\") threw: " << e.what());
   }
+}
 
-  {
-    LOG("API (thow):");
-    try {
-      auto value = bad_api_throw(condition);
-      LOG("value = " + std::to_string(value));
-    } catch (const std::exception& e) {
-      LOG(std::string("exception: ") + e.what());
+void usingOptional() {
+  LOG_SECTION("With std::optional");
+  for (const std::string_view input : {"42", "-1", "abc"}) {
+    if (const std::optional<int> number = parse(input)) {  // explicit check
+      LOG_S("parse(\"" << input << "\") -> " << *number);
+    } else {
+      LOG_S("parse(\"" << input << "\") -> no value");
     }
   }
-  
-  // Good pattern
-  LOG("API (optional):");
-  auto opt = optional_api(condition);
-
-  // 1. Check explicitly
-  if (opt) {
-    LOG("value = " + std::to_string(*opt));  // preferred over value()
-  } else {
-    LOG("empty");
-  }
-
-  // 2. Provide default
-  int v = opt.value_or(-1);
-  LOG("value_or(-1) = " + std::to_string(v));
 
-  // 3. Early return style (clean pattern)
-  auto process = [](std::optional<int> v) {
-    if (!v) {
-      LOG("no value, exit early");
-      return;
-    }
-    LOG("processing value = " + std::to_string(*v));
-  };
-  process(opt);
-
-  // 4. Dangerous usage
+  const std::optional<int> missing = parse("oops");
+  LOG_S("value_or(0)  -> " << missing.value_or(0));
   try {
-    LOG("Trying value()...");
-    int x = opt.value();  // throws if empty
-    LOG("value = " + std::to_string(x));
-  } catch (const std::exception& e) {
-    LOG(std::string("exception: ") + e.what());
+    LOG_S("value()      -> " << missing.value());
+  } catch (const std::bad_optional_access& e) {
+    LOG_S("value() on an empty optional throws: " << e.what());
   }
+  // *missing would be undefined behavior - always check first.
 }
 
-}  // namespace
+/// Optional parameter with a default of "not provided".
+std::string greet(const std::string& name,
+                  std::optional<std::string> title = std::nullopt) {
+  return "Hello, " + (title ? *title + " " : std::string{}) + name;
+}
 
-class Optional : public IExample {
- public:
-  std::string group() const override { return "core/utils"; }
-  std::string name() const override { return "std::optional"; }
-  std::string description() const override {
-    return "The examples for <optional>";
-  }
+void modifying() {
+  LOG_SECTION("Optional parameters, emplace and reset");
+  LOG(greet("Ada"));
+  LOG(greet("Lovelace", "Countess"));
+
+  std::optional<std::string> cache;
+  LOG_S("has_value() = " << std::boolalpha << cache.has_value());
+  cache.emplace(3, 'z');  // constructs "zzz" in place
+  LOG_S("after emplace(3, 'z'): " << *cache << ", size via -> "
+                                  << cache->size());
+  cache.reset();
+  LOG_S("after reset(): has_value() = " << std::boolalpha << cache.has_value());
+  LOG_S("sizeof(std::optional<int>) = " << sizeof(std::optional<int>)
+                                        << " (int + flag)");
+}
 
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Optional);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Optional",
+    "std::optional instead of magic values, null pointers or exceptions") {
+  oldWays();
+  usingOptional();
+  modifying();
+}
diff --git a/src/core/utils/README.md b/src/core/utils/README.md
index 25e2436..6a2e00c 100644
--- a/src/core/utils/README.md
+++ b/src/core/utils/README.md
@@ -1,3 +1,14 @@
+# Utilities
+
+| Example | Topic |
+|---|---|
+| `Optional` | `std::optional` instead of magic values, null pointers or exceptions |
+| `Algorithm` | `<algorithm>`, `<numeric>` and C++20 ranges/views |
+| `Regex` | `<regex>`: match, search, capture groups, replace |
+| `TypeTraits` | `<type_traits>`, the detection idiom, `enable_if`, C++20 concepts |
+| `Variadic` | C-style `va_list` vs variadic templates and fold expressions |
+
+---
 ## Utilities library
 
 ### 1. `<optional>`
diff --git a/src/core/utils/Regex.cpp b/src/core/utils/Regex.cpp
index 77e5b89..957f5a4 100644
--- a/src/core/utils/Regex.cpp
+++ b/src/core/utils/Regex.cpp
@@ -1,74 +1,100 @@
+// -----------------------------------------------------------------------------
+// Regular expressions (<regex>)
+//
+//   std::regex_match    does the WHOLE string match?     (validation)
+//   std::regex_search   is there a match ANYWHERE?       (searching)
+//   std::smatch         the match and its capture groups  (extraction)
+//   std::sregex_iterator iterate over all matches
+//   std::regex_replace  replace matches ($& whole match, $1 first group)
+//
+// Tips:
+//   - Use raw string literals R"(...)" so backslashes need no escaping.
+//   - Constructing a std::regex is expensive: build it once and reuse it.
+//   - std::regex is known to be slow; fine for learning and small inputs.
+//
+// Reference: https://en.cppreference.com/w/cpp/regex
+// -----------------------------------------------------------------------------
+
 #include <iterator>
 #include <regex>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include <string>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-void run() {
-  const std::string text =
-      "This is my string. "
-      "I'll use regular expression. "
-      "Now I have two problems.";
-  LOG("String: " + text);
 
-  // Case-insensitive search
-  // Match any part
-  const std::regex regex_search_exp(R"(regular expression)",
-                                    std::regex_constants::icase);
+const std::string kText =
+    "This is my string. I'll use regular expressions. Now I have two problems.";
 
-  if (std::regex_search(text, regex_search_exp)) {
-    LOG("\tString contains 'regular expression'");
-  }
+void searching() {
+  LOG_SECTION("regex_search: find a match anywhere");
+  LOG_S("text: " << kText);
+  const std::regex phrase(R"(regular expression)", std::regex::icase);
+  LOG_S("contains 'REGULAR EXPRESSION' (ignoring case): "
+        << std::boolalpha << std::regex_search(kText, phrase));
+}
 
-  // Phone validation
-  // Match entire
-  const std::string phone = "+84336821417";
-  const std::regex phone_regex(R"(^[+](?:[0-9\-\(\)/\.]\s?){6,15}[0-9]$)");
-  if (!std::regex_match(phone, phone_regex)) {
-    throw std::invalid_argument(
-        "Invalid phone number format. "
-        "Try including the country code.");
+void validation() {
+  LOG_SECTION("regex_match: validate the whole string");
+  const std::regex phone(
+      R"(^\+[0-9]{8,15}$)");  // '+' followed by 8 to 15 digits
+  for (const std::string candidate :
+       {"+84336821417", "0336821417", "+84 33 682"}) {
+    LOG_S(candidate << " -> "
+                    << (std::regex_match(candidate, phone) ? "valid"
+                                                           : "invalid"));
   }
+}
 
-  // Word matching
-  LOG("Find words: ");
-  const std::regex word_regex(R"((\w+))");
-  auto words_begin = std::sregex_iterator(
-      text.begin(), text.end(),
-      word_regex);  // iterator over regex matches in a string
-  auto words_end = std::sregex_iterator();
+void captureGroups() {
+  LOG_SECTION("Capture groups with std::smatch");
+  const std::regex iso_date(R"((\d{4})-(\d{2})-(\d{2}))");
+  const std::string log_line = "backup finished on 2026-09-11 at 23:00";
 
-  LOG_S("\tFound " << std::distance(words_begin, words_end) << " words");
+  std::smatch match;
+  if (std::regex_search(log_line, match, iso_date)) {
+    LOG_S("whole match: " << match[0] << " at position " << match.position(0));
+    LOG_S("year = " << match[1] << ", month = " << match[2]
+                    << ", day = " << match[3]);
+  }
+}
 
-  LOG("Find words longer than 5 chars: ");
-  for (auto it = std::sregex_iterator(text.begin(), text.end(), word_regex);
-       it != words_end; ++it) {
-    const std::string word = it->str();
+void iterating() {
+  LOG_SECTION("Iterating over all matches");
+  const std::regex word(R"(\w+)");
+  const auto begin = std::sregex_iterator(kText.begin(), kText.end(), word);
+  const auto end = std::sregex_iterator();
+  LOG_S("found " << std::distance(begin, end) << " words");
 
-    if (word.size() > 5) {
-      LOG("\t" + word);
+  std::string long_words;
+  for (auto it = begin; it != end; ++it) {
+    if (it->str().size() > 5) {
+      long_words += it->str() + " ";
     }
   }
+  LOG_S("words longer than 5 characters: " << long_words);
+}
 
-  // Replace long words
-  LOG("Replace \"long_words\" to : \"[long_words]\"");
-  const std::regex long_word_regex(R"((\w{5,}))");
-  const std::string highlighted =
-      std::regex_replace(text, long_word_regex, "[$&]");  // "$&": entire match
+void replacing() {
+  LOG_SECTION("regex_replace");
+  const std::regex long_word(R"(\w{6,})");
+  LOG_S("[$&] around long words: " << std::regex_replace(kText, long_word,
+                                                         "[$&]"));
 
-  LOG("\t" + highlighted);
+  const std::regex date(R"((\d{4})-(\d{2})-(\d{2}))");
+  LOG_S("2026-09-11 reordered with $3/$2/$1: " << std::regex_replace(
+            std::string("2026-09-11"), date, "$3/$2/$1"));
 }
-}  // namespace
-
-class Regex : public IExample {
- public:
-  std::string group() const override { return "core/utils"; }
-  std::string name() const override { return "Regex"; }
-  std::string description() const override {
-    return "The examples for regular expression <regex>";
-  }
 
-  void execute() override { run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(Regex);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Regex",
+    "regex_match, regex_search, capture groups, iterators and regex_replace") {
+  searching();
+  validation();
+  captureGroups();
+  iterating();
+  replacing();
+}
diff --git a/src/core/utils/TypeTrait.cpp b/src/core/utils/TypeTrait.cpp
deleted file mode 100644
index 77e5f8d..0000000
--- a/src/core/utils/TypeTrait.cpp
+++ /dev/null
@@ -1,119 +0,0 @@
-#include <memory>
-#include <string>
-#include <type_traits>
-#include <typeinfo>
-
-#ifdef __GNUG__
-#include <cxxabi.h>
-#endif
-
-#include <sstream>
-#include "ExampleRegistry.h"
-#include "Logger.h"
-
-namespace type_trait {
-
-// Utility: readable type name
-template <typename T>
-std::string type_name() {
-#ifdef __GNUG__
-  int status = 0;
-  std::unique_ptr<char, void (*)(void*)> demangled(
-      abi::__cxa_demangle(typeid(T).name(), nullptr, nullptr, &status),
-      std::free);
-  return (status == 0 && demangled) ? demangled.get() : typeid(T).name();
-#else
-  return typeid(T).name();
-#endif
-}
-
-// Trait: has operator &=
-template <typename T, typename = void>
-struct HaveAndAssign : std::false_type {};
-
-template <typename T>
-struct HaveAndAssign<
-    T, std::void_t<decltype(std::declval<T&>() &= std::declval<T>())>>
-    : std::true_type {};
-
-// Trait: has operator !
-template <typename T, typename = void>
-struct HaveNot : std::false_type {};
-
-template <typename T>
-struct HaveNot<T, std::void_t<decltype(!std::declval<T&>())>> : std::true_type {
-};
-
-// Example class WITH &=
-template <typename T>
-class A {
- public:
-  A& operator&=(const A&) { return *this; }
-};
-
-// Example class WITHOUT &=
-template <typename T>
-class B {};
-
-// Constrained class
-template <typename T, std::enable_if_t<HaveAndAssign<T>::value, int> = 0>
-class C {
- public:
-  C() {
-    std::ostringstream oss;
-    oss << "C<" << type_name<T>() << "> instantiated";
-    LOG(oss.str());
-  }
-};
-
-// Debug printer
-template <typename T>
-void printTypeInfo() {
-  std::ostringstream oss;
-  oss << "==== Type Info ====\n"
-      << "Type: " << type_name<T>() << '\n'
-      << "is_bool: " << std::is_same_v<T, bool> << '\n'
-      << "HaveAndAssign: " << HaveAndAssign<T>::value << '\n'
-      << "HaveNot (!): " << HaveNot<T>::value;
-  LOG(oss.str());
-  LOG("===================");
-}
-
-void run() {
-  LOG("===== Type Traits Examples =====");
-
-  printTypeInfo<bool>();
-  printTypeInfo<B<bool>>();
-  printTypeInfo<A<bool>>();
-
-  if constexpr (HaveAndAssign<A<bool>>::value) {
-    LOG("A<bool> supports &=");
-    C<A<bool>> c_instance;
-  } else {
-    LOG("B<bool> does NOT support &=");
-  }
-
-  if constexpr (HaveAndAssign<B<bool>>::value) {
-    LOG("B<bool> supports &=");
-  } else {
-    LOG("B<bool> does NOT support &=");
-  }
-  LOG("================================");
-}
-
-}  // namespace type_trait
-
-class TypeTrait : public IExample {
- public:
-  std::string group() const override { return "core/utils"; }
-
-  std::string name() const override { return "std::type_traits"; }
-
-  std::string description() const override {
-    return "Examples for <type_traits> with improved logging and SFINAE checks";
-  }
-
-  void execute() override { type_trait::run(); }
-};
-
-REGISTER_EXAMPLE(TypeTrait);
\ No newline at end of file
diff --git a/src/core/utils/TypeTraits.cpp b/src/core/utils/TypeTraits.cpp
new file mode 100644
index 0000000..8dd73fc
--- /dev/null
+++ b/src/core/utils/TypeTraits.cpp
@@ -0,0 +1,157 @@
+// -----------------------------------------------------------------------------
+// Type traits (<type_traits>), SFINAE and C++20 concepts
+//
+// Type traits answer questions about types at compile time:
+//   std::is_integral_v<T>, std::is_same_v<A, B>, std::is_pointer_v<T>, ...
+// and transform types:
+//   std::remove_const_t<T>, std::decay_t<T>, std::conditional_t<cond, A, B>
+//
+// Constraining templates:
+//   - C++11/17: SFINAE with std::enable_if_t and the "detection idiom"
+//     (std::void_t) - powerful but hard to read.
+//   - C++20: concepts and requires clauses say the same thing clearly and give
+//     far better error messages.
+//
+// Reference: https://en.cppreference.com/w/cpp/header/type_traits
+// -----------------------------------------------------------------------------
+
+#include <concepts>
+#include <cstdlib>
+#include <memory>
+#include <string>
+#include <type_traits>
+#include <typeinfo>
+#include <utility>
+#include <vector>
+
+#ifdef __GNUG__
+#include <cxxabi.h>
+#endif
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+/// Human-readable type name (typeid(T).name() is mangled on GCC/Clang).
+template <typename T>
+std::string typeName() {
+#ifdef __GNUG__
+  int status = 0;
+  const std::unique_ptr<char, void (*)(void*)> demangled(
+      abi::__cxa_demangle(typeid(T).name(), nullptr, nullptr, &status),
+      std::free);
+  return status == 0 && demangled ? demangled.get() : typeid(T).name();
+#else
+  return typeid(T).name();
+#endif
+}
+
+void standardTraits() {
+  LOG_SECTION("Querying and transforming types");
+  LOG_S(std::boolalpha << "is_integral_v<int>          = "
+                       << std::is_integral_v<int>);
+  LOG_S(std::boolalpha << "is_floating_point_v<float>  = "
+                       << std::is_floating_point_v<float>);
+  LOG_S(std::boolalpha << "is_pointer_v<int*>          = "
+                       << std::is_pointer_v<int*>);
+  LOG_S(std::boolalpha << "is_same_v<int, const int>   = "
+                       << std::is_same_v<int, const int>);
+  LOG_S("remove_const_t<const int>   = "
+        << typeName<std::remove_const_t<const int>>());
+  LOG_S(
+      "decay_t<const int&>         = " << typeName<std::decay_t<const int&>>());
+  LOG_S("decay_t<int[3]>             = " << typeName<std::decay_t<int[3]>>());
+  LOG_S("conditional_t<true, A, B>   = "
+        << typeName<std::conditional_t<true, long, short>>());
+
+  static_assert(std::is_trivially_copyable_v<int>, "checked at compile time");
+}
+
+// --- detection idiom (pre-C++20) --------------------------------------------
+
+/// HasAndAssign<T>::value is true if `t &= t` compiles.
+template <typename T, typename = void>
+struct HasAndAssign : std::false_type {};
+
+template <typename T>
+struct HasAndAssign<
+    T, std::void_t<decltype(std::declval<T&>() &= std::declval<T>())>>
+    : std::true_type {};
+
+struct WithAndAssign {
+  WithAndAssign& operator&=(const WithAndAssign&) { return *this; }
+};
+
+struct WithoutAndAssign {};
+
+/// SFINAE: this overload only exists for integral types.
+template <typename T, std::enable_if_t<std::is_integral_v<T>, int> = 0>
+std::string describeSfinae(T value) {
+  return "integral " + std::to_string(value);
+}
+
+template <typename T, std::enable_if_t<std::is_floating_point_v<T>, int> = 0>
+std::string describeSfinae(T value) {
+  return "floating point " + std::to_string(value);
+}
+
+void sfinae() {
+  LOG_SECTION("Detection idiom and std::enable_if (C++11/17)");
+  LOG_S(std::boolalpha << "HasAndAssign<int>              = "
+                       << HasAndAssign<int>::value);
+  LOG_S(std::boolalpha << "HasAndAssign<WithAndAssign>    = "
+                       << HasAndAssign<WithAndAssign>::value);
+  LOG_S(std::boolalpha << "HasAndAssign<WithoutAndAssign> = "
+                       << HasAndAssign<WithoutAndAssign>::value);
+  LOG_S("describeSfinae(42)  -> " << describeSfinae(42));
+  LOG_S("describeSfinae(2.5) -> " << describeSfinae(2.5));
+  // describeSfinae("text");  // error: no matching function (hard-to-read message)
+}
+
+// --- concepts (C++20) --------------------------------------------------------
+
+template <typename T>
+concept AndAssignable = requires(T& a, const T& b) {
+  { a &= b } -> std::same_as<T&>;
+};
+
+template <std::integral T>
+std::string describeConcept(T value) {
+  return "integral " + std::to_string(value);
+}
+
+template <std::floating_point T>
+std::string describeConcept(T value) {
+  return "floating point " + std::to_string(value);
+}
+
+template <typename Container>
+  requires requires(const Container& c) { c.size(); }
+std::size_t countElements(const Container& container) {
+  return container.size();
+}
+
+void concepts() {
+  LOG_SECTION("The same with C++20 concepts");
+  LOG_S(std::boolalpha << "AndAssignable<int>              = "
+                       << AndAssignable<int>);
+  LOG_S(std::boolalpha << "AndAssignable<WithAndAssign>    = "
+                       << AndAssignable<WithAndAssign>);
+  LOG_S(std::boolalpha << "AndAssignable<WithoutAndAssign> = "
+                       << AndAssignable<WithoutAndAssign>);
+  LOG_S("describeConcept(42)  -> " << describeConcept(42));
+  LOG_S("describeConcept(2.5) -> " << describeConcept(2.5));
+  LOG_S("countElements(vector{1, 2, 3}) -> "
+        << countElements(std::vector<int>{1, 2, 3}));
+  // countElements(42);  // error: "the required expression 'c.size()' is invalid"
+}
+
+}  // namespace
+
+LAB_EXAMPLE("TypeTraits",
+            "type traits, detection idiom, enable_if and C++20 concepts") {
+  standardTraits();
+  sfinae();
+  concepts();
+}
diff --git a/src/core/utils/Variadic.cpp b/src/core/utils/Variadic.cpp
index 3f02483..b2c3996 100644
--- a/src/core/utils/Variadic.cpp
+++ b/src/core/utils/Variadic.cpp
@@ -1,114 +1,126 @@
-#include <cstdarg>  // va_list, va_start, va_arg, va_end
+// -----------------------------------------------------------------------------
+// Variadic functions: C-style `...` vs variadic templates
+//
+// C style (<cstdarg>):   void log(const char* format, ...);
+//   va_list args; va_start(args, format); va_arg(args, int); va_end(args);
+//   - No type safety: the format must match the arguments exactly.
+//   - Default promotions apply: char/short -> int, float -> double.
+//
+// C++ variadic templates:  template <typename... Args> void log(Args&&... args);
+//   - Fully type-safe, resolved at compile time.
+//   - sizeof...(Args) counts the arguments.
+//   - C++17 fold expressions (args + ...) replace most recursion.
+//   - std::forward<Args>(args)... passes arguments on unchanged.
+//
+// Reference: https://en.cppreference.com/w/cpp/language/variadic_arguments
+//            https://en.cppreference.com/w/cpp/language/pack
+// -----------------------------------------------------------------------------
+
+#include <cstdarg>
+#include <memory>
+#include <sstream>
 #include <string>
+#include <utility>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-namespace c_variadic_style {
+namespace {
 
-/// @brief Simple C-style variadic function
-/// The format string controls how arguments are read:
-///   d -> int
-///   c -> char
-///   f -> double
-void simple_printf(const char* fmt, ...) {
-  // Holds all unnamed arguments
-  va_list args;
-
-  va_start(args, fmt);  // reading the unnamed arguments that come after fmt
-
-  // Parse format string character by character
-  while (*fmt != '\0') {
-    if (*fmt == 'd') {
-      // Read next argument as int
-      int value = va_arg(args, int);
-      LOG(std::to_string(value));
+namespace c_style {
 
-    } else if (*fmt == 'c') {
-      // char is promoted to int in variadic functions
-      int value = va_arg(args, int);
-      LOG(std::string(1, static_cast<char>(value)));
-
-    } else if (*fmt == 'f') {
-      // float is promoted to double
-      double value = va_arg(args, double);
-      LOG(std::to_string(value));
+/// Reads one argument per format character: d = int, c = char, f = double.
+std::string format(const char* spec, ...) {
+  std::ostringstream out;
+  va_list args;
+  va_start(args, spec);  // start reading after the last named parameter
+  for (; *spec != '\0'; ++spec) {
+    switch (*spec) {
+      case 'd':
+        out << va_arg(args, int) << ' ';
+        break;
+      case 'c':
+        out << static_cast<char>(va_arg(args, int))
+            << ' ';  // char was promoted to int
+        break;
+      case 'f':
+        out << va_arg(args, double) << ' ';  // float was promoted to double
+        break;
+      default:
+        out << "<unknown '" << *spec << "'> ";
+        break;
     }
-
-    ++fmt;
   }
-
-  // Cleanup
-  va_end(args);
+  va_end(args);  // always pair va_start with va_end
+  return out.str();
 }
 
 void run() {
-  LOG("C-Style Variadic Example");
-
-  simple_printf("dcff", 3, 'a', 1.999, 42.5);
+  LOG_SECTION("C-style variadic function");
+  LOG_S("format(\"dcff\", 3, 'a', 1.999, 42.5) -> "
+        << format("dcff", 3, 'a', 1.999, 42.5));
+  // format("d", 1.5) compiles too but reads garbage: undefined behavior.
 }
 
-}  // namespace c_variadic_style
+}  // namespace c_style
 
-namespace modern_variadic_style {
+namespace templates {
 
-/// @brief Base case for recursion
-inline void simple_printf(const char* /*fmt*/) {}
+// Recursion (C++11 style): one base case plus one step.
+void printRecursive(std::ostringstream& /*out*/) {}
 
-/// @brief Print one argument based on format specifier
-template <typename T>
-void print_arg(char fmt, const T& value) {
-  switch (fmt) {
-    case 'd':
-      LOG(std::to_string(static_cast<int>(value)));
-      break;
+template <typename First, typename... Rest>
+void printRecursive(std::ostringstream& out, const First& first,
+                    const Rest&... rest) {
+  out << first << ' ';
+  printRecursive(out, rest...);  // expands the remaining arguments
+}
 
-    case 'c':
-      LOG(std::string(1, static_cast<char>(value)));
-      break;
+// Fold expressions (C++17): no recursion needed.
+template <typename... Numbers>
+auto sum(const Numbers&... numbers) {
+  return (numbers + ... + 0);  // ((n1 + (n2 + (n3 + 0))))
+}
 
-    case 'f':
-      LOG(std::to_string(static_cast<double>(value)));
-      break;
+template <typename... Args>
+std::string joinAll(const Args&... args) {
+  std::ostringstream out;
+  ((out << args << ' '), ...);  // comma fold: stream every argument
+  return out.str();
+}
 
-    default:
-      throw std::runtime_error("Unknown format specifier");
-  }
+template <typename... Args>
+std::size_t count(const Args&... /*args*/) {
+  return sizeof...(Args);
 }
 
-/// @brief Recursive variadic template implementation
+/// Perfect forwarding: build any T from any arguments, like std::make_unique.
 template <typename T, typename... Args>
-void simple_printf(const char* fmt, T value, Args... args) {
-  if (*fmt == '\0') {
-    return;
-  }
-
-  print_arg(*fmt, value);
-
-  // Move to next format character
-  simple_printf(fmt + 1, args...);
+std::unique_ptr<T> create(Args&&... args) {
+  return std::unique_ptr<T>(new T(std::forward<Args>(args)...));
 }
 
 void run() {
-  LOG("Modern Variadic Example");
-
-  simple_printf("dcff", 3, 'a', 1.999, 42.5);
+  LOG_SECTION("Variadic templates");
+  std::ostringstream out;
+  printRecursive(out, 3, 'a', 1.999, "text", std::string("string"));
+  LOG_S("printRecursive -> " << out.str());
+  LOG_S("sum(1, 2, 3.5)  -> " << sum(1, 2, 3.5));
+  LOG_S("joinAll(...)    -> " << joinAll("pi is", 3.14, '!', 42));
+  LOG_S("count(1, \"two\", 3.0) -> " << count(1, "two", 3.0));
+
+  const auto text =
+      create<std::string>(5, '*');  // forwards (5, '*') to std::string
+  LOG_S("create<std::string>(5, '*') -> " << *text);
 }
 
-}  // namespace modern_variadic_style
+}  // namespace templates
 
-class Variadic : public IExample {
- public:
-  std::string group() const override { return "core/utils"; }
-  std::string name() const override { return "Variadic"; }
-  std::string description() const override {
-    return "Examples for C-style variadic arguments";
-  }
+}  // namespace
 
-  void execute() override {
-    c_variadic_style::run();
-    modern_variadic_style::run();
-  }
-};
-
-REGISTER_EXAMPLE(Variadic);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Variadic",
+    "C-style va_list vs variadic templates, fold expressions, forwarding") {
+  c_style::run();
+  templates::run();
+}
diff --git a/src/demo/dlopen/CMakeLists.txt b/src/demo/dlopen/CMakeLists.txt
index d3550ba..b9e2435 100644
--- a/src/demo/dlopen/CMakeLists.txt
+++ b/src/demo/dlopen/CMakeLists.txt
@@ -1,16 +1,21 @@
-# bridge shared lib
-add_library(bridge SHARED
-    bridge.cpp
-)
+# bridge: SHARED library used by both the host and the plugin, so the whole process shares
+# one bridge singleton (see README.md for what breaks when it is STATIC).
+add_library(bridge SHARED bridge.cpp)
+target_include_directories(bridge PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(bridge PRIVATE cpplab::options Threads::Threads)
 
-# shared lib
-add_library(sample_app SHARED
-    sample_app.cpp
-)
-target_link_libraries(sample_app PRIVATE bridge)
+# sample_app: the "plugin", a shared library that is only loaded at run time with dlopen().
+add_library(sample_app SHARED sample_app.cpp)
+target_link_libraries(sample_app PRIVATE bridge cpplab::options)
 
-# executable demo
-add_executable(demo_dlopen
-    main.cpp
-)
-target_link_libraries(demo_dlopen PRIVATE bridge sample_app)
\ No newline at end of file
+# demo_dlopen: the host executable. It links the bridge but NOT the plugin. The plugin path
+# is compiled in, so the demo works from any working directory.
+add_executable(demo_dlopen main.cpp)
+target_link_libraries(demo_dlopen PRIVATE bridge cpplab::options Threads::Threads ${CMAKE_DL_LIBS})
+target_compile_definitions(demo_dlopen PRIVATE SAMPLE_APP_PATH="$<TARGET_FILE:sample_app>")
+add_dependencies(demo_dlopen sample_app)
+
+if(CPPLAB_BUILD_TESTS)
+    add_test(NAME demo:dlopen COMMAND demo_dlopen)
+    set_tests_properties(demo:dlopen PROPERTIES LABELS "demo" TIMEOUT 30)
+endif()
diff --git a/src/demo/dlopen/README.md b/src/demo/dlopen/README.md
index bf13be4..1ab9f90 100644
--- a/src/demo/dlopen/README.md
+++ b/src/demo/dlopen/README.md
@@ -1,43 +1,62 @@
-# dlopen demo
+# dlopen plugin demo
 
-Minimal demo of the **host process + `dlopen` plugin + shared-lib bridge** pattern
+A minimal **host process + `dlopen` plugin + shared-library bridge** setup, the pattern behind
+plugin systems: the host does not know the plugin at link time and loads it at run time.
 
 ## Layout
 
 ```text
-dlopen_plugin_demo/
+src/demo/dlopen/
 ├── CMakeLists.txt
-├── bridge.h/.cpp    # shared bridge API + singleton
-├── sample_app       # SHARED lib with main()
-├── main.cpp         # executable that dlopen + dlsym(main)
+├── bridge.h / bridge.cpp   # SHARED library: API + one singleton for the whole process
+├── sample_app.cpp          # the "plugin": a SHARED library that contains main()
+├── main.cpp                # the host: dlopen + dlsym("main")
 └── README.md
 ```
 
----
-**Expected flow:**
-1. `demo_dlopen` loads `libsample_app.so`
-2. finds symbol `main` via `dlsym`
-3. background thread marks bridge ready
-4. plugin waits, then write/read a fake register through `libbridge.so`
-5. both sides share **one** bridge singleton (because bridge is **SHARED**)
+## Run it
+
+```bash
+cmake --build build && ./build/bin/demo_dlopen
+ctest --test-dir build -R demo:dlopen        # the same as a test
+```
+
+The plugin path is compiled into the host (`SAMPLE_APP_PATH`, set by CMake), so the demo works
+from any working directory. Pass another path as the first argument to load a different plugin.
+
+**Expected flow**
+
+1. `demo_dlopen` loads `libsample_app.so` with `dlopen`
+2. it looks up the symbol `main` with `dlsym` (C++ never mangles the name `main`)
+3. a background thread writes a register through the bridge and marks it ready
+4. the plugin waits for that signal, then writes and reads a fake register
+5. both sides use **one** bridge singleton, because `bridge` is a SHARED library
 
 ```text
-demo:     host  --dlopen-->  libsample_app.so  --calls-->  libbridge.so
+host  --dlopen-->  libsample_app.so  --calls-->  libbridge.so
+  |                                                  ^
+  +--------------------------------------------------+
+                  same singleton
 ```
 
-## Why bridge must be SHARED
+## Why the bridge must be SHARED
 
-If `bridge` were STATIC, `host` and `libsample_app.so` would each get a private singleton -> `bridge_wait_ready()` would hang forever (plugin never sees host’s `ready` flag).
+If `bridge` were a STATIC library, the host and the plugin would each get their own copy of the
+singleton. `bridge_wait_ready()` in the plugin would then never see the host's `ready` flag and
+would block forever.
 
-Try the broken variant (optional experiment):
+Try the broken variant:
 
 ```cmake
 # in CMakeLists.txt, change:
 add_library(bridge STATIC bridge.cpp)
 ```
 
-Rebuild & run => plugin will block on `bridge_wait_ready()`.
+Rebuild and run: the plugin hangs in `bridge_wait_ready()` (stop it with Ctrl+C).
+
+## Things worth knowing
 
-----
-EOF
-----
\ No newline at end of file
+- `dlopen` flags: `RTLD_LAZY` resolves symbols on first use (`RTLD_NOW` resolves everything at
+  load time), `RTLD_GLOBAL` makes the plugin's symbols visible to libraries loaded later.
+- `dlerror()` must be cleared before `dlsym`, because `dlsym` may legitimately return `nullptr`.
+- The handle is closed by a `std::unique_ptr` with a custom deleter - RAII also works for C APIs.
diff --git a/src/demo/dlopen/main.cpp b/src/demo/dlopen/main.cpp
index 722bce0..61c55e7 100644
--- a/src/demo/dlopen/main.cpp
+++ b/src/demo/dlopen/main.cpp
@@ -1,38 +1,65 @@
-#include "bridge.h"
+// Host program of the dlopen demo (see README.md in this folder).
+//
+//   1. dlopen()  loads libsample_app.so at run time
+//   2. dlsym()   looks up the symbol "main" inside it
+//   3. a background thread initializes the shared bridge and marks it ready
+//   4. the plugin's main() runs and talks to the host through libbridge.so
 
 #include <dlfcn.h>
 
 #include <chrono>
 #include <iostream>
+#include <memory>
 #include <thread>
 
-using app_main_t = int (*)(int, char**);
+#include "bridge.h"
 
-int main(int argc, char* argv[]) {
-  const char* plugin_path = "./libsample_app.so";
-  if (argc > 1) {
-    plugin_path = argv[1];
+// CMake passes the absolute path of the plugin; the fallback expects it in the
+// current working directory.
+#ifndef SAMPLE_APP_PATH
+#define SAMPLE_APP_PATH "./libsample_app.so"
+#endif
+
+namespace {
+
+using AppMain = int (*)(int, char**);
+
+/// Closes a dlopen() handle automatically (RAII for a C resource).
+struct LibraryCloser {
+  void operator()(void* handle) const {
+    if (handle != nullptr) {
+      dlclose(handle);
+    }
   }
+};
+
+}  // namespace
+
+int main(int argc, char* argv[]) {
+  const char* plugin_path = argc > 1 ? argv[1] : SAMPLE_APP_PATH;
 
   std::cout << "[host] starting (bridge=" << bridge_name() << ")\n";
   std::cout << "[host] dlopen: " << plugin_path << "\n";
 
-  void* handle = dlopen(plugin_path, RTLD_LAZY | RTLD_GLOBAL);
-  if (!handle) {
+  // RTLD_LAZY  : resolve function symbols on first use
+  // RTLD_GLOBAL: make the plugin's symbols available to libraries loaded later
+  const std::unique_ptr<void, LibraryCloser> library(
+      dlopen(plugin_path, RTLD_LAZY | RTLD_GLOBAL));
+  if (!library) {
     std::cerr << "[host] dlopen failed: " << dlerror() << "\n";
     return 1;
   }
 
-  dlerror();  // clear
-  auto* app_main = reinterpret_cast<app_main_t>(dlsym(handle, "main"));
-  const char* err = dlerror();
-  if (err != nullptr || app_main == nullptr) {
-    std::cerr << "[host] dlsym(main) failed: " << (err ? err : "null") << "\n";
-    dlclose(handle);
+  dlerror();  // clear any old error: dlsym may legitimately return nullptr
+  // dlsym returns void*; converting it to a function pointer is allowed on POSIX.
+  const auto app_main = reinterpret_cast<AppMain>(dlsym(library.get(), "main"));
+  if (const char* error = dlerror(); error != nullptr || app_main == nullptr) {
+    std::cerr << "[host] dlsym(main) failed: "
+              << (error != nullptr ? error : "null") << "\n";
     return 1;
   }
 
-  // init on another thread, then notify plugin
+  // Initialize on another thread, then notify the plugin through the bridge.
   std::thread init_thread([] {
     std::this_thread::sleep_for(std::chrono::milliseconds(200));
     bridge_write_reg(0x0000, 0x1U);  // fake "device present"
@@ -42,14 +69,13 @@ int main(int argc, char* argv[]) {
   char arg0[] = "sample_app";
   char arg1[] = "hello";
   char* app_argv[] = {arg0, arg1, nullptr};
-  const int app_argc = 2;
+  constexpr int kAppArgc = 2;
 
   std::cout << "[host] calling plugin main()\n";
-  const int rc = app_main(app_argc, app_argv);
+  const int rc = app_main(kAppArgc, app_argv);
   std::cout << "[host] plugin returned " << rc << "\n";
 
   init_thread.join();
-  dlclose(handle);
   std::cout << "[host] done\n";
   return rc;
-}
\ No newline at end of file
+}  // `library` is closed here, after the plugin has finished
diff --git a/src/demo/dlopen/sample_app.cpp b/src/demo/dlopen/sample_app.cpp
index 36e27fd..32f488a 100644
--- a/src/demo/dlopen/sample_app.cpp
+++ b/src/demo/dlopen/sample_app.cpp
@@ -1,22 +1,28 @@
-#include "bridge.h"
+// The "plugin": a shared library that contains its own main().
+//
+// It is never started as a process. The host loads it with dlopen() and calls
+// main() through a function pointer. The C++ compiler never mangles the name
+// `main`, so dlsym(handle, "main") can find it.
 
 #include <cstdint>
 #include <iostream>
 
-extern "C" int main(const int argc, const char* argv[]) {
+#include "bridge.h"
+
+int main(int argc, char* argv[]) {
   std::cout << "[plugin] main() started (argc=" << argc << ")\n";
   for (int i = 0; i < argc; ++i) {
     std::cout << "[plugin]   argv[" << i << "] = " << argv[i] << "\n";
   }
 
   std::cout << "[plugin] waiting for host via " << bridge_name() << "...\n";
-  bridge_wait_ready();
+  bridge_wait_ready();  // blocks until the host thread calls bridge_set_ready()
 
   bridge_write_reg(0x1000, 0xA5A5A5A5U);
-  const std::uint32_t v = bridge_read_reg(0x1000);
-  std::cout << "[plugin] round-trip value = 0x" << std::hex << v << std::dec
+  const std::uint32_t value = bridge_read_reg(0x1000);
+  std::cout << "[plugin] round-trip value = 0x" << std::hex << value << std::dec
             << "\n";
 
   std::cout << "[plugin] main() done\n";
   return 0;
-}
\ No newline at end of file
+}
diff --git a/src/dp/CMakeLists.txt b/src/dp/CMakeLists.txt
deleted file mode 100644
index d8a6b1d..0000000
--- a/src/dp/CMakeLists.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-set(DP_SOURCES
-
-    # Structural Patterns
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Adapter.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Bridge.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Proxy.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Composite.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Flyweight.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Facade.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/structural/Decorator.cpp
-
-    # Behavioral Patterns
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/ChainOfCommand.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Command.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Iterator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Mediator.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Memento.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Visitor.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/TemplateMethod.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Strategy.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/State.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/behavioral/Observer.cpp
-
-    # Creational Patterns
-    ${CMAKE_CURRENT_SOURCE_DIR}/creational/Singleton.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/creational/FactoryMethod.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/creational/AbstractFactory.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/creational/Builder.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/creational/Prototype.cpp
-)
-
-set(DP_SOURCES ${DP_SOURCES} PARENT_SCOPE)
\ No newline at end of file
diff --git a/src/dp/behavioral/ChainOfCommand.cpp b/src/dp/behavioral/ChainOfCommand.cpp
deleted file mode 100644
index 224a97c..0000000
--- a/src/dp/behavioral/ChainOfCommand.cpp
+++ /dev/null
@@ -1,147 +0,0 @@
-// CoR is a behavioral design pattern that lets you pass requests along a chain
-// of handlers. Upon receiving a request, each handler decides either to process
-// the request or to pass it to the next handler in the chain. Allows an object
-// to send a command without knowing what object will receive and handle it.
-// Appicability:
-// (*) when it’s essential to execute several handlers in a particular order.
-// (**)when the set of handlers and their order are supposed to change at
-// runtime.
-
-// UML: docs/uml/patterns_behavioral_CoR.drawio.svg
-
-#include <string>
-#include "Logger.h"
-
-namespace {
-namespace co_r {
-/*
- *  Handler - defines an interface for handling requests
- */
-class IHandler {
- public:
-  virtual ~IHandler() = default;
-  virtual void setNextHandler(IHandler* handler) = 0;
-  virtual IHandler* setNext(IHandler* handler) = 0;
-  virtual void handle(const std::string& request) = 0;
-};
-
-class AbstractHandler : public IHandler {
- private:
-  IHandler* setNext_{};
-
- public:
-  AbstractHandler() = default;
-
-  void setNextHandler(IHandler* handler) override { this->setNext_ = handler; }
-
-  // handler1->setNext(handler2)->setNext(handler3)
-  IHandler* setNext(IHandler* handler) override {
-    this->setNext_ = handler;
-    return handler;
-  }
-
-  void handle(const std::string& request) override {
-    if (this->setNext_ != nullptr) {
-      this->setNext_->handle(request);
-    } else {
-      LOG("\tNo handler processed request: " + request);
-    }
-  }
-};
-
-/**
- * CoreteHandlers - handles the requests it is responsible for
- * If it can handle the request it does so, otherwise it sends the request to
- * its successor
- */
-class ConcreteHandlerGET : public AbstractHandler {
- private:
-  static constexpr const char* kHeader = "GET";
-
- public:
-  void handle(const std::string& request) override {
-    if (request.rfind(kHeader, 0) == 0) {
-      // If request is eligible, handle it
-      LOG("\tHandle GET request: " + request);
-      // In realworld, it should be other logics here
-    } else {
-      AbstractHandler::handle(request);
-    }
-  }
-};
-
-class ConcreteHandlerPUT : public AbstractHandler {
- private:
-  static constexpr const char* kHeader = "PUT";
-
- public:
-  void handle(const std::string& request) override {
-    if (request.rfind(kHeader, 0) == 0) {
-      LOG("\tHandle PUT request: " + request);
-    } else {
-      AbstractHandler::handle(request);
-    }
-  }
-};
-
-class ConcreteHandlerPOST : public AbstractHandler {
- private:
-  static constexpr const char* kHeader = "POST";
-
- public:
-  void handle(const std::string& request) override {
-    if (request.rfind(kHeader, 0) == 0) {
-      LOG("\tHandle POST request: " + request);
-    } else {
-      AbstractHandler::handle(request);
-    }
-  }
-};
-
-/**
- * Client - sends commands to the first object in the chain that may handle the
- * command
- */
-namespace client {
-void clientCode(IHandler& handler, const std::string& request) {
-  handler.handle(request);
-}
-}  // namespace client
-
-void run() {
-  // Setup Chain of Responsibility
-  IHandler* post_handler = new ConcreteHandlerPOST();
-  IHandler* gett_handler = new ConcreteHandlerGET();
-  IHandler* putt_handler = new ConcreteHandlerPUT();
-  post_handler->setNext(gett_handler)->setNext(putt_handler);
-
-  // Send requests to the chain
-  std::string dummy = "DUMMY ..";
-  std::string post_request = "POST /test/demo_form.php HTTP/1.1 ..";
-  std::string get_request = "GET /users/123 ..";
-  LOG("Send dummy request");
-  client::clientCode(*post_handler, dummy);
-  LOG("Send POST request");
-  client::clientCode(*post_handler, post_request);
-  LOG("Send GET request");
-  client::clientCode(*post_handler, get_request);
-
-  delete post_handler;
-  delete gett_handler;
-  delete putt_handler;
-}
-}  // namespace co_r
-
-}  // namespace
-
-#include "ExampleRegistry.h"
-
-class ChainOfResponsibilityExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "ChainOfResponsibility"; }
-  std::string description() const override { return "CoR Pattern Example"; }
-  void execute() override { co_r::run(); }
-};
-
-REGISTER_EXAMPLE(ChainOfResponsibilityExample);
\ No newline at end of file
diff --git a/src/dp/behavioral/ChainOfResponsibility.cpp b/src/dp/behavioral/ChainOfResponsibility.cpp
new file mode 100644
index 0000000..e28851b
--- /dev/null
+++ b/src/dp/behavioral/ChainOfResponsibility.cpp
@@ -0,0 +1,125 @@
+// -----------------------------------------------------------------------------
+// Chain of Responsibility (behavioral pattern)
+//
+// Passes a request along a chain of handlers. Each handler decides to handle
+// the request, to reject it, or to pass it to the next handler. The sender only
+// knows the first handler of the chain.
+//
+// Use it when:
+//   - several objects may handle a request and the handler is not known upfront
+//   - handlers must run in a specific order that can change at run time
+//
+// Real world: web-server middleware, GUI event bubbling, support escalation.
+//
+// Participants:
+//   Handler          interface + link to the next handler (Handler)
+//   ConcreteHandler  AuthenticationHandler, LoggingHandler, GetHandler, PostHandler
+//   Client           builds the chain and sends requests to its head
+//
+// UML: docs/uml/dp/behavioral_CoR.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+struct Request {
+  std::string method;
+  std::string path;
+  std::string token;
+};
+
+/// Handler: stores the next link and forwards by default.
+class Handler {
+ public:
+  virtual ~Handler() = default;
+
+  /// Returns `next` so a chain can be written as a.setNext(b).setNext(c).
+  Handler& setNext(Handler& next) {
+    next_ = &next;
+    return next;
+  }
+
+  virtual void handle(const Request& request) const {
+    if (next_ != nullptr) {
+      next_->handle(request);
+    } else {
+      LOG_S("  [end of chain] nobody handled " << request.method << ' '
+                                               << request.path);
+    }
+  }
+
+ private:
+  const Handler* next_{nullptr};  // non-owning: the client owns all handlers
+};
+
+/// Can STOP the chain.
+class AuthenticationHandler : public Handler {
+ public:
+  void handle(const Request& request) const override {
+    if (request.token != "secret") {
+      LOG_S("  [auth] rejected " << request.path << " (invalid token)");
+      return;  // not forwarded
+    }
+    Handler::handle(request);
+  }
+};
+
+/// Does some work and always PASSES the request on.
+class LoggingHandler : public Handler {
+ public:
+  void handle(const Request& request) const override {
+    LOG_S("  [log]  " << request.method << ' ' << request.path);
+    Handler::handle(request);
+  }
+};
+
+/// HANDLES the requests it is responsible for, forwards the others.
+class MethodHandler : public Handler {
+ public:
+  explicit MethodHandler(std::string method) : method_{std::move(method)} {}
+
+  void handle(const Request& request) const override {
+    if (request.method == method_) {
+      LOG_S("  [" << method_ << "]  handled " << request.path);
+      return;
+    }
+    Handler::handle(request);
+  }
+
+ private:
+  std::string method_;
+};
+
+void run() {
+  LOG_SECTION("Building the chain: auth -> log -> GET -> POST");
+  AuthenticationHandler auth;
+  LoggingHandler logging;
+  MethodHandler get{"GET"};
+  MethodHandler post{"POST"};
+  auth.setNext(logging).setNext(get).setNext(post);
+
+  const auto send = [&auth](const Request& request) {
+    LOG_S("client sends " << request.method << ' ' << request.path);
+    auth.handle(request);  // the client only talks to the head of the chain
+  };
+
+  send({"GET", "/users/123", "secret"});
+  send({"POST", "/login", "secret"});
+  send({"DELETE", "/users/123", "secret"});
+  send({"GET", "/admin", "wrong"});
+
+  LOG_SECTION("Changing the chain at run time: skip authentication");
+  logging.handle({"POST", "/public/feedback", ""});
+}
+
+}  // namespace
+
+LAB_EXAMPLE("ChainOfResponsibility",
+            "pass a request along handlers that handle, forward or stop it") {
+  run();
+}
diff --git a/src/dp/behavioral/Command.cpp b/src/dp/behavioral/Command.cpp
index a6a2bfb..acaabae 100644
--- a/src/dp/behavioral/Command.cpp
+++ b/src/dp/behavioral/Command.cpp
@@ -1,152 +1,166 @@
-// Command is a behavioral design pattern that turns a request into a
-// stand-alone object that contains all information about the request.
-// (receivers, payloads) This transformation lets you pass requests as a method
-// arguments, delay or queue a request’s execution, and support undoable
-// operations. Allows an object to send a command without knowing what object
-// will receive and handle it. Appicability:
-// (*)   when you want to parameterize objects with operations.
-// (**)  when you want to queue operations, schedule their execution, or execute
-// them remotely.
-// (***) when you want to implement reversible operations.
-
-// UML: docs/uml/patterns_behavioral_command.drawio.svg
-
+// -----------------------------------------------------------------------------
+// Command (behavioral pattern)
+//
+// Turns a request into a stand-alone object that contains everything needed to
+// perform it (receiver + arguments). Requests can then be passed around, queued,
+// logged, combined into macros and UNDONE.
+//
+// Use it when:
+//   - UI elements (buttons, shortcuts, menus) should trigger operations without
+//     knowing how they are implemented
+//   - operations must be queued, scheduled or executed remotely
+//   - operations must be reversible (undo/redo)
+//
+// Participants:
+//   Command          interface with execute() / undo()
+//   ConcreteCommand  InsertTextCommand, ClearCommand, MacroCommand
+//   Receiver         TextDocument - does the real work
+//   Invoker          Editor - runs commands and keeps the history
+//   Client           creates commands and hands them to the invoker
+//
+// UML: docs/uml/dp/behavioral_command.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <memory>
 #include <string>
 #include <utility>
-#include "Logger.h"
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace command {
 
-/**
- * The Command interface usually declares just a single method for executing the
- * command. e.g. Save, Undo, Jump, Backup, CreateOrder
- */
-class ICommand {
+/// Receiver: contains the business logic.
+class TextDocument {
  public:
-  virtual ~ICommand() = default;
-  virtual void execute() const = 0;
+  void insert(const std::string& text) { content_ += text; }
+  void eraseLast(std::size_t count) { content_.erase(content_.size() - count); }
+  const std::string& content() const { return content_; }
+  void setContent(std::string content) { content_ = std::move(content); }
+
+ private:
+  std::string content_;
 };
 
-/**
- * The Receiver class contains some business logic. Almost any object may act as
- * a receiver. Most commands only handle the details of how a request is passed
- * to the receiver, while the receiver itself does the actual work. e.g.
- * Document, GameCharacter, DB service
- */
-class Receiver {
+/// Command interface.
+class Command {
  public:
-  void doCheck() {
-    LOG("Receiver checking... ");
-    dummy_++;
-  };
+  virtual ~Command() = default;
+  virtual void execute() = 0;
+  virtual void undo() = 0;
+  virtual std::string name() const = 0;
+};
 
-  void doInit() {
-    LOG("Receiver initializing... ");
-    dummy_++;
-  };
+class InsertTextCommand : public Command {
+ public:
+  InsertTextCommand(TextDocument& document, std::string text)
+      : document_{document}, text_{std::move(text)} {}
 
-  void doLaunch(const std::string& arg) {
-    LOG("Receiver launching...  \n\t" + arg);
-    dummy_++;
-  };
+  void execute() override { document_.insert(text_); }
+  void undo() override { document_.eraseLast(text_.size()); }
+  std::string name() const override { return "insert \"" + text_ + "\""; }
 
  private:
-  int dummy_{};
+  TextDocument& document_;
+  std::string text_;
 };
 
-/**
- * Concrete Commands implement various kinds of requests.
- *  A concrete command isn’t supposed to perform the work on its own, but rather
- * to pass the call to one of the business logic objects. However, for the sake
- * of simplifying the code, these classes can be merged.
- */
-class SimpleConcreteCommand : public ICommand {
+class ClearCommand : public Command {
  public:
-  void execute() const override { LOG("executed"); }
-};
-
-class ComplexConcreteCommand : public ICommand {
- private:
-  Receiver* receiver_;
-  std::string payload_;
+  explicit ClearCommand(TextDocument& document) : document_{document} {}
 
- public:
-  ComplexConcreteCommand(Receiver* receiver, std::string payload)
-      : receiver_{receiver}, payload_{std::move(payload)} {};
-
-  void execute() const override {
-    LOG("executed");
-    this->receiver_->doCheck();
-    this->receiver_->doInit();
-    this->receiver_->doLaunch(payload_);
+  void execute() override {
+    backup_ = document_.content();  // remember what is needed to undo
+    document_.setContent("");
   }
-};
+  void undo() override { document_.setContent(backup_); }
+  std::string name() const override { return "clear"; }
 
-/**
- *The Sender class (aka invoker) is responsible for initiating requests.
- *This class must have a field for storing a reference to a command object.
- *The sender triggers that command instead of sending the request directly to
- * the receiver. Note that the sender isn’t responsible for creating the command
- * object. Usually, it gets a pre-created command from the client via the
- * constructor. e.g. Button, Shortcut, Scheduler, Event bus...
- */
-class Invoker {
  private:
-  ICommand* on_start_;
-  ICommand* on_finish_;
+  TextDocument& document_;
+  std::string backup_;
+};
 
+/// A command made of other commands.
+class MacroCommand : public Command {
  public:
-  explicit Invoker(ICommand* s = nullptr) : on_start_{s}, on_finish_{s} {}
+  void add(std::unique_ptr<Command> command) {
+    commands_.push_back(std::move(command));
+  }
 
-  ~Invoker() {
-    delete on_start_;
-    delete on_finish_;
+  void execute() override {
+    for (const auto& command : commands_) {
+      command->execute();
+    }
+  }
+  void undo() override {  // undo in reverse order
+    for (auto it = commands_.rbegin(); it != commands_.rend(); ++it) {
+      (*it)->undo();
+    }
+  }
+  std::string name() const override {
+    return "macro of " + std::to_string(commands_.size());
   }
 
-  void setOnStart(ICommand* command) { this->on_start_ = command; }
+ private:
+  std::vector<std::unique_ptr<Command>> commands_;
+};
 
-  void setOnFinish(ICommand* command) { this->on_finish_ = command; }
+/// Invoker: executes commands without knowing what they do, and keeps a history.
+class Editor {
+ public:
+  explicit Editor(const TextDocument& document) : document_{document} {}
 
-  void invoke() const {
-    LOG("executed");
-    if (on_start_ != nullptr) {
-      on_start_->execute();
-    }
+  void run(std::unique_ptr<Command> command) {
+    command->execute();
+    LOG_S("  run  " << command->name() << " -> \"" << document_.content()
+                    << "\"");
+    history_.push_back(std::move(command));
+  }
 
-    if (on_finish_ != nullptr) {
-      on_finish_->execute();
+  void undo() {
+    if (history_.empty()) {
+      LOG("  undo: nothing to undo");
+      return;
     }
+    history_.back()->undo();
+    LOG_S("  undo " << history_.back()->name() << " -> \""
+                    << document_.content() << "\"");
+    history_.pop_back();
   }
+
+ private:
+  const TextDocument& document_;
+  std::vector<std::unique_ptr<Command>> history_;
 };
 
 void run() {
-  auto client_code = [](const Invoker* invoker) {
-    invoker->invoke();
-  };
-
-  // Receiver: UI
-  auto* ui = new Receiver();
-
-  // How to execute these command when something triggered
-  auto* invoker = new Invoker();
-  invoker->setOnStart(new SimpleConcreteCommand());
-  invoker->setOnFinish(new ComplexConcreteCommand(ui, "cmd --version"));
-
-  client_code(invoker);
-  delete ui;
+  TextDocument document;
+  Editor editor{document};
+
+  LOG_SECTION("Executing commands");
+  editor.run(std::make_unique<InsertTextCommand>(document, "Hello"));
+  editor.run(std::make_unique<InsertTextCommand>(document, " World"));
+  editor.run(std::make_unique<ClearCommand>(document));
+
+  LOG_SECTION("Undo");
+  editor.undo();  // restores "Hello World"
+  editor.undo();  // removes " World"
+
+  LOG_SECTION("Macro command: one undo step for several commands");
+  auto signature = std::make_unique<MacroCommand>();
+  signature->add(std::make_unique<InsertTextCommand>(document, "\n--\n"));
+  signature->add(std::make_unique<InsertTextCommand>(document, "Best regards"));
+  editor.run(std::move(signature));
+  editor.undo();
+  editor.undo();
+  editor.undo();
 }
-}  // namespace command
-}  // namespace
-
-#include "ExampleRegistry.h"
 
-class CommandExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Command"; }
-  std::string description() const override { return "Command Pattern Example"; }
-  void execute() override { command::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(CommandExample);
\ No newline at end of file
+LAB_EXAMPLE("Command",
+            "requests as objects: execute, undo history and macro commands") {
+  run();
+}
diff --git a/src/dp/behavioral/Iterator.cpp b/src/dp/behavioral/Iterator.cpp
index 62fbc27..bc4e529 100644
--- a/src/dp/behavioral/Iterator.cpp
+++ b/src/dp/behavioral/Iterator.cpp
@@ -1,210 +1,192 @@
-// Iterator is a behavioral design pattern that lets you traverse elements of a
-// collection without exposing its underlying representation (list, stack, tree,
-// etc.). Provide a way to access the elements of an aggregate object
-// sequentially without exposing its underlying representation. Appicability:
-// (*)   when your collection has a complex data structure under the hood, but
-// you want to hide its complexity from clients (either for convenience or
-// security reasons).
-// (**)  reduce duplication of the traversal code across your app.
-// (***) when you want your code to be able to traverse different data
-// structures or when types of these structures are unknown beforehand.
-
-// UML: docs/uml/patterns_behavioral_iterator.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Iterator (behavioral pattern)
+//
+// Lets clients traverse the elements of a collection without knowing how the
+// collection is stored (array, list, tree, ...).
+//
+// Use it when:
+//   - a collection has a complex internal structure you want to hide
+//   - the same client code should traverse different kinds of collections
+//   - traversal logic should not be duplicated across the code base
+//
+// Participants:
+//   Iterator           interface: hasNext() / next()
+//   ConcreteIterator   VectorIterator, ListIterator (track their own position)
+//   Aggregate          interface: createIterator()
+//   ConcreteAggregate  VectorCollection, ListCollection
+//
+// In C++ the standard library already implements this pattern: containers
+// provide begin()/end() iterators, which range-based for loops and algorithms
+// use. The second part shows how a custom collection plugs into that.
+//
+// UML: docs/uml/dp/behavioral_iterator.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
 #include <list>
+#include <memory>
+#include <numeric>
 #include <string>
 #include <vector>
 
-namespace {
-namespace iterator {
-class DataModel {
- private:
-  int value_;
-
- public:
-  explicit DataModel(int value) : value_{value} {}
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-  void setValue(int v) { value_ = v; }
+namespace {
 
-  int getValue() const { return value_; }
-};
+namespace classic {
 
-/**
- * Iterator interface: declares the operations required for traversing a
- * collection: fetching the next element, retrieving the current position,
- * restarting iteration, etc.
- */
 template <typename T>
-class IIterator {
+class Iterator {
  public:
+  virtual ~Iterator() = default;
   virtual bool hasNext() const = 0;
-  virtual const T* next() = 0;
-  virtual ~IIterator() = default;
+  virtual const T& next() = 0;
 };
 
-/**
- * Aggregate interface: declares one or multiple methods for getting iterators
- * compatible with the collection. Note that the return type of the methods must
- * be declared as the iterator interface so that the concrete collections can
- * return various kinds of iterators.
- */
 template <typename T>
-class IAggregate {
+class Aggregate {
  public:
-  virtual IIterator<T>* createIterator() = 0;
-  virtual ~IAggregate() = default;
+  virtual ~Aggregate() = default;
+  virtual std::unique_ptr<Iterator<T>> createIterator() const = 0;
 };
 
-/**
- * Concrete Iterator: implement specific algorithms for traversing a collection.
- * The iterator object should track the traversal progress on its own. This
- * allows several iterators to traverse the same collection independently of
- * each other.
- */
 template <typename T>
-class VectorConcreteIterator : public IIterator<T> {
- private:
-  const std::vector<T>& data_;
-  size_t currentIndex_{0};
-
+class VectorIterator : public Iterator<T> {
  public:
-  explicit VectorConcreteIterator(const std::vector<T>& data) : data_{data} {}
-
-  bool hasNext() const override { return currentIndex_ < data_.size(); }
-
-  const T* next() override {
-    if (hasNext()) {
-      return &data_[currentIndex_++];
-    }
+  explicit VectorIterator(const std::vector<T>& data) : data_{data} {}
+  bool hasNext() const override { return index_ < data_.size(); }
+  const T& next() override { return data_[index_++]; }
 
-    return nullptr;
-  }
+ private:
+  const std::vector<T>& data_;
+  std::size_t index_{0};
 };
 
 template <typename T>
-class ListConcreteIterator : public IIterator<T> {
- private:
-  const std::list<T>& data_;
-  typename std::list<T>::const_iterator it_;
-
+class ListIterator : public Iterator<T> {
  public:
-  explicit ListConcreteIterator(const std::list<T>& data)
-      : data_(data), it_(data_.begin()) {}
+  explicit ListIterator(const std::list<T>& data)
+      : data_{data}, position_{data.begin()} {}
+  bool hasNext() const override { return position_ != data_.end(); }
+  const T& next() override { return *position_++; }
 
-  bool hasNext() const override { return it_ != data_.end(); }
-
-  const T* next() override {
-    if (!hasNext())
-      return nullptr;
-    const T* ptr = &(*it_);
-    ++it_;
-    return ptr;
-  }
+ private:
+  const std::list<T>& data_;
+  typename std::list<T>::const_iterator position_;
 };
 
-/**
- * Concrete Aggregate: return new instances of a particular concrete iterator
- * class each time the client requests one.
- */
 template <typename T>
-class ListConreteAggregate : public IAggregate<T> {
- private:
-  std::list<T> data_;
-
+class VectorCollection : public Aggregate<T> {
  public:
-  void add(const T& i) { data_.push_back(i); }
-
-  IIterator<T>* createIterator() override {
-    return new ListConcreteIterator<T>(data_);
+  void add(const T& value) { data_.push_back(value); }
+  std::unique_ptr<Iterator<T>> createIterator() const override {
+    return std::make_unique<VectorIterator<T>>(data_);
   }
-};
 
-template <typename T>
-class VectorConcreteAggregate : public IAggregate<T> {
  private:
   std::vector<T> data_;
+};
 
+template <typename T>
+class ListCollection : public Aggregate<T> {
  public:
-  void add(const T& i) { data_.push_back(i); }
-
-  IIterator<T>* createIterator() override {
-    return new VectorConcreteIterator<T>(data_);
+  void add(const T& value) { data_.push_back(value); }
+  std::unique_ptr<Iterator<T>> createIterator() const override {
+    return std::make_unique<ListIterator<T>>(data_);
   }
-};
 
-/**
- * The Client works with both collections and iterators via their interfaces.
- * This way the client isn’t coupled to concrete classes, allowing you to use
- * various collections and iterators with the same client code.
- */
-namespace client {
-
-void clientCode(IAggregate<int>* collection) {
-  IIterator<int>* iterator = collection->createIterator();
+ private:
+  std::list<T> data_;
+};
 
-  if (iterator != nullptr) {
-    while (iterator->hasNext()) {
-      std::cout << "int: " << *(iterator->next()) << "\n";
-    }
+/// Client code: works with any Aggregate<std::string>.
+void printAll(const char* label, const Aggregate<std::string>& collection) {
+  std::string line;
+  for (auto it = collection.createIterator(); it->hasNext();) {
+    line += it->next() + " ";
   }
+  LOG_S("  " << label << line);
+}
 
-  delete iterator;
+void run() {
+  LOG_SECTION("Classic Iterator: one client, two storages");
+  VectorCollection<std::string> vector_names;
+  ListCollection<std::string> list_names;
+  for (const char* name : {"Ada", "Grace", "Linus"}) {
+    vector_names.add(name);
+    list_names.add(name);
+  }
+  printAll("vector-backed: ", vector_names);
+  printAll("list-backed:   ", list_names);
 }
 
-void clientCode(IAggregate<DataModel>* collection) {
-  IIterator<DataModel>* iterator = collection->createIterator();
+}  // namespace classic
 
-  if (iterator != nullptr) {
-    while (iterator->hasNext()) {
-      std::cout << "data: " << iterator->next()->getValue() << "\n";
+namespace cpp_style {
+
+/// A fixed ring of numbers that supports range-based for and std algorithms.
+class Ring {
+ public:
+  class iterator {  // NOLINT(readability-identifier-naming): standard naming
+   public:
+    using value_type = int;
+    using difference_type = std::ptrdiff_t;
+
+    iterator() = default;
+    iterator(const Ring* ring, std::size_t index)
+        : ring_{ring}, index_{index} {}
+
+    int operator*() const {
+      return ring_->values_[(ring_->start_ + index_) % kSize];
+    }
+    iterator& operator++() {
+      ++index_;
+      return *this;
+    }
+    iterator operator++(int) {
+      iterator old = *this;
+      ++index_;
+      return old;
+    }
+    bool operator==(const iterator& other) const {
+      return index_ == other.index_;
     }
-  }
-  delete iterator;
-}
-}  // namespace Client
 
-void run() {
-  std::cout << "\nVectorConcreteAggregate\n";
-  VectorConcreteAggregate<int> int_collection;
-  for (int i = 0; i < 10; ++i) {
-    int_collection.add(i);
-  }
-  client::clientCode(&int_collection);
-  std::cout << "\n";
-  VectorConcreteAggregate<DataModel> data_collection;
-  for (int i = 0; i < 10; ++i) {
-    data_collection.add(DataModel(i * 10));
-  }
-  client::clientCode(&data_collection);
+   private:
+    const Ring* ring_{nullptr};
+    std::size_t index_{0};
+  };
 
-  std::cout << "\nListConreteAggregate\n";
-  ListConreteAggregate<int> int_collection2;
-  for (int i = 0; i < 10; ++i) {
-    int_collection2.add(i);
-  }
+  explicit Ring(std::size_t start) : start_{start % kSize} {}
+  iterator begin() const { return {this, 0}; }
+  iterator end() const { return {this, kSize}; }
+
+ private:
+  static constexpr std::size_t kSize = 5;
+  int values_[kSize]{10, 20, 30, 40, 50};
+  std::size_t start_;
+};
 
-  client::clientCode(&int_collection2);
-  std::cout << "\n";
-  ListConreteAggregate<DataModel> data_collection2;
-  for (int i = 0; i < 10; ++i) {
-    data_collection2.add(DataModel(i * 10));
+void run() {
+  LOG_SECTION("The C++ way: begin()/end() iterators");
+  const Ring ring{3};  // starts at the fourth element and wraps around
+  std::string line;
+  for (const int value : ring) {  // range-based for uses begin() and end()
+    line += std::to_string(value) + " ";
   }
-  client::clientCode(&data_collection2);
+  LOG_S("  range-for over Ring(3): " << line);
+  LOG_S("  std::accumulate works too: " << std::accumulate(ring.begin(),
+                                                           ring.end(), 0));
 }
-}  // namespace iterator
-}  // namespace
 
-#include "ExampleRegistry.h"
+}  // namespace cpp_style
 
-class IteratorExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Iterator"; }
-  std::string description() const override {
-    return "Iterator Pattern Example";
-  }
-  void execute() override { iterator::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(IteratorExample);
\ No newline at end of file
+LAB_EXAMPLE("Iterator",
+            "traverse collections without exposing their storage; "
+            "begin()/end() in C++") {
+  classic::run();
+  cpp_style::run();
+}
diff --git a/src/dp/behavioral/Mediator.cpp b/src/dp/behavioral/Mediator.cpp
index 9d607ff..fb1eba9 100644
--- a/src/dp/behavioral/Mediator.cpp
+++ b/src/dp/behavioral/Mediator.cpp
@@ -1,177 +1,136 @@
-// Mediator is a behavioral design pattern that lets you reduce chaotic
-// dependencies between objects. The pattern restricts direct communications
-// between the objects and forces them to collaborate only via a mediator
-// object. Usage examples: The most popular usage of the Mediator pattern in C++
-// code is facilitating communications between GUI components of an app. The
-// synonym of the Mediator is the `Controller` part of MVC pattern.
-// Appicability:
-// (*)   when your collection has a complex data structure under the hood, but
-// you want to hide its complexity from clients (either for convenience or
-// security reasons).
-// (**)  when you can’t reuse a component in a different program because it’s
-// too dependent on other components.
-// (***) when you find yourself creating tons of component subclasses just to
-// reuse some basic behavior in various contexts.
-
-// UML: docs/uml/patterns_behavioral_mediator.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Mediator (behavioral pattern)
+//
+// Reduces chaotic dependencies between objects: instead of talking to each
+// other directly, components talk only to a mediator that coordinates them.
+//
+// Problem: with N aircraft that negotiate the runway directly, every aircraft
+// must know every other aircraft (N * (N - 1) connections) and the landing
+// rules are spread over all of them.
+// Solution: a control tower (mediator) owns the rules; each aircraft only
+// knows the tower.
+//
+// Use it when:
+//   - classes are hard to change because they are tightly coupled to many others
+//   - a component cannot be reused because it depends on too many others
+//   - coordination logic is scattered over many classes
+//
+// Participants:
+//   Mediator           ControlTower interface
+//   ConcreteMediator   Tower - implements the coordination rules
+//   Component          Aircraft - knows only the mediator interface
+//
+// Related: the Controller in MVC plays a mediator role (see src/ap).
+// UML: docs/uml/dp/behavioral_mediator.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <deque>
 #include <string>
 #include <utility>
-#include <vector>
-namespace {
-namespace mediator {
 
-enum class Event {
-  kCreate = 0,
-  kRead,
-  kUpdate,
-  kDelete,
-};
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-inline const char* getEventName(const Event& e) {
-  switch (e) {
-    case Event::kCreate:
-      return "CREATE";
-    case Event::kRead:
-      return "READ";
-    case Event::kUpdate:
-      return "UPDATE";
-    case Event::kDelete:
-      return "DELETE";
-  }
-  return "invalid_event";
-}
+namespace {
 
-class IComponent {
- public:
-  virtual ~IComponent() = default;
+class Aircraft;
 
-  virtual void send(const Event& e) = 0;
-  virtual void receive(const Event& e) = 0;
+/// Mediator interface.
+class ControlTower {
+ public:
+  virtual ~ControlTower() = default;
+  virtual void requestLanding(Aircraft& aircraft) = 0;
+  virtual void reportLanded(Aircraft& aircraft) = 0;
 };
 
-/**
- * The Mediator interface declares methods of communication with components,
- * which usually include just a single notification method. Components may pass
- * any context as arguments of this method, including their own objects, but
- * only in such a way that no coupling occurs between a receiving component and
- * the sender’s class.
- */
-class IMediator {
+/// Component: communicates only through the tower.
+class Aircraft {
  public:
-  virtual ~IMediator() = default;
-  virtual void registerComponent(IComponent* const& c) = 0;
-  virtual void notify(IComponent* sender, const Event& e) = 0;
-};
+  Aircraft(std::string callsign, ControlTower& tower)
+      : callsign_{std::move(callsign)}, tower_{tower} {}
 
-/**
- * Concrete Mediators implement cooperative behavior by coordinating several
- * components. Concrete mediators often keep references to all components they
- * manage and sometimes even manage their lifecycle.
- */
-class ComponentMediator : public IMediator {
- private:
-  std::vector<IComponent*> components_;
+  const std::string& callsign() const { return callsign_; }
 
- public:
-  void registerComponent(IComponent* const& c) override {
-    components_.push_back(c);
+  void requestLanding() {
+    LOG_S("  " << callsign_ << ": requesting landing");
+    tower_.requestLanding(*this);
   }
 
-  void notify(IComponent* const sender, const Event& e) override {
-    for (auto* c : components_) {
-      if (c != sender) {
-        c->receive(e);
-      }
-    }
+  // Called by the tower.
+  void clearToLand() {
+    cleared_ = true;
+    LOG_S("  " << callsign_ << ": cleared to land");
   }
-};
+  void hold() const { LOG_S("  " << callsign_ << ": holding pattern"); }
 
-/**
- * Components are various classes that contain some business logic.
- * Each component has a reference to a mediator, declared with the type of the
- * mediator interface. The component isn’t aware of the actual class of the
- * mediator, so you can reuse the component in other programs by linking it to a
- * different mediator.
- */
-class AbstractComponent : public IComponent {
- private:
-  const std::string id_;
-
- protected:
-  IMediator* mediator_;
-  void log(const Event& e, const std::string& msg) const {
-    std::cout << "\t" + msg + "-id:" + id_ + "-event:" + getEventName(e) + "\n";
+  void land() {
+    if (!cleared_) {
+      LOG_S("  " << callsign_ << ": cannot land without clearance");
+      return;
+    }
+    LOG_S("  " << callsign_ << ": touchdown");
+    cleared_ = false;
+    tower_.reportLanded(*this);
   }
 
- public:
-  explicit AbstractComponent(std::string  id,
-                             IMediator* const m = nullptr)
-      : id_{std::move(id)}, mediator_{m} {};
+ private:
+  std::string callsign_;
+  ControlTower& tower_;
+  bool cleared_{false};
 };
 
-/**
- * Concrete Components implement various functionality. They don't depend on
- * other components. They also don't depend on any concrete mediator classes.
- */
-class ConreteComponent : public AbstractComponent {
+/// Concrete mediator: one runway, first come first served.
+class Tower : public ControlTower {
  public:
-  explicit ConreteComponent(const std::string& id, IMediator* const m = nullptr)
-      : AbstractComponent{id, m} {}
-
-  void send(const Event& e) override {
-    log(e, "[SEND]");
-    if (mediator_ != nullptr)
-      mediator_->notify(this, e);
+  void requestLanding(Aircraft& aircraft) override {
+    if (runway_user_ == nullptr) {
+      runway_user_ = &aircraft;
+      aircraft.clearToLand();
+    } else {
+      waiting_.push_back(&aircraft);
+      LOG_S("  [tower] runway busy with "
+            << runway_user_->callsign() << ", " << aircraft.callsign()
+            << " is number " << waiting_.size() << " in the queue");
+      aircraft.hold();
+    }
   }
 
-  void receive(const Event& e) override {
-    log(e, "[RECV]");
-    // Additional handling logic can go here
+  void reportLanded(Aircraft& aircraft) override {
+    LOG_S("  [tower] " << aircraft.callsign() << " vacated the runway");
+    runway_user_ = nullptr;
+    if (!waiting_.empty()) {
+      Aircraft* next = waiting_.front();
+      waiting_.pop_front();
+      runway_user_ = next;
+      next->clearToLand();
+    }
   }
-};
 
-namespace client {
-void clientCode(IComponent* comp) {
-  comp->send(Event::kRead);
-}
-}  // namespace client
+ private:
+  Aircraft* runway_user_{nullptr};
+  std::deque<Aircraft*> waiting_;
+};
 
 void run() {
-  IMediator* mediator = new ComponentMediator();
-  IComponent* c1 = new ConreteComponent("1763700876", mediator);
-  IComponent* c2 = new ConreteComponent("1763700882", mediator);
-  IComponent* c3 = new ConreteComponent("1763700899", mediator);
-  IComponent* c4 = new ConreteComponent("1763700900", mediator);
-
-  // Only c1, c3, c4 receive notifications.
-  mediator->registerComponent(c1);
-  mediator->registerComponent(c3);
-  mediator->registerComponent(c4);
-
-  // c2 triggers event => observed by others
-  client::clientCode(c2);
-
-  delete mediator;
-  delete c1;
-  delete c2;
-  delete c3;
-  delete c4;
+  LOG_SECTION("Three aircraft, one runway, coordinated by the tower");
+  Tower tower;
+  Aircraft alpha{"VN-101", tower};
+  Aircraft bravo{"SQ-202", tower};
+  Aircraft charlie{"JL-303", tower};
+
+  alpha.requestLanding();
+  bravo.requestLanding();
+  charlie.requestLanding();
+  charlie.land();  // not cleared yet
+
+  alpha.land();  // the tower now clears bravo
+  bravo.land();  // ...then charlie
+  charlie.land();
 }
-}  // namespace mediator
-}  // namespace
-
-#include "ExampleRegistry.h"
 
-class MediatorExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Mediator"; }
-  std::string description() const override {
-    return "Mediator Pattern Example";
-  }
-  void execute() override { mediator::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(MediatorExample);
\ No newline at end of file
+LAB_EXAMPLE("Mediator",
+            "components coordinate through a mediator instead of each other") {
+  run();
+}
diff --git a/src/dp/behavioral/Memento.cpp b/src/dp/behavioral/Memento.cpp
index 46fc58d..42003f5 100644
--- a/src/dp/behavioral/Memento.cpp
+++ b/src/dp/behavioral/Memento.cpp
@@ -1,210 +1,147 @@
-// Memento is a behavioral design pattern that lets you save and restore the
-// previous state of an object without violating encapsulation, captures and
-// externalizes an object's internal state Appicability:
-// (*)    when you want to produce snapshots of the object’s state to be able to
-// restore a previous state of the object.
-// (**)   when direct access to the object’s fields/getters/setters violates its
-// encapsulation. UML: docs/uml/patterns_behavioral_memento.drawio.svg
-
-#include <cstdlib>  // for std::rand, std::srand
-#include <ctime>    // for std::time
-#include <iomanip>
-#include <iostream>
-#include <sstream>
+// -----------------------------------------------------------------------------
+// Memento (behavioral pattern)
+//
+// Captures an object's internal state so it can be restored later, WITHOUT
+// exposing that state to the rest of the program.
+//
+// Problem: to implement undo, some other object (the history) would need to
+// read and write the editor's private fields - breaking encapsulation.
+// Solution: the editor itself creates an opaque snapshot (memento). The history
+// only stores snapshots; only the editor can look inside them.
+//
+// Use it when:
+//   - you need snapshots to undo or roll back
+//   - direct access to the fields would break encapsulation
+//
+// Participants:
+//   Originator  Editor - creates and restores mementos
+//   Memento     Editor::Snapshot - state is private, readable only by Editor
+//   Caretaker   History - keeps mementos, never inspects them
+//
+// UML: docs/uml/dp/behavioral_memento.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
+#include <memory>
 #include <string>
 #include <utility>
 #include <vector>
 
-namespace {
-namespace memento {
-/**
- * Memento interface provides a way to retrieve the memento's metadata, such as
- * creation date or name. However, it doesn't expose the Originator's state.
- */
-class IMemento {
- public:
-  virtual ~IMemento() = default;
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-  virtual std::string getName() const = 0;
-  virtual std::string getDate() const = 0;
-  virtual std::string getState() const = 0;
-};
-
-/**
- * Concrete Memento contains the infrastructure for storing the Originator's
- * state.
- */
-class ConcreteMemento : public IMemento {
- private:
-  std::string state_;
-  std::string date_;
-  std::string name_;
+namespace {
 
+/// Originator.
+class Editor {
  public:
-  explicit ConcreteMemento(std::string  state) : state_{std::move(state)} {
-    // Get current time
-    std::time_t now = std::time(nullptr);
-    std::tm* t = std::localtime(&now);
-
-    // Format date as YYYYMMDD_HHMMSS
-    std::stringstream date_ss;
-    date_ss << std::put_time(t, "%Y%m%d_%H%M%S");
-    date_ = date_ss.str();
-
-    // Append a random number for uniqueness
-    int rand_num = std::rand() % 10000;  // optional: limit size
-    std::stringstream name_ss;
-    name_ss << "me" << date_ << "_" << rand_num;
-    name_ = name_ss.str();
+  /// Memento: public metadata, private state.
+  class Snapshot {
+   public:
+    const std::string& label() const { return label_; }  // safe to show
+
+   private:
+    friend class Editor;  // only the originator can read the state
+    Snapshot(std::string text, std::size_t cursor, std::string label)
+        : text_{std::move(text)}, cursor_{cursor}, label_{std::move(label)} {}
+
+    std::string text_;
+    std::size_t cursor_;
+    std::string label_;
+  };
+
+  void type(const std::string& text) {
+    text_.insert(cursor_, text);
+    cursor_ += text.size();
   }
 
-  std::string getName() const override { return name_; };
-
-  std::string getDate() const override { return this->date_; };
-
-  std::string getState() const override { return this->state_; }
-};
-
-/**
- * Originator holds some important state that may change over time.
- * It also defines a method for saving the state inside a memento and another
- * method for restoring the state from it.
- */
-class Originator {
- private:
-  std::string state_;
-  int dummy_{};
-
-  // Simulate new state using rand
-  std::string generateRandomString(int len = 10) {
-    // String literal concatenation
-    const char alpha_num[] =
-        "0123456789"
-        "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
-        "abcdefghijklmnopqrstuvwxyz";
-
-    int str_len = sizeof(alpha_num) - 1;
-    std::string ran_str;
-    for (int i = 0; i < len; ++i) {
-      ran_str += alpha_num[std::rand() % str_len];
-    }
-    dummy_++;
-    return ran_str;
+  void moveCursor(std::size_t position) {
+    cursor_ = std::min(position, text_.size());
   }
 
- public:
-  explicit Originator(std::string  state) : state_{std::move(state)} {
-    std::cout << "[O]Initial state is: " << this->state_ << "\n";
+  std::unique_ptr<Snapshot> save(const std::string& label) const {
+    // std::make_unique cannot reach the private constructor, so `new` is used.
+    return std::unique_ptr<Snapshot>(new Snapshot(text_, cursor_, label));
   }
 
-  void operation() {
-    std::cout << "[O]Doing something important.\n";
-    this->state_ = this->generateRandomString(30);
-    std::cout << "[O]The state has changed to: " << this->state_ << "\n";
+  void restore(const Snapshot& snapshot) {
+    text_ = snapshot.text_;
+    cursor_ = snapshot.cursor_;
   }
 
-  //  Save the current state inside a memento.
-  IMemento* save() { return new ConcreteMemento(this->state_); }
-
-  // Restores the Originator's state from a memento object.
-  void restore(IMemento* mem) {
-    this->state_ = mem->getState();
-    std::cout << "[O]The state has restored to: " << this->state_ << "\n";
-
-    delete mem;
+  std::string show() const {
+    std::string view = text_;
+    view.insert(cursor_, "|");  // visualize the cursor
+    return "\"" + view + "\"";
   }
-};
 
-/**
- * The Caretaker doesn't depend on the Concrete Memento class. Therefore, it
- * doesn't have access to the originator's state, stored inside the memento. It
- * works with all mementos via the base Memento interface.
- */
-class CareTaker {
  private:
-  std::vector<IMemento*> mementos_;
-  Originator* originator_;
+  std::string text_;
+  std::size_t cursor_{0};
+};
 
+/// Caretaker: stores snapshots, has no idea what they contain.
+class History {
  public:
-  explicit CareTaker(Originator* const org) : originator_{org} {}
-  ~CareTaker() {
-    for (IMemento* m : mementos_) {
-      delete m;
-    }
-  }
+  explicit History(Editor& editor) : editor_{editor} {}
 
-  void backup() {
-    std::cout << "[C]Saving Originator's state...\n";
-    this->mementos_.push_back(this->originator_->save());
+  void backup(const std::string& label) {
+    snapshots_.push_back(editor_.save(label));
   }
 
   void undo() {
-    if (this->mementos_.size() != 0) {
-      IMemento* mem = mementos_.back();
-      this->mementos_.pop_back();
-
-      std::cout << "[C]Restoring state to: " << mem->getName() << "\n";
-      this->originator_->restore(mem);
+    if (snapshots_.empty()) {
+      LOG("  nothing to undo");
+      return;
     }
+    const std::unique_ptr<Editor::Snapshot> snapshot =
+        std::move(snapshots_.back());
+    snapshots_.pop_back();
+    editor_.restore(*snapshot);
+    LOG_S("  undo to '" << snapshot->label() << "' -> " << editor_.show());
   }
 
-  void history() const {
-    std::cout << "[C]The list of mementos:\n";
-    for (const IMemento* m : mementos_) {
-      std::cout << "\t" << m->getName() << "\n";
+  void list() const {
+    for (const auto& snapshot : snapshots_) {
+      LOG_S("    saved: " << snapshot->label());
     }
   }
-};
-
-namespace client {
-void clientCode(Originator* const org) {
-  auto* care_taker = new CareTaker(org);
-
-  // 1
-  care_taker->backup();
-  org->operation();
-
-  // 2
-  care_taker->backup();
-  org->operation();
 
-  // 3
-  care_taker->backup();
-  org->operation();
-
-  care_taker->history();
-  care_taker->undo();
-  care_taker->undo();
-  care_taker->history();
-  care_taker->undo();
-
-  // [P] The previous state can’t be restored directly because state is
-  // private. We need a Memento to save and recover internal state safely.
-}
-}  // namespace client
+ private:
+  Editor& editor_;
+  std::vector<std::unique_ptr<Editor::Snapshot>> snapshots_;
+};
 
 void run() {
-  // Gen seed
-  std::srand(static_cast<unsigned int>(std::time(nullptr)));
-
-  auto* origin = new Originator("Hello World");
-  client::clientCode(origin);
-
-  delete origin;
+  Editor editor;
+  History history{editor};
+
+  LOG_SECTION("Editing and taking snapshots");
+  history.backup("empty");
+  editor.type("Hello");
+  LOG_S("  typed           -> " << editor.show());
+
+  history.backup("after Hello");
+  editor.type(" World");
+  LOG_S("  typed           -> " << editor.show());
+
+  history.backup("after World");
+  editor.moveCursor(5);
+  editor.type(",");
+  LOG_S("  inserted comma  -> " << editor.show());
+  history.list();
+
+  LOG_SECTION("Undo");
+  history.undo();
+  history.undo();
+  history.undo();
+  history.undo();
+  // history.snapshots_[0]->text_;  // error: private - encapsulation is preserved
 }
-}  // namespace memento
-}  // namespace
 
-#include "ExampleRegistry.h"
-
-class MementoExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Memento"; }
-  std::string description() const override {
-    return "Memento Pattern Example ";
-  }
-  void execute() override { memento::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(MementoExample);
\ No newline at end of file
+LAB_EXAMPLE("Memento",
+            "save and restore state (undo) without breaking encapsulation") {
+  run();
+}
diff --git a/src/dp/behavioral/Observer.cpp b/src/dp/behavioral/Observer.cpp
index 3855713..2b8d274 100644
--- a/src/dp/behavioral/Observer.cpp
+++ b/src/dp/behavioral/Observer.cpp
@@ -1,201 +1,172 @@
-// Observer is a behavioral design pattern that lets you define a subscription
-// mechanism to notify multiple objects about any events that happen to the
-// object they’re observing. Usage examples: The most popular usage of the
-// Observer pattern in C++ code is facilitating communications between GUI
-// components of an app. The synonym of the Observer is the `Controller` part of
-// MVC pattern. Appicability:
-// (*)   when changes to the state of one object may require changing other
-// objects, and the actual set of objects is unknown beforehand or changes
-// dynamically.
-// (**)   when some objects in your app must observe others, but only for a
-// limited time or in specific cases.
-
-// UML: docs/uml/patterns_behavioral_observer.drawio.svg
-
-#include <list>
+// -----------------------------------------------------------------------------
+// Observer (behavioral pattern)
+//
+// Defines a subscription mechanism: a subject (publisher) notifies all its
+// observers (subscribers) when an event happens, without knowing their
+// concrete types.
+//
+// Use it when:
+//   - changes in one object must update others, and the set of interested
+//     objects is not known in advance or changes at run time
+//   - some objects only need to listen for a limited time
+//
+// Real world: GUI events, model -> view updates (MVC, see src/ap), signals and
+// slots, event buses.
+//
+// Participants:
+//   Subject           Button - attach / detach / notify
+//   Observer          ClickListener interface - onEvent()
+//   ConcreteObserver  AnalyticsListener, SoundListener
+//
+// Pitfall: the subject stores pointers to observers. An observer destroyed
+// while still attached leaves a dangling pointer - always detach first, or use
+// subscriptions that detach automatically (RAII).
+//
+// UML: docs/uml/dp/behavioral_observer.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <algorithm>
+#include <functional>
 #include <string>
-#include "Logger.h"
+#include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace observer {
 
-enum class Event {
-  kCreate = 0,
-  kRead,
-  kUpdate,
-  kDelete,
-};
+enum class Event { kPressed, kReleased };
 
-/**
- * @brief Get the Event Name object
- * 
- * This is a static definition in anonymous namespace
- * @param e 
- * @return const char* 
- */
-inline std::string getEventName(const Event& e) {
-  switch (e) {
-    case Event::kCreate:
-      return "CREATE";
-    case Event::kRead:
-      return "READ";
-    case Event::kUpdate:
-      return "UPDATE";
-    case Event::kDelete:
-      return "DELETE";
-  }
-  return "UNKNOWN";
+std::string toString(Event event) {
+  return event == Event::kPressed ? "pressed" : "released";
 }
 
-/**
- * IObserver aka Subscriber
- * The Subscriber interface declares the notification interface.
- * In most cases, it consists of a single update method.
- * The method may have several parameters that let the publisher pass some event
- * details along with the update. E.g. Event Listen to UI events
- */
-class IListenerObserver {
- public:
-  virtual ~IListenerObserver() = default;
-
-  // update
-  virtual void update(const Event& e) = 0;
+namespace classic {
 
-  virtual std::string get_name() const = 0;
-};
-
-/**
- * Subject aka Publisher
- * The Publisher issues events of interest to other objects.
- * These events occur when the publisher changes its state or executes some
- * behaviors. Publishers contain a subscription infrastructure that lets new
- * subscribers join and current subscribers leave the list.
- *
- * E.g Widget dispatches click events to observers
- */
-class IWidgetSubject {
+/// Observer interface.
+class Listener {
  public:
-  virtual ~IWidgetSubject() = default;
-
-  // addListener
-  virtual void attach(IListenerObserver* observer) = 0;
-  // removeLister
-  virtual void detach(IListenerObserver* observer) = 0;
-  // e.g.click
-  virtual void notify(const Event& e) = 0;
+  virtual ~Listener() = default;
+  virtual void onEvent(const std::string& source, Event event) = 0;
 };
 
-class ButtonConcreteSubject : public IWidgetSubject {
- private:
-  std::list<IListenerObserver*> listeners_;
-
+/// Subject.
+class Button {
  public:
-  void attach(IListenerObserver* observer) override {
-    LOG("attched: " + observer->get_name());
-    listeners_.push_back(observer);
-  }
+  explicit Button(std::string name) : name_{std::move(name)} {}
 
-  void detach(IListenerObserver* observer) override {
-    LOG("detached: " + observer->get_name());
-    listeners_.remove(observer);
-  }
+  void attach(Listener& listener) { listeners_.push_back(&listener); }
+  void detach(Listener& listener) { std::erase(listeners_, &listener); }
 
-  void notify(const Event& e) override {
-    LOG("notify event: " + getEventName(e));
-    for (IListenerObserver* o : listeners_) {
-      o->update(e);
-    }
-  }
-};
+  void press() { notify(Event::kPressed); }
+  void release() { notify(Event::kReleased); }
 
-class AbstractListenerObserver : public IListenerObserver {
  private:
-  std::string name_;
-
- protected:
-  void log(const Event& e) const {
-    LOG(this->get_name() + " updated after event: " + getEventName(e));
+  void notify(Event event) {
+    LOG_S("  " << name_ << " " << toString(event) << ", notifying "
+               << listeners_.size() << " listener(s)");
+    for (Listener* listener : listeners_) {
+      listener->onEvent(name_, event);
+    }
   }
 
- public:
-  explicit AbstractListenerObserver(std::string name)
-      : name_(std::move(name)) {}
-
-  std::string get_name() const override { return name_; }
+  std::string name_;
+  std::vector<Listener*> listeners_;  // non-owning
 };
 
-/**
- * Concrete Subscribers perform some actions in response to notifications issued
- * by the publisher. All of these classes must implement the same interface so
- * the publisher isn’t coupled to concrete classes.
- */
-class ConcreteListenerObserverA : public AbstractListenerObserver {
+class AnalyticsListener : public Listener {
  public:
-  void update(const Event& e) override { log(e); }
+  void onEvent(const std::string& source, Event event) override {
+    ++events_;
+    LOG_S("    [analytics] recorded " << source << " " << toString(event)
+                                      << " (total " << events_ << ")");
+  }
 
-  explicit ConcreteListenerObserverA(std::string name)
-      : AbstractListenerObserver(std::move(name)){};
+ private:
+  int events_{0};
 };
 
-class ConcreteListenerObserverB : public AbstractListenerObserver {
+class SoundListener : public Listener {
  public:
-  explicit ConcreteListenerObserverB(std::string name)
-      : AbstractListenerObserver(std::move(name)){};
-
-  void update(const Event& e) override { log(e); }
+  void onEvent(const std::string& /*source*/, Event event) override {
+    if (event == Event::kPressed) {
+      LOG("    [sound] click!");
+    }
+  }
 };
 
 void run() {
+  LOG_SECTION("Classic Observer with an interface");
+  Button save{"Save button"};
+  AnalyticsListener analytics;
+  SoundListener sound;
+
+  save.attach(analytics);
+  save.attach(sound);
+  save.press();
+  save.release();
+
+  LOG("  -- detaching the sound listener --");
+  save.detach(sound);
+  save.press();
+}
 
-  // Client code that triggers event
-  auto client_code = [](IWidgetSubject* const widget, const Event& e) {
-    widget->notify(e);
-  };
+}  // namespace classic
 
-  // Create subject - Button
-  IWidgetSubject* btn = new ButtonConcreteSubject();
+namespace callbacks {
 
-  // Create observers - Listenerss
-  IListenerObserver* listener_1 = new ConcreteListenerObserverA("listener 1");
-  IListenerObserver* listener_2 = new ConcreteListenerObserverA("listener 2");
-  IListenerObserver* listener_3 = new ConcreteListenerObserverA("listener 3");
-  IListenerObserver* listener_4 = new ConcreteListenerObserverB("listener 4");
+/// A lighter alternative: observers are std::function callbacks.
+class Button {
+ public:
+  using Callback = std::function<void(Event)>;
 
-  // Register observers to the subject
-  btn->attach(listener_1);
-  btn->attach(listener_2);
-  btn->attach(listener_3);
-  btn->attach(listener_4);
+  /// Returns an id that can be used to unsubscribe.
+  int subscribe(Callback callback) {
+    subscribers_.emplace_back(next_id_, std::move(callback));
+    return next_id_++;
+  }
 
-  // Notify all observers
-  client_code(btn, Event::kCreate);
+  void unsubscribe(int id) {
+    std::erase_if(subscribers_,
+                  [id](const auto& entry) { return entry.first == id; });
+  }
 
-  // Unregister one observer
-  btn->detach(listener_2);
+  void press() const {
+    for (const auto& [id, callback] : subscribers_) {
+      callback(Event::kPressed);
+    }
+  }
 
-  // Notify all observers
-  client_code(btn, Event::kUpdate);
+ private:
+  std::vector<std::pair<int, Callback>> subscribers_;
+  int next_id_{0};
+};
 
-  delete btn;
-  delete listener_1;
-  delete listener_2;
-  delete listener_3;
-  delete listener_4;
+void run() {
+  LOG_SECTION("Observers as std::function callbacks");
+  Button button;
+  int clicks = 0;
+  const int counter = button.subscribe([&clicks](Event) { ++clicks; });
+  button.subscribe([](Event event) {
+    LOG_S("    lambda observer got " << toString(event));
+  });
+
+  button.press();
+  button.press();
+  button.unsubscribe(counter);
+  button.press();
+  LOG_S("  counter observer saw "
+        << clicks << " clicks (it unsubscribed before the third)");
 }
 
-}  // namespace observer
-}  // namespace
-
-#include "ExampleRegistry.h"
+}  // namespace callbacks
 
-class ObserverExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Observer"; }
-  std::string description() const override {
-    return "Observer Pattern Example";
-  }
-  void execute() override { observer::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(ObserverExample);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Observer",
+    "publish/subscribe with listener interfaces or std::function callbacks") {
+  classic::run();
+  callbacks::run();
+}
diff --git a/src/dp/behavioral/README.md b/src/dp/behavioral/README.md
index 3ef5a5b..0935281 100644
--- a/src/dp/behavioral/README.md
+++ b/src/dp/behavioral/README.md
@@ -1,3 +1,7 @@
+> Examples: `dp/behavioral/{ChainOfResponsibility, Command, Iterator, Mediator, Memento, Observer,
+> State, Strategy, TemplateMethod, Visitor}` - run one with
+> `./build/bin/cpp_lab_project --run dp/behavioral/Observer`
+
 # Behavioral Design Patterns
 
 Behavioral design patterns are concerned with algorithms and the assignment of responsibilities between objects.
diff --git a/src/dp/behavioral/State.cpp b/src/dp/behavioral/State.cpp
index 9f1441e..394a911 100644
--- a/src/dp/behavioral/State.cpp
+++ b/src/dp/behavioral/State.cpp
@@ -1,139 +1,127 @@
-// State is a behavioral design pattern that lets an object alter its behavior
-// when its internal state changes. It appears as if the object changed its
-// class. Appicability:
-// (*)    when you have an object that behaves differently depending on its
-// current state
-//        , the number of states is enormous, and the state-specific code
-//        changes frequently.
-// (**)   when you have a class polluted with massive conditionals that alter
-//        how the class behaves according to the current values of the class’s
-//        fields.
-// (***)  when you have a lot of duplicate code across similar states and
-// transitions of a condition-based state machine. UML:
-// docs/uml/patterns_behavioral_state.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// State (behavioral pattern)
+//
+// Lets an object change its behavior when its internal state changes - it
+// looks as if the object changed its class. Each state is a class; the context
+// delegates the state-specific work to the current state object.
+//
+// Problem: a class full of `switch (state_)` blocks in every method, where
+// adding a state means touching all of them.
+// Solution: one class per state; transitions are explicit.
+//
+// Use it when:
+//   - an object behaves differently depending on its state, with many states
+//   - state-specific code changes often
+//   - there are massive conditionals on the current state
+//
+// Participants:
+//   Context        Device - holds the current state, delegates to it
+//   State          DeviceState interface
+//   ConcreteState  IdleState, ProcessingState, ErrorState
+//
+// Implementation note: a state that replaces itself in the middle of its own
+// handle() would destroy the object that is still running. Here the context
+// applies the requested transition AFTER handle() returns.
+//
+// UML: docs/uml/dp/behavioral_state.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <memory>
 #include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
 namespace {
-namespace state {
-class DeviceContext;
-
-/**
- * The State interface declares the state-specific methods.
- * These methods should make sense for all concrete states because you don’t
- * want some of your states to have useless methods that will never be called.
- */
-class IState {
- public:
-  virtual ~IState() = default;
-  virtual void setContext(DeviceContext* ctx) = 0;
-  virtual void handle() = 0;
-};
 
-/*
- * To avoid duplication of similar code across multiple states, you may provide
- * intermediate abstract classes that encapsulate some common behavior.
- */
-class AbstractState : public IState {
- protected:
-  DeviceContext* ctx_;
+class Device;
 
+/// State interface.
+class DeviceState {
  public:
-  void setContext(DeviceContext* ctx) override { this->ctx_ = ctx; }
+  virtual ~DeviceState() = default;
+  virtual std::string name() const = 0;
+  virtual void handle(Device& device) = 0;
 };
 
-/**
- * Context stores a reference to one of the concrete state objects and delegates
- * to it all state-specific work. The context communicates with the state object
- * via the state interface. The context exposes a setter for passing it a new
- * state object.
- */
-class DeviceContext {
- private:
-  IState* state_{};
-
+/// Context.
+class Device {
  public:
-  explicit DeviceContext(IState* state) { this->changeState(state); }
-
-  ~DeviceContext() { delete state_; }
-
-  void changeState(IState* state) {
-    std::cout << "[DeviceContext]: Changing state\n";
-
-    delete this->state_;  // delete nullptr has no effect
+  explicit Device(std::unique_ptr<DeviceState> initial)
+      : state_{std::move(initial)} {}
+
+  /// One tick of work: delegates to the current state.
+  void tick() {
+    state_->handle(*this);
+    if (next_state_) {
+      LOG_S("    transition " << state_->name() << " -> "
+                              << next_state_->name());
+      state_ = std::move(next_state_);  // safe: handle() has already returned
+    }
+  }
 
-    this->state_ = state;
-    this->state_->setContext(this);
+  /// Called by states to request a transition.
+  void transitionTo(std::unique_ptr<DeviceState> next) {
+    next_state_ = std::move(next);
   }
 
-  void operation() { this->state_->handle(); }
+  int startJob() { return ++jobs_; }
+
+ private:
+  std::unique_ptr<DeviceState> state_;
+  std::unique_ptr<DeviceState> next_state_;
+  int jobs_{0};
 };
 
-/**
- * Concrete States provide their own implementations for the state-specific
- * methods.
- */
-class IdeConcreteState : public AbstractState {
+class IdleState : public DeviceState {
  public:
-  void handle() override;
+  std::string name() const override { return "Idle"; }
+  void handle(Device& device) override;
 };
 
-class ProcessingConcreteState : public AbstractState {
+class ProcessingState : public DeviceState {
  public:
-  void handle() override;
+  std::string name() const override { return "Processing"; }
+  void handle(Device& device) override;
 };
 
-class ErrorConcreteState : public AbstractState {
+class ErrorState : public DeviceState {
  public:
-  void handle() override {
-    std::cout << "[Error] Device error! Reset required.\n";
-
-    // After recover => go Idle
-    this->ctx_->changeState(new IdeConcreteState());
+  std::string name() const override { return "Error"; }
+  void handle(Device& device) override {
+    LOG("  [Error] resetting the device");
+    device.transitionTo(std::make_unique<IdleState>());
   }
 };
 
-void IdeConcreteState::handle() {
-  std::cout << "[Ide] Device is idle. Waiting...\n";
-  this->ctx_->changeState(new ProcessingConcreteState());
+void IdleState::handle(Device& device) {
+  LOG("  [Idle] new job arrived");
+  device.transitionTo(std::make_unique<ProcessingState>());
 }
 
-void ProcessingConcreteState::handle() {
-  std::cout << "[Processing] Processing data...\n";
-  bool ok = true;  // Example processing result
-  static int index = 0;
-  index++;
-  ok = index % 2 == 0;
-  if (ok) {
-    // Back to idle after finishing job
-    this->ctx_->changeState(new IdeConcreteState());
+void ProcessingState::handle(Device& device) {
+  const int job = device.startJob();
+  const bool failed = job % 3 == 0;  // every third job fails in this simulation
+  LOG_S("  [Processing] job " << job << (failed ? " failed" : " done"));
+  if (failed) {
+    device.transitionTo(std::make_unique<ErrorState>());
   } else {
-    this->ctx_->changeState(new ErrorConcreteState());
+    device.transitionTo(std::make_unique<IdleState>());
   }
 }
 
-namespace client {
-void clientCode(DeviceContext* const device) {
-  device->operation();
-}
-}  // namespace client
 void run() {
-  auto* device = new DeviceContext(new IdeConcreteState());
-  for (int loop_idx = 0; loop_idx < 10; ++loop_idx)
-    client::clientCode(device);
-  delete device;
+  LOG_SECTION("A device moving through Idle -> Processing -> Error states");
+  Device device{std::make_unique<IdleState>()};
+  for (int tick = 0; tick < 8; ++tick) {
+    device.tick();
+  }
 }
-}  // namespace state
-}  // namespace
 
-#include "ExampleRegistry.h"
-
-class StateExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "State"; }
-  std::string description() const override { return "State Pattern Example"; }
-  void execute() override { state::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(StateExample);
\ No newline at end of file
+LAB_EXAMPLE("State",
+            "an object changes behavior with its state: one class per state") {
+  run();
+}
diff --git a/src/dp/behavioral/Strategy.cpp b/src/dp/behavioral/Strategy.cpp
index 88997c3..6aa2171 100644
--- a/src/dp/behavioral/Strategy.cpp
+++ b/src/dp/behavioral/Strategy.cpp
@@ -1,117 +1,138 @@
-// cppcheck-suppress-file [functionStatic]
-
-// Strategy is a behavioral design pattern that lets you define a family of
-// algorithms, put each of them into a separate class, and make their objects
-// interchangeable. Appicability:
-// (*)    when you want to use different variants of an algorithm within an
-// object and be able to switch from one algorithm to another during runtime.
-// (**)   when you have a lot of similar classes that only differ in the way
-// they execute some behavior.
-// (***)  when your class has a massive conditional statement that switches
-// between different variants of the same algorithm. UML:
-// docs/uml/patterns_behavioral_strategy.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Strategy (behavioral pattern)
+//
+// Defines a family of algorithms, puts each into its own class and makes them
+// interchangeable at run time.
+//
+// Problem:
+//   std::string exportDocument(const std::string& format) {
+//     if (format == "html") { ... } else if (format == "json") { ... } ...
+//   }
+//   - data (the document) and behavior (every export format) are mixed
+//   - each new format modifies this function (violates Open/Closed)
+// Solution: every format is a strategy; the context only holds the data and
+// the currently selected strategy.
+//
+// Use it when:
+//   - you need different variants of an algorithm and want to switch at run time
+//   - many classes only differ in how they execute some behavior
+//   - a class has a massive conditional selecting an algorithm
+//
+// Participants:
+//   Strategy          ExportStrategy interface
+//   ConcreteStrategy  HtmlExport, JsonExport, MarkdownExport
+//   Context           Document - uses a strategy through the interface
+//
+// Modern C++ alternative: store a std::function when a strategy is just one
+// function (shown at the end).
+//
+// UML: docs/uml/dp/behavioral_strategy.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <algorithm>
+#include <cctype>
+#include <functional>
+#include <iterator>
+#include <memory>
 #include <string>
 #include <utility>
-#include "Logger.h"
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace strategy {
-class IExportStrategy {
+
+/// Strategy interface.
+class ExportStrategy {
  public:
-  virtual ~IExportStrategy() = default;
-  virtual std::string executeExportData(const std::string& content) const = 0;
+  virtual ~ExportStrategy() = default;
+  virtual std::string exportText(const std::string& content) const = 0;
 };
 
-class ExportContext {
- private:
-  std::string content_;
-  IExportStrategy* strategy_;
-
+class HtmlExport : public ExportStrategy {
  public:
-  ~ExportContext() { delete strategy_; }
-
-  explicit ExportContext(std::string content,
-                         IExportStrategy* const strategy = nullptr)
-      : content_(std::move(content)), strategy_(strategy) {}
-
-  void setExportStrategy(IExportStrategy* const strategy) {
-    delete strategy_;
-    this->strategy_ = strategy;
+  std::string exportText(const std::string& content) const override {
+    return "<p>" + content + "</p>";
   }
+};
 
-  // The old approach using if-else for each format is commented out:
-  // if(format == "HTML") {
-  //     // export HTML
-  // } else if(format == "JSON") {
-  //     // export JSON
-  // } else if(format == "Markdown") {
-  //     // export Markdown
-  // }
-  //
-  // 1. This approach mixes data (Context) and behavior (export logic), which is
-  // hard to maintain.
-  // 2. Adding new formats requires modifying this function, violating the
-  // Open/Closed Principle.
-  // 3. Strategy Pattern allows each format to be a separate class, and Context
-  // only holds data.
-  // ======================================================================================
-  std::string exportDocument() const {
-    if (strategy_ != nullptr) {
-      return this->strategy_->executeExportData(this->content_);
-    }
-
-    LOG("Strategy isn't set");
-    return "";
+class JsonExport : public ExportStrategy {
+ public:
+  std::string exportText(const std::string& content) const override {
+    return R"({"content": ")" + content + "\"}";
   }
 };
 
-class JsonExportStrategy : public IExportStrategy {
+class MarkdownExport : public ExportStrategy {
  public:
-  std::string executeExportData(const std::string& content) const override {
-    return R"({"content": ")" + content + "\" }";
+  std::string exportText(const std::string& content) const override {
+    return "**" + content + "**";
   }
 };
 
-class HtmlExportStrategy : public IExportStrategy {
+/// Context.
+class Document {
  public:
-  std::string executeExportData(const std::string& content) const override {
-    return "<p>" + content + "</p>";
+  explicit Document(std::string content) : content_{std::move(content)} {}
+
+  void setExportStrategy(std::unique_ptr<ExportStrategy> strategy) {
+    strategy_ = std::move(strategy);
   }
-};
 
-void run() {
-  auto client_code = [](const ExportContext& ctx) {
-    LOG(ctx.exportDocument());
-  };
+  std::string exportDocument() const {
+    if (!strategy_) {
+      return "(no export strategy selected)";
+    }
+    return strategy_->exportText(content_);
+  }
+
+ private:
+  std::string content_;
+  std::unique_ptr<ExportStrategy> strategy_;
+};
 
-  auto* ctx = new ExportContext("This is the report content.");
-  client_code(*ctx);
+void classicStrategy() {
+  LOG_SECTION("Swapping strategy objects at run time");
+  Document report{"quarterly report"};
+  LOG_S("  none     : " << report.exportDocument());
 
-  LOG("===HTML Export===");
-  ctx->setExportStrategy(new HtmlExportStrategy());
-  client_code(*ctx);
+  report.setExportStrategy(std::make_unique<HtmlExport>());
+  LOG_S("  HTML     : " << report.exportDocument());
 
-  LOG("===JSON Export===");
-  ctx->setExportStrategy(new JsonExportStrategy());
-  client_code(*ctx);
+  report.setExportStrategy(std::make_unique<JsonExport>());
+  LOG_S("  JSON     : " << report.exportDocument());
 
-  delete ctx;
+  report.setExportStrategy(std::make_unique<MarkdownExport>());
+  LOG_S("  Markdown : " << report.exportDocument());
 }
-}  // namespace strategy
-}  // namespace
 
-#include "ExampleRegistry.h"
+void functionStrategy() {
+  LOG_SECTION("Lightweight strategies with std::function");
+  using Formatter = std::function<std::string(const std::string&)>;
+  const std::string content = "release notes";
+
+  Formatter upper = [](const std::string& text) {
+    std::string result;
+    std::transform(
+        text.begin(), text.end(), std::back_inserter(result),
+        [](unsigned char c) { return static_cast<char>(std::toupper(c)); });
+    return result;
+  };
+  Formatter quoted = [](const std::string& text) {
+    return "\"" + text + "\"";
+  };
 
-class StrategyExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Strategy"; }
-  std::string description() const override {
-    return "Strategy Pattern Example";
+  for (const auto& [name, format] :
+       {std::pair{"upper ", upper}, std::pair{"quoted", quoted}}) {
+    LOG_S("  " << name << " : " << format(content));
   }
-  void execute() override { strategy::run(); }
-};
+}
+
+}  // namespace
 
-REGISTER_EXAMPLE(StrategyExample);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Strategy",
+    "interchangeable algorithms behind an interface or a std::function") {
+  classicStrategy();
+  functionStrategy();
+}
diff --git a/src/dp/behavioral/TemplateMethod.cpp b/src/dp/behavioral/TemplateMethod.cpp
index c3ff44f..e458574 100644
--- a/src/dp/behavioral/TemplateMethod.cpp
+++ b/src/dp/behavioral/TemplateMethod.cpp
@@ -1,123 +1,98 @@
-// cppcheck-suppress-file [functionStatic]
-
-//  is a behavioral design pattern that defines the skeleton of an algorithm in
-//  the `superclass`
-// but lets `subclasses` override specific steps of the algorithm without
-// changing its structure. Appicability:
-// (*)    when you want to let clients extend only particular steps of an
-// algorithm, but not the whole algorithm or its structure.
-// (**)   when you have several classes that contain almost identical algorithms
-// with some minor differences.
-//        As a result, you might need to modify all classes when the algorithm
-//        changes.
-// (**)  when a behavior makes sense only in some classes of a class hierarchy,
-// but not in others. UML:
-// docs/uml/patterns_behavioral_templatemethod.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Template Method (behavioral pattern)
+//
+// Defines the skeleton of an algorithm in a base class and lets subclasses
+// override specific steps without changing the overall structure.
+//
+// Kinds of steps:
+//   - fixed steps     : implemented in the base class, not virtual
+//   - abstract steps  : pure virtual, every subclass MUST implement them
+//   - hooks           : virtual with a default, subclasses MAY override them
+//
+// Use it when:
+//   - several classes contain almost identical algorithms with small differences
+//   - clients should extend only particular steps, not the whole algorithm
+//
+// C++ note: the public template method is non-virtual and the customizable
+// steps are private virtual functions - the Non-Virtual Interface (NVI) idiom.
+//
+// UML: docs/uml/dp/behavioral_templatemethod.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <memory>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace template_method {
-class AbstractClass {
- public:
-  virtual ~AbstractClass() = default;
-  // Template Method (non-virtual => cannot be overridden)
-  // Defines the algorithm's skeleton and ensures subclasses cannot change the
-  // flow.
-  void templateMethod() {
-    baseOperation1();
-    abstractMethod1();
-    hookOperation1();
-
-    baseOperation2();
-    abstractMethod2();
-    hookOperation2();
-  }
 
- protected:
-  // 1. Base operations: These have full implementations and cannot be
-  // overridden.
-  void baseOperation1() {
-    // Common logic step 1
-    std::cout << "[AbstractClass]\t Executed base operation - 1\n";
-    dummy_++;
+/// Abstract class with the template method.
+class Beverage {
+ public:
+  virtual ~Beverage() = default;
+
+  /// The template method: fixed order, cannot be overridden.
+  void prepare() const {
+    boilWater();
+    brew();
+    pourInCup();
+    if (wantsCondiments()) {
+      addCondiments();
+    }
+    LOG("    ready!");
   }
 
-  void baseOperation2() {
-    // Common logic step 2
-    std::cout << "[AbstractClass]\t Executed base operation - 2\n";
-    dummy_++;
-  }
+ private:
+  // Fixed steps.
+  void boilWater() const { LOG("    boil water"); }
+  void pourInCup() const { LOG("    pour into cup"); }
 
-  // 2. Hook methods: Subclasses may override them to extend behavior, but
-  // overriding is optional.
-  virtual void hookOperation1() const {}
-  virtual void hookOperation2() const {}
+  // Abstract steps: subclasses must provide them.
+  virtual void brew() const = 0;
+  virtual void addCondiments() const = 0;
 
-  // 3. Abstract methods: Subclasses MUST provide implementations.
-  virtual void abstractMethod1() const = 0;
-  virtual void abstractMethod2() const = 0;
+  // Hook: optional customization point with a default.
+  virtual bool wantsCondiments() const { return true; }
+};
 
+class Coffee : public Beverage {
  private:
-  int dummy_{};
+  void brew() const override { LOG("    drip coffee through the filter"); }
+  void addCondiments() const override { LOG("    add sugar and milk"); }
 };
 
-class ConcreteClass1 : public AbstractClass {
- public:
-  void abstractMethod1() const override {
-    std::cout << "[ConcreteClass1]\t Implemented Operation - 2\n";
-  }
-
-  void abstractMethod2() const override {
-    std::cout << "[ConcreteClass1]\t Implemented Operation - 2\n";
-  }
-
-  void hookOperation1() const override {
-    std::cout << "[ConcreteClass1]\t Overridden Hook - 1\n";
-  }
+class Tea : public Beverage {
+ private:
+  void brew() const override { LOG("    steep the tea bag"); }
+  void addCondiments() const override { LOG("    add lemon"); }
 };
 
-class ConcreteClass2 : public AbstractClass {
- public:
-  void abstractMethod1() const override {
-    std::cout << "[ConcreteClass2]\t Implemented Operation - 2\n";
-  }
-
-  void abstractMethod2() const override {
-    std::cout << "[ConcreteClass2]\t Implemented Operation - 2\n";
-  }
+class BlackCoffee : public Coffee {
+ private:
+  bool wantsCondiments() const override {
+    return false;
+  }  // overrides only the hook
 };
 
-namespace client {
-void clientCode(AbstractClass* clazz) {
-  clazz->templateMethod();
-}
-}  // namespace client
 void run() {
-  std::cout << "\t[ConcreteClass1] Executed templateMethod\n";
-  AbstractClass* clazz1 = new ConcreteClass1();
-  client::clientCode(clazz1);
-
-  std::cout << "\t[ConcreteClass1] Executed templateMethod\n";
-  AbstractClass* clazz2 = new ConcreteClass2();
-  client::clientCode(clazz2);
-
-  delete clazz1;
-  delete clazz2;
+  LOG_SECTION("Same algorithm, different steps");
+  std::vector<std::pair<const char*, std::unique_ptr<Beverage>>> orders;
+  orders.emplace_back("Coffee", std::make_unique<Coffee>());
+  orders.emplace_back("Tea", std::make_unique<Tea>());
+  orders.emplace_back("Black coffee (hook overridden)",
+                      std::make_unique<BlackCoffee>());
+
+  for (const auto& [name, beverage] : orders) {
+    LOG_S("  " << name << ':');
+    beverage->prepare();  // client code only calls the template method
+  }
 }
-}  // namespace template_method
-}  // namespace
 
-#include "ExampleRegistry.h"
-
-class TemplateMethodExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "TemplateMethod"; }
-  std::string description() const override {
-    return "TemplateMethod Pattern Example";
-  }
-  void execute() override { template_method::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(TemplateMethodExample);
\ No newline at end of file
+LAB_EXAMPLE(
+    "TemplateMethod",
+    "algorithm skeleton in a base class, steps and hooks in subclasses") {
+  run();
+}
diff --git a/src/dp/behavioral/Visitor.cpp b/src/dp/behavioral/Visitor.cpp
index 1cf1ca6..3bffdfc 100644
--- a/src/dp/behavioral/Visitor.cpp
+++ b/src/dp/behavioral/Visitor.cpp
@@ -1,249 +1,212 @@
-// Visitor is a behavioral design pattern that lets you separate algorithms from
-// the objects on which they operate. Appicability:
-// (*)   when you need to perform an operation on all elements of a complex
-// object structure (for example, an object tree, document).
-// (**)  to clean up the business logic of auxiliary behaviors.
-// (**)  when a behavior makes sense only in some classes of a class hierarchy,
-// but not in others. UML: docs/uml/patterns_behavioral_visitor.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Visitor (behavioral pattern)
+//
+// Separates operations from the objects they work on. New operations become
+// new visitor classes; the element classes stay untouched.
+//
+// Problem: adding exportHtml(), exportJson(), exportMarkdown()... to every
+// element class means modifying ALL of them for each new format, and each
+// element collects unrelated responsibilities.
+// Solution: each element only implements accept(visitor), which calls the
+// visitor method for its concrete type ("double dispatch").
+//
+// Use it when:
+//   - you need many unrelated operations on a stable set of element types
+//   - an operation only makes sense for some classes of a hierarchy
+// Trade-off: adding a new ELEMENT type requires changing every visitor.
+//
+// Participants:
+//   Visitor          interface with one visit method per element type
+//   ConcreteVisitor  HtmlExporter, JsonExporter, WordCounter
+//   Element          accept(Visitor&)
+//   ConcreteElement  Paragraph, Image, Table
+//
+// Modern C++ alternative for a closed set of types: std::variant + std::visit.
+//
+// UML: docs/uml/dp/behavioral_visitor.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <memory>
+#include <sstream>
 #include <string>
 #include <utility>
+#include <variant>
 #include <vector>
 
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
 namespace {
-namespace visitor {
-class TextConcreteElement;
-class ImageConcreteElement;
-class TableConcreteElement;
-
-/**
- * The Visitor interface declares a set of visiting methods that can take
- * concrete elements of an object structure as arguments. These methods may have
- * the same names if the program is written in a language that supports
- * overloading, but the type of their parameters must be different.
- */
-class IVisitor {
- public:
-  virtual ~IVisitor() = default;
 
-  virtual void visitText(const TextConcreteElement* t) = 0;
-  virtual void visitImage(const ImageConcreteElement* i) = 0;
-  virtual void visitTable(const TableConcreteElement* t) = 0;
-};
+namespace classic {
+
+class Paragraph;
+class Image;
+class Table;
 
-/**
- * The Element interface declares a method for “accepting” visitors.
- * This method should have one parameter declared with the type of the visitor
- * interface.
- */
-class IElement {
+/// Visitor interface.
+class Visitor {
  public:
-  virtual ~IElement() = default;
-  // [P1]
-  // if we implement exportHtml(), exportMarkdown(), exportJson(), etc.. here,
-  // every time we add a new export format we must modify ALL element classes.
-  // This violates the Open/Closed Principle
-  // and makes each element hold multiple unrelated behaviors.
-  // => Use `Visitor Pattern` to separate export logic from the element classes.
-
-  virtual void accept(IVisitor* visitor) = 0;
+  virtual ~Visitor() = default;
+  virtual void visit(const Paragraph& paragraph) = 0;
+  virtual void visit(const Image& image) = 0;
+  virtual void visit(const Table& table) = 0;
 };
 
-/**
- * The complex object structure
- */
-class DocumentConcreteStructure {
- private:
-  std::vector<IElement*> elements_;
-
+/// Element interface.
+class Element {
  public:
-  ~DocumentConcreteStructure() {
-    for (IElement* e : this->elements_) {
-      delete e;
-    }
-    elements_.clear();
-  }
-
-  void add(IElement* e) { elements_.push_back(e); }
-
-  std::vector<IElement*>& get() { return this->elements_; };
+  virtual ~Element() = default;
+  virtual void accept(Visitor& visitor) const = 0;
 };
 
-/**
- * Each Concrete Element must implement the acceptance method.
- * The purpose of this method is to redirect the call to the proper visitor’s
- * method corresponding to the current element class. Be aware that even if a
- * base element class implements this method, all subclasses must still override
- * this method in their own classes and call the appropriate method on the
- * visitor object.
- */
-class TextConcreteElement : public IElement {
- private:
-  std::string content_;
-
+class Paragraph : public Element {
  public:
-  explicit TextConcreteElement(std::string c) : content_{std::move(c)} {};
-  std::string getContent() const { return this->content_; }
-
-  void accept(IVisitor* visitor) override { visitor->visitText(this); }
-};
+  explicit Paragraph(std::string text) : text_{std::move(text)} {}
+  const std::string& text() const { return text_; }
+  // Second dispatch: `*this` has the static type Paragraph here.
+  void accept(Visitor& visitor) const override { visitor.visit(*this); }
 
-class ImageConcreteElement : public IElement {
  private:
-  std::string path_;
+  std::string text_;
+};
 
+class Image : public Element {
  public:
-  explicit ImageConcreteElement(std::string p) : path_{std::move(p)} {};
+  explicit Image(std::string path) : path_{std::move(path)} {}
+  const std::string& path() const { return path_; }
+  void accept(Visitor& visitor) const override { visitor.visit(*this); }
 
-  std::string getPath() const { return this->path_; }
-
-  void accept(IVisitor* visitor) override { visitor->visitImage(this); }
-};
-
-class TableConcreteElement : public IElement {
  private:
-  int rows_, cols_;
+  std::string path_;
+};
 
+class Table : public Element {
  public:
-  TableConcreteElement(int r, int c) : rows_{r}, cols_{c} {};
-  int getRows() const { return this->rows_; }
-  int getCols() const { return this->cols_; }
+  Table(int rows, int columns) : rows_{rows}, columns_{columns} {}
+  int rows() const { return rows_; }
+  int columns() const { return columns_; }
+  void accept(Visitor& visitor) const override { visitor.visit(*this); }
 
-  void accept(IVisitor* visitor) override { visitor->visitTable(this); }
+ private:
+  int rows_;
+  int columns_;
 };
 
-/**
- * Each Concrete Visitor implements several versions of the same behaviors,
- * tailored for different concrete element classes.
- */
-class HtmlExportConcreteVisitor : public IVisitor {
-  void visitText(const TextConcreteElement* t) override {
-    std::cout << "<p>" + t->getContent() + "</p>\n";
+class HtmlExporter : public Visitor {
+ public:
+  void visit(const Paragraph& paragraph) override {
+    LOG_S("    <p>" << paragraph.text() << "</p>");
   }
-
-  void visitImage(const ImageConcreteElement* i) override {
-    std::cout << "<img src=\"" + i->getPath() + "\" />\n";
+  void visit(const Image& image) override {
+    LOG_S("    <img src=\"" << image.path() << "\"/>");
   }
-
-  void visitTable(const TableConcreteElement* t) override {
-    std::cout << "<table>\n";
-    for (int r = 0; r < t->getRows(); ++r) {
-      std::cout << "  <tr>";
-      for (int c = 0; c < t->getCols(); ++c) {
-        std::cout << "<td>cell</td>";
-      }
-      std::cout << "</tr>\n";
-    }
-    std::cout << "</table>\n";
+  void visit(const Table& table) override {
+    LOG_S("    <table rows=\"" << table.rows() << "\" cols=\""
+                               << table.columns() << "\"/>");
   }
 };
 
-class JsonExportConcreteVisitor : public IVisitor {
-  void visitText(const TextConcreteElement* t) override {
-    std::cout << R"({ "type": "text", "content": ")" << t->getContent()
-              << "\" }\n";
+class JsonExporter : public Visitor {
+ public:
+  void visit(const Paragraph& paragraph) override {
+    LOG_S(R"(    {"type": "text", "content": ")" << paragraph.text() << "\"}");
   }
-  void visitImage(const ImageConcreteElement* i) override {
-    std::cout << R"({ "type": "image", "path": ")" << i->getPath() << "\" }\n";
+  void visit(const Image& image) override {
+    LOG_S(R"(    {"type": "image", "path": ")" << image.path() << "\"}");
   }
-
-  void visitTable(const TableConcreteElement* t) override {
-    std::cout << R"({ "type": "table", "rows": )" << t->getRows()
-              << ", \"cols\": " << t->getCols() << " }\n";
+  void visit(const Table& table) override {
+    LOG_S(R"(    {"type": "table", "rows": )"
+          << table.rows() << ", \"cols\": " << table.columns() << '}');
   }
 };
 
-class MarkdownExportConcreteVisitor : public IVisitor {
-  void visitText(const TextConcreteElement* t) override {
-    std::cout << t->getContent() << "\n\n";
+/// A visitor that computes something instead of printing.
+class WordCounter : public Visitor {
+ public:
+  void visit(const Paragraph& paragraph) override {
+    std::istringstream words(paragraph.text());
+    for (std::string word; words >> word;) {
+      ++count_;
+    }
   }
+  void visit(const Image& /*image*/) override {}
+  void visit(const Table& /*table*/) override {}
+  int count() const { return count_; }
 
-  void visitImage(const ImageConcreteElement* i) override {
-    std::cout << "![](" << i->getPath() << ")\n\n";
-  }
+ private:
+  int count_{0};
+};
 
-  void visitTable(const TableConcreteElement* t) override {
-    for (int r = 0; r < t->getRows(); ++r) {
-      for (int c = 0; c < t->getCols(); ++c) {
-        std::cout << "| cell ";
-      }
-      std::cout << "|\n";
+void run() {
+  std::vector<std::unique_ptr<Element>> document;
+  document.push_back(
+      std::make_unique<Paragraph>("Visitor separates data from behavior."));
+  document.push_back(std::make_unique<Image>("diagram.png"));
+  document.push_back(std::make_unique<Table>(3, 4));
+  document.push_back(
+      std::make_unique<Paragraph>("New exports need no element changes."));
+
+  const auto apply = [&document](Visitor& visitor) {
+    for (const auto& element : document) {
+      element->accept(visitor);
     }
-    std::cout << "\n";
-  }
-};
+  };
 
-/**
- * clients aren’t aware of all the concrete element classes because they work
- * with objects from that collection via some abstract interface.
- */
-namespace client {
-void clientCode(DocumentConcreteStructure* const doc, IVisitor* const visitor) {
-  // [P2] Instead of adding exportHtml(), exportMarkdown(), exportJson() in each
-  // element, we use the Visitor pattern to separate data from behavior. This
-  // avoids bloating element classes with multiple unrelated functions and makes
-  // it easier to add new export formats without modifying the elements.
-  for (IElement* ele : doc->get()) {
-    ele->accept(visitor);
-  }
+  LOG_SECTION("HTML export");
+  HtmlExporter html;
+  apply(html);
+
+  LOG_SECTION("JSON export");
+  JsonExporter json;
+  apply(json);
+
+  LOG_SECTION("Word count (a visitor that collects data)");
+  WordCounter counter;
+  apply(counter);
+  LOG_S("    words in paragraphs: " << counter.count());
 }
-}  // namespace client
+
+}  // namespace classic
+
+namespace with_variant {
+
+struct Paragraph {
+  std::string text;
+};
+struct Image {
+  std::string path;
+};
+
+using Element = std::variant<Paragraph, Image>;
+
+/// Helper that merges several lambdas into one overloaded function object.
+template <typename... Lambdas>
+struct Overloaded : Lambdas... {
+  using Lambdas::operator()...;
+};
+
 void run() {
-  auto* document = new DocumentConcreteStructure();
-  // Add images
-  document->add(new ImageConcreteElement("header.png"));
-  document->add(new ImageConcreteElement("diagram1.png"));
-  document->add(new ImageConcreteElement("chart.png"));
-
-  // Add text paragraphs
-  document->add(new TextConcreteElement(
-      "Introduction: This document demonstrates the Visitor pattern."));
-  document->add(
-      new TextConcreteElement("Section 1: Visitor allows adding new operations "
-                              "without modifying elements."));
-  document->add(new TextConcreteElement(
-      "Section 2: Elements are data holders, visitors implement behaviors."));
-
-  // Add tables
-  document->add(
-      new TableConcreteElement(3, 4));  // e.g., 3 rows x 4 columns table
-  document->add(new TableConcreteElement(2, 2));  // smaller table
-  document->add(new TableConcreteElement(4, 3));  // another table
-
-  // Add more text
-  document->add(new TextConcreteElement(
-      "Conclusion: Using Visitor pattern makes code open for extension but "
-      "closed for modification."));
-
-  IVisitor* visitor = new HtmlExportConcreteVisitor();
-  std::cout << " ===HTML Export ===\n";
-  client::clientCode(document, visitor);
-  std::cout << " ==================\n";
-
-  visitor = new JsonExportConcreteVisitor();
-  std::cout << " ===JSON Export ===\n";
-  client::clientCode(document, visitor);
-  std::cout << " ==================\n";
-
-  visitor = new MarkdownExportConcreteVisitor();
-  std::cout << " ===MD Export ===\n";
-  client::clientCode(document, visitor);
-  std::cout << " ==================\n";
-  delete visitor;
-  delete document;
+  LOG_SECTION("Modern alternative: std::variant + std::visit");
+  const std::vector<Element> document{Paragraph{"no base classes needed"},
+                                      Image{"photo.jpg"}};
+  for (const Element& element : document) {
+    std::visit(
+        Overloaded{
+            [](const Paragraph& p) { LOG_S("    paragraph: " << p.text); },
+            [](const Image& i) { LOG_S("    image: " << i.path); },
+        },
+        element);
+  }
 }
-}  // namespace visitor
-}  // namespace
 
-#include "ExampleRegistry.h"
+}  // namespace with_variant
 
-class VisitorExample : public IExample {
- public:
-  std::string group() const override { return "dp/behavioral"; }
-  std::string name() const override { return "Visitor"; }
-  std::string description() const override { return "Visitor Pattern Example"; }
-  void execute() override { visitor::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(VisitorExample);
\ No newline at end of file
+LAB_EXAMPLE("Visitor",
+            "add operations without changing element classes; std::variant "
+            "alternative") {
+  classic::run();
+  with_variant::run();
+}
diff --git a/src/dp/creational/AbstractFactory.cpp b/src/dp/creational/AbstractFactory.cpp
index ffb5626..0fe31fd 100644
--- a/src/dp/creational/AbstractFactory.cpp
+++ b/src/dp/creational/AbstractFactory.cpp
@@ -1,162 +1,162 @@
-// cppcheck-suppress-file [functionStatic]
-
-// Abstract Factory — create families of related products without concrete types.
+// -----------------------------------------------------------------------------
+// Abstract Factory (creational pattern)
+//
+// Creates FAMILIES of related objects without naming their concrete classes.
+// One factory produces matching products, so products from different families
+// cannot be mixed by accident.
+//
+// Example: a toolchain installer. Each operating system needs its own GDB and
+// CMake installation commands; a Linux factory only creates Linux products.
+//
+// Flow:
+//   1. Product interfaces            GdbProduct, CMakeProduct
+//   2. Concrete products per family  Linux / Windows / MacOs variants
+//   3. Abstract factory              ToolchainFactory
+//   4. One concrete factory per family
+//   5. The client receives one factory and uses it for every product
 //
-// Flow in this file:
-//   1. Define product interfaces             -> IGdbProduct, ICMakeProduct
-//   2. Implement concrete products per OS    -> Linux / Windows / MacOs variants
-//   3. Define an abstract factory            -> IProductAbstractFactory
-//   4. Implement concrete factories          -> one factory = one matching family
-//   5. Client uses one factory for all products -> products stay consistent (same OS)
+// Factory Method vs Abstract Factory: a factory method creates ONE product; an
+// abstract factory groups several factory methods for a family of products.
+//
+// UML: docs/uml/dp/creational_abstractfactory.drawio.svg
+// -----------------------------------------------------------------------------
 
 #include <memory>
-#include <string>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace abstract_factory {
 
-/// @class Product Interface
-/// @brief Declares the operations that all concrete products must implement
-class IGdbProduct {
+// 1. Product interfaces
+class GdbProduct {
  public:
-  virtual ~IGdbProduct() = default;
-  virtual void launch() const = 0;
+  virtual ~GdbProduct() = default;
+  virtual void install() const = 0;
 };
 
-/// @brief The concrete product
-class LinuxGdbProduct : public IGdbProduct {
+class CMakeProduct {
  public:
-  void launch() const override {
-    LOG("sudo apt update && sudo apt install -y gdb && gdb --version");
-  }
+  virtual ~CMakeProduct() = default;
+  virtual void install() const = 0;
 };
 
-class WindowsGdbProduct : public IGdbProduct {
+// 2. Concrete products, one set per family
+class LinuxGdb : public GdbProduct {
  public:
-  void launch() const override {
-    LOG("pacman -Syu mingw-w64-x86_64-gdb && gdb --version");
+  void install() const override {
+    LOG("    sudo apt install -y gdb && gdb --version");
   }
 };
-
-class MacOsGdbProduct : public IGdbProduct {
+class WindowsGdb : public GdbProduct {
  public:
-  void launch() const override { LOG("brew install gdb && gdb --version"); }
+  void install() const override {
+    LOG("    pacman -S mingw-w64-x86_64-gdb && gdb --version");
+  }
 };
-
-class ICMakeProduct {
+class MacOsGdb : public GdbProduct {
  public:
-  virtual ~ICMakeProduct() = default;
-  virtual void launch() const = 0;
+  void install() const override {
+    LOG("    brew install gdb && gdb --version");
+  }
 };
 
-class LinuxCMakeProduct : public ICMakeProduct {
+class LinuxCMake : public CMakeProduct {
  public:
-  void launch() const override {
-    LOG("sudo apt update && sudo apt install -y cmake && cmake --version");
+  void install() const override {
+    LOG("    sudo apt install -y cmake && cmake --version");
   }
 };
-
-class WindowsCMakeProduct : public ICMakeProduct {
+class WindowsCMake : public CMakeProduct {
  public:
-  void launch() const override { LOG("pacman -Syu cmake && cmake --version"); }
+  void install() const override {
+    LOG("    pacman -S mingw-w64-x86_64-cmake && cmake --version");
+  }
 };
-
-class MacOsCMakeProduct : public ICMakeProduct {
+class MacOsCMake : public CMakeProduct {
  public:
-  void launch() const override {
-    LOG("\tbrew install cmake && cmake --version");
+  void install() const override {
+    LOG("    brew install cmake && cmake --version");
   }
 };
 
-/// @class Abstract Factory
-/// @brief Provide abstract interface for creating a family of products
-class IProductAbstractFactory {
+// 3. Abstract factory
+class ToolchainFactory {
  public:
-  virtual ~IProductAbstractFactory() = default;
-  virtual std::unique_ptr<IGdbProduct> create_gdb_product() = 0;
-  virtual std::unique_ptr<ICMakeProduct> create_cmake_product() = 0;
+  virtual ~ToolchainFactory() = default;
+  virtual std::unique_ptr<GdbProduct> createGdb() const = 0;
+  virtual std::unique_ptr<CMakeProduct> createCMake() const = 0;
 };
 
-/// @class Concrete Factory
-/// @brief concrete factory create a family of products and client uses
-/// one of these factories so it never has to instantiate a product object
-class WindowsProductFactory : public IProductAbstractFactory {
+// 4. Concrete factories
+class LinuxToolchainFactory : public ToolchainFactory {
  public:
-  std::unique_ptr<IGdbProduct> create_gdb_product() override {
-    return std::make_unique<WindowsGdbProduct>();
+  std::unique_ptr<GdbProduct> createGdb() const override {
+    return std::make_unique<LinuxGdb>();
   }
-  std::unique_ptr<ICMakeProduct> create_cmake_product() override {
-    return std::make_unique<WindowsCMakeProduct>();
+  std::unique_ptr<CMakeProduct> createCMake() const override {
+    return std::make_unique<LinuxCMake>();
   }
 };
 
-class LinuxProductFactory : public IProductAbstractFactory {
+class WindowsToolchainFactory : public ToolchainFactory {
  public:
-  std::unique_ptr<IGdbProduct> create_gdb_product() override {
-    return std::make_unique<LinuxGdbProduct>();
+  std::unique_ptr<GdbProduct> createGdb() const override {
+    return std::make_unique<WindowsGdb>();
   }
-
-  std::unique_ptr<ICMakeProduct> create_cmake_product() override {
-    return std::make_unique<LinuxCMakeProduct>();
+  std::unique_ptr<CMakeProduct> createCMake() const override {
+    return std::make_unique<WindowsCMake>();
   }
 };
 
-class MacOsProductFactory : public IProductAbstractFactory {
+class MacOsToolchainFactory : public ToolchainFactory {
  public:
-  std::unique_ptr<IGdbProduct> create_gdb_product() override {
-    return std::make_unique<MacOsGdbProduct>();
+  std::unique_ptr<GdbProduct> createGdb() const override {
+    return std::make_unique<MacOsGdb>();
   }
-
-  std::unique_ptr<ICMakeProduct> create_cmake_product() override {
-    return std::make_unique<MacOsCMakeProduct>();
+  std::unique_ptr<CMakeProduct> createCMake() const override {
+    return std::make_unique<MacOsCMake>();
   }
 };
 
-/// @brief Factory selector
-/// static redudant inside anonymous namespace
-std::unique_ptr<IProductAbstractFactory> create_product_factory(
-    const std::string& os) {
+/// Picks the family once, e.g. from configuration. Returns nullptr if unknown.
+std::unique_ptr<ToolchainFactory> makeFactory(std::string_view os) {
   if (os == "linux") {
-    return std::make_unique<LinuxProductFactory>();
+    return std::make_unique<LinuxToolchainFactory>();
   }
   if (os == "windows") {
-    return std::make_unique<WindowsProductFactory>();
+    return std::make_unique<WindowsToolchainFactory>();
   }
   if (os == "macos") {
-    return std::make_unique<MacOsProductFactory>();
+    return std::make_unique<MacOsToolchainFactory>();
   }
-  LOG("OS not support yet - " + os);
-
   return nullptr;
 }
 
-void run() {
-  LOG("Abstract Factory Pattern Example");
-
-  auto client_code = [](IProductAbstractFactory* f) {
-    auto cmake = f->create_cmake_product();
-    auto gdb = f->create_gdb_product();
-    cmake->launch();
-    gdb->launch();
-  };
-
-  const std::string os = "linux";
-  auto factory = create_product_factory(os);
-  client_code(factory.get());
+// 5. Client code: depends only on the abstract interfaces.
+void installToolchain(const ToolchainFactory& factory) {
+  const auto cmake = factory.createCMake();
+  const auto gdb = factory.createGdb();
+  cmake->install();
+  gdb->install();  // guaranteed to belong to the same family as cmake
 }
-}  // namespace abstract_factory
-}  // namespace
 
-class AbstractFactoryExample : public IExample {
- public:
-  std::string group() const override { return "dp/creational"; }
-  std::string name() const override { return "AbstractFactory"; }
-  std::string description() const override {
-    return "AbstractFactory Pattern Example";
+void run() {
+  for (const std::string_view os : {"linux", "windows", "macos", "solaris"}) {
+    LOG_SECTION(os);
+    const std::unique_ptr<ToolchainFactory> factory = makeFactory(os);
+    if (!factory) {
+      LOG_S("    no toolchain factory for '" << os << "'");
+      continue;
+    }
+    installToolchain(*factory);
   }
-  void execute() override { abstract_factory::run(); }
-};
+}
 
-REGISTER_EXAMPLE(AbstractFactoryExample);
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE("AbstractFactory",
+            "create families of related products that always match") {
+  run();
+}
diff --git a/src/dp/creational/Builder.cpp b/src/dp/creational/Builder.cpp
index ae861a2..e1545fc 100644
--- a/src/dp/creational/Builder.cpp
+++ b/src/dp/creational/Builder.cpp
@@ -1,150 +1,216 @@
-// cppcheck-suppress-file [functionStatic]
-
-// Flow in this file:
-//   1. Define the product being built        -> Product (parts list)
-//   2. Define a builder interface            -> IBuilder (produce_part_N / build)
-//   3. Share common builder state            -> AbstractBuilder (reset / product_)
-//   4. Implement concrete builders           -> SimpleBuilder / ComplexBuilder
-//   5. Client chains steps, then build()     -> same steps, different representations
-
+// -----------------------------------------------------------------------------
+// Builder (creational pattern)
+//
+// Constructs a complex object step by step. The same construction process can
+// create different representations.
+//
+// Problem: a constructor with many (often optional) parameters -
+//   House(walls, doors, windows, roof, garage, pool, garden, ...)
+// is hard to read and easy to call with arguments in the wrong order.
+//
+// Participants:
+//   Product          House
+//   Builder          HouseBuilder interface: one method per step
+//   ConcreteBuilder  WoodenHouseBuilder, StoneHouseBuilder
+//   Director         defines the ORDER of steps for common configurations
+//
+// The second part shows the "fluent builder" that is common in C++ code:
+// chained setters and a build() that validates the result.
+//
+// UML: docs/uml/dp/creational_builder.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <map>
 #include <memory>
-#include <ostream>
-#include <sstream>
+#include <stdexcept>
 #include <string>
+#include <utility>
 #include <vector>
-#include "Logger.h"
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace builder_pattern {
-class Product {
- private:
-  std::vector<std::string> parts_;
 
+namespace classic {
+
+/// Product.
+class House {
  public:
-  void add_part(const std::string& part) { parts_.push_back(part); }
-
-  void print() const {
-    LOG("Product parts: ");
-    std::ostringstream oss;
-    for (size_t i = 0; i < parts_.size(); ++i) {
-      oss << parts_[i];
-      if (i + 1 < parts_.size()) {
-        oss << ", ";
-      }
+  void addPart(std::string part) { parts_.push_back(std::move(part)); }
+
+  std::string describe() const {
+    std::string text;
+    for (const std::string& part : parts_) {
+      text += (text.empty() ? "" : ", ") + part;
     }
-    LOG(oss.str());
+    return text.empty() ? "(empty)" : text;
   }
+
+ private:
+  std::vector<std::string> parts_;
 };
 
-/// @class Builder Interface
-/// @brief specifics methods for creating the different parts
-class IBuilder {
+/// Builder interface.
+class HouseBuilder {
  public:
-  virtual ~IBuilder() = default;
-  virtual IBuilder& reset() = 0;
-  virtual IBuilder& produce_part_1() = 0;
-  virtual IBuilder& produce_part_2() = 0;
-  virtual IBuilder& produce_part_3() = 0;
-
-  virtual std::unique_ptr<Product> build() = 0;
-};
+  virtual ~HouseBuilder() = default;
+  virtual void buildWalls() = 0;
+  virtual void buildRoof() = 0;
+  virtual void buildGarage() = 0;
+  virtual void buildPool() = 0;
+
+  /// Hands out the finished product and starts a fresh one, so the builder
+  /// can be reused safely.
+  std::unique_ptr<House> result() {
+    auto finished = std::move(house_);
+    house_ = std::make_unique<House>();
+    return finished;
+  }
 
-class AbstractBuilder : public IBuilder {
  protected:
-  std::unique_ptr<Product> product_;
-
- public:
-  explicit AbstractBuilder() : product_{std::make_unique<Product>()} {}
+  House& house() { return *house_; }
 
-  AbstractBuilder(const AbstractBuilder&) = delete;
-  AbstractBuilder& operator=(const AbstractBuilder&) = delete;
+ private:
+  std::unique_ptr<House> house_ = std::make_unique<House>();
+};
 
-  AbstractBuilder(AbstractBuilder&&) = default;
-  AbstractBuilder& operator=(AbstractBuilder&&) = default;
+class WoodenHouseBuilder : public HouseBuilder {
+ public:
+  void buildWalls() override { house().addPart("wooden walls"); }
+  void buildRoof() override { house().addPart("shingle roof"); }
+  void buildGarage() override { house().addPart("wooden carport"); }
+  void buildPool() override { house().addPart("above-ground pool"); }
+};
 
-  /// @brief the child classes are no longer override this function
-  IBuilder& reset() final {
-    product_ = std::make_unique<Product>();
-    return *this;
-  }
+class StoneHouseBuilder : public HouseBuilder {
+ public:
+  void buildWalls() override { house().addPart("stone walls"); }
+  void buildRoof() override { house().addPart("clay tile roof"); }
+  void buildGarage() override { house().addPart("stone garage"); }
+  void buildPool() override { house().addPart("in-ground pool"); }
 };
 
-/// @class Concrete Builder
-class SimpleBuilder : public AbstractBuilder {
+/// Director: knows the recipes, not the materials.
+class Director {
  public:
-  IBuilder& produce_part_1() override {
-    product_->add_part("PART1");
-    return *this;
+  static void buildMinimal(HouseBuilder& builder) {
+    builder.buildWalls();
+    builder.buildRoof();
   }
 
-  IBuilder& produce_part_2() override {
-    product_->add_part("PART2");
-    return *this;
+  static void buildLuxury(HouseBuilder& builder) {
+    builder.buildWalls();
+    builder.buildRoof();
+    builder.buildGarage();
+    builder.buildPool();
   }
+};
 
-  IBuilder& produce_part_3() override {
-    product_->add_part("PART3");
-    return *this;
+void run() {
+  LOG_SECTION("Director + builders: same steps, different representations");
+  WoodenHouseBuilder wood;
+  StoneHouseBuilder stone;
+
+  Director::buildMinimal(wood);
+  LOG_S("  minimal wooden house: " << wood.result()->describe());
+
+  Director::buildLuxury(wood);  // the builder was reset by result()
+  LOG_S("  luxury wooden house : " << wood.result()->describe());
+
+  Director::buildLuxury(stone);
+  LOG_S("  luxury stone house  : " << stone.result()->describe());
+
+  stone.buildWalls();  // clients can also drive a builder without a director
+  stone.buildPool();
+  LOG_S("  custom stone house  : " << stone.result()->describe());
+}
+
+}  // namespace classic
+
+namespace fluent {
+
+class HttpRequest {
+ public:
+  class Builder;
+
+  std::string describe() const {
+    std::string text = method_ + " " + url_;
+    for (const auto& [name, value] : headers_) {
+      text += "\n      " + name + ": " + value;
+    }
+    if (!body_.empty()) {
+      text += "\n      body: " + body_;
+    }
+    return text;
   }
 
-  std::unique_ptr<Product> build() override { return std::move(product_); }
+ private:
+  HttpRequest() = default;  // only the Builder can create requests
+  std::string method_ = "GET";
+  std::string url_;
+  std::map<std::string, std::string> headers_;
+  std::string body_;
 };
 
-class ComplexBuilder : public AbstractBuilder {
+class HttpRequest::Builder {
  public:
-  IBuilder& produce_part_1() override {
-    product_->add_part("PART_1-X9a7Fq!2@Lm#48Z");
+  explicit Builder(std::string url) { request_.url_ = std::move(url); }
+
+  // Each setter returns *this, so calls can be chained.
+  Builder& method(std::string method) {
+    request_.method_ = std::move(method);
     return *this;
   }
-
-  IBuilder& produce_part_2() override {
-    product_->add_part("PART_2-X9a7Fq!2@Lm#48Z");
+  Builder& header(std::string name, std::string value) {
+    request_.headers_[std::move(name)] = std::move(value);
     return *this;
   }
-
-  IBuilder& produce_part_3() override {
-    product_->add_part("PART_3-X9a7Fq!2@Lm#48Z");
+  Builder& body(std::string body) {
+    request_.body_ = std::move(body);
     return *this;
   }
 
-  std::unique_ptr<Product> build() override { return std::move(product_); }
+  /// Validates before handing out the product.
+  HttpRequest build() const {
+    if (request_.url_.rfind("http", 0) != 0) {
+      throw std::invalid_argument("URL must start with http: " + request_.url_);
+    }
+    if (request_.method_ == "GET" && !request_.body_.empty()) {
+      throw std::invalid_argument("a GET request must not have a body");
+    }
+    return request_;
+  }
+
+ private:
+  HttpRequest request_;
 };
 
 void run() {
-  auto client_code = [](IBuilder* const builder) {
-    // product 1
-    auto p1 =
-        (*builder).produce_part_1().produce_part_2().produce_part_3().build();
-    p1->print();
-
-    // product 2
-    auto p2 = (*builder).reset().produce_part_1().build();
-    p2->print();
-  };
-
-  {
-    LOG("ConcreteBuilder: Simple");
-    auto builder = std::make_unique<SimpleBuilder>();
-    client_code(builder.get());
-  }
-  {
-    LOG("ConcreteBuilder: Complex");
-    IBuilder* builder = new ComplexBuilder();
-    client_code(builder);
-    delete builder;
+  LOG_SECTION("Fluent builder with validation");
+  const HttpRequest request =
+      HttpRequest::Builder("https://api.example.com/users")
+          .method("POST")
+          .header("Content-Type", "application/json")
+          .header("Authorization", "Bearer token")
+          .body(R"({"name": "Ada"})")
+          .build();
+  LOG_S("  " << request.describe());
+
+  try {
+    HttpRequest::Builder("https://example.com").body("oops").build();
+  } catch (const std::invalid_argument& e) {
+    LOG_S("  build() rejected an invalid request: " << e.what());
   }
 }
-}  // namespace builder_pattern
-}  // namespace
 
-class BuilderExample : public IExample {
- public:
-  std::string group() const override { return "dp/creational"; }
-  std::string name() const override { return "Builder"; }
-  std::string description() const override { return "Builder Pattern Example"; }
-  void execute() override { builder_pattern::run(); }
-};
+}  // namespace fluent
 
-REGISTER_EXAMPLE(BuilderExample);
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE("Builder",
+            "step-by-step construction with builders, a director and a fluent "
+            "builder") {
+  classic::run();
+  fluent::run();
+}
diff --git a/src/dp/creational/FactoryMethod.cpp b/src/dp/creational/FactoryMethod.cpp
index 5c13432..f835bfa 100644
--- a/src/dp/creational/FactoryMethod.cpp
+++ b/src/dp/creational/FactoryMethod.cpp
@@ -1,143 +1,133 @@
-// cppcheck-suppress-file [functionStatic]
-
-// Flow in this file:
-//   1. Define a product interface            -> IGdbProduct
-//   2. Implement concrete products           -> Linux / Windows / MacOs Gdb
-//   3. Define a creator interface            -> IGdbFactory (+ AbstractGdbFactory)
-//   4. Implement concrete creators           -> Linux / Windows / MacOs factories
-//   5. Client picks a factory, then uses it  -> never constructs products directly
+// -----------------------------------------------------------------------------
+// Factory Method (creational pattern)
+//
+// Declares a method for creating an object in a base class and lets subclasses
+// decide which concrete class to instantiate. Code that USES the product
+// (installAndCheck) lives in the base class and never names a concrete type.
+//
+// Use it when:
+//   - the exact types of objects your code works with are not known in advance
+//   - users of your library should be able to extend its internal components
+//   - you want to reuse existing objects instead of rebuilding them
+//
+// Flow:
+//   1. Product interface          Debugger
+//   2. Concrete products          LinuxGdb, WindowsGdb, MacOsLldb
+//   3. Creator                    DebuggerInstaller: createDebugger() is the
+//                                 factory method, installAndCheck() uses it
+//   4. Concrete creators          one per platform, override the factory method
+//   5. Client picks a creator     and never constructs products directly
+//
+// UML: docs/uml/dp/creational_factorymethod.drawio.svg
+// -----------------------------------------------------------------------------
 
 #include <memory>
 #include <string>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace factory_method {
 
-/// @class Product Interface
-class IGdbProduct {
+// 1. Product interface
+class Debugger {
  public:
-  virtual ~IGdbProduct() = default;
-  virtual void launch() const = 0;
+  virtual ~Debugger() = default;
+  virtual std::string installCommand() const = 0;
+  virtual std::string versionCommand() const = 0;
 };
 
-class LinuxGdbProduct : public IGdbProduct {
+// 2. Concrete products
+class LinuxGdb : public Debugger {
  public:
-  void launch() const override {
-    LOG("sudo apt update && sudo apt install -y gdb && gdb --version");
+  std::string installCommand() const override {
+    return "sudo apt install -y gdb";
   }
+  std::string versionCommand() const override { return "gdb --version"; }
 };
 
-class WindowsGdbProduct : public IGdbProduct {
+class WindowsGdb : public Debugger {
  public:
-  void launch() const override {
-    LOG("pacman -Syu mingw-w64-x86_64-gdb && gdb --version");
+  std::string installCommand() const override {
+    return "pacman -S mingw-w64-x86_64-gdb";
   }
+  std::string versionCommand() const override { return "gdb.exe --version"; }
 };
 
-class MacOsGdbProduct : public IGdbProduct {
- public:
-  void launch() const override { LOG("brew install gdb && gdb --version"); }
-};
-
-/// @class Creator Interface
-class IGdbFactory {
+class MacOsLldb : public Debugger {
  public:
-  virtual ~IGdbFactory() = default;
-  virtual std::unique_ptr<IGdbProduct> factory_method() = 0;
-  virtual void launch_gdb() = 0;
+  std::string installCommand() const override {
+    return "xcode-select --install";
+  }
+  std::string versionCommand() const override { return "lldb --version"; }
 };
 
-class AbstractGdbFactory : public IGdbFactory {
+// 3. Creator
+class DebuggerInstaller {
  public:
-  /// @brief call the factory method to create a Product object
-  /// execute operation
-  void launch_gdb() final {
-    auto gdb = this->factory_method();
-    gdb->launch();
+  virtual ~DebuggerInstaller() = default;
+
+  /// Business logic shared by all platforms. It relies on the factory method
+  /// and works with ANY product.
+  void installAndCheck() const {
+    const std::unique_ptr<Debugger> debugger = createDebugger();
+    LOG_S("    install: " << debugger->installCommand());
+    LOG_S("    verify : " << debugger->versionCommand());
   }
+
+ private:
+  /// The factory method.
+  virtual std::unique_ptr<Debugger> createDebugger() const = 0;
 };
 
-class WindowsGdbFactory : public AbstractGdbFactory {
- public:
-  std::unique_ptr<IGdbProduct> factory_method() override {
-    return std::make_unique<WindowsGdbProduct>();
+// 4. Concrete creators
+class LinuxInstaller : public DebuggerInstaller {
+  std::unique_ptr<Debugger> createDebugger() const override {
+    return std::make_unique<LinuxGdb>();
   }
 };
 
-class LinuxGdbFactory : public AbstractGdbFactory {
- public:
-  std::unique_ptr<IGdbProduct> factory_method() override {
-    return std::make_unique<LinuxGdbProduct>();
+class WindowsInstaller : public DebuggerInstaller {
+  std::unique_ptr<Debugger> createDebugger() const override {
+    return std::make_unique<WindowsGdb>();
   }
 };
 
-class MacOsGdbFactory : public AbstractGdbFactory {
- public:
-  std::unique_ptr<IGdbProduct> factory_method() override {
-    return std::make_unique<MacOsGdbProduct>();
+class MacOsInstaller : public DebuggerInstaller {
+  std::unique_ptr<Debugger> createDebugger() const override {
+    return std::make_unique<MacOsLldb>();
   }
 };
 
-/// @brief selector
-std::unique_ptr<IGdbFactory> create_gdb_factory(const std::string& os) {
+std::unique_ptr<DebuggerInstaller> installerFor(std::string_view os) {
   if (os == "linux") {
-    return std::make_unique<LinuxGdbFactory>();
+    return std::make_unique<LinuxInstaller>();
   }
   if (os == "windows") {
-    return std::make_unique<WindowsGdbFactory>();
+    return std::make_unique<WindowsInstaller>();
   }
   if (os == "macos") {
-    return std::make_unique<MacOsGdbFactory>();
+    return std::make_unique<MacOsInstaller>();
   }
-  LOG("OS not support yet - " + os);
   return nullptr;
 }
 
+// 5. Client
 void run() {
-  auto client_code = [](IGdbFactory* gdb) {
-    if (gdb != nullptr) {
-      gdb->launch_gdb();
+  for (const std::string_view os : {"linux", "windows", "macos", "unknown"}) {
+    LOG_SECTION(os);
+    if (const auto installer = installerFor(os)) {
+      installer->installAndCheck();
+    } else {
+      LOG_S("    no installer for '" << os << "'");
     }
-  };
-
-  // Create factory base on the os
-  {
-    const std::string os = "linux";
-    auto gdb = create_gdb_factory(os);
-
-    client_code(gdb.get());
-  }
-  {
-    const std::string os = "windows";
-    auto gdb = create_gdb_factory(os);
-
-    client_code(gdb.get());
-  }
-  {
-    const std::string os = "macos";
-    auto gdb = create_gdb_factory(os);
-
-    client_code(gdb.get());
-  }
-  {
-    const std::string os = "unknown";
-    auto gdb = create_gdb_factory(os);
-    client_code(gdb.get());
   }
 }
-}  // namespace factory_method
-}  // namespace
 
-class FactoryMethodExample : public IExample {
- public:
-  std::string group() const override { return "dp/creational"; }
-  std::string name() const override { return "FactoryMethod"; }
-  std::string description() const override {
-    return "FactoryMethod Pattern Example";
-  }
-  void execute() override { factory_method::run(); }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(FactoryMethodExample);
\ No newline at end of file
+LAB_EXAMPLE("FactoryMethod",
+            "subclasses decide which product a creator makes") {
+  run();
+}
diff --git a/src/dp/creational/Prototype.cpp b/src/dp/creational/Prototype.cpp
index 3816684..a16900d 100644
--- a/src/dp/creational/Prototype.cpp
+++ b/src/dp/creational/Prototype.cpp
@@ -1,131 +1,131 @@
-// cppcheck-suppress-file [functionStatic]
-
-// Prototype = create new objects by cloning existing ones.
+// -----------------------------------------------------------------------------
+// Prototype (creational pattern)
+//
+// Creates new objects by CLONING existing ones, without depending on their
+// concrete classes.
+//
+// Problem: to copy an object through a base-class pointer you would need its
+// concrete type - `Base copy = *pointer;` slices, and the client may not even
+// know which derived classes exist.
+// Solution: each class implements a virtual clone() that returns a copy of
+// itself ("virtual copy constructor").
+//
+// Use it when:
+//   - code must copy objects it only knows through an interface
+//   - creating an object is expensive or needs a lot of configuration: set up
+//     preset prototypes once and clone them
+//
+// Flow:
+//   1. Prototype interface       Extension::clone()
+//   2. Concrete prototypes       LoggerExtension, AnalyticsExtension
+//   3. (Optional) registry       ExtensionRegistry of named, pre-configured presets
+//   4. Client asks for a clone by name and never names a concrete type
 //
-// Flow in this file:
-//   1. Define a cloneable interface          -> IExtensionPrototype
-//   2. Implement concrete prototypes         -> Logger / Analytics
-//   3. (Optional) Store named presets        -> ExtensionPrototypeRegistry
-//   4. Client asks registry to clone by id   -> never mentions concrete types
+// UML: docs/uml/dp/creational_prototype.drawio.svg
+// -----------------------------------------------------------------------------
 
+#include <map>
 #include <memory>
 #include <string>
-#include <string_view>
-#include <unordered_map>
 #include <utility>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace prototy {
 
-constexpr std::string_view kLoggerExtId = "logger";
-constexpr std::string_view kAnalyzeId = "analyze";
-
-/// @class Prototype interface: "I know how to copy myself."
-/// @brief client code only depends on this class
-class IExtensionPrototype {
+/// 1. Prototype interface: "I know how to copy myself."
+class Extension {
  public:
-  virtual ~IExtensionPrototype() = default;
-
-  /// return a new object
-  virtual std::unique_ptr<IExtensionPrototype> clone() const = 0;
-
-  virtual void execute() const = 0;
+  virtual ~Extension() = default;
+  virtual std::unique_ptr<Extension> clone() const = 0;
+  virtual std::string describe() const = 0;
 };
 
-/// @class Concrete Prototype
-/// @brief each class copies itself
-class LoggerExtension : public IExtensionPrototype {
+/// 2. Concrete prototypes: clone() uses the (deep-copying) copy constructor.
+class LoggerExtension : public Extension {
  public:
-  explicit LoggerExtension(std::string level = "DEBUG")
-      : log_level_{std::move(level)} {}
+  explicit LoggerExtension(std::string level) : level_{std::move(level)} {}
 
-  std::unique_ptr<IExtensionPrototype> clone() const override {
+  std::unique_ptr<Extension> clone() const override {
     return std::make_unique<LoggerExtension>(*this);
   }
-
-  void execute() const override { LOG("log level: " + log_level_); }
+  std::string describe() const override { return "logger, level " + level_; }
+  void setLevel(std::string level) { level_ = std::move(level); }
 
  private:
-  std::string log_level_;
+  std::string level_;
 };
 
-class AnalyticsExtension : public IExtensionPrototype {
+class AnalyticsExtension : public Extension {
  public:
-  explicit AnalyticsExtension(int sampling_rate = 1)
-      : sampling_rate_{sampling_rate} {}
+  AnalyticsExtension(int sampling_rate, std::string endpoint)
+      : sampling_rate_{sampling_rate}, endpoint_{std::move(endpoint)} {}
 
-  std::unique_ptr<IExtensionPrototype> clone() const override {
+  std::unique_ptr<Extension> clone() const override {
     return std::make_unique<AnalyticsExtension>(*this);
   }
-
-  void execute() const override { LOG_S("sampling rate: " << sampling_rate_); }
+  std::string describe() const override {
+    return "analytics, sampling " + std::to_string(sampling_rate_) + " Hz to " +
+           endpoint_;
+  }
 
  private:
   int sampling_rate_;
+  std::string endpoint_;
 };
 
-/// @class Prototype Registry
-/// @brief a map of named presets ready to be cloned.
-class ExtensionPrototypeRegistry {
+/// 3. Registry of named presets.
+class ExtensionRegistry {
  public:
-  void register_extension(std::string_view id,
-                          std::unique_ptr<IExtensionPrototype> proto) {
-    LOG(id);
-    prototypes_[std::string(id)] = std::move(proto);
+  void add(const std::string& name, std::unique_ptr<Extension> prototype) {
+    prototypes_[name] = std::move(prototype);
   }
 
-  /// clone the preset for `id`. Returns nullptr if the id is unknown.
-  std::unique_ptr<IExtensionPrototype> create(std::string_view id) const {
-    auto it = prototypes_.find(std::string(id));
-    if (it == prototypes_.end()) {
-      return nullptr;
-    }
-    return it->second->clone();  // copy the template, leave the original intact
+  /// Returns a fresh copy of the preset, or nullptr for unknown names.
+  std::unique_ptr<Extension> create(const std::string& name) const {
+    const auto it = prototypes_.find(name);
+    return it == prototypes_.end() ? nullptr : it->second->clone();
   }
 
  private:
-  std::unordered_map<std::string, std::unique_ptr<IExtensionPrototype>>
-      prototypes_;
+  std::map<std::string, std::unique_ptr<Extension>> prototypes_;
 };
 
 void run() {
-  // build presets once, register by name
-  ExtensionPrototypeRegistry registry;
-  registry.register_extension(kLoggerExtId,
-                              std::make_unique<LoggerExtension>("DEBUG"));
-  registry.register_extension(kAnalyzeId,
-                              std::make_unique<AnalyticsExtension>(1200));
-
-  // create-by-clone
-  auto client_code = [](const ExtensionPrototypeRegistry& reg) {
-    auto logger_ext = reg.create(kLoggerExtId);
-    auto analytics_ext = reg.create(kAnalyzeId);
-
-    if (logger_ext) {
-      logger_ext->execute();
-    }
-    if (analytics_ext) {
-      analytics_ext->execute();
+  LOG_SECTION("Registering configured prototypes");
+  ExtensionRegistry registry;
+  registry.add("debug-logger", std::make_unique<LoggerExtension>("DEBUG"));
+  registry.add("analytics", std::make_unique<AnalyticsExtension>(
+                                1200, "https://stats.example"));
+
+  LOG_SECTION("Client clones by name");
+  for (const std::string name : {"debug-logger", "analytics", "unknown"}) {
+    if (const auto extension = registry.create(name)) {
+      LOG_S("  " << name << " -> " << extension->describe());
+    } else {
+      LOG_S("  " << name << " -> no such prototype");
     }
-  };
+  }
 
-  client_code(registry);
+  LOG_SECTION("Clones are independent copies");
+  const LoggerExtension original{"INFO"};
+  std::unique_ptr<Extension> copy = original.clone();
+  static_cast<LoggerExtension&>(*copy).setLevel("TRACE");
+  LOG_S("  original: " << original.describe());
+  LOG_S("  clone   : " << copy->describe());
+
+  const Extension& through_base = original;
+  const std::unique_ptr<Extension> full_copy =
+      through_base.clone();  // no slicing
+  LOG_S("  clone through a base reference keeps the real type: "
+        << full_copy->describe());
 }
 
-}  // namespace prototy
 }  // namespace
 
-class PrototypeExample : public IExample {
- public:
-  std::string group() const override { return "dp/creational"; }
-  std::string name() const override { return "Prototype"; }
-  std::string description() const override {
-    return "Clone configured objects via a prototype interface + registry";
-  }
-  void execute() override { prototy::run(); }
-};
-
-REGISTER_EXAMPLE(PrototypeExample);
+LAB_EXAMPLE(
+    "Prototype",
+    "copy objects through an interface with virtual clone() and presets") {
+  run();
+}
diff --git a/src/dp/creational/README.md b/src/dp/creational/README.md
index cca129c..30171f4 100644
--- a/src/dp/creational/README.md
+++ b/src/dp/creational/README.md
@@ -1,3 +1,6 @@
+> Examples: `dp/creational/{FactoryMethod, AbstractFactory, Builder, Prototype, Singleton}` - run
+> one with `./build/bin/cpp_lab_project --run dp/creational/Builder`
+
 # Creational Design Patterns
 
 Creational design patterns provide various object creation mechanisms, which increase flexibility and reuse of existing code.
diff --git a/src/dp/creational/Singleton.cpp b/src/dp/creational/Singleton.cpp
index b3bc6ac..6b253bf 100644
--- a/src/dp/creational/Singleton.cpp
+++ b/src/dp/creational/Singleton.cpp
@@ -1,75 +1,98 @@
-// cppcheck-suppress-file [functionStatic]
-
-// Singleton — ensure a class has only one instance, accessed globally.
+// -----------------------------------------------------------------------------
+// Singleton (creational pattern)
+//
+// Ensures a class has only one instance and provides a global access point.
+//
+// Implementation in modern C++ ("Meyers' singleton"):
+//   static Config& instance() { static Config config; return config; }
+//   - The local static is created on first use.
+//   - Since C++11 that initialization is thread-safe.
+//   - Constructor private, copy and move deleted.
 //
-// Flow in this file:
-//   1. Hide the constructor                  -> private SingletonConfig()
-//   2. Ban copy / assign                     -> deleted special members
-//   3. Expose a single access point          -> get_instance() (Meyers' singleton)
-//   4. Client always uses get_instance()     -> same object everywhere
+// Caution - a singleton is global state in disguise:
+//   - hidden dependencies (functions use it without saying so)
+//   - hard to test (tests share and modify the same instance)
+//   - destruction order problems when other statics use it at shutdown
+// Prefer passing dependencies explicitly; use a singleton only for things that
+// really are unique (e.g. the lab's own Registry and Logger).
+//
+// UML: docs/uml/dp/creational_singleton.drawio.svg
+// -----------------------------------------------------------------------------
 
+#include <mutex>
 #include <string>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include <thread>
+#include <vector>
 
-namespace {
-namespace singleton_pattern {
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-/// @class Singleton class
-/// @brief defines the `GetInstance` method that serves as an alternative to constructor
-class SingletonConfig {
+namespace {
 
+class Config {
  public:
-  // 1. Should not be cloneable.
-  SingletonConfig(const SingletonConfig& other) = delete;
-
-  // 2. Should not be assignable
-  SingletonConfig& operator=(const SingletonConfig& other) = delete;
-
-  static SingletonConfig& get_instance() {
-    static SingletonConfig instance;
-    return instance;
+  static Config& instance() {
+    static Config config;  // created once, on the first call, thread-safe
+    return config;
   }
 
-  void init(const std::string& input) {
-    LOG(input);
-    value_ = input;
+  Config(const Config&) = delete;
+  Config& operator=(const Config&) = delete;
+  Config(Config&&) = delete;
+  Config& operator=(Config&&) = delete;
+
+  void set(const std::string& value) {
+    const std::lock_guard<std::mutex> lock(
+        mutex_);  // the instance is shared: protect it
+    value_ = value;
   }
 
-  const std::string& get_value() const {
-    LOG("");
+  std::string get() const {
+    const std::lock_guard<std::mutex> lock(mutex_);
     return value_;
-  };
+  }
 
  private:
-  /// @brief Default constructor should always be private
-  SingletonConfig() = default;
-  std::string value_;
-};
+  Config() { LOG("  Config constructed (happens exactly once)"); }
+  ~Config() = default;
 
-void run() {
-  auto client_code = []() {
-    LOG(SingletonConfig::get_instance().get_value());
-  };
+  mutable std::mutex mutex_;
+  std::string value_{"default"};
+};
 
-  SingletonConfig& s1 = SingletonConfig::get_instance();
-  s1.init("0x001");
-  client_code();
+void readSomewhereElse() {
+  // A far-away function reaches the same object without any parameter.
+  LOG_S("  readSomewhereElse() sees value = " << Config::instance().get());
+}
 
-  // Singleton* s3 = new Singleton(); // ERROR
+void run() {
+  LOG_SECTION("One instance, global access");
+  LOG("  first call to Config::instance():");
+  Config& config = Config::instance();
+  config.set("0x001");
+  readSomewhereElse();
+  // Config copy = Config::instance();  // error: copy constructor is deleted
+  // Config other;                     // error: constructor is private
+
+  LOG_SECTION("Every thread gets the same object");
+  std::vector<const Config*> seen(4, nullptr);
+  std::vector<std::thread> threads;
+  for (std::size_t i = 0; i < seen.size(); ++i) {
+    threads.emplace_back([&seen, i] { seen[i] = &Config::instance(); });
+  }
+  for (std::thread& thread : threads) {
+    thread.join();
+  }
+  bool all_same = true;
+  for (const Config* address : seen) {
+    all_same = all_same && address == &config;
+  }
+  LOG_S("  4 threads saw the same address: " << std::boolalpha << all_same);
 }
 
-}  // namespace singleton_pattern
 }  // namespace
 
-class SingletonExample : public IExample {
- public:
-  std::string group() const override { return "dp/creational"; }
-  std::string name() const override { return "Singleton"; }
-  std::string description() const override {
-    return "Singleton Pattern Example";
-  }
-  void execute() override { singleton_pattern::run(); }
-};
-
-REGISTER_EXAMPLE(SingletonExample);
\ No newline at end of file
+LAB_EXAMPLE("Singleton",
+            "Meyers' singleton: one lazily created, thread-safe instance") {
+  run();
+}
diff --git a/src/dp/structural/Adapter.cpp b/src/dp/structural/Adapter.cpp
index e881bd1..06f53de 100644
--- a/src/dp/structural/Adapter.cpp
+++ b/src/dp/structural/Adapter.cpp
@@ -1,148 +1,149 @@
-#include <memory>
-#include "Logger.h"
+// -----------------------------------------------------------------------------
+// Adapter (structural pattern)
+//
+// Lets objects with incompatible interfaces work together. An adapter wraps an
+// existing class (the adaptee) and exposes the interface the client expects
+// (the target).
+//
+// Use it when:
+//   - you want to use an existing or third-party class whose interface does not
+//     match the rest of your code
+//   - you cannot (or should not) modify that class
+//
+// Participants:
+//   Target   interface the client depends on
+//   Adaptee  existing class with an incompatible interface
+//   Adapter  implements Target by translating calls to the Adaptee
+//
+// Two variants: the OBJECT adapter holds the adaptee (composition, preferred);
+// the CLASS adapter inherits from it (here: private inheritance).
+//
+// UML: docs/uml/dp/structural_adapter.drawio.svg
+// -----------------------------------------------------------------------------
 
-#include "ExampleRegistry.h"
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
 
-namespace adapter_pattern {
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-/// @class Adaptee
-/// @brief Existing class with an incompatible interface
-class Adaptee {
- public:
-  void specific_request() {
-    ++dummy_;
-    LOG("Adaptee::specific_request()");
-  }
+namespace {
 
- private:
-  int dummy_{0};
-};
+namespace basic {
 
-/// @class Target
-/// @brief Interface expected by the client
+/// Target: the interface the client code expects.
 class Target {
  public:
   virtual ~Target() = default;
-
   virtual void request() = 0;
 };
 
-/// @class ConcreteTarget
-/// @brief A normal implementation of Target
-class ConcreteTarget : public Target {
+/// Adaptee: useful, but with a different interface.
+class Adaptee {
  public:
-  void request() override { LOG("request"); }
+  void specificRequest(int code) const {
+    LOG_S("    Adaptee::specificRequest(" << code << ")");
+  }
 };
 
-/// @class Adapter
-/// @brief Converts the Target interface into the Adaptee interface
-class Adapter : public Target {
+/// Object adapter: HAS an adaptee.
+class ObjectAdapter : public Target {
  public:
-  explicit Adapter(std::unique_ptr<Adaptee> adaptee)
-      : adaptee_(std::move(adaptee)) {
-    LOG("CTR");
-  }
-
-  void request() override { adaptee_->specific_request(); }
+  explicit ObjectAdapter(std::unique_ptr<Adaptee> adaptee)
+      : adaptee_{std::move(adaptee)} {}
+  void request() override { adaptee_->specificRequest(42); }
 
  private:
   std::unique_ptr<Adaptee> adaptee_;
 };
 
-/// @brief Client code only depends on Target.
-void client_code(Target& target) {
-  LOG("");
+/// Class adapter: IS implemented in terms of the adaptee (private inheritance).
+class ClassAdapter : public Target, private Adaptee {
+ public:
+  void request() override { specificRequest(7); }
+};
+
+void clientCode(Target& target) {
+  LOG("  client calls request()");
   target.request();
 }
 
 void run() {
-  LOG("Adapter Example");
-  {
-    ConcreteTarget target;
-    client_code(target);
-  }
-  LOG("");
-
-  {
-    auto adaptee = std::make_unique<Adaptee>();
-    Adapter adapter(std::move(adaptee));
-    client_code(adapter);
-  }
+  LOG_SECTION("Object adapter and class adapter");
+  ObjectAdapter object_adapter{std::make_unique<Adaptee>()};
+  clientCode(object_adapter);
+  ClassAdapter class_adapter;
+  clientCode(class_adapter);
 }
-}  // namespace adapter_pattern
 
-namespace case_study {
-// Target interface expected by the existing system
-class PaymentSystem {
- public:
-  virtual void pay_with_card(const std::string& card_number) {
-    LOG_S("Payment using card: " << card_number);
-  }
+}  // namespace basic
 
-  virtual ~PaymentSystem() = default;
+namespace payments {
+
+/// Target: what the shop checkout already uses.
+class PaymentProcessor {
+ public:
+  virtual ~PaymentProcessor() = default;
+  virtual bool pay(const std::string& customer, double amount_eur) = 0;
 };
 
-// Adaptee: a new payment API with an incompatible interface
-class PayPalAPI {
+class CardProcessor : public PaymentProcessor {
  public:
-  void send_payment(const std::string& email) {
-    LOG_S("Payment sent via PayPal to " << email);
-    dummy_++;
+  bool pay(const std::string& customer, double amount_eur) override {
+    LOG_S("    [card] charged " << amount_eur << " EUR to the card of "
+                                << customer);
+    return true;
   }
-
- private:
-  int dummy_{};
 };
 
-// Adapter: makes PayPalAPI compatible with PaymentSystem
-class PayPalAdapter : public PaymentSystem {
- private:
-  PayPalAPI paypal_;
-
+/// Adaptee: a third-party SDK we cannot change. Different method name,
+/// different parameters, amounts in cents and an error code instead of bool.
+class PayPalSdk {
  public:
-  void pay_with_card(const std::string& cardNumber) override {
-    // Treat the cardNumber parameter as a PayPal email
-    paypal_.send_payment(cardNumber);
+  int sendPayment(const std::string& email, long amount_cents,
+                  const std::string& currency) const {
+    LOG_S("    [PayPal SDK] sent " << amount_cents << " cents (" << currency
+                                   << ") to " << email);
+    return 0;  // 0 = success
   }
 };
 
-// Client code: uses the old interface without modification
-void run() {
-  LOG("Case Study Example");
-  std::string method;
-  std::string input;
-  method = std::string("card") + std::string("");
-  input = "1234-5678-9999";
-  // method = std::string("paypal") + std::string("");input =
-  // "user@example.com";
-
-  LOG_S("Choose payment method (card/paypal): " << method);
-
-  PaymentSystem* payment_system = nullptr;
-
-  if (method == "card") {
-    payment_system = new PaymentSystem();
-    payment_system->pay_with_card(input);
-  } else if (method == "paypal") {
-    payment_system = new PayPalAdapter();
-    payment_system->pay_with_card(input);
-  } else {
-    LOG("Unsupported payment method!");
+/// Adapter: translates the checkout's call into the SDK's call.
+class PayPalAdapter : public PaymentProcessor {
+ public:
+  bool pay(const std::string& customer, double amount_eur) override {
+    const std::string email =
+        customer + "@example.com";  // look up the PayPal account
+    const auto cents = static_cast<long>(amount_eur * 100.0 + 0.5);
+    return sdk_.sendPayment(email, cents, "EUR") == 0;
   }
 
-  delete payment_system;
+ private:
+  PayPalSdk sdk_;
+};
+
+void checkout(PaymentProcessor& processor, const std::string& customer,
+              double amount) {
+  const bool ok = processor.pay(customer, amount);  // unchanged client code
+  LOG_S("  checkout for " << customer << ": " << (ok ? "paid" : "failed"));
 }
-}  // namespace case_study
 
-class AdapterExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Adapter"; }
-  std::string description() const override { return "Factory Pattern Example"; }
-  void execute() override {
-    adapter_pattern::run();
-    case_study::run();
-  }
-};
+void run() {
+  LOG_SECTION("Case study: plugging a third-party SDK into existing code");
+  CardProcessor card;
+  PayPalAdapter paypal;
+  checkout(card, "alice", 19.99);
+  checkout(paypal, "bob", 42.50);
+}
+
+}  // namespace payments
 
-REGISTER_EXAMPLE(AdapterExample);
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE("Adapter",
+            "make an incompatible class fit the interface the client expects") {
+  basic::run();
+  payments::run();
+}
diff --git a/src/dp/structural/Bridge.cpp b/src/dp/structural/Bridge.cpp
index c59b7d2..bf90086 100644
--- a/src/dp/structural/Bridge.cpp
+++ b/src/dp/structural/Bridge.cpp
@@ -1,160 +1,169 @@
+// -----------------------------------------------------------------------------
+// Bridge (structural pattern)
+//
+// Splits one large class hierarchy into two independent ones - the
+// ABSTRACTION (what the client uses) and the IMPLEMENTATION (how it is done) -
+// connected by composition.
+//
+// Problem: widgets x platforms as subclasses
+//   Button, WindowsButton, LinuxButton, Label, WindowsLabel, LinuxLabel, ...
+//   Every new widget needs one class per platform and vice versa: M x N classes.
+// Solution: Widget HAS-A Renderer. Widgets and renderers vary independently:
+//   M + N classes, and the renderer can even be switched at run time.
+//
+// Participants:
+//   Abstraction         Widget (holds a Renderer)
+//   RefinedAbstraction  Button, Label
+//   Implementor         Renderer interface
+//   ConcreteImplementor WindowsRenderer, LinuxRenderer
+//
+// UML: docs/uml/dp/structural_bridge.drawio.svg
+// -----------------------------------------------------------------------------
+
 #include <memory>
+#include <string>
 #include <utility>
-#include "ExampleRegistry.h"
-#include "Logger.h"
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
+
 namespace problem {
+
 class Widget {
  public:
   virtual ~Widget() = default;
-  virtual void click_on() const = 0;
-};
-
-class Button : public Widget {
- public:
-  void click_on() const override { LOG("executed"); }
-};
-
-class ButtonWindows : public Button {
- public:
-  void click_on() const override {
-    LOG("executed");
-    Button::click_on();
-  }
+  virtual void draw() const = 0;
 };
 
-class ButtonLinux : public Button {
+class Button : public Widget {};
+class WindowsButton : public Button {
  public:
-  void click_on() const override {
-    LOG("executed");
-    Button::click_on();
-  }
+  void draw() const override { LOG("    WindowsButton::draw"); }
 };
-
-class Label : public Widget {
+class LinuxButton : public Button {
  public:
-  void click_on() const override { LOG("executed"); }
+  void draw() const override { LOG("    LinuxButton::draw"); }
 };
-
-class LabelWindows : public Label {
+class Label : public Widget {};
+class WindowsLabel : public Label {
  public:
-  void click_on() const override {
-    LOG("executed");
-    Label::click_on();
-  }
+  void draw() const override { LOG("    WindowsLabel::draw"); }
 };
-
-class LabelLinux : public Label {
+class LinuxLabel : public Label {
  public:
-  void click_on() const override {
-    LOG("executed");
-    Label::click_on();
-  }
+  void draw() const override { LOG("    LinuxLabel::draw"); }
 };
+// Adding MacOs means MacOsButton, MacOsLabel, ...; adding a Slider means
+// WindowsSlider, LinuxSlider, ... The hierarchy grows in two directions.
 
 void run() {
-  LOG("Problem");
-  // [Problem 1] We have to write the Text/TextLinux ...
-  auto client_code = [](const Widget* widget) {
-    if (widget != nullptr)
-      widget->click_on();
-  };
-
-  // [Problem 2] : Use the Bridge if you need to be able to switch
-  // implementations at runtime. how to exmaple for this still don't know
-  Widget* button = new ButtonWindows();
-  client_code(button);
-  delete button;
+  LOG_SECTION("Problem: one subclass per widget AND platform");
+  const std::unique_ptr<Widget> widgets[] = {std::make_unique<WindowsButton>(),
+                                             std::make_unique<LinuxLabel>()};
+  for (const auto& widget : widgets) {
+    widget->draw();
+  }
 }
+
 }  // namespace problem
 
-namespace bridge_pattern {
-/// @class Implemetation Interface
-/// @brief Define the interface for all implementation classes
-class OsImplemetation {
+namespace bridge {
+
+/// Implementor: platform-specific primitives.
+class Renderer {
  public:
-  virtual void click_on_ipl() const = 0;
-  virtual ~OsImplemetation() = default;
+  virtual ~Renderer() = default;
+  virtual void drawRectangle(const std::string& label) const = 0;
+  virtual void drawText(const std::string& text) const = 0;
 };
 
-class WindowsImplemetation : public OsImplemetation {
+class WindowsRenderer : public Renderer {
  public:
-  void click_on_ipl() const override { LOG("[Windows]"); }
+  void drawRectangle(const std::string& label) const override {
+    LOG_S("    [Win32] DrawRectangle for '" << label << "'");
+  }
+  void drawText(const std::string& text) const override {
+    LOG_S("    [Win32] DrawText '" << text << "'");
+  }
 };
 
-class LinuxImplemetation : public OsImplemetation {
+class LinuxRenderer : public Renderer {
  public:
-  void click_on_ipl() const override { LOG("[Linux]"); }
+  void drawRectangle(const std::string& label) const override {
+    LOG_S("    [X11] XDrawRectangle for '" << label << "'");
+  }
+  void drawText(const std::string& text) const override {
+    LOG_S("    [X11] XDrawString '" << text << "'");
+  }
 };
 
-/// @class Abstractio Class
-/// @brief Define the interface for the control part
-class WidgetAbstraction {
- protected:
-  std::shared_ptr<OsImplemetation> implementation_;
-
+/// Abstraction: high-level widget logic, delegates primitives to the renderer.
+class Widget {
  public:
-  explicit WidgetAbstraction(std::shared_ptr<OsImplemetation> implemetation)
-      : implementation_{std::move(implemetation)} {}
-  virtual ~WidgetAbstraction() = default;
+  explicit Widget(std::shared_ptr<const Renderer> renderer)
+      : renderer_{std::move(renderer)} {}
+  virtual ~Widget() = default;
 
-  virtual void click_on() const = 0;
+  virtual void draw() const = 0;
+  void setRenderer(std::shared_ptr<const Renderer> renderer) {
+    renderer_ = std::move(renderer);
+  }
+
+ protected:
+  const Renderer& renderer() const { return *renderer_; }
+
+ private:
+  std::shared_ptr<const Renderer> renderer_;  // the "bridge"
 };
 
-class ButtonAbstraction : public WidgetAbstraction {
+/// Refined abstractions.
+class Button : public Widget {
  public:
-  explicit ButtonAbstraction(std::shared_ptr<OsImplemetation> implemetation)
-      : WidgetAbstraction{std::move(implemetation)} {}
-  void click_on() const override {
-    LOG("executed");
-    this->implementation_->click_on_ipl();
+  Button(std::shared_ptr<const Renderer> renderer, std::string caption)
+      : Widget{std::move(renderer)}, caption_{std::move(caption)} {}
+  void draw() const override {
+    renderer().drawRectangle(caption_);
+    renderer().drawText(caption_);
   }
+
+ private:
+  std::string caption_;
 };
 
-class LabelAbstraction : public WidgetAbstraction {
+class Label : public Widget {
  public:
-  explicit LabelAbstraction(std::shared_ptr<OsImplemetation> implemetation)
-      : WidgetAbstraction{std::move(implemetation)} {}
-  void click_on() const override {
-    LOG("executed");
-    this->implementation_->click_on_ipl();
-  }
+  Label(std::shared_ptr<const Renderer> renderer, std::string text)
+      : Widget{std::move(renderer)}, text_{std::move(text)} {}
+  void draw() const override { renderer().drawText(text_); }
+
+ private:
+  std::string text_;
 };
 
 void run() {
-  LOG("Bridge Example");
-  auto client_code = [](const WidgetAbstraction* widget) {
-    if (widget != nullptr) {
-      LOG("");
-      widget->click_on();
-    }
-  };
-
-  {
-    auto os = std::make_shared<WindowsImplemetation>();
-    auto widget = std::make_unique<ButtonAbstraction>(os);
-    client_code(widget.get());
-  }
-
-  {
-    auto os = std::make_shared<LinuxImplemetation>();
-    auto widget = std::make_unique<LabelAbstraction>(os);
-    client_code(widget.get());
-  }
+  LOG_SECTION("Bridge: widgets and renderers vary independently");
+  const auto windows = std::make_shared<WindowsRenderer>();
+  const auto linux_renderer = std::make_shared<LinuxRenderer>();
+
+  Button ok{windows, "OK"};
+  const Label title{linux_renderer, "Settings"};
+  ok.draw();
+  title.draw();
+
+  LOG("  switching the button's renderer at run time:");
+  ok.setRenderer(linux_renderer);
+  ok.draw();
 }
-}  // namespace bridge_pattern
 
-class BridgeExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Bridge"; }
-  std::string description() const override { return "Bridge Pattern Example"; }
-  void execute() override {
-    problem::run();
-    bridge_pattern::run();
-  }
-};
+}  // namespace bridge
 
-REGISTER_EXAMPLE(BridgeExample);
-}  // namespace
\ No newline at end of file
+}  // namespace
+
+LAB_EXAMPLE(
+    "Bridge",
+    "separate abstraction from implementation to avoid M x N subclasses") {
+  problem::run();
+  bridge::run();
+}
diff --git a/src/dp/structural/Composite.cpp b/src/dp/structural/Composite.cpp
index c7e2fff..e0e9f1b 100644
--- a/src/dp/structural/Composite.cpp
+++ b/src/dp/structural/Composite.cpp
@@ -1,445 +1,159 @@
-// Composite is a structural design pattern
-// that lets you compose objects into "tree structures"
-// and then work with these structures as if they were individual objects.
-// Appicability:
-// (*)   when you have to implement a tree-like object structure.
-// (**)  when you want the client code to treat both simple and complex elements
-// uniformly. UML: docs/uml/patterns_structural_composite.drawio.svg
+// -----------------------------------------------------------------------------
+// Composite (structural pattern)
+//
+// Composes objects into tree structures and lets clients treat individual
+// objects (leaves) and groups of objects (composites) the same way.
+//
+// Problem: a file browser with separate File and Folder classes. Every
+// operation (size, print, search) needs `if file ... else if folder ...`
+// branches, and each new node type touches all of them.
+// Solution: File and Folder share one interface. A Folder implements the
+// operations by delegating to its children, recursively.
+//
+// Use it when:
+//   - you have a tree-like structure (file systems, GUIs, org charts, scenes)
+//   - clients should not care whether they deal with a leaf or a group
+//
+// Participants:
+//   Component  Node - common interface
+//   Leaf       File, Shortcut - no children
+//   Composite  Folder - owns children and delegates to them
+//
+// UML: docs/uml/dp/structural_composite.drawio.svg
+// -----------------------------------------------------------------------------
 
 #include <algorithm>
-#include <iostream>
-#include <list>
+#include <cstddef>
+#include <memory>
 #include <string>
 #include <utility>
+#include <vector>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-namespace problem {
-class File {
- private:
-  std::string name_;
 
+/// Component.
+class Node {
  public:
-  explicit File(std::string fileName) : name_{std::move(fileName)} {}
-  std::string getName() const { return this->name_; }
+  explicit Node(std::string name) : name_{std::move(name)} {}
+  virtual ~Node() = default;
 
-  void setName(const std::string& name) { this->name_ = name; }
+  const std::string& name() const { return name_; }
 
-  void open() const { std::cout << "Open file: " << name_ << "\n"; }
-};
+  virtual std::size_t sizeBytes() const = 0;
+  virtual void print(int depth) const = 0;
 
-// [P1] Have the NewTypeFile => Update Folder (fields, functions)
+ protected:
+  static std::string indent(int depth) {
+    return std::string(static_cast<std::size_t>(depth) * 2, ' ');
+  }
 
-class Folder {
  private:
   std::string name_;
-  std::list<File*>
-      files_;  // Should store the pointer to the actual file so when we delete
-               // the file it should delete in the list
-  std::list<Folder*> subFolders_;
-  // [P2] What about the parrent ?
-
- public:
-  explicit Folder(std::string name) : name_{std::move(name)} {}
-
-  ~Folder() {
-    for (File* f : files_) {
-      delete f;
-    }
-
-    for (Folder* sf : subFolders_) {
-      delete sf;
-    }
-  }
-
-  void removeFile(const File* file) {
-    files_.remove_if([file](const File* f) { return f == file; });
-  }
-
-  void removeFileByName(const std::string& name) {
-
-    // for (auto i = _files.begin(); i != _files.end(); ++i)
-    // {
-    //     if ((*i)->getName() == name)
-    //     {
-    //         delete (*i);
-    //         _files.erase(i);
-    //         return;
-    //     }
-    // }
-
-    auto it =
-        std::find_if(files_.begin(), files_.end(),
-                     [&name](const File* f) { return f->getName() == name; });
-
-    if (it != files_.end()) {
-      delete *it;        // free the memory
-      files_.erase(it);  // remove the pointer from the list
-    }
-  }
-
-  void removeFolderByName(const std::string& name) {
-    // for (auto i = _subFolders.begin(); i != _subFolders.end(); ++i)
-    // {
-    //     if ((*i)->getName() == name)
-    //     {
-    //         delete (*i);
-    //         _subFolders.erase(i);
-    //         return;
-    //     }
-    // }
-    auto it =
-        std::find_if(subFolders_.begin(), subFolders_.end(),
-                     [&name](const Folder* f) { return f->getName() == name; });
-
-    if (it != subFolders_.end()) {
-      delete *it;             // free the memory
-      subFolders_.erase(it);  // remove the pointer from the list
-    }
-  }
-
-  void addFile(File* file) { files_.push_back(file); }
-
-  void addFolder(Folder* folder) { subFolders_.push_back(folder); }
-
-  void removeFolder(const Folder* folder) {
-    subFolders_.remove_if([folder](const Folder* f) { return f == folder; });
-  }
-
-  std::string getName() const { return name_; }
-
-  void open() const { std::cout << "Open Folder: " << name_ << "\n"; }
-
-  int size() const {
-    int size = static_cast<int>(files_.size());
-
-    //  Consider using std::accumulate algorithm instead of a raw loop.
-    std::for_each(subFolders_.begin(), subFolders_.end(),
-                  [&size](const Folder* sf) { size += sf->size(); });
-
-    // for (const Folder *subFolder : _subFolders)
-    // {
-    //     size += subFolder->size();
-    // }
-
-    return size;
-  }
-
-  const std::list<Folder*>& getSubFolders() const { return subFolders_; }
-
-  const std::list<File*>& getFiles() const { return files_; }
-
-  void getFilesRecursive(std::list<File*>& out) const {
-    out.insert(out.end(), files_.begin(), files_.end());
-    for (const Folder* sf : subFolders_) {
-      sf->getFilesRecursive(out);
-    }
-  }
-
-  void getSubFoldersRecursive(std::list<Folder*>& out) const {
-    out.insert(out.end(), subFolders_.begin(), subFolders_.end());
-    for (const Folder* sf : subFolders_) {
-      sf->getSubFoldersRecursive(out);
-    }
-  }
 };
 
-namespace client {
-void clientCode(const Folder* folder) {
-  std::cout << "File name: " << folder->getName() << "\n";
-  folder->open();
-
-  std::cout << "Folder size: " << folder->getName()
-            << ", size: " << folder->size() << "\n";
-  std::list<File*> files;
-  folder->getFilesRecursive(files);
-  for (const File* f : files) {
-    std::cout << "\t\tFile: " << f->getName() << "\n";
-  }
+/// Leaf.
+class File : public Node {
+ public:
+  File(std::string name, std::size_t bytes)
+      : Node{std::move(name)}, bytes_{bytes} {}
 
-  std::list<Folder*> sub_folders;
-  folder->getSubFoldersRecursive(sub_folders);
-  for (const Folder* sf : sub_folders) {
-    std::cout << "\t\tFolder: " << sf->getName() << "\n";
+  std::size_t sizeBytes() const override { return bytes_; }
+  void print(int depth) const override {
+    LOG_S(indent(depth) << "- " << name() << " (" << bytes_ << " B)");
   }
-}
-}  // namespace client
-
-void run() {
-  std::cout << "\n\n";
-  auto* root = new Folder("root");
-  root->open();
-
-  // Prepare files
-  File* file1 = new File("fileName1.txt");
-  File* file2 = new File("fileName2.txt");
-  File* file3 = new File("fileName3.txt");
-  root->addFile(new File(*file1));
-  root->addFile(new File(*file2));
-  root->addFile(new File(*file3));
-
-  auto* sub_folder1 = new Folder("subFolder1");
-  auto* sub_folder2 = new Folder("subFolder2");
-  auto* sub_folder3 = new Folder("subFolder3");
-
-  root->addFolder(new Folder(*sub_folder1));
-  root->addFolder(new Folder(*sub_folder2));
-  root->addFolder(new Folder(*sub_folder3));
 
-  client::clientCode(root);
-
-  // Clean up memory
-  delete sub_folder1;
-  delete sub_folder2;
-  delete sub_folder3;
-  delete file1;
-  delete file2;
-  delete file3;
-
-  root->removeFileByName("fileName1.txt");
-  client::clientCode(root);
-  delete root;  // deletes all files/subfolders inside recursively
-}
-
-}  // namespace problem
-
-namespace composite_pattern {
-/**
- * Component is the abstraction for leafs and composites.
- * It defines the interface that must be implemented by the objects in the
- * composition. For example a file system resource defines move, copy, rename,
- * and getSize methods for files and folders.
- */
-class FileSystem {
  private:
-  FileSystem* parent_{};
-  std::string name_;
+  std::size_t bytes_;
+};
 
+/// Another leaf: refers to a path, takes (almost) no space itself.
+class Shortcut : public Node {
  public:
-  explicit FileSystem(std::string fileName) : name_{std::move(fileName)} {}
-  virtual ~FileSystem() {
-    std::cout << "Destructor: " << this->getName() << "\n";
-  }
-
-  FileSystem* getParent() const { return parent_; }
-
-  void setParent(FileSystem* parent) { parent_ = parent; }
-
-  std::string getName() const { return this->name_; }
-
-  virtual int size() const { return 1; }
-
-  void setName(const std::string& name) { this->name_ = name; }
-
-  virtual void add(FileSystem*) {
-    // do nothing here
-  }
+  Shortcut(std::string name, std::string target)
+      : Node{std::move(name)}, target_{std::move(target)} {}
 
-  virtual void remove(FileSystem*) {
-    // do nothing here
+  std::size_t sizeBytes() const override { return 1; }
+  void print(int depth) const override {
+    LOG_S(indent(depth) << "~ " << name() << " -> " << target_);
   }
 
-  /**
-   * Check if the component is composite or not
-   * You can provide a method that lets the client code figure out whether a
-   * component can bear children.
-   */
-  virtual bool isComposite() const { return false; }
-
-  virtual void open() const = 0;
-};
-
-/**
- * Composite - A Composite stores child components in addition to implementing
- * methods defined by the component interface. Composites implement methods
- * defined in the Component interface by delegating to child components. In
- * addition composites provide additional methods for adding, removing, as well
- * as getting components.
- */
-class Folder : public FileSystem {
  private:
-  std::list<FileSystem*> children_;
-
-  // Remove children
-  [[maybe_unused]] void removeChildren(const FileSystem* file) {
-    children_.remove_if([file](const FileSystem* f) { return f == file; });
-  }
-
-  [[maybe_unused]] void removeChildrenByName(const std::string& name) {
+  std::string target_;
+};
 
-    auto it = std::find_if(
-        children_.begin(), children_.end(),
-        [&name](const FileSystem* f) { return f->getName() == name; });
+/// Composite: owns its children and delegates to them.
+class Folder : public Node {
+ public:
+  using Node::Node;
 
-    if (it != children_.end()) {
-      delete *it;           // free the memory
-      children_.erase(it);  // remove the pointer from the list
-    }
+  /// Adds a child and returns a reference to it for convenient tree building.
+  template <typename T, typename... Args>
+  T& add(Args&&... args) {
+    auto child = std::make_unique<T>(std::forward<Args>(args)...);
+    T& reference = *child;
+    children_.push_back(std::move(child));
+    return reference;
   }
 
-  [[maybe_unused]] const std::list<FileSystem*>& getChildren() const {
-    return children_;
+  bool remove(const std::string& child_name) {
+    return std::erase_if(children_, [&child_name](const auto& child) {
+             return child->name() == child_name;
+           }) > 0;
   }
 
-  void getChildrensRecursive(std::list<FileSystem*>& out) const {
-    for (FileSystem* fs : children_) {
-      if (fs->isComposite()) {
-        const Folder* f = static_cast<Folder*>(fs);
-        if (f != nullptr)
-          f->getChildrensRecursive(out);
-      } else {
-        out.push_back(fs);
-      }
+  std::size_t sizeBytes() const override {
+    std::size_t total = 0;
+    for (const auto& child : children_) {
+      total += child->sizeBytes();  // leaf or folder - no need to know
     }
+    return total;
   }
 
- public:
-  explicit Folder(const std::string& name) : FileSystem{name} {}
-
-  ~Folder() override {
-    // Delete folder should delete all children
-    for (auto* f : children_) {
-      std::cout << "Folder '" << this->getName()
-                << "' deleted : " << f->getName() << "\n";
-      delete f;
+  void print(int depth) const override {
+    LOG_S(indent(depth) << "+ " << name() << "/ (" << sizeBytes() << " B)");
+    for (const auto& child : children_) {
+      child->print(depth + 1);
     }
   }
 
-  void add(FileSystem* fs) override {
-    std::cout << "Folder '" << this->getName() << "' added : " << fs->getName()
-              << "\n";
-    children_.push_back(fs);
-    fs->setParent(this);
-  }
-
-  void remove(FileSystem* fs) override {
-    std::cout << "Folder: " << this->getName() << "removed : " << fs->getName()
-              << "\n";
-    children_.remove(fs);
-    fs->setParent(nullptr);
-  }
-
-  void open() const override {
-    std::cout << "Open Folder: " << this->getName() << "\n";
-  }
-
-  int size() const override {
-    int size = static_cast<int>(children_.size());
-    std::for_each(children_.begin(), children_.end(), [&size](FileSystem* fs) {
-      if (fs->isComposite()) {
-        const Folder* f = static_cast<Folder*>(fs);
-        if (f != nullptr)
-          size += f->size();
-      }
-    });
-
-    return size;
-  }
-};
-
-/**
- * The Leaf class represents the end objects of a composition. A leaf can't have
- * any children.
- *
- * Usually, it's the Leaf objects that do the actual work, whereas Composite
- * objects only delegate to their sub-components.
- */
-class File : public FileSystem {
- public:
-  explicit File(const std::string& name) : FileSystem{name} {}
-
-  void open() const override {
-    std::cout << "Open File: " << this->getName() << "\n";
-  }
-};
-
-class ZipFile : public FileSystem {
- public:
-  explicit ZipFile(const std::string& name) : FileSystem{name} {}
-
-  void open() const override {
-    std::cout << "Open ZipFile: " << this->getName() << "\n";
-  }
-};
-
-class ShortCut : public FileSystem {
  private:
-  FileSystem* origin_;
-
- public:
-  explicit ShortCut(FileSystem* fs) : FileSystem{fs->getName()} {
-    origin_ = fs;
-  }
-
-  void open() const override {
-    std::cout << "Open ShortCut: " << this->getName() << "\n";
-    if (origin_ != nullptr) {
-      std::cout << "Navigate to: " << origin_->getName() << "\n";
-    } else {
-      std::cout << "Original file no longer exist\n";
-    }
-  }
+  std::vector<std::unique_ptr<Node>>
+      children_;  // destroyed recursively with the folder
 };
 
-namespace client {
-void clientCode(const FileSystem* fs) {
-  std::cout << "File name: " << fs->getName() << ", size: " << fs->size()
-            << "\n";
-  fs->open();
+/// Client code: works with any Node.
+void report(const Node& node) {
+  LOG_S("  " << node.name() << " uses " << node.sizeBytes() << " bytes");
 }
-}  // namespace client
 
 void run() {
-  std::cout << "\n\n";
-  FileSystem* root = new Folder("root");
-  root->open();
-
-  // Prepare files
-  FileSystem* file1 = new File("file_name.txt");
-  FileSystem* file2 = new ZipFile("zipfile_name.txt");
-  FileSystem* file3 = new ShortCut(file2);
-  root->add(file1);
-  root->add(file2);
-  root->add(file3);
-  client::clientCode(file1);
-  client::clientCode(root);
-
-  auto* sub_folder1 = new Folder("subFolder1");
-  auto* sub_folder2 = new Folder("subFolder2");
-  auto* sub_folder3 = new Folder("subFolder3");
-  root->add(sub_folder1);
-  root->add(sub_folder2);
-  root->add(sub_folder3);
-  client::clientCode(root);
-
-  root->remove(file1);
-  delete file1;
-
-  root->remove(file2);
-  delete file2;
-
-  root->remove(file3);
-  delete file3;
-
-  delete root;  // deletes all files/subfolders inside recursively
+  LOG_SECTION("Building a tree");
+  Folder root{"root"};
+  root.add<File>("readme.md", 1200);
+  Folder& src = root.add<Folder>("src");
+  src.add<File>("main.cpp", 5400);
+  Folder& lab = src.add<Folder>("lab");
+  lab.add<File>("Registry.cpp", 4100);
+  lab.add<File>("Menu.cpp", 6300);
+  root.add<Shortcut>("latest-log", "/var/log/cpplab.log");
+  root.print(1);
+
+  LOG_SECTION("The client treats leaves and composites alike");
+  report(root);
+  report(src);
+  report(lab);
+
+  LOG_SECTION("Removing a subtree");
+  src.remove("lab");  // unique_ptr frees the whole subtree
+  root.print(1);
 }
 
-}  // namespace composite_pattern
-
 }  // namespace
 
-#include "ExampleRegistry.h"
-
-class CompositeExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Composite"; }
-  std::string description() const override {
-    return "Composite Pattern Example";
-  }
-  void execute() override {
-    problem::run();
-    composite_pattern::run();
-  }
-};
-
-REGISTER_EXAMPLE(CompositeExample);
\ No newline at end of file
+LAB_EXAMPLE("Composite",
+            "tree structures where leaves and groups share one interface") {
+  run();
+}
diff --git a/src/dp/structural/Decorator.cpp b/src/dp/structural/Decorator.cpp
index 5676fc3..a4d2dfc 100644
--- a/src/dp/structural/Decorator.cpp
+++ b/src/dp/structural/Decorator.cpp
@@ -1,146 +1,161 @@
+// -----------------------------------------------------------------------------
+// Decorator (structural pattern)
+//
+// Attaches new behavior to an object by wrapping it in decorator objects that
+// implement the same interface. Decorators can be stacked in any combination
+// at run time.
+//
+// Problem: a notifier that can also send SMS, Slack or both, with or without
+// email... Subclasses for every combination explode: 3 optional features
+// already need 2^3 = 8 classes.
+// Solution: one decorator per feature; combine them by wrapping:
+//   SlackDecorator(SmsDecorator(EmailNotifier))
+//
+// Use it when:
+//   - responsibilities should be added to individual objects at run time
+//   - extending by subclassing is impractical or impossible (final classes)
+//
+// Participants:
+//   Component           Notifier interface
+//   ConcreteComponent   EmailNotifier
+//   Decorator           NotifierDecorator - holds and forwards to a Notifier
+//   ConcreteDecorator   SmsDecorator, SlackDecorator
+//
+// UML: docs/uml/dp/structural_decorator.drawio.svg
+// -----------------------------------------------------------------------------
+
 #include <memory>
 #include <string>
-#include "Logger.h"
+#include <utility>
 
-#include "ExampleRegistry.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
-class IComponent {
+/// Component.
+class Notifier {
  public:
-  virtual ~IComponent() = default;
-  virtual std::string operation() const = 0;
-};
-
-auto client_code = [](const IComponent* comp) {
-  LOG(comp->operation());
+  virtual ~Notifier() = default;
+  virtual void send(const std::string& message) const = 0;
 };
 
 namespace problem {
-class ConcreteComponent : public IComponent {
+
+class EmailNotifier : public Notifier {
  public:
-  std::string operation() const override { return "ConcreteComponent"; }
+  void send(const std::string& message) const override {
+    LOG_S("    email: " << message);
+  }
 };
 
-class ComponentWithA : public ConcreteComponent {
+class EmailAndSmsNotifier : public EmailNotifier {
  public:
-  std::string operation() const override {
-    return ConcreteComponent::operation() + " + FeatureA";
+  void send(const std::string& message) const override {
+    EmailNotifier::send(message);
+    LOG_S("    sms  : " << message);
   }
 };
 
-class ComponentWithB : public ConcreteComponent {
+class EmailAndSlackNotifier : public EmailNotifier {
  public:
-  std::string operation() const override {
-    return ConcreteComponent::operation() + " + FeatureB";
+  void send(const std::string& message) const override {
+    EmailNotifier::send(message);
+    LOG_S("    slack: " << message);
   }
 };
 
-class ComponentWithAandB : public ConcreteComponent {
+class EmailAndSmsAndSlackNotifier : public EmailAndSmsNotifier {
  public:
-  std::string operation() const override {
-    return ConcreteComponent::operation() + " + FeatureA + FeatureB";
+  void send(const std::string& message) const override {
+    EmailAndSmsNotifier::send(message);
+    LOG_S("    slack: " << message);
   }
 };
+// ...plus SmsOnly, SlackOnly, SmsAndSlack... one class per combination.
 
 void run() {
-  // [P1]
-  // If you have 3 features , e.g FeatureC -> many combinations
-  // If you have 5 features -> 32 subclasses
-  LOG("Problem");
-  std::unique_ptr<IComponent> simple = std::make_unique<ConcreteComponent>();
-  client_code(simple.get());
-
-  std::unique_ptr<IComponent> with_a = std::make_unique<ComponentWithA>();
-  client_code(with_a.get());
-
-  std::unique_ptr<IComponent> with_b = std::make_unique<ComponentWithB>();
-  client_code(with_b.get());
-
-  std::unique_ptr<IComponent> with_ab = std::make_unique<ComponentWithAandB>();
-  client_code(with_ab.get());
+  LOG_SECTION("Problem: one subclass per combination");
+  const EmailAndSmsAndSlackNotifier notifier;
+  notifier.send("server is down");
 }
+
 }  // namespace problem
 
-namespace decorator_pattern {
-/// @class Concrete Component
-class ConcreteComponent : public IComponent {
+namespace decorator {
+
+/// Concrete component.
+class EmailNotifier : public Notifier {
  public:
-  std::string operation() const override { return "ConcreteComponent"; }
+  void send(const std::string& message) const override {
+    LOG_S("    email: " << message);
+  }
 };
 
-/// @class Base Decorator
-class BaseDecorator : public IComponent {
- protected:
-  std::unique_ptr<IComponent> component_;
-
+/// Base decorator: same interface, forwards to the wrapped object.
+class NotifierDecorator : public Notifier {
  public:
-  explicit BaseDecorator(std::unique_ptr<IComponent> component)
-      : component_(std::move(component)) {}
+  explicit NotifierDecorator(std::unique_ptr<Notifier> wrapped)
+      : wrapped_{std::move(wrapped)} {}
+  void send(const std::string& message) const override {
+    wrapped_->send(message);
+  }
 
-  /// the Decorator delegates all work to the wrapped componentx
-  std::string operation() const override { return component_->operation(); }
+ private:
+  std::unique_ptr<Notifier> wrapped_;
 };
 
-/// @class Concrete Decorator
-class ConcreteDecoratorA : public BaseDecorator {
+/// Concrete decorators add behavior before/after forwarding.
+class SmsDecorator : public NotifierDecorator {
  public:
-  explicit ConcreteDecoratorA(std::unique_ptr<IComponent> component)
-      : BaseDecorator(std::move(component)) {}
-
-  std::string operation() const override {
-    return BaseDecorator::operation() + " + FeatureA";
+  using NotifierDecorator::NotifierDecorator;
+  void send(const std::string& message) const override {
+    NotifierDecorator::send(message);
+    LOG_S("    sms  : " << message);
   }
 };
 
-class ConcreteDecoratorB : public BaseDecorator {
+class SlackDecorator : public NotifierDecorator {
  public:
-  explicit ConcreteDecoratorB(std::unique_ptr<IComponent> component)
-      : BaseDecorator(std::move(component)) {}
-
-  std::string operation() const override {
-    return BaseDecorator::operation() + " + FeatureB";
+  using NotifierDecorator::NotifierDecorator;
+  void send(const std::string& message) const override {
+    NotifierDecorator::send(message);
+    LOG_S("    slack: " << message);
   }
 };
 
-class ConcreteDecoratorC : public BaseDecorator {
+class UrgentDecorator
+    : public NotifierDecorator {  // changes the message itself
  public:
-  explicit ConcreteDecoratorC(std::unique_ptr<IComponent> component)
-      : BaseDecorator(std::move(component)) {}
-
-  std::string operation() const override {
-    return BaseDecorator::operation() + " + FeatureC";
+  using NotifierDecorator::NotifierDecorator;
+  void send(const std::string& message) const override {
+    NotifierDecorator::send("[URGENT] " + message);
   }
 };
 
 void run() {
-  LOG("Decorator");
-  std::unique_ptr<IComponent> simple = std::make_unique<ConcreteComponent>();
-  client_code(simple.get());
-
-  std::unique_ptr<IComponent> with_a =
-      std::make_unique<ConcreteDecoratorA>(std::move(simple));
-  std::unique_ptr<IComponent> with_ab =
-      std::make_unique<ConcreteDecoratorB>(std::move(with_a));
-  std::unique_ptr<IComponent> with_abc =
-      std::make_unique<ConcreteDecoratorC>(std::move(with_ab));
-  client_code(with_abc.get());
+  LOG_SECTION("Decorator: combine features by wrapping");
+  std::unique_ptr<Notifier> notifier = std::make_unique<EmailNotifier>();
+  LOG("  email only:");
+  notifier->send("build finished");
+
+  notifier = std::make_unique<SmsDecorator>(std::move(notifier));
+  notifier = std::make_unique<SlackDecorator>(std::move(notifier));
+  LOG("  email + sms + slack:");
+  notifier->send("deploy started");
+
+  notifier = std::make_unique<UrgentDecorator>(std::move(notifier));
+  LOG("  wrapped once more with UrgentDecorator:");
+  notifier->send("server is down");
 }
-}  // namespace decorator_pattern
 
-}  // namespace
+}  // namespace decorator
 
-class DecoratorExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Decorator"; }
-  std::string description() const override {
-    return "Decorator Pattern Example";
-  }
-  void execute() override {
-    problem::run();
-    decorator_pattern::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(DecoratorExample);
\ No newline at end of file
+LAB_EXAMPLE(
+    "Decorator",
+    "stack wrappers at run time instead of subclassing every combination") {
+  problem::run();
+  decorator::run();
+}
diff --git a/src/dp/structural/Facade.cpp b/src/dp/structural/Facade.cpp
index ff918ec..eb5b085 100644
--- a/src/dp/structural/Facade.cpp
+++ b/src/dp/structural/Facade.cpp
@@ -1,265 +1,142 @@
-// cppcheck-suppress-file [functionStatic]
+// -----------------------------------------------------------------------------
+// Facade (structural pattern)
+//
+// Provides a simple interface to a complex subsystem. Clients call the facade
+// instead of orchestrating many subsystem classes themselves.
+//
+// Problem: to send one request, every client must validate, authenticate, log
+// and call the backend - in the right order, with the right error handling.
+// The same orchestration gets copied everywhere.
+// Solution: RequestFacade::send() does it once. Clients that need more control
+// can still use the subsystems directly.
+//
+// Use it when:
+//   - you want a limited but straightforward interface to a complex subsystem
+//   - you want to structure a system into layers
+//
+// Injecting the subsystems (instead of creating them inside the facade) also
+// makes the facade easy to test with fakes, as shown at the end.
+//
+// UML: docs/uml/dp/structural_facade.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-// Facade is a structural design pattern that provides a simplified interface
-// to a library, a framework, or any other complex set of classes.
-// Appicability:
-// (*)   when you need to have a limited but straightforward interface to a
-// complex subsystem.
-// (**)  when you want to structure a subsystem into layers.
-// UML: docs/uml/patterns_structural_facade.drawio.svg
-
-#include <iostream>
 namespace {
-namespace problem {
 
-class AuthSubSystem {
+// --- Subsystem classes -------------------------------------------------------
+
+class Validator {
  public:
-  virtual ~AuthSubSystem() = default;
-  void login() {
-    std::cout << "AuthSubSystem: login\n";
-    dummy_++;
+  bool check(const std::string& payload) const {
+    const bool ok = !payload.empty();
+    LOG_S("    Validator: payload " << (ok ? "is valid" : "is empty"));
+    return ok;
   }
-
- private:
-  int dummy_{};
 };
 
-class ValidatorSubSystem {
+class Authenticator {
  public:
-  virtual ~ValidatorSubSystem() = default;
-  virtual void check() {
-    std::cout << "ValidatorSubSystem: check input\n";
-    dummy_++;
+  bool login(const std::string& user) const {
+    LOG_S("    Authenticator: login " << user);
+    return user != "guest";
   }
-
- private:
-  int dummy_{};
 };
 
-class LoggerSubSystem {
+class AuditLog {
  public:
-  virtual ~LoggerSubSystem() = default;
-  void write() {
-    std::cout << "LoggerSubSystem: write log\n";
-    dummy_++;
+  void write(const std::string& entry) const {
+    LOG_S("    AuditLog: " << entry);
   }
-
- private:
-  int dummy_{};
 };
 
-class BackendSubSystem {
+class Backend {
  public:
-  virtual ~BackendSubSystem() = default;
-  void send() {
-    std::cout << "BackendSubSystem: send request\n";
-    dummy_++;
+  virtual ~Backend() = default;
+  virtual void send(const std::string& payload) const {
+    LOG_S("    Backend: POST " << payload);
   }
-
- private:
-  int dummy_{};
 };
 
-namespace client1 {
-// The client must manually interact with each subsystem.
-// This creates unnecessary complexity.
-void clientCode(ValidatorSubSystem& s1, AuthSubSystem& s2, LoggerSubSystem& s3,
-                BackendSubSystem& s4) {
-  s1.check();
-  s2.login();
-  s3.write();
-  s4.send();
-
-  // In real code, the client must also
-  //   - know call ordering
-  //   - combine subsystem operations
-  //   - manage lifecycle and error handling
-}
-}  // namespace client1
-
-namespace client2 {
-// The client must manually interact with each subsystem.
-// This creates unnecessary complexity.
-void clientCode(ValidatorSubSystem& s1) {
-  s1.check();
-}
-}  // namespace client2
+namespace problem {
 
 void run() {
-  std::cout << "\n\nProblem\n";
-
-  ValidatorSubSystem v;
-  AuthSubSystem a;
-  LoggerSubSystem l;
-  BackendSubSystem b;
-
-  client1::clientCode(v, a, l, b);
-  client2::clientCode(v);
-}
-}  // namespace problem
-
-namespace facade {
-
-class AuthSubSystem {
- public:
-  virtual ~AuthSubSystem() = default;
-  void login() {
-    std::cout << "AuthSubSystem: login\n";
-    dummy_++;
+  LOG_SECTION("Problem: every client orchestrates the subsystem itself");
+  const Validator validator;
+  const Authenticator authenticator;
+  const AuditLog log;
+  const Backend backend;
+
+  const std::string payload = R"({"order": 42})";
+  if (validator.check(payload) &&
+      authenticator.login("alice")) {  // must know the order...
+    log.write("alice sends an order");
+    backend.send(payload);  // ...and every step
   }
+}
 
- private:
-  int dummy_{};
-};
-
-class ValidatorSubSystem {
- public:
-  virtual ~ValidatorSubSystem() = default;
-  void check() {
-    std::cout << "ValidatorSubSystem: check input\n";
-    dummy_++;
-  }
+}  // namespace problem
 
- private:
-  int dummy_{};
-};
+// --- Facade ------------------------------------------------------------------
 
-class LoggerSubSystem {
+class RequestFacade {
  public:
-  virtual ~LoggerSubSystem() = default;
-  void write() {
-    std::cout << "LoggerSubSystem: write log\n";
-    dummy_++;
+  explicit RequestFacade(
+      std::unique_ptr<Backend> backend = std::make_unique<Backend>())
+      : backend_{std::move(backend)} {}
+
+  /// One call hides the whole workflow.
+  bool send(const std::string& user, const std::string& payload) const {
+    if (!validator_.check(payload)) {
+      return false;
+    }
+    if (!authenticator_.login(user)) {
+      log_.write(user + " was rejected");
+      return false;
+    }
+    log_.write(user + " sends a request");
+    backend_->send(payload);
+    return true;
   }
 
  private:
-  int dummy_{};
-};
-
-class BackendSubSystem {
- public:
-  virtual ~BackendSubSystem() = default;
-  virtual void send() const { std::cout << "BackendSubSystem: send request\n"; }
+  Validator validator_;
+  Authenticator authenticator_;
+  AuditLog log_;
+  std::unique_ptr<Backend> backend_;
 };
 
-// =======================
-// Mock subclasses (for testing)
-// =======================
-class MockBackendSubSystem : public BackendSubSystem {
+/// A fake backend for tests: no network access.
+class FakeBackend : public Backend {
  public:
-  void send() const override { std::cout << "[MockBackend] fake-send\n"; }
-};
-
-/**
- * The Facade class provides a simple interface to the complex logic of one or
- * several subsystems. The Facade delegates the client requests to the
- * appropriate objects within the subsystem. The Facade is also responsible for
- * managing their lifecycle. All of this shields the client from the undesired
- * complexity of the subsystem.
- */
-class RequestFacade {
- protected:
-  AuthSubSystem* auth_;
-  ValidatorSubSystem* validator_;
-  LoggerSubSystem* logger_;
-  BackendSubSystem* backend_;
-
-  /**
-   * Depending on your application's needs, you can provide the Facade with
-   * existing subsystem objects or force the Facade to create them on its own.
-   */
- public:
-  /**
-   * In this case we will delegate the memory ownership to Facade Class
-   */
-  explicit RequestFacade(AuthSubSystem* s1 = nullptr,
-                         ValidatorSubSystem* s2 = nullptr,
-                         LoggerSubSystem* s3 = nullptr,
-                         BackendSubSystem* s4 = nullptr) {
-    this->auth_ = s1 ? s1 : new AuthSubSystem();
-    this->validator_ = s2 ? s2 : new ValidatorSubSystem();
-    this->logger_ = s3 ? s3 : new LoggerSubSystem();
-    this->backend_ = s4 ? s4 : new BackendSubSystem();
-  }
-
-  ~RequestFacade() {
-    delete auth_;
-    delete validator_;
-    delete logger_;
-    delete backend_;
-  }
-
-  /**
-   * The Facade's methods are convenient shortcuts to the sophisticated
-   * functionality of the subsystems. However, clients get only to a fraction of
-   * a subsystem's capabilities.
-   */
-  void sendRequest() {
-    validator_->check();
-    auth_->login();
-    logger_->write();
-    backend_->send();
+  void send(const std::string& payload) const override {
+    LOG_S("    FakeBackend: pretended to send " << payload);
   }
-
-  void validate() { validator_->check(); }
 };
 
-namespace client1 {
-/**
- * The client code works with complex subsystems through a simple interface
- * provided by the Facade. When a facade manages the lifecycle of the subsystem,
- * the client might not even know about the existence of the subsystem. This
- * approach lets you keep the complexity under control.
- */
-void clientCode(RequestFacade& facade) {
-  facade.sendRequest();
-}
-}  // namespace client1
-
-namespace client2 {
-/**
- * The client code works with complex subsystems through a simple interface
- * provided by the Facade. When a facade manages the lifecycle of the subsystem,
- * the client might not even know about the existence of the subsystem. This
- * approach lets you keep the complexity under control.
- */
-void clientCode(RequestFacade& facade) {
-  facade.validate();
-}
-}  // namespace client2
-
 void run() {
-  std::cout << "\n\nFacade\n";
-  {
-    auto* facade = new RequestFacade();
-    client1::clientCode(*facade);
-    client2::clientCode(*facade);
-    delete facade;
-  }
-
-  {
-    // injected subsystems for mocktest
-    std::cout << "\n";
-    auto* b = new MockBackendSubSystem();
-    auto* facade = new RequestFacade(nullptr, nullptr, nullptr, b);
-    client1::clientCode(*facade);
-    delete facade;
-  }
+  LOG_SECTION("Facade: clients call one simple method");
+  const RequestFacade facade;
+  LOG_S("  result: " << std::boolalpha
+                     << facade.send("alice", R"({"order": 42})"));
+  LOG_S("  result: " << std::boolalpha
+                     << facade.send("guest", R"({"order": 43})"));
+  LOG_S("  result: " << std::boolalpha << facade.send("alice", ""));
+
+  LOG_SECTION("Injecting a fake subsystem for testing");
+  const RequestFacade test_facade{std::make_unique<FakeBackend>()};
+  test_facade.send("tester", R"({"order": "test"})");
 }
-}  // namespace facade
-}  // namespace
-
-#include "ExampleRegistry.h"
 
-class FacadeExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Facade"; }
-  std::string description() const override { return "Facade Pattern Example"; }
-  void execute() override {
-    problem::run();
-    facade::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(FacadeExample);
\ No newline at end of file
+LAB_EXAMPLE("Facade",
+            "one simple entry point in front of a complex subsystem") {
+  problem::run();
+  run();
+}
diff --git a/src/dp/structural/Flyweight.cpp b/src/dp/structural/Flyweight.cpp
index 14cedbd..ce44ec5 100644
--- a/src/dp/structural/Flyweight.cpp
+++ b/src/dp/structural/Flyweight.cpp
@@ -1,346 +1,160 @@
-// Flyweight is a structural design pattern that lets you fit more objects
-// into the available amount of RAM by sharing common parts of state between
-// multiple objects
-//  instead of keeping all of the data in each object.
-// Appicability:
-// (*) when your program must support a huge number of objects which barely fit
-// into available RAM,
-//     and the objects contain duplicate states which can be extracted and
-//     shared between multiple objects
-// UML: docs/uml/patterns_structural_flyweight.drawio.svg
-
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Flyweight (structural pattern)
+//
+// Fits more objects into memory by sharing the parts of their state that are
+// identical, instead of storing a copy in every object.
+//
+//   intrinsic state : shared, immutable (the pixels of an image, a font glyph)
+//   extrinsic state : unique per object (position, scale, opacity)
+//
+// Problem: thousands of sprites of the same tree image each store their own
+// copy of the pixel data.
+// Solution: one shared, immutable ImageData per distinct image; each sprite
+// only stores a pointer to it plus its own extrinsic state.
+//
+// Use it when:
+//   - a program needs a huge number of similar objects
+//   - most of their state can be extracted and shared
+//
+// Participants:
+//   Flyweight         ImageData (intrinsic state, immutable)
+//   FlyweightFactory  ImageCache - returns an existing flyweight or creates one
+//   Context           Sprite (extrinsic state + pointer to the flyweight)
+//
+// UML: docs/uml/dp/structural_flyweight.drawio.svg
+// -----------------------------------------------------------------------------
+
+#include <cstddef>
+#include <map>
+#include <memory>
 #include <string>
-#include <unordered_map>
+#include <tuple>
 #include <utility>
+#include <vector>
 
-namespace {
-namespace problem {
-class ImageContext {
- protected:
- private:
-  // Shared attrs
-  std::string fileName_;
-  int width_, height_, dpi_;
-  int* data_;
-
-  // Unique attrs
-  float scale_;
-  float opacity_;
-
-  void deepCopy(const ImageContext& other) {
-    // normal field
-    this->fileName_ = other.fileName_;
-    this->width_ = other.width_;
-    this->height_ = other.height_;
-    this->dpi_ = other.dpi_;
-    this->scale_ = other.scale_;
-    this->opacity_ = other.opacity_;
-
-    // ptr field
-    delete[] this->data_;
-    if (other.data_ != nullptr) {
-      int size = this->width_ * this->height_;
-      this->data_ = new int[size];
-      for (int i = 0; i < size; ++i) {
-        this->data_[i] = other.data_[i];
-      }
-    } else {
-      this->data_ = nullptr;
-    }
-  }
-
- public:
-  // Role of five
-  // CONSTRUCTOR
-  explicit ImageContext(std::string fileName, int w = 8, int h = 8,
-                        int dpi = 96, float scale = 1, float opacity = 1)
-      : fileName_{std::move(fileName)},
-        width_{w},
-        height_{h},
-        dpi_{dpi},
-        data_{new int[w * h]},
-        scale_{scale},
-        opacity_{opacity} {
-    std::cout << "Image: " << fileName_ << " created.\n";
-  }
-
-  // DESTRUCTOR
-  virtual ~ImageContext() { delete[] data_; }
-
-  // COPY CONSTRUCTOR
-  ImageContext(const ImageContext& other) { this->deepCopy(other); }
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-  // COPY ASSIGNMENT
-  ImageContext& operator=(const ImageContext& other) {
-    if (this != &other) {
-      this->deepCopy(other);
-    }
-    return *this;
-  }
+namespace {
 
-  void setScale(const float scale) { this->scale_ = scale; }
+constexpr int kWidth = 32;
+constexpr int kHeight = 32;
+constexpr std::size_t kSpriteCount = 2'000;
 
-  void setOpacity(const float opacity) { this->opacity_ = opacity; }
+namespace problem {
 
-  void display() const {
-    std::cout << "Image: " << fileName_ << " displayed. \n";
-    std::cout << "\tWidth: " << width_ << " Height: " << height_
-              << " DPI: " << dpi_ << "\n";
-    std::cout << "\tScale: " << scale_ << " Opacity: " << opacity_ << "\n";
-  }
+/// Every sprite owns its own copy of the pixels (Rule of Zero: std::vector copies itself).
+struct Sprite {
+  std::string file;
+  std::vector<int> pixels;  // intrinsic, duplicated in every object
+  float x;
+  float y;
+  float scale;
 };
 
-namespace client {
-void clientCode(const ImageContext* img) {
-  img->display();
-}
-}  // namespace client
-
 void run() {
-  std::cout << "\n\nProblem\n";
-  auto** imgs = new ImageContext*[5];
-  for (int i = 0; i < 5; i++) {
-    imgs[i] = new ImageContext("img1.svg");
-    imgs[i]->setOpacity(1 - static_cast<float>(1) / (i + 1));
-    imgs[i]->setScale(static_cast<float>(1) / (i + 1));
-    client::clientCode(imgs[i]);
-  }
-
-  // delete objects first
-  for (int i = 0; i < 5; i++) {
-    delete imgs[i];
+  LOG_SECTION("Problem: every object stores the same pixels");
+  std::vector<Sprite> forest;
+  forest.reserve(kSpriteCount);
+  for (std::size_t i = 0; i < kSpriteCount; ++i) {
+    forest.push_back({"tree.png", std::vector<int>(kWidth * kHeight),
+                      static_cast<float>(i), 0.0F, 1.0F});
   }
-
-  // then delete array
-  delete[] imgs;
-  std::cout << "Size of objects: " << sizeof(ImageContext) * 5 << "\n";
+  const std::size_t bytes =
+      forest.size() * (sizeof(Sprite) + kWidth * kHeight * sizeof(int));
+  LOG_S("  " << forest.size() << " sprites use about " << bytes / 1024
+             << " KiB");
 }
-}  // namespace problem
-
-namespace flyweight_pattern {
-
-/**
- * The Flyweight stores a common portion of the state (also called intrinsic
- * state) that belongs to multiple real business entities.
- * The Flyweight accepts the rest of the state (extrinsic state, unique for each
- * entity) via its method parameters.
- */
-class ImageFlyweight {
- private:
-  std::string fileName_;
-  int width_, height_, dpi_;
-  int* data_;
 
-  void deepCopy(const ImageFlyweight& other) {
-    // normal field
-    this->fileName_ = other.fileName_;
-    this->width_ = other.width_;
-    this->height_ = other.height_;
-    this->dpi_ = other.dpi_;
+}  // namespace problem
 
-    // ptr field
-    delete[] this->data_;
-    if (other.data_ != nullptr) {
-      int size = this->width_ * this->height_;
-      this->data_ = new int[size];
-      for (int i = 0; i < size; ++i) {
-        this->data_[i] = other.data_[i];
-      }
-    } else {
-      this->data_ = nullptr;
-    }
-  }
+namespace flyweight {
 
+/// Flyweight: intrinsic state, immutable and therefore safe to share.
+class ImageData {
  public:
-  explicit ImageFlyweight(std::string fileName, int w = 8, int h = 8,
-                          int dpi = 96)
-      : fileName_{std::move(fileName)},
-        width_{w},
-        height_{h},
-        dpi_{dpi},
-        data_{new int[w * h]} {};
-
-  ~ImageFlyweight() { delete[] data_; }
-
-  // Note:
-  // [Copy constructor/assignment]: creates a new copy(shallow or deep) of the
-  // source object's data.
-  //                        -> Allocates new memory and duplicates all elements.
-  //                        -> Source object remains unchanged.
-  //
-  // [Move constructor/assignment[] ("steal"): transfers ownership of the
-  // source's resources
-  //                        -> No new memory allocation; destination uses the
-  //                        same memory as source.
-  //                        -> Source is reset to a safe empty state (nullptr,
-  //                        0, etc.).
-  //                        ==> Much faster for large objects since no deep copy
-  //                        occurs.
-
-  ImageFlyweight(const ImageFlyweight& other) { this->deepCopy(other); }
-
-  ImageFlyweight& operator=(const ImageFlyweight& other) {
-    if (this != &other) {
-      this->deepCopy(other);
-    }
-    return *this;
-  }
-
-  ImageFlyweight(ImageFlyweight&& source) noexcept
-      : fileName_(std::move(source.fileName_)),
-        width_(source.width_),
-        height_(source.height_),
-        dpi_(source.dpi_),
-        data_(source.data_) {
-    source.width_ = 0;
-    source.height_ = 0;
-    source.dpi_ = 0;
-    source.data_ = nullptr;
+  ImageData(std::string file, int width, int height)
+      : file_{std::move(file)},
+        width_{width},
+        height_{height},
+        pixels_(width * height) {
+    LOG_S("    loading " << file_ << " (" << width_ << "x" << height_ << ")");
   }
 
-  ImageFlyweight& operator=(ImageFlyweight&& source) noexcept {
-    if (this != &source) {
-      // stealSource
-      // free current resource
-      delete[] data_;
-
-      // move resource from source
-      fileName_ = std::move(source.fileName_);  // move string
-      width_ = source.width_;
-      height_ = source.height_;
-      dpi_ = source.dpi_;
-      data_ = source.data_;
-
-      // reset source
-      source.width_ = 0;
-      source.height_ = 0;
-      source.dpi_ = 0;
-      source.data_ = nullptr;
-    }
-    return *this;
+  const std::string& file() const { return file_; }
+  std::size_t bytes() const {
+    return sizeof(*this) + pixels_.size() * sizeof(int);
   }
 
-  /**
-   * Display the image at give scale, opacity
-   */
-  void display(const float& scale, const float& opacity) const {
-    std::cout << "Image: " << fileName_ << " displayed. \n";
-    std::cout << "\tWidth: " << width_ << " Height: " << height_
-              << " DPI: " << dpi_ << "\n";
-    std::cout << "\tScale: " << scale << " Opacity: " << opacity << "\n";
-  }
+ private:
+  std::string file_;
+  int width_;
+  int height_;
+  std::vector<int> pixels_;
 };
 
-/**
- * The Flyweight Factory manages a pool of existing flyweights.
- *  With the factory, clients don’t create flyweights directly. Instead, they
- * call the factory, passing it bits of the intrinsic state of the desired
- * flyweight. The factory looks over previously created flyweights and either
- * returns an existing one that matches search criteria or creates a new one if
- * nothing is found.
- */
-class ImageFlyweightFactory {
- private:
-  std::unordered_map<std::string, ImageFlyweight>
-      imageFlyweights_;  // unordered_map => need to role of five
-  static std::string getKey(const std::string& name, int w, int h, int dpi) {
-    return "key_" + name + std::to_string(w * h * dpi);
+/// Flyweight factory: one ImageData per distinct (file, width, height).
+class ImageCache {
+ public:
+  std::shared_ptr<const ImageData> get(const std::string& file, int width,
+                                       int height) {
+    const auto key =
+        std::make_tuple(file, width, height);  // all intrinsic fields
+    auto& slot = cache_[key];
+    if (!slot) {
+      slot = std::make_shared<const ImageData>(file, width, height);
+    }
+    return slot;
   }
 
- public:
-  ImageFlyweight& getImangeFlyweight(const std::string& fileName, int w = 8,
-                                     int h = 8, int dpi = 96) {
-    std::string key = getKey(fileName, w, h, dpi);
-    std::cout << "Key: " << key << "\n";
-    if (this->imageFlyweights_.find(key) == this->imageFlyweights_.end()) {
-      std::cout << "ImageFlyweightFactory: Can't find a image flyweight, "
-                   "creating new one.\n";
-      this->imageFlyweights_.insert(
-          std::make_pair(key, ImageFlyweight(fileName, w, h, dpi)));
-    } else {
-      std::cout << "ImageFlyweightFactory: Reusing existing image flyweight.\n";
+  std::size_t size() const { return cache_.size(); }
+  std::size_t bytes() const {
+    std::size_t total = 0;
+    for (const auto& [key, image] : cache_) {
+      total += image->bytes();
     }
-    return this->imageFlyweights_.at(key);
+    return total;
   }
-};
 
-/**
- * The Context class contains the extrinsic state, unique across all original
- * objects. When a context is paired with one of the flyweight objects, it
- * represents the full state of the original object.
- */
-class ImageContext {
  private:
-  float scale_;
-  float opacity_;
-  ImageFlyweight* flyweight_;
-
- public:
-  ImageContext(ImageFlyweight& imageFlyweight, const float& s, const float& o)
-      : scale_{s}, opacity_{o}, flyweight_{&imageFlyweight} {}
-
-  void display() const { this->flyweight_->display(scale_, opacity_); }
+  std::map<std::tuple<std::string, int, int>, std::shared_ptr<const ImageData>>
+      cache_;
 };
 
-/**
- * The Client calculates or stores the extrinsic state of flyweights.
- * From the client’s perspective, a flyweight is a template object which can be
- * configured at runtime by passing some contextual data into parameters of its
- * methods.
- */
-namespace client {
-void clientCode(const ImageContext* img) {
-  img->display();
-}
-}  // namespace client
+/// Context: extrinsic state + shared flyweight.
+struct Sprite {
+  std::shared_ptr<const ImageData> image;
+  float x;
+  float y;
+  float scale;
+};
 
 void run() {
-  std::cout << "\n\nFlyweight\n";
-  // Regis the images to the factory
-  auto* image_register = new ImageFlyweightFactory();
-  auto* img1 =
-      new ImageContext(image_register->getImangeFlyweight("img1.svg"), 1, 0.1);
-  client::clientCode(img1);
-  auto* img2 =
-      new ImageContext(image_register->getImangeFlyweight("img1.svg"), 1, 0.2);
-  client::clientCode(img2);
-  auto* img3 =
-      new ImageContext(image_register->getImangeFlyweight("img1.svg"), 1, 0.3);
-  client::clientCode(img3);
-  auto* img4 =
-      new ImageContext(image_register->getImangeFlyweight("img1.svg"), 1, 0.4);
-  client::clientCode(img4);
-  auto* img5 =
-      new ImageContext(image_register->getImangeFlyweight("img1.svg"), 1, 0.5);
-  client::clientCode(img5);
-  std::cout << "Size of objects: "
-            << sizeof(ImageFlyweightFactory) + sizeof(ImageContext) * 5 << "\n";
+  LOG_SECTION("Flyweight: share the pixels, keep only positions per object");
+  ImageCache cache;
+  std::vector<Sprite> forest;
+  forest.reserve(kSpriteCount);
+  for (std::size_t i = 0; i < kSpriteCount; ++i) {
+    const char* file =
+        (i % 3 == 0) ? "pine.png" : "oak.png";  // two distinct images
+    forest.push_back(
+        {cache.get(file, kWidth, kHeight), static_cast<float>(i), 0.0F, 1.0F});
+  }
 
-  delete img1;
-  delete img2;
-  delete img3;
-  delete img4;
-  delete img5;
-  delete image_register;
+  const std::size_t bytes = forest.size() * sizeof(Sprite) + cache.bytes();
+  LOG_S("  " << forest.size() << " sprites share " << cache.size()
+             << " images, about " << bytes / 1024 << " KiB in total");
+  LOG_S("  sprite 0 draws " << forest[0].image->file() << ", sprite 1 draws "
+                            << forest[1].image->file() << " (use_count "
+                            << forest[1].image.use_count() << ")");
 }
 
-}  // namespace flyweight_pattern
-}  // namespace
+}  // namespace flyweight
 
-#include "ExampleRegistry.h"
-
-class FlyweightExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Flyweight"; }
-  std::string description() const override {
-    return "Flyweight Pattern Example";
-  }
-  void execute() override {
-    problem::run();
-    flyweight_pattern::run();
-  }
-};
+}  // namespace
 
-REGISTER_EXAMPLE(FlyweightExample);
\ No newline at end of file
+LAB_EXAMPLE("Flyweight",
+            "share immutable intrinsic state between many small objects") {
+  problem::run();
+  flyweight::run();
+}
diff --git a/src/dp/structural/Proxy.cpp b/src/dp/structural/Proxy.cpp
index dd7427c..b76881c 100644
--- a/src/dp/structural/Proxy.cpp
+++ b/src/dp/structural/Proxy.cpp
@@ -1,149 +1,110 @@
-// Composition - lazy
-// Aggregation - x
+// -----------------------------------------------------------------------------
+// Proxy (structural pattern)
+//
+// Provides a substitute for another object. The proxy implements the same
+// interface and controls access to the real object, doing something before or
+// after forwarding the request.
+//
+// Common kinds of proxies:
+//   - virtual proxy    : creates an expensive object only when first needed
+//   - protection proxy : checks permissions before forwarding
+//   - logging proxy    : records requests
+//   - remote proxy     : hides that the object lives in another process
+//   (std::shared_ptr is a "smart reference" proxy for the pointee.)
+//
+// Problem: a heavy Server is constructed even if nobody ever calls it, and
+// access checks and logging would have to be added inside the Server itself.
+// Solution: ServerProxy adds lazy creation, access control and logging without
+// changing Server.
+//
+// Participants:
+//   Subject      Service interface
+//   RealSubject  Server
+//   Proxy        ServerProxy (same interface, owns the Server lazily)
+//
+// UML: docs/uml/dp/structural_proxy.drawio.svg
+// -----------------------------------------------------------------------------
 
 #include <memory>
+#include <string>
 #include <utility>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
-/// @class Server Interface
-class IServer {
- public:
-  virtual ~IServer() = default;
 
-  /// @brief api
-  virtual void request() = 0;
+/// Subject.
+class Service {
+ public:
+  virtual ~Service() = default;
+  virtual void request(const std::string& user) = 0;
 };
 
-/// @brief User code
-void clientCode(IServer* s) {
-  if (s != nullptr) {
-    s->request();
-  }
-}
-
-namespace problem {
-const std::string kAdmin = "admin";
-class Server : public IServer {
- private:
-  std::string id_;
-
+/// Real subject: expensive to create.
+class Server : public Service {
  public:
-  explicit Server(std::string id) : id_{std::move(id)} {
-    // [P1] Heavy or complex construction, so ideally should be lazy-loaded
-    LOG_S("CTR: " << id_);
+  Server() {
+    LOG("    Server: expensive construction (connect, load data...)");
   }
-
-  // [P2] Need access control
-  // [P3] Need to log requests without modifying the Server itself
-  void request() override {
-    if (id_ != kAdmin) {
-      LOG_S("Invalid ID: " << id_);
-      return;
-    }
-    LOG_S("Handling request for: " << id_);
+  void request(const std::string& user) override {
+    LOG_S("    Server: handling request of " << user);
   }
 };
 
-void run() {
-  {
-    std::string connection_id = "admin";
-    // [P4] The Server is constructed immediately even if we do not call any
-    // requests
-    auto server = std::make_unique<Server>(connection_id);
-    LOG("User request");
-    clientCode(server.get());
-  }
-
-  {
-    // [P4] Server is constructed even for invalid ID, wasting resources
-    std::string invalid_id = "xxx";
-    auto server = std::make_unique<Server>(invalid_id);
-    LOG("User request");
-    clientCode(server.get());
-  }
+void clientCode(Service& service, const std::string& user) {
+  LOG_S("  client: request as " << user);
+  service.request(user);
 }
-}  // namespace problem
 
-namespace proxy_pattern {
-const std::string kAdmin = "admin";
-class Server : public IServer {
- private:
-  std::string id_;
-
- public:
-  explicit Server(std::string id) : id_{std::move(id)} {
-    LOG_S("CTR: " << id_);
-  }
+namespace problem {
 
-  void request() override { LOG_S("Handling request for: " << id_); }
-};
+void run() {
+  LOG_SECTION("Problem: the real object is created up front");
+  Server server;  // paid for even if nobody uses it
+  clientCode(server, "admin");
+  clientCode(server, "guest");  // no access control, no logging
+}
 
-class ServerProxy : public IServer {
- private:
-  std::string id_;
-  std::unique_ptr<Server> server_;
+}  // namespace problem
 
-  bool checkAccess() {
-    LOG("Checking access before forwarding request.");
-    if (id_ != kAdmin) {
-      LOG("Invalid id. Return");
-      return false;
+/// Proxy: lazy creation + access control + logging.
+class ServerProxy : public Service {
+ public:
+  void request(const std::string& user) override {
+    if (!hasAccess(user)) {
+      LOG_S("    Proxy: access denied for " << user);
+      return;
     }
-
-    // Lazy initialization: construct Server only on first access
-    if (server_ == nullptr) {
-      server_ = std::make_unique<Server>(id_);
+    if (!server_) {
+      LOG("    Proxy: first authorized request, creating the Server now");
+      server_ = std::make_unique<Server>();
     }
-    return true;
+    server_->request(user);
+    ++requests_;
+    LOG_S("    Proxy: logged request #" << requests_);
   }
 
-  void logAccess() const { LOG_S("Logging request time: " << id_); }
-
- public:
-  explicit ServerProxy(std::string id) : id_{std::move(id)} {
-    LOG_S("CTR: " << id_);
-  }
+ private:
+  static bool hasAccess(const std::string& user) { return user == "admin"; }
 
-  void request() override {
-    if (checkAccess()) {
-      server_->request();
-      logAccess();
-    }
-  }
+  std::unique_ptr<Server> server_;  // created on demand
+  int requests_{0};
 };
 
 void run() {
-  {
-    std::string connection_id = "admin";
-    // Server is not constructed until first request is made
-    auto server_proxy = std::make_unique<ServerProxy>(connection_id);
-    LOG("User request");
-    clientCode(server_proxy.get());
-  }
-
-  {
-    // Server is not constructed if id is invalid
-    std::string invalid_id = "xxx";
-    auto server_proxy = std::make_unique<ServerProxy>(invalid_id);
-    LOG("User request");
-    clientCode(server_proxy.get());
-  }
+  LOG_SECTION("Proxy: same interface, controlled access");
+  ServerProxy proxy;
+  LOG("  proxy constructed - no Server exists yet");
+  clientCode(proxy, "guest");  // denied, the Server is still not created
+  clientCode(proxy, "admin");  // creates the Server lazily
+  clientCode(proxy, "admin");  // reuses it
 }
-}  // namespace proxy_pattern
 
-class ProxyExample : public IExample {
- public:
-  std::string group() const override { return "dp/structural"; }
-  std::string name() const override { return "Proxy"; }
-  std::string description() const override { return "Proxy Pattern Example"; }
-  void execute() override {
-    problem::run();
-    proxy_pattern::run();
-  }
-};
-
-REGISTER_EXAMPLE(ProxyExample);
 }  // namespace
+
+LAB_EXAMPLE("Proxy",
+            "a stand-in that adds lazy creation, access control and logging") {
+  problem::run();
+  run();
+}
diff --git a/src/dp/structural/README.md b/src/dp/structural/README.md
index 70bf189..f76753b 100644
--- a/src/dp/structural/README.md
+++ b/src/dp/structural/README.md
@@ -1,3 +1,6 @@
+> Examples: `dp/structural/{Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy}` - run
+> one with `./build/bin/cpp_lab_project --run dp/structural/Decorator`
+
 # Structural Design Patterns
 
 Structural design patterns explain how to assemble objects and classes into larger structures, while keeping these structures flexible and efficient.
diff --git a/src/embedded/startup.c b/src/embedded/startup.c
index 9fbfb2f..252d529 100644
--- a/src/embedded/startup.c
+++ b/src/embedded/startup.c
@@ -51,7 +51,7 @@ __attribute__((section(".isr_vector"))) const void* vector_table[] = {
 /// Responsible for initializing the C runtime environment
 void Reset_Handler(void) {
   // Copy initialized data (.data) * from Flash to RAM.
-  uint32_t* src = &_sidata;
+  const uint32_t* src = &_sidata;
   uint32_t* dst = &_sdata;
 
   while (dst < &_edata) {
diff --git a/src/lab/CMakeLists.txt b/src/lab/CMakeLists.txt
new file mode 100644
index 0000000..acd3c28
--- /dev/null
+++ b/src/lab/CMakeLists.txt
@@ -0,0 +1,37 @@
+# ----------------------------------------------------------------------------------------
+# lab: the small framework behind the examples
+#   - Registry     : examples register themselves with LAB_EXAMPLE (lab/Example.h)
+#   - Logger       : LOG / LOG_S / LOG_FUNC / LOG_SECTION (lab/Logger.h)
+#   - Menu, Runner : interactive menu and command-line runner used by main.cpp
+# ----------------------------------------------------------------------------------------
+
+string(TIMESTAMP CPPLAB_BUILD_TIME "%Y-%m-%d %H:%M:%S")
+configure_file(
+    ${PROJECT_SOURCE_DIR}/include/lab/version.h.in
+    ${PROJECT_BINARY_DIR}/generated/lab/version.h
+    @ONLY
+)
+
+add_library(cpplab_lab STATIC
+    CommandLine.cpp
+    Logger.cpp
+    Menu.cpp
+    Registry.cpp
+    Runner.cpp
+)
+add_library(cpplab::lab ALIAS cpplab_lab)
+
+target_include_directories(cpplab_lab
+    PUBLIC
+        ${PROJECT_SOURCE_DIR}/include
+        ${PROJECT_BINARY_DIR}/generated
+)
+
+target_link_libraries(cpplab_lab
+    PUBLIC
+        cpplab::options
+        Threads::Threads
+)
+
+# Lets the registry turn __FILE__ into a repository-relative path (menu groups).
+target_compile_definitions(cpplab_lab PRIVATE CPPLAB_SOURCE_DIR="${PROJECT_SOURCE_DIR}")
diff --git a/src/lab/CommandLine.cpp b/src/lab/CommandLine.cpp
new file mode 100644
index 0000000..4d68cd3
--- /dev/null
+++ b/src/lab/CommandLine.cpp
@@ -0,0 +1,171 @@
+#include "lab/CommandLine.h"
+
+#include <algorithm>
+#include <cctype>
+
+namespace lab {
+namespace {
+
+std::string toLower(std::string_view text) {
+  std::string lower(text);
+  std::transform(lower.begin(), lower.end(), lower.begin(), [](unsigned char c) {
+    return static_cast<char>(std::tolower(c));
+  });
+  return lower;
+}
+
+ParseResult failure(std::string message) {
+  return ParseResult{std::nullopt, std::move(message)};
+}
+
+}  // namespace
+
+std::string_view toString(AppMode mode) {
+  switch (mode) {
+    case AppMode::kDev:
+      return "dev";
+    case AppMode::kUat:
+      return "uat";
+    case AppMode::kProd:
+      return "prod";
+  }
+  return "unknown";
+}
+
+std::optional<AppMode> parseAppMode(std::string_view text) {
+  const std::string mode = toLower(text);
+  if (mode == "dev") {
+    return AppMode::kDev;
+  }
+  if (mode == "uat") {
+    return AppMode::kUat;
+  }
+  if (mode == "prod") {
+    return AppMode::kProd;
+  }
+  return std::nullopt;
+}
+
+ParseResult parseCommandLine(const std::vector<std::string_view>& args) {
+  CommandLine cli;
+  bool command_given = false;
+
+  for (std::size_t i = 0; i < args.size(); ++i) {
+    std::string_view option = args[i];
+
+    // Support both "--run id" and "--run=id".
+    std::optional<std::string_view> inline_value;
+    if (option.rfind("--", 0) == 0) {
+      if (const auto equals = option.find('='); equals != option.npos) {
+        inline_value = option.substr(equals + 1);
+        option = option.substr(0, equals);
+      }
+    }
+
+    // Returns the value that follows the option, if there is one.
+    auto takeValue = [&]() -> std::optional<std::string_view> {
+      if (inline_value) {
+        return inline_value;
+      }
+      if (i + 1 < args.size() && args[i + 1].rfind('-', 0) != 0) {
+        return args[++i];
+      }
+      return std::nullopt;
+    };
+
+    auto setCommand = [&](Command command) {
+      if (command_given) {
+        return false;
+      }
+      cli.command = command;
+      command_given = true;
+      return true;
+    };
+    const std::string kOneCommand =
+        "only one of --list, --list-ids, --run, --run-all, --help and "
+        "--version can be used at a time";
+
+    if (option == "-h" || option == "--help") {
+      if (!setCommand(Command::kHelp)) {
+        return failure(kOneCommand);
+      }
+    } else if (option == "-v" || option == "--version") {
+      if (!setCommand(Command::kVersion)) {
+        return failure(kOneCommand);
+      }
+    } else if (option == "-l" || option == "--list" || option == "--list-ids" ||
+               option == "-a" || option == "--run-all") {
+      Command command = Command::kRunAll;
+      if (option == "-l" || option == "--list") {
+        command = Command::kList;
+      } else if (option == "--list-ids") {
+        command = Command::kListIds;
+      }
+      if (!setCommand(command)) {
+        return failure(kOneCommand);
+      }
+      if (auto value = takeValue()) {
+        cli.argument = std::string(*value);
+      }
+    } else if (option == "-r" || option == "--run") {
+      if (!setCommand(Command::kRun)) {
+        return failure(kOneCommand);
+      }
+      auto value = takeValue();
+      if (!value || value->empty()) {
+        return failure("--run needs an example id or filter");
+      }
+      cli.argument = std::string(*value);
+    } else if (option == "--plain") {
+      cli.plain = true;
+    } else if (option == "--mode" || option == "-mode") {
+      auto value = takeValue();
+      if (!value) {
+        return failure("--mode needs a value: dev, uat or prod");
+      }
+      auto mode = parseAppMode(*value);
+      if (!mode) {
+        return failure("invalid mode '" + std::string(*value) +
+                       "', expected dev, uat or prod");
+      }
+      cli.mode = *mode;
+    } else {
+      return failure("unknown option '" + std::string(args[i]) + "'");
+    }
+  }
+
+  return ParseResult{cli, {}};
+}
+
+std::string usage(std::string_view program) {
+  std::string text = "Usage: ";
+  text.append(program);
+  text.append(R"( [options]
+
+Without options the interactive menu starts.
+
+Options:
+  -l, --list [filter]      list examples (id and description)
+  -r, --run <id|filter>    run one example: an exact id, or a filter that
+                           matches exactly one example
+  -a, --run-all [filter]   run every non-interactive example
+      --list-ids [filter]  print ids of non-interactive examples (for scripts)
+      --plain              plain output: no log prefixes, no colors
+      --mode <mode>        application mode: dev (default), uat or prod
+  -v, --version            print version information
+  -h, --help               print this help
+
+Filters are case-insensitive substrings of the id or the description.
+
+Examples:
+  )");
+  text.append(program);
+  text.append(" --list smart_pointer\n  ");
+  text.append(program);
+  text.append(" --run core/smart_pointer/Weak\n  ");
+  text.append(program);
+  text.append(" --run-all dp/behavioral\n");
+  return text;
+}
+
+}  // namespace lab
diff --git a/src/lab/Logger.cpp b/src/lab/Logger.cpp
new file mode 100644
index 0000000..3bb3932
--- /dev/null
+++ b/src/lab/Logger.cpp
@@ -0,0 +1,108 @@
+#include "lab/Logger.h"
+
+#include <unistd.h>  // isatty
+
+#include <chrono>
+#include <cstdlib>  // std::getenv
+#include <ctime>
+#include <iostream>
+#include <string>
+
+namespace lab {
+namespace {
+
+#ifdef NDEBUG
+constexpr bool kShowLocationByDefault = false;
+#else
+constexpr bool kShowLocationByDefault = true;
+#endif
+
+constexpr std::string_view kGreen = "\033[32m";
+constexpr std::string_view kBold = "\033[1m";
+constexpr std::string_view kReset = "\033[0m";
+
+bool stdoutSupportsColor() {
+  // https://no-color.org: an existing NO_COLOR variable disables colors.
+  if (std::getenv("NO_COLOR") != nullptr) {
+    return false;
+  }
+  return ::isatty(STDOUT_FILENO) == 1;
+}
+
+std::string_view fileName(std::string_view path) {
+  const auto slash = path.find_last_of("/\\");
+  return slash == std::string_view::npos ? path : path.substr(slash + 1);
+}
+
+std::string currentTime() {
+  const std::time_t now =
+      std::chrono::system_clock::to_time_t(std::chrono::system_clock::now());
+  std::tm local{};
+  localtime_r(&now, &local);  // thread-safe variant of std::localtime
+
+  char buffer[16]{};
+  std::strftime(buffer, sizeof(buffer), "%H:%M:%S", &local);
+  return buffer;
+}
+
+}  // namespace
+
+Logger& Logger::instance() {
+  static Logger logger;
+  return logger;
+}
+
+Logger::Logger()
+    : show_location_{kShowLocationByDefault}, use_color_{stdoutSupportsColor()} {}
+
+void Logger::log(std::string_view message,
+                 const std::source_location& location) {
+  write(message, location, /*with_function=*/true);
+}
+
+void Logger::logFunction(const std::source_location& location) {
+  // The function name is the message, so it is not repeated in the prefix.
+  write(location.function_name(), location, /*with_function=*/false);
+}
+
+void Logger::section(std::string_view title) {
+  constexpr std::size_t kWidth = 72;
+  std::string line = "--- ";
+  line.append(title);
+  line.push_back(' ');
+  if (line.size() < kWidth) {
+    line.append(kWidth - line.size(), '-');
+  }
+
+  const std::lock_guard<std::mutex> lock(mutex_);
+  std::cout << '\n';
+  if (use_color_) {
+    std::cout << kBold << line << kReset << '\n';
+  } else {
+    std::cout << line << '\n';
+  }
+}
+
+void Logger::write(std::string_view message,
+                   const std::source_location& location, bool with_function) {
+  if (!message.empty() && message.back() == '\n') {
+    message.remove_suffix(1);
+  }
+
+  const std::lock_guard<std::mutex> lock(mutex_);
+  if (show_location_) {
+    std::cout << '[' << currentTime() << "][" << fileName(location.file_name())
+              << ':' << location.line() << ']';
+    if (with_function) {
+      std::cout << '[' << location.function_name() << ']';
+    }
+    std::cout << ' ';
+  }
+  if (use_color_) {
+    std::cout << kGreen << message << kReset << '\n';
+  } else {
+    std::cout << message << '\n';
+  }
+}
+
+}  // namespace lab
diff --git a/src/lab/Menu.cpp b/src/lab/Menu.cpp
new file mode 100644
index 0000000..9cce3ae
--- /dev/null
+++ b/src/lab/Menu.cpp
@@ -0,0 +1,255 @@
+#include "lab/Menu.h"
+
+#include <algorithm>
+#include <cctype>
+#include <iomanip>
+#include <iostream>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "lab/Runner.h"
+
+namespace lab {
+namespace {
+
+constexpr std::size_t kRuleWidth = 72;
+constexpr int kNameWidth = 26;
+
+/// One folder of the menu. The root folder has an empty name and path.
+struct MenuNode {
+  std::string name;  ///< last path segment, e.g. "smart_pointer"
+  std::string path;  ///< full group, e.g. "core/smart_pointer"
+  std::vector<MenuNode> children;
+  std::vector<const Example*> examples;
+  std::size_t total{0};  ///< examples in this folder and all sub-folders
+};
+
+MenuNode& childNamed(MenuNode& parent, const std::string& name) {
+  const auto it =
+      std::find_if(parent.children.begin(), parent.children.end(),
+                   [&name](const MenuNode& child) { return child.name == name; });
+  if (it != parent.children.end()) {
+    return *it;
+  }
+  MenuNode child;
+  child.name = name;
+  child.path = parent.path.empty() ? name : parent.path + "/" + name;
+  parent.children.push_back(std::move(child));
+  return parent.children.back();
+}
+
+void sortChildren(MenuNode& node) {
+  std::sort(node.children.begin(), node.children.end(),
+            [](const MenuNode& a, const MenuNode& b) { return a.name < b.name; });
+  for (MenuNode& child : node.children) {
+    sortChildren(child);
+  }
+}
+
+/// Turns the flat list of "group/name" ids into a folder tree.
+MenuNode buildTree(const Registry& registry) {
+  MenuNode root;
+  for (const Example& example : registry.examples()) {
+    MenuNode* node = &root;
+    ++node->total;
+
+    std::string_view rest = example.group;
+    while (!rest.empty()) {
+      const auto slash = rest.find('/');
+      const std::string segment(rest.substr(0, slash));
+      rest = slash == std::string_view::npos ? std::string_view{}
+                                             : rest.substr(slash + 1);
+      node = &childNamed(*node, segment);
+      ++node->total;
+    }
+    node->examples.push_back(&example);
+  }
+  sortChildren(root);
+  return root;
+}
+
+std::string trim(const std::string& text) {
+  const auto first = text.find_first_not_of(" \t\r\n");
+  if (first == std::string::npos) {
+    return {};
+  }
+  const auto last = text.find_last_not_of(" \t\r\n");
+  return text.substr(first, last - first + 1);
+}
+
+std::optional<std::size_t> parseIndex(const std::string& text) {
+  constexpr std::size_t kMaxDigits = 6;
+  if (text.empty() || text.size() > kMaxDigits ||
+      !std::all_of(text.begin(), text.end(),
+                   [](unsigned char c) { return std::isdigit(c) != 0; })) {
+    return std::nullopt;
+  }
+  return static_cast<std::size_t>(std::stoul(text));
+}
+
+std::string countLabel(std::size_t count) {
+  return std::to_string(count) + (count == 1 ? " example" : " examples");
+}
+
+void printNode(const MenuNode& node, bool is_root, std::ostream& out) {
+  const std::string rule(kRuleWidth, '-');
+  std::string location = "cpp-lab";
+  if (!node.path.empty()) {
+    location += " / ";
+    for (const char c : node.path) {
+      location += c == '/' ? std::string(" / ") : std::string(1, c);
+    }
+  }
+
+  out << '\n'
+      << rule << '\n'
+      << ' ' << location << "   (" << countLabel(node.total) << ")\n"
+      << rule << '\n';
+
+  std::size_t index = 1;
+  for (const MenuNode& child : node.children) {
+    out << std::setw(4) << index++ << ". " << std::left
+        << std::setw(kNameWidth) << (child.name + "/") << std::right << ' '
+        << countLabel(child.total) << '\n';
+  }
+  for (const Example* example : node.examples) {
+    out << std::setw(4) << index++ << ". " << std::left
+        << std::setw(kNameWidth) << example->name << std::right << ' '
+        << example->description
+        << (example->isInteractive() ? "  [interactive]" : "") << '\n';
+  }
+  out << rule << '\n'
+      << " <number> open    0 " << (is_root ? "quit" : "back")
+      << "    <text> search    ? help    q quit\n";
+}
+
+void printHelp(std::ostream& out) {
+  out << "\nMenu help\n"
+         "  <number>  open a folder or run an example\n"
+         "  0, b      go back one folder (quit in the top folder)\n"
+         "  <text>    search ids and descriptions, e.g. \"thread\" or "
+         "\"dp/\"\n"
+         "  q         quit\n\n"
+         "Tip: run examples without the menu, e.g.\n"
+         "  cpp_lab_project --list pointer\n"
+         "  cpp_lab_project --run core/smart_pointer/Weak\n";
+}
+
+/// Prints the prompt and reads one trimmed line. False when input ended.
+bool readLine(std::istream& in, std::ostream& out, std::string& line) {
+  out << "> " << std::flush;
+  if (!std::getline(in, line)) {
+    return false;
+  }
+  line = trim(line);
+  return true;
+}
+
+/// Runs an example and waits for Enter. False when input ended.
+bool runAndWait(const Example& example, std::istream& in, std::ostream& out) {
+  runExample(example, out);
+
+  // An example that reads from std::cin may leave it in a failed state.
+  if (in.fail() && !in.eof()) {
+    in.clear();
+  }
+  if (!in) {
+    return false;
+  }
+  out << "\nPress Enter to return to the menu..." << std::flush;
+  std::string ignored;
+  return static_cast<bool>(std::getline(in, ignored));
+}
+
+/// Shows the examples matching `query` and runs the chosen one.
+/// False when input ended.
+bool search(const Registry& registry, std::string_view query, std::istream& in,
+            std::ostream& out) {
+  const std::vector<const Example*> matches = registry.match(query);
+  if (matches.empty()) {
+    out << "No example matches \"" << query << "\".\n";
+    return true;
+  }
+
+  out << "\nExamples matching \"" << query << "\":\n";
+  for (std::size_t i = 0; i < matches.size(); ++i) {
+    out << std::setw(4) << i + 1 << ". " << std::left << std::setw(40)
+        << matches[i]->id << std::right << ' ' << matches[i]->description
+        << '\n';
+  }
+  out << " <number> run    0 cancel\n";
+
+  std::string line;
+  if (!readLine(in, out, line)) {
+    return false;
+  }
+  const auto index = parseIndex(line);
+  if (!index || *index == 0 || *index > matches.size()) {
+    return true;
+  }
+  return runAndWait(*matches[*index - 1], in, out);
+}
+
+}  // namespace
+
+void runMenu(const Registry& registry, std::istream& in, std::ostream& out) {
+  if (registry.examples().empty()) {
+    out << "No examples registered.\n";
+    return;
+  }
+
+  const MenuNode root = buildTree(registry);
+  std::vector<const MenuNode*> path{&root};
+  std::string line;
+
+  while (true) {
+    const MenuNode& node = *path.back();
+    const bool is_root = path.size() == 1;
+    printNode(node, is_root, out);
+
+    if (!readLine(in, out, line)) {
+      out << '\n';
+      return;
+    }
+    if (line.empty()) {
+      continue;
+    }
+    if (line == "q" || line == "quit" || line == "exit") {
+      return;
+    }
+    if (line == "0" || line == "b" || line == "..") {
+      if (is_root) {
+        return;
+      }
+      path.pop_back();
+      continue;
+    }
+    if (line == "?" || line == "h" || line == "help") {
+      printHelp(out);
+      continue;
+    }
+
+    if (const auto index = parseIndex(line)) {
+      const std::size_t folders = node.children.size();
+      if (*index <= folders) {
+        path.push_back(&node.children[*index - 1]);
+      } else if (*index - folders <= node.examples.size()) {
+        if (!runAndWait(*node.examples[*index - folders - 1], in, out)) {
+          return;
+        }
+      } else {
+        out << "Invalid choice: " << line << '\n';
+      }
+      continue;
+    }
+
+    const std::string_view query =
+        line.front() == '/' ? std::string_view(line).substr(1) : line;
+    if (!search(registry, query, in, out)) {
+      return;
+    }
+  }
+}
+
+}  // namespace lab
diff --git a/src/lab/Registry.cpp b/src/lab/Registry.cpp
new file mode 100644
index 0000000..8916c3d
--- /dev/null
+++ b/src/lab/Registry.cpp
@@ -0,0 +1,166 @@
+#include "lab/Registry.h"
+
+#include <algorithm>
+#include <cctype>
+#include <utility>
+
+// Absolute path of the repository, injected by CMake. Used to turn __FILE__
+// into a repository-relative path.
+#ifndef CPPLAB_SOURCE_DIR
+#define CPPLAB_SOURCE_DIR ""
+#endif
+
+namespace lab {
+namespace {
+
+std::string toLower(std::string_view text) {
+  std::string lower(text);
+  std::transform(lower.begin(), lower.end(), lower.begin(), [](unsigned char c) {
+    return static_cast<char>(std::tolower(c));
+  });
+  return lower;
+}
+
+bool lessIgnoreCase(std::string_view lhs, std::string_view rhs) {
+  return std::lexicographical_compare(
+      lhs.begin(), lhs.end(), rhs.begin(), rhs.end(),
+      [](unsigned char a, unsigned char b) {
+        return std::tolower(a) < std::tolower(b);
+      });
+}
+
+bool equalIgnoreCase(std::string_view lhs, std::string_view rhs) {
+  return lhs.size() == rhs.size() &&
+         std::equal(lhs.begin(), lhs.end(), rhs.begin(),
+                    [](unsigned char a, unsigned char b) {
+                      return std::tolower(a) == std::tolower(b);
+                    });
+}
+
+bool isValidName(std::string_view name) {
+  return !name.empty() &&
+         std::none_of(name.begin(), name.end(), [](unsigned char c) {
+           return c == '/' || std::isspace(c) != 0;
+         });
+}
+
+}  // namespace
+
+namespace detail {
+
+std::string relativeSourcePath(std::string_view file,
+                               std::string_view source_root) {
+  std::string path(file);
+  std::replace(path.begin(), path.end(), '\\', '/');
+
+  std::string root(source_root);
+  std::replace(root.begin(), root.end(), '\\', '/');
+  if (!root.empty()) {
+    if (root.back() != '/') {
+      root.push_back('/');
+    }
+    if (path.rfind(root, 0) == 0) {
+      return path.substr(root.size());
+    }
+  }
+
+  // Fallback when __FILE__ is not below the root (e.g. relative paths):
+  // keep everything from the last "src/" directory on.
+  if (path.rfind("src/", 0) == 0) {
+    return path;
+  }
+  if (const auto pos = path.rfind("/src/"); pos != std::string::npos) {
+    return path.substr(pos + 1);
+  }
+  return path;
+}
+
+std::string groupFromSourcePath(std::string_view relative_path) {
+  std::string_view path = relative_path;
+  if (path.rfind("src/", 0) == 0) {
+    path.remove_prefix(4);
+  }
+  const auto slash = path.rfind('/');
+  if (slash == std::string_view::npos || slash == 0) {
+    return "misc";
+  }
+  return std::string(path.substr(0, slash));
+}
+
+}  // namespace detail
+
+Registry& Registry::instance() {
+  // A function-local static is created on first use. This makes it safe to
+  // call from other static initializers (the "static initialization order
+  // fiasco" cannot happen).
+  static Registry registry;
+  return registry;
+}
+
+bool Registry::add(std::string_view file, std::string_view name,
+                   std::string_view description, ExampleFunction run,
+                   unsigned flags) {
+  Example example;
+  example.source = detail::relativeSourcePath(file, CPPLAB_SOURCE_DIR);
+  example.group = detail::groupFromSourcePath(example.source);
+  example.name = std::string(name);
+  example.id = example.group + "/" + example.name;
+  example.description = std::string(description);
+  example.run = run;
+  example.flags = flags;
+
+  if (!isValidName(name)) {
+    errors_.push_back(example.source + ": invalid example name '" +
+                      example.name + "' (use no spaces and no '/')");
+    return false;
+  }
+  if (run == nullptr) {
+    errors_.push_back(example.source + ": example '" + example.name +
+                      "' has no function");
+    return false;
+  }
+
+  const auto position = std::lower_bound(
+      examples_.begin(), examples_.end(), example.id,
+      [](const Example& existing, const std::string& id) {
+        return lessIgnoreCase(existing.id, id);
+      });
+  if (position != examples_.end() &&
+      equalIgnoreCase(position->id, example.id)) {
+    errors_.push_back("duplicate example id '" + example.id + "' in " +
+                      example.source + " (already defined in " +
+                      position->source + ")");
+    return false;
+  }
+
+  examples_.insert(position, std::move(example));
+  return true;
+}
+
+const Example* Registry::find(std::string_view id) const {
+  const Example* case_insensitive = nullptr;
+  for (const Example& example : examples_) {
+    if (example.id == id) {
+      return &example;
+    }
+    if (case_insensitive == nullptr && equalIgnoreCase(example.id, id)) {
+      case_insensitive = &example;
+    }
+  }
+  return case_insensitive;
+}
+
+std::vector<const Example*> Registry::match(std::string_view filter) const {
+  const std::string needle = toLower(filter);
+  std::vector<const Example*> matches;
+  for (const Example& example : examples_) {
+    if (needle.empty() ||
+        toLower(example.id).find(needle) != std::string::npos ||
+        toLower(example.description).find(needle) != std::string::npos) {
+      matches.push_back(&example);
+    }
+  }
+  return matches;
+}
+
+}  // namespace lab
diff --git a/src/lab/Runner.cpp b/src/lab/Runner.cpp
new file mode 100644
index 0000000..18c4c63
--- /dev/null
+++ b/src/lab/Runner.cpp
@@ -0,0 +1,89 @@
+#include "lab/Runner.h"
+
+#include <chrono>
+#include <exception>
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace lab {
+namespace {
+
+constexpr std::size_t kRuleWidth = 72;
+
+}  // namespace
+
+bool runExample(const Example& example, std::ostream& out) {
+  const std::string heavy_rule(kRuleWidth, '=');
+  const std::string light_rule(kRuleWidth, '-');
+
+  out << '\n'
+      << heavy_rule << '\n'
+      << "> " << example.id
+      << (example.isInteractive() ? "  [interactive]" : "") << '\n'
+      << "  " << example.description << '\n'
+      << "  source: " << example.source << '\n'
+      << heavy_rule << '\n'
+      << std::flush;
+
+  // Examples may change the formatting state of std::cout (std::hex,
+  // std::boolalpha, ...). Save it so the next example starts clean.
+  std::ios saved_format(nullptr);
+  saved_format.copyfmt(std::cout);
+
+  const auto start = std::chrono::steady_clock::now();
+  bool succeeded = true;
+  try {
+    example.run();
+  } catch (const std::exception& e) {
+    succeeded = false;
+    std::cout.flush();
+    out << "\n[error] uncaught exception: " << e.what() << '\n';
+  } catch (...) {
+    succeeded = false;
+    std::cout.flush();
+    out << "\n[error] uncaught exception of unknown type\n";
+  }
+  const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+      std::chrono::steady_clock::now() - start);
+
+  std::cout.copyfmt(saved_format);
+  std::cout.flush();
+  std::cerr.flush();
+
+  out << light_rule << '\n'
+      << (succeeded ? "finished" : "FAILED") << " in " << elapsed.count()
+      << " ms\n"
+      << std::flush;
+  return succeeded;
+}
+
+int runAll(const Registry& registry, std::string_view filter,
+           std::ostream& out) {
+  std::vector<std::string> failed;
+  std::size_t ran = 0;
+  std::size_t skipped = 0;
+
+  for (const Example* example : registry.match(filter)) {
+    if (example->isInteractive()) {
+      ++skipped;
+      continue;
+    }
+    ++ran;
+    if (!runExample(*example, out)) {
+      failed.push_back(example->id);
+    }
+  }
+
+  out << '\n'
+      << std::string(kRuleWidth, '=') << '\n'
+      << "Ran " << ran << " example(s), skipped " << skipped
+      << " interactive, " << failed.size() << " failed.\n";
+  for (const std::string& id : failed) {
+    out << "  FAILED: " << id << '\n';
+  }
+  out << std::flush;
+  return static_cast<int>(failed.size());
+}
+
+}  // namespace lab
diff --git a/src/main.cpp b/src/main.cpp
index a177103..c74c584 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -1,199 +1,151 @@
-#include <exception>
+// Entry point of the cpp-lab application.
+//
+// Every example registers itself with LAB_EXAMPLE before main() starts, so
+// main() only has to parse the command line and hand the registry to the menu
+// or to the runner.
+
+#include <algorithm>
 #include <iomanip>
 #include <iostream>
-#include <limits>
-#include <stdexcept>
 #include <string>
+#include <string_view>
 #include <vector>
 
-#include "ExampleRegistry.h"
-#include "Logger.h"
-#include "version.h"
-
-int readChoice() {
-  int x;
-  while (!(std::cin >> x)) {
-    std::cin.clear();
-    std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
-    std::cout << "Invalid input. Try again: ";
+#include "lab/CommandLine.h"
+#include "lab/Logger.h"
+#include "lab/Menu.h"
+#include "lab/Registry.h"
+#include "lab/Runner.h"
+#include "lab/version.h"
+
+namespace {
+
+std::string cppStandard() {
+  switch (__cplusplus) {
+    case 202302L:
+      return "C++23";
+    case 202002L:
+      return "C++20";
+    case 201703L:
+      return "C++17";
+    case 201402L:
+      return "C++14";
+    case 201103L:
+      return "C++11";
+    default:
+      return "__cplusplus = " + std::to_string(__cplusplus);
   }
-  // Clear leftover newline from input buffer
-  std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
-  return x;
 }
 
-void runMenu() {
-  ExampleRegistry& registry = ExampleRegistry::instance();
-  const auto& data = registry.getAll();
-
-  while (true) {
-    std::cout << "\n========================================\n";
-    std::cout << "         CPP LAB - Examples Menu        \n";
-    std::cout << "========================================\n";
-
-    if (data.empty()) {
-      std::cout << "No examples registered.\n";
-      return;
-    }
-
-    // Group
-    size_t g_index = 1;
-    std::vector<std::string> groups;
-    groups.reserve(data.size());
-
-    for (const auto& [group, _] : data) {
-      groups.push_back(group);
-    }
+void printVersion() {
+  std::cout << lab::version::kName << " v" << lab::version::kVersion << '\n'
+            << lab::version::kDescription << '\n'
+            << "standard : " << cppStandard() << '\n'
+            << "compiler : " << lab::version::kCompiler << '\n'
+            << "build    : " << lab::version::kBuildType << " ("
+            << lab::version::kBuildTime << ")\n";
+}
 
-    // sort
-    std::sort(groups.begin(), groups.end());
-    for (const auto& group : groups) {
-      std::cout
-          << std::setw(2) << g_index++ << ". " << group
-          << "\n";  // use at least 2 characters of space for the next value
-    }
-    std::cout << g_index << ". Exit\n";
-    std::cout << "----------------------------------------\n";
-    std::cout << "Enter choice: ";
+void listExamples(const lab::Registry& registry, std::string_view filter) {
+  const std::vector<const lab::Example*> matches = registry.match(filter);
+
+  const auto longest =
+      std::max_element(matches.begin(), matches.end(),
+                       [](const lab::Example* a, const lab::Example* b) {
+                         return a->id.size() < b->id.size();
+                       });
+  const std::size_t width =
+      longest == matches.end() ? 0U : (*longest)->id.size();
+
+  for (const lab::Example* example : matches) {
+    std::cout << std::left << std::setw(static_cast<int>(width)) << example->id
+              << "  " << example->description
+              << (example->isInteractive() ? "  [interactive]" : "") << '\n';
+  }
+  std::cout << std::right << matches.size() << " example(s)\n";
+}
 
-    size_t g_choice = readChoice();
-    if (g_choice == g_index) {
-      std::cout << "\n--- Exit ---\n";
-      break;
+void listIds(const lab::Registry& registry, std::string_view filter) {
+  for (const lab::Example* example : registry.match(filter)) {
+    if (!example->isInteractive()) {
+      std::cout << example->id << '\n';
     }
+  }
+}
 
-    if (g_choice < 1 || g_choice > groups.size()) {
-      std::cout << "Invalid group choice\n";
-      continue;
+int runOne(const lab::Registry& registry, const std::string& query) {
+  const lab::Example* example = registry.find(query);
+  if (example == nullptr) {
+    const std::vector<const lab::Example*> matches = registry.match(query);
+    if (matches.empty()) {
+      std::cerr << "error: no example matches '" << query << "' (see --list)\n";
+      return 1;
     }
-
-    while (true) {
-      try {
-        // Sub-group
-        const auto& selected_group = groups[g_choice - 1];
-        const auto& examples = data.at(selected_group);
-
-        int e_index = 1;
-        std::vector<std::string> names;
-
-        for (const auto& [name, _] : examples) {
-          std::cout << std::setw(2) << e_index++ << ". " << name << "\n";
-          names.push_back(name);
-        }
-        std::cout << std::setw(2) << e_index << ". Back\n";
-        std::cout << "----------------------------------------\n";
-        std::cout << "Enter choice: ";
-
-        int e_choice = readChoice();
-        // return
-        if (e_choice == e_index) {
-          break;
-        }
-
-        if (e_choice < 1 || e_choice > e_index) {
-          std::cout << "Invalid example choice\n";
-          continue;
-        }
-
-        auto example = registry.create(selected_group, names[e_choice - 1]);
-        if (example != nullptr) {
-          std::cout << "\n--- Running Example [" << example->name() << "] ["
-                    << example->description() << "]---\n\n";
-          example->execute();
-          std::cout << "\n--- Finished ---\n";
-          std::cout << "Press any key to continue ...\n";
-          std::cin.get();
-        }
-      } catch (std::out_of_range& e) {
-        std::cout << "\nError" << e.what();
-        std::cout << "\nInvalid example. Try again.\n";
+    if (matches.size() > 1) {
+      std::cerr << "error: '" << query << "' matches " << matches.size()
+                << " examples, be more specific:\n";
+      for (const lab::Example* match : matches) {
+        std::cerr << "  " << match->id << '\n';
       }
+      return 1;
     }
+    example = matches.front();
   }
+  return lab::runExample(*example, std::cout) ? 0 : 1;
 }
 
-void printInfo() {
-  std::cout << std::endl;
-  if (__cplusplus == 202302L)
-    std::cout << "C++23";
-  else if (__cplusplus == 202002L)
-    std::cout << "C++20";
-  else if (__cplusplus == 201703L)
-    std::cout << "C++17";
-  else if (__cplusplus == 201402L)
-    std::cout << "C++14";
-  else if (__cplusplus == 201103L)
-    std::cout << "C++11";
-  else if (__cplusplus == 199711L)
-    std::cout << "C++98";
-  else
-    std::cout << "pre-standard C++ or an unknown version: " << __cplusplus;
-  std::cout << "\n";
-  std::cout << APP_NAME << " v" << APP_VERSION << std::endl;
-  std::cout << APP_DESCRIPTION << std::endl;
-}
-
-enum class ApplicationMode {
-  kDev,
-  kUAT,
-  kProd,
-};
-
-static ApplicationMode mode = ApplicationMode::kDev;
-
-std::string toString(ApplicationMode m) {
-  switch (m) {
-    case ApplicationMode::kDev:
-      return "dev";
-    case ApplicationMode::kUAT:
-      return "uat";
-    case ApplicationMode::kProd:
-      return "prod";
-  }
-  return "unknown";
-}
+}  // namespace
 
-ApplicationMode parseMode(const std::string& value) {
-  if (value == "Dev")
-    return ApplicationMode::kDev;
-  if (value == "Uat")
-    return ApplicationMode::kUAT;
-  if (value == "Prod")
-    return ApplicationMode::kProd;
-
-  throw std::invalid_argument("Invalid mode: " + value +
-                              ". Expected: dev, uat, prod");
-}
+int main(int argc, char* argv[]) {
+  const std::vector<std::string_view> args(argv + 1, argv + argc);
+  const std::string_view program = argc > 0 ? argv[0] : "cpp_lab_project";
 
-void handleArg(int argc, const char* const argv[]) {
-  // argv[0] = executable
-  for (int i = 1; i < argc; ++i) {
-    std::string arg = argv[i];
+  const lab::ParseResult parsed = lab::parseCommandLine(args);
+  if (!parsed.value) {
+    std::cerr << "error: " << parsed.error << "\n\n" << lab::usage(program);
+    return 2;
+  }
+  const lab::CommandLine& cli = *parsed.value;
 
-    if (arg == "-mode") {
-      if (i + 1 >= argc) {
-        std::cerr << "Missing value for -mode\n";
-        return;
-      }
+  if (cli.plain) {
+    lab::Logger::instance().setShowLocation(false);
+    lab::Logger::instance().setUseColor(false);
+  }
 
-      std::string value = argv[++i];
-      try {
-        mode = parseMode(value);
-      } catch (const std::exception& e) {
-        std::cerr << e.what() << '\n';
-      }
-    } else {
-      std::cerr << "Invalid argv param: " << arg << "\n";
+  const lab::Registry& registry = lab::Registry::instance();
+  if (!registry.errors().empty()) {
+    for (const std::string& error : registry.errors()) {
+      std::cerr << "registry error: " << error << '\n';
     }
+    return 1;
   }
-}
 
-int main(int argc, char* argv[]) {
-  handleArg(argc, argv);
-  LOG("Running in mode: " + toString(mode));
-  LOG("Logger has been integrated");
-  printInfo();
-  runMenu();
+  switch (cli.command) {
+    case lab::Command::kHelp:
+      std::cout << lab::usage(program);
+      return 0;
+    case lab::Command::kVersion:
+      printVersion();
+      return 0;
+    case lab::Command::kList:
+      listExamples(registry, cli.argument);
+      return 0;
+    case lab::Command::kListIds:
+      listIds(registry, cli.argument);
+      return 0;
+    case lab::Command::kRun:
+      return runOne(registry, cli.argument);
+    case lab::Command::kRunAll:
+      return lab::runAll(registry, cli.argument, std::cout) == 0 ? 0 : 1;
+    case lab::Command::kMenu:
+      break;
+  }
 
+  printVersion();
+  std::cout << "mode     : " << lab::toString(cli.mode) << '\n'
+            << "examples : " << registry.examples().size()
+            << "  (run with --help for command-line usage)\n";
+  lab::runMenu(registry, std::cin, std::cout);
+  std::cout << "Bye!\n";
   return 0;
-}
\ No newline at end of file
+}
diff --git a/src/socket/CMakeLists.txt b/src/socket/CMakeLists.txt
deleted file mode 100644
index d807f84..0000000
--- a/src/socket/CMakeLists.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-set(SOCKET_SOURCES
-
-    # Socket
-    ${CMAKE_CURRENT_SOURCE_DIR}/simple_tcp/TCPServer.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/simple_tcp/SimpleTCPServer.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/simple_tcp/TCPClient.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/simple_tcp/SimpleTCPClient.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/multiple_client/MultiTCPServer.cpp
-)
-
-set(SOCKET_SOURCES ${SOCKET_SOURCES} PARENT_SCOPE)
\ No newline at end of file
diff --git a/src/socket/README.md b/src/socket/README.md
index 38ec1fc..84cf187 100644
--- a/src/socket/README.md
+++ b/src/socket/README.md
@@ -1,3 +1,18 @@
+# Sockets
+
+| Example | What it does |
+|---|---|
+| `simple_tcp/LoopbackEcho` | server thread + client in one process (runs unattended) |
+| `simple_tcp/SimpleTCPServer` | echo server on 127.0.0.1:8080, one client at a time `[interactive]` |
+| `simple_tcp/SimpleTCPClient` | sends the lines you type to that server `[interactive]` |
+| `multiple_client/MultiTCPServer` | echo server with one thread per client `[interactive]` |
+
+Try it: run the server example, then in another terminal `telnet localhost 8080` (or `nc localhost
+8080`). Lines are echoed back; `Q` disconnects, `SHUTDOWN` stops the server.
+
+The classes are `net::TCPServer` and `net::TCPClient` in `simple_tcp/`.
+
+---
 ## Socket
 - A `socket` is a mechanism that allows programs to communicate with other programs using standard Unix file descriptors.
 
diff --git a/src/socket/multiple_client/MultiTCPServer.cpp b/src/socket/multiple_client/MultiTCPServer.cpp
index 9ff9c27..0f21353 100644
--- a/src/socket/multiple_client/MultiTCPServer.cpp
+++ b/src/socket/multiple_client/MultiTCPServer.cpp
@@ -1,57 +1,112 @@
+// -----------------------------------------------------------------------------
+// Multi-client TCP echo server: one thread per connection
+//
+// SimpleTCPServer serves clients one after another. Here accept() hands every
+// new connection to its own std::thread, so a slow client no longer blocks the
+// others.
+//
+// Things to notice:
+//   - Shared state (the list of connected sockets) is protected by a mutex.
+//   - On shutdown the remaining client sockets are shut down, which wakes up
+//     their threads blocked in recv(), so all threads can be joined.
+//   - One thread per client does not scale to thousands of connections;
+//     real servers use thread pools or event loops (epoll, io_uring, asio).
+//
+// Try it: run this example, then connect from several terminals with
+//   telnet localhost 8080
+// Send SHUTDOWN from any client to stop the server.
+// -----------------------------------------------------------------------------
+
 #include "MultiTCPServer.h"
 
-#include <arpa/inet.h>   // sockaddr_in, inet_ntoa
-#include <sys/socket.h>  // socket, bind, listen, accept
-#include <unistd.h>      // close(server)
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <sys/socket.h>
+#include <unistd.h>
 
-#include <iostream>
-#include "ExampleRegistry.h"
+#include <algorithm>
+#include <cerrno>
+#include <cstring>
+#include <exception>
 
-void MultiTCPServer::acceptLoop() {
-  while (isRunning()) {
-    sockaddr_in client_addr{};
-    socklen_t client_add_len = sizeof(client_addr);
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
-    int client_fd =
-        accept(getServerFD(), reinterpret_cast<sockaddr*>(&client_addr),
-               &client_add_len);
+namespace net {
 
+MultiTCPServer::~MultiTCPServer() {
+  stop();
+  disconnectAllClients();
+  for (std::thread& thread : client_threads_) {
+    if (thread.joinable()) {
+      thread.join();
+    }
+  }
+}
+
+void MultiTCPServer::acceptLoop() {
+  while (isRunning()) {
+    sockaddr_in client_address{};
+    socklen_t length = sizeof(client_address);
+    const int client_fd = ::accept(
+        serverFd(), reinterpret_cast<sockaddr*>(&client_address), &length);
     if (client_fd < 0) {
-      if (!isRunning())
+      if (!isRunning()) {
         break;
-      std::cerr << "[MultiTCPServer] accept failed\n";
+      }
+      if (errno != EINTR) {
+        LOG_S("[MultiTCPServer] accept failed: " << std::strerror(errno));
+      }
       continue;
     }
 
-    std::cout << "[MultiTCPServer] client " << inet_ntoa(client_addr.sin_addr)
-              << " connected\n";
+    {
+      const std::lock_guard<std::mutex> lock(clients_mutex_);
+      client_fds_.push_back(client_fd);
+      LOG_S("[MultiTCPServer] client fd " << client_fd << " connected ("
+                                          << client_fds_.size()
+                                          << " connected)");
+    }
 
-    client_threads_.emplace_back([this, client_fd]() {
+    client_threads_.emplace_back([this, client_fd] {
       try {
         handleClient(client_fd);
       } catch (const std::exception& e) {
-        std::cerr << "[MultiTCPServer] client error: " << e.what() << "\n";
-        close(client_fd);
+        LOG_S("[MultiTCPServer] client error: " << e.what());
       }
+      {
+        // Forget the fd BEFORE closing it, so disconnectAllClients() can never
+        // touch a number the OS has already reused for another socket.
+        const std::lock_guard<std::mutex> lock(clients_mutex_);
+        std::erase(client_fds_, client_fd);
+      }
+      ::close(client_fd);
     });
   }
 
-  for (auto& t : client_threads_) {
-    if (t.joinable()) {
-      t.join();
-    }
+  disconnectAllClients();
+  for (std::thread& thread : client_threads_) {
+    thread.join();
   }
+  client_threads_.clear();
 }
 
-void MultiTCPServer::run() {
-  setPort(8080);
+void MultiTCPServer::disconnectAllClients() {
+  const std::lock_guard<std::mutex> lock(clients_mutex_);
+  for (const int fd : client_fds_) {
+    ::shutdown(fd, SHUT_RDWR);  // recv() in the client thread returns 0
+  }
+}
 
+}  // namespace net
+
+LAB_EXAMPLE("MultiTCPServer",
+            "echo server on 127.0.0.1:8080 with one thread per client",
+            lab::kInteractive) {
+  net::MultiTCPServer server{8080};
   try {
-    start();
+    server.start();  // blocks until a client sends SHUTDOWN
   } catch (const std::exception& e) {
-    std::cerr << e.what() << '\n';
-    stop();
+    LOG_S("server error: " << e.what());
   }
 }
-
-REGISTER_EXAMPLE(MultiTCPServer);
\ No newline at end of file
diff --git a/src/socket/multiple_client/MultiTCPServer.h b/src/socket/multiple_client/MultiTCPServer.h
index 5e1c870..e683d9d 100644
--- a/src/socket/multiple_client/MultiTCPServer.h
+++ b/src/socket/multiple_client/MultiTCPServer.h
@@ -1,24 +1,29 @@
 #pragma once
+
+#include <mutex>
 #include <thread>
 #include <vector>
-#include "../simple_tcp/TCPServer.h"
-#include "IExample.h"
 
-class MultiTCPServer : public TCPServer, public IExample {
- public:
-  std::string group() const override { return "socket/tcp"; }
-
-  std::string name() const override { return "MultiTCPServer"; }
+#include "../simple_tcp/TCPServer.h"
 
-  std::string description() const override {
-    return "Multi TCP server listening on port 8080.\nRun `telnet localhost "
-           "8080` to connect.";
-  }
+namespace net {
 
-  void execute() override { run(); }
+/// Echo server that serves every client on its own thread, so several clients
+/// can be connected at the same time ("thread per connection").
+class MultiTCPServer : public TCPServer {
+ public:
+  using TCPServer::TCPServer;
+  ~MultiTCPServer() override;
 
  protected:
   void acceptLoop() override;
-  void run();
+
+ private:
+  void disconnectAllClients();
+
   std::vector<std::thread> client_threads_;
+  std::mutex clients_mutex_;
+  std::vector<int> client_fds_;  // sockets of the clients still connected
 };
+
+}  // namespace net
diff --git a/src/socket/simple_tcp/LoopbackEcho.cpp b/src/socket/simple_tcp/LoopbackEcho.cpp
new file mode 100644
index 0000000..9898558
--- /dev/null
+++ b/src/socket/simple_tcp/LoopbackEcho.cpp
@@ -0,0 +1,61 @@
+// -----------------------------------------------------------------------------
+// Server and client in one process
+//
+// The same TCPServer and TCPClient classes as in SimpleTCPServer and
+// SimpleTCPClient, but both run inside this example: the server serves on a
+// background thread and the client talks to it over the loopback interface.
+// No second terminal is needed, so this example also runs in the smoke tests.
+//
+// Things to notice:
+//   - Port 0 asks the operating system for any free port; boundPort() tells
+//     which one was chosen (so the example never collides with other servers).
+//   - open() binds and listens BEFORE the thread starts, so the client can
+//     connect right away: connections queue up in the listen backlog.
+//   - stop() wakes up the blocking accept() so the server thread can finish.
+// -----------------------------------------------------------------------------
+
+#include <string>
+#include <thread>
+
+#include "TCPClient.h"
+#include "TCPServer.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+std::string trimmed(std::string text) {
+  while (!text.empty() && (text.back() == '\n' || text.back() == '\r')) {
+    text.pop_back();
+  }
+  return text;
+}
+
+void run() {
+  LOG_SECTION("Starting the server on a free port");
+  net::TCPServer server{0};
+  server.open();
+  std::thread server_thread([&server] { server.serve(); });
+
+  LOG_SECTION("Talking to it with a client");
+  net::TCPClient client{"127.0.0.1", server.boundPort()};
+  if (client.connect()) {
+    LOG_S("client got: " << trimmed(client.receive()));
+    for (const std::string message : {"hello", "sockets are file descriptors", "Q"}) {
+      client.send(message + "\n");
+      LOG_S("client sent \"" << message << "\", echo: \"" << trimmed(client.receive()) << '"');
+    }
+    const std::string after_quit = client.receive();
+    LOG_S("after Q the server closed the connection: " << std::boolalpha << after_quit.empty());
+  }
+
+  LOG_SECTION("Stopping the server");
+  server.stop();
+  server_thread.join();
+}
+
+}  // namespace
+
+LAB_EXAMPLE("LoopbackEcho", "TCP server thread and client in one process over 127.0.0.1") {
+  run();
+}
diff --git a/src/socket/simple_tcp/SimpleTCPClient.cpp b/src/socket/simple_tcp/SimpleTCPClient.cpp
index 2881194..a67325e 100644
--- a/src/socket/simple_tcp/SimpleTCPClient.cpp
+++ b/src/socket/simple_tcp/SimpleTCPClient.cpp
@@ -1,52 +1,60 @@
+// -----------------------------------------------------------------------------
+// Simple TCP client
+//
+//   socket()   create an endpoint
+//   connect()  open a connection to the server's address and port
+//   send()     write bytes, recv() reads the reply
+//   close()    end the connection
+//
+// Start SimpleTCPServer or MultiTCPServer in another terminal first, then type
+// lines here. Each line is sent with a trailing '\n' because the server's
+// protocol is line-based: std::getline removes the newline, and without it the
+// server could not tell where a command such as "Q" ends. (telnet sends "\r\n".)
+// -----------------------------------------------------------------------------
+
+#include <exception>
 #include <iostream>
-#include "ExampleRegistry.h"
+#include <string>
+
 #include "TCPClient.h"
+#include "lab/Example.h"
+#include "lab/Logger.h"
 
 namespace {
 
 void run() {
-  try {
-    TCPClient client("127.0.0.1", 8080);
-
-    if (!client.connect()) {
-      std::cout << "connect failed\n";
-      return;
+  net::TCPClient client{"127.0.0.1", 8080};
+  if (!client.connect()) {
+    LOG("Is the server running? Start SimpleTCPServer in another terminal "
+        "first.");
+    return;
+  }
+  LOG_S("connected to " << client.host() << ':' << client.port());
+  std::cout << client.receive() << std::flush;  // welcome message
+
+  std::string line;
+  while (std::getline(std::cin, line)) {
+    client.send(line + "\n");
+    const std::string reply = client.receive();
+    if (reply.empty()) {
+      LOG("the server closed the connection");
+      break;
     }
-    std::cout << "connected to " << "host: " << client.getHost()
-              << " port:" << client.getPort() << "\n";
-    std::string response = client.receive();
-    std::cout << response << std::endl;
-    std::string msg;
-    while (true) {
-      if (!std::getline(std::cin, msg)) {
-        std::cout << "get line failed" << std::endl;
-        break;
-      };
-
-      // TODO(phong-nguyen): why we need \n here
-      client.send(msg + "\n");
-      response = client.receive();
-      std::cout << response;
+    std::cout << "echo: " << reply << std::flush;
+    if (line == "Q" || line == "SHUTDOWN") {
+      break;
     }
-
-    client.close();
-  } catch (const std::exception& e) {
-    // Connection closed by foreign host
-    std::cout << "error: " << e.what() << std::endl;
   }
 }
 
 }  // namespace
 
-class SimpleTCPClient : public IExample {
- public:
-  std::string group() const override { return "socket/tcp"; }
-
-  std::string name() const override { return "SimpleTCPClient"; }
-
-  std::string description() const override { return "Simple TCP Client"; }
-
-  void execute() override { run(); }
-};
-
-REGISTER_EXAMPLE(SimpleTCPClient);
\ No newline at end of file
+LAB_EXAMPLE("SimpleTCPClient",
+            "type lines and send them to the echo server on 127.0.0.1:8080",
+            lab::kInteractive) {
+  try {
+    run();
+  } catch (const std::exception& e) {
+    LOG_S("client error: " << e.what());
+  }
+}
diff --git a/src/socket/simple_tcp/SimpleTCPServer.cpp b/src/socket/simple_tcp/SimpleTCPServer.cpp
index 8449b6f..6771664 100644
--- a/src/socket/simple_tcp/SimpleTCPServer.cpp
+++ b/src/socket/simple_tcp/SimpleTCPServer.cpp
@@ -1,35 +1,36 @@
-#include <iostream>
+// -----------------------------------------------------------------------------
+// Simple TCP echo server (see README.md in src/socket for the background)
+//
+//   socket()  create an endpoint
+//   bind()    attach it to an address and port (127.0.0.1:8080)
+//   listen()  mark it as passive: it waits for connections
+//   accept()  block until a client connects, returns a NEW socket for it
+//   recv()    read bytes from the client, send() writes bytes back
+//   close()   release the client socket, and finally the server socket
+//
+// This server handles ONE client at a time: while it serves a client, other
+// clients wait in the listen queue (see MultiTCPServer for a threaded server).
+//
+// Try it in a second terminal:
+//   telnet localhost 8080      (or: nc localhost 8080)
+//   or run the SimpleTCPClient example
+// Type lines to get them echoed, Q to disconnect, SHUTDOWN to stop the server.
+// -----------------------------------------------------------------------------
+
+#include <exception>
 
-#include "ExampleRegistry.h"
 #include "TCPServer.h"
-
-namespace {
-
-void run() {
-  TCPServer server(8080);
-
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+LAB_EXAMPLE("SimpleTCPServer",
+            "echo server on 127.0.0.1:8080, one client at a time (telnet "
+            "localhost 8080)",
+            lab::kInteractive) {
+  net::TCPServer server{8080};
   try {
-    server.start();
+    server.start();  // blocks until a client sends SHUTDOWN
   } catch (const std::exception& e) {
-    std::cerr << e.what() << '\n';
-    server.stop();
+    LOG_S("server error: " << e.what());
   }
 }
-
-}  // namespace
-
-class SimpleTCPServer : public IExample {
- public:
-  std::string group() const override { return "socket/tcp"; }
-
-  std::string name() const override { return "SimpleTCPServer"; }
-
-  std::string description() const override {
-    return "Simple TCP server listening on port 8080.\nRun `telnet localhost "
-           "8080` to connect.";
-  }
-
-  void execute() override { run(); }
-};
-
-REGISTER_EXAMPLE(SimpleTCPServer);
\ No newline at end of file
diff --git a/src/socket/simple_tcp/TCPClient.cpp b/src/socket/simple_tcp/TCPClient.cpp
index c993289..36635e9 100644
--- a/src/socket/simple_tcp/TCPClient.cpp
+++ b/src/socket/simple_tcp/TCPClient.cpp
@@ -1,85 +1,96 @@
 #include "TCPClient.h"
 
-#include <sys/socket.h>
+#include <arpa/inet.h>   // inet_pton, htons
+#include <netinet/in.h>  // sockaddr_in
+#include <sys/socket.h>  // socket, connect, send, recv
+#include <unistd.h>      // close
+
+#include <array>
+#include <cerrno>
+#include <cstring>
 #include <stdexcept>
+#include <system_error>
+#include <utility>
 
-#include <arpa/inet.h>
-#include <netinet/in.h>
-#include <unistd.h>
+#include "lab/Logger.h"
 
-TCPClient::TCPClient(const std::string& host, uint16_t port)
-    : host_{host}, port_{port}, client_fd_{-1} {}
+namespace net {
+
+TCPClient::TCPClient(std::string host, std::uint16_t port)
+    : host_{std::move(host)}, port_{port} {}
+
+TCPClient::~TCPClient() {
+  close();
+}
 
 bool TCPClient::connect() {
-  client_fd_ = socket(AF_INET, SOCK_STREAM, 0);
-  if (client_fd_ < 0) {
-    throw std::runtime_error("socket failed.");
-  }
+  close();  // reconnecting: release a previous socket first
 
-  // specifying the address
   sockaddr_in server_address{};
   server_address.sin_family = AF_INET;
   server_address.sin_port = htons(port_);
+  // inet_pton converts "127.0.0.1" into the binary form (1 = ok, 0 = invalid).
+  if (::inet_pton(AF_INET, host_.c_str(), &server_address.sin_addr) != 1) {
+    throw std::invalid_argument("invalid IPv4 address: " + host_);
+  }
 
-  // serverAddress.sin_addr.s_addr = INADDR_ANY;
-  if (::inet_pton(AF_INET, host_.c_str(), &server_address.sin_addr) <= 0) {
-    throw std::runtime_error("invalid address");
+  fd_ = ::socket(AF_INET, SOCK_STREAM, 0);
+  if (fd_ < 0) {
+    throw std::system_error(errno, std::generic_category(), "socket");
   }
 
-  // sending connection request
-  return (
-      ::connect(client_fd_,
-                reinterpret_cast<sockaddr*>(&server_address),  // global syscall
-                sizeof(server_address)) == 0);
+  // `::connect` is the POSIX function; plain `connect` would be this member.
+  if (::connect(fd_, reinterpret_cast<sockaddr*>(&server_address),
+                sizeof(server_address)) < 0) {
+    LOG_S("[TCPClient] connect to " << host_ << ':' << port_
+                                    << " failed: " << std::strerror(errno));
+    close();
+    return false;
+  }
+  return true;
 }
 
-void TCPClient::send(const std::string& msg) const {
-  if (client_fd_ < 0) {
-    throw std::runtime_error("socket not connected");
+void TCPClient::send(std::string_view message) const {
+  if (fd_ < 0) {
+    throw std::logic_error("TCPClient::send: not connected");
   }
-
-  const char* data = msg.c_str();
-  size_t total = 0;
-  size_t len = msg.size();
-  while (total < len) {
-    ssize_t sent = ::send(client_fd_, data + total, len - total, 0);
-    if (sent <= 0) {
-      throw std::runtime_error("send failed");
+  std::size_t total = 0;
+  while (total < message.size()) {
+    const ssize_t sent = ::send(fd_, message.data() + total,
+                                message.size() - total, MSG_NOSIGNAL);
+    if (sent < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      throw std::system_error(errno, std::generic_category(), "send");
     }
-    total += sent;
+    total += static_cast<std::size_t>(sent);
   }
 }
 
 std::string TCPClient::receive() const {
-  if (client_fd_ < 0) {
-    throw std::runtime_error("socket not connected");
+  if (fd_ < 0) {
+    throw std::logic_error("TCPClient::receive: not connected");
   }
-
-  char buffer[1024];
-
-  ssize_t bytes = recv(client_fd_, buffer, sizeof(buffer), 0);
-  if (bytes < 0) {
-    throw std::runtime_error("recv failed");
-  }
-
-  if (bytes == 0) {
-    throw std::runtime_error("connection closed");
+  std::array<char, 1024> buffer{};
+  while (true) {
+    const ssize_t received = ::recv(fd_, buffer.data(), buffer.size(), 0);
+    if (received < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      throw std::system_error(errno, std::generic_category(), "recv");
+    }
+    return std::string(buffer.data(),
+                       static_cast<std::size_t>(received));  // "" = closed
   }
-
-  return std::string(buffer, bytes);
 }
 
 void TCPClient::close() {
-  if (client_fd_ >= 0) {
-    ::close(client_fd_);
-    client_fd_ = -1;
+  if (fd_ >= 0) {
+    ::close(fd_);
+    fd_ = -1;
   }
 }
 
-const std::string& TCPClient::getHost() const {
-  return host_;
-}
-
-uint16_t TCPClient::getPort() const {
-  return port_;
-}
\ No newline at end of file
+}  // namespace net
diff --git a/src/socket/simple_tcp/TCPClient.h b/src/socket/simple_tcp/TCPClient.h
index 61b4900..9dcdc51 100644
--- a/src/socket/simple_tcp/TCPClient.h
+++ b/src/socket/simple_tcp/TCPClient.h
@@ -1,21 +1,45 @@
 #pragma once
+
 #include <cstdint>
 #include <string>
+#include <string_view>
+
+namespace net {
 
+/// Blocking IPv4 TCP client.
+///
+/// Lifecycle of a client socket: socket() -> connect() -> send()/recv() -> close()
+/// The socket is closed automatically by the destructor (RAII).
 class TCPClient {
  public:
-  TCPClient(const std::string& host, uint16_t port);
+  TCPClient(std::string host, std::uint16_t port);
+  ~TCPClient();
+
+  TCPClient(const TCPClient&) = delete;
+  TCPClient& operator=(const TCPClient&) = delete;
 
+  /// Connects to the server. Returns false if the connection is refused.
+  /// Throws std::invalid_argument for a malformed address and
+  /// std::system_error if the socket cannot be created.
   bool connect();
-  void close();
-  void send(const std::string& msg) const;
+
+  /// Sends every byte of `message`. Throws std::system_error on failure.
+  void send(std::string_view message) const;
+
+  /// Blocks until data arrives. Returns an empty string when the server has
+  /// closed the connection. Throws std::system_error on failure.
   std::string receive() const;
 
-  const std::string& getHost() const;
-  uint16_t getPort() const;
+  void close();
+
+  bool isConnected() const { return fd_ >= 0; }
+  const std::string& host() const { return host_; }
+  std::uint16_t port() const { return port_; }
 
  private:
   std::string host_;
-  uint16_t port_;
-  int client_fd_;
-};
\ No newline at end of file
+  std::uint16_t port_;
+  int fd_{-1};
+};
+
+}  // namespace net
diff --git a/src/socket/simple_tcp/TCPServer.cpp b/src/socket/simple_tcp/TCPServer.cpp
index 1a3848a..b892109 100644
--- a/src/socket/simple_tcp/TCPServer.cpp
+++ b/src/socket/simple_tcp/TCPServer.cpp
@@ -1,186 +1,228 @@
 #include "TCPServer.h"
 
-#include <arpa/inet.h>   // sockaddr_in, inet_ntoa
-#include <sys/socket.h>  // socket, bind, listen, accept
-#include <unistd.h>      // close(server)
+#include <arpa/inet.h>   // inet_ntop, htons, htonl
+#include <netinet/in.h>  // sockaddr_in, INADDR_LOOPBACK
+#include <sys/socket.h>  // socket, bind, listen, accept, recv, send, shutdown
+#include <unistd.h>      // close
 
-#include <iostream>
+#include <array>
+#include <cerrno>
+#include <cstring>
+#include <string>
+#include <system_error>
 
-TCPServer::TCPServer(uint16_t port) : port_{port} {}
+#include "lab/Logger.h"
+
+namespace net {
+namespace {
+
+/// Wraps errno in an exception, e.g. "bind: Address already in use".
+[[noreturn]] void throwSystemError(const char* operation) {
+  throw std::system_error(errno, std::generic_category(), operation);
+}
+
+std::string toString(const sockaddr_in& address) {
+  std::array<char, INET_ADDRSTRLEN> text{};
+  // inet_ntop is the thread-safe replacement for inet_ntoa.
+  ::inet_ntop(AF_INET, &address.sin_addr, text.data(), text.size());
+  return std::string(text.data()) + ":" +
+         std::to_string(ntohs(address.sin_port));
+}
+
+std::string_view withoutLineEnd(std::string_view text) {
+  while (!text.empty() && (text.back() == '\n' || text.back() == '\r')) {
+    text.remove_suffix(1);
+  }
+  return text;
+}
+
+}  // namespace
+
+TCPServer::TCPServer(std::uint16_t port) : requested_port_{port} {}
 
 TCPServer::~TCPServer() {
+  closeServerSocket();
+}
+
+void TCPServer::start() {
+  open();
+  serve();
+}
+
+void TCPServer::open() {
   if (server_fd_ >= 0) {
-    close(server_fd_);
+    return;  // already open
+  }
+  createSocket();
+  bindSocket();
+  listenSocket();
+  running_ = true;
+  LOG_S("[TCPServer] listening on 127.0.0.1:" << bound_port_);
+}
+
+void TCPServer::serve() {
+  acceptLoop();
+  LOG("[TCPServer] stopped");
+}
+
+void TCPServer::stop() {
+  if (running_.exchange(false)) {
+    // shutdown() on a listening socket makes a blocked accept() return an
+    // error, which lets acceptLoop() notice that it should exit.
+    const int fd = server_fd_;
+    if (fd >= 0) {
+      ::shutdown(fd, SHUT_RDWR);
+    }
   }
 }
 
 void TCPServer::createSocket() {
-  // create the TCP socket (file descriptor IPv4 + stream socket)
-  server_fd_ = socket(AF_INET, SOCK_STREAM, 0);
-  if (server_fd_ < 0) {
-    throw std::runtime_error("socket creation failed");
+  // IPv4 (AF_INET) + reliable byte stream (SOCK_STREAM = TCP)
+  const int fd = ::socket(AF_INET, SOCK_STREAM, 0);
+  if (fd < 0) {
+    throwSystemError("socket");
   }
+  server_fd_ = fd;  // from here on the destructor closes it
 
-  // allow the port to be reused immediately after the server stop
-  // otherwise, the OS may keep the port reserved for 60 seconds
-  int reuse = 1;
-  if (setsockopt(server_fd_, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse)) <
-      0) {
-    throw std::runtime_error("setsockopt(SO_REUSEADDR) failed");
+  // Allow restarting the server immediately. Without SO_REUSEADDR the port
+  // stays blocked in TIME_WAIT for up to a few minutes after the server stops.
+  const int reuse = 1;
+  if (::setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse)) < 0) {
+    throwSystemError("setsockopt(SO_REUSEADDR)");
   }
 }
 
-void TCPServer::bindSocket() const {
-  sockaddr_in server_addr{};
-  server_addr.sin_family = AF_INET;  // IPv4
-  // server_addr.sin_addr.s_addr = INADDR_ANY;  // accept connections on all network interfaces
-  // e.g. if the machine has multiple IP addresses:
-  //   127.0.0.1     (localhost / loopback)
-  //   192.168.1.50  (LAN IP)
-  // binding with INADDR_ANY means the server will listen on ALL of them.
-  //
-  // If we instead bind to 127.0.0.1, the server only accepts connections
-  // from the same machine (localhost).
-  server_addr.sin_addr.s_addr = inet_addr("127.0.0.1");
-  server_addr.sin_port = htons(port_);  // onvert port to network byte order
-
-  // associate the socket with the address/port
-  if (bind(server_fd_, reinterpret_cast<sockaddr*>(&server_addr),
-           sizeof(server_addr)) < 0) {
-    throw std::runtime_error(
-        "bind failed");  // TODO(phong-nguyen): anyway to know what kind of the error
+void TCPServer::bindSocket() {
+  sockaddr_in address{};
+  address.sin_family = AF_INET;
+  // 127.0.0.1 accepts connections from this machine only. INADDR_ANY would
+  // listen on every network interface (loopback, LAN, Wi-Fi, ...).
+  address.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+  address.sin_port = htons(requested_port_);  // host -> network byte order
+
+  if (::bind(server_fd_, reinterpret_cast<sockaddr*>(&address),
+             sizeof(address)) < 0) {
+    throwSystemError("bind");  // e.g. "Address already in use"
   }
 
-  std::cout << "Server running on " << inet_ntoa(server_addr.sin_addr) << ":"
-            << ntohs(server_addr.sin_port) << "\n";
+  // Ask the OS which port we really got (relevant for port 0).
+  socklen_t length = sizeof(address);
+  if (::getsockname(server_fd_, reinterpret_cast<sockaddr*>(&address),
+                    &length) < 0) {
+    throwSystemError("getsockname");
+  }
+  bound_port_ = ntohs(address.sin_port);
 }
 
 void TCPServer::listenSocket() const {
-  // (128) is the maximum number of queued connection requests
-  if (listen(server_fd_, 128) < 0) {
-    throw std::runtime_error("listen failed");
+  // SOMAXCONN: maximum length of the queue of pending connections.
+  if (::listen(server_fd_, SOMAXCONN) < 0) {
+    throwSystemError("listen");
   }
-
-  std::cout << "[TCPServer] listening on port " << port_ << "\n";
 }
 
 void TCPServer::acceptLoop() {
   while (running_) {
-    sockaddr_in client_addr{};
-    socklen_t client_add_len = sizeof(client_addr);
-
-    // this block until a client connect
-    int client_fd = accept(
-        server_fd_, reinterpret_cast<sockaddr*>(&client_addr), &client_add_len);
-
-    if (client_fd < 0) {  // connection failed
-      std::cerr << "[TCPServer] accept failed\n";
+    sockaddr_in client_address{};
+    socklen_t length = sizeof(client_address);
+
+    // Blocks until a client connects (or stop() is called).
+    const int client_fd = ::accept(
+        server_fd_, reinterpret_cast<sockaddr*>(&client_address), &length);
+    if (client_fd < 0) {
+      if (!running_) {
+        break;
+      }
+      if (errno == EINTR) {
+        continue;  // interrupted by a signal: just try again
+      }
+      LOG_S("[TCPServer] accept failed: " << std::strerror(errno));
       continue;
     }
 
-    std::cout << "[TCPServer] client " << inet_ntoa(client_addr.sin_addr)
-              << " connected\n";
-
+    LOG_S("[TCPServer] client " << toString(client_address) << " connected");
     try {
       handleClient(client_fd);
     } catch (const std::exception& e) {
-      std::cerr << "[TCPServer] client error: " << e.what() << "\n";
-      close(client_fd);
-    }
-  }
-}
-
-void TCPServer::sendAll(int fd, const char* data, size_t len) {
-  size_t total = 0;
-  while (total < len) {
-    ssize_t sent = send(fd, data + total, len - total, 0);
-    if (sent <= 0) {
-      throw std::runtime_error("send failed");
+      LOG_S("[TCPServer] client error: " << e.what());
     }
-    total += sent;
+    ::close(client_fd);  // always release the client socket
   }
 }
 
-void TCPServer::handleClient(int client_fd) const {
-  char buffer[1024];
-
-  // send a notify to the client
-  std::string welcome = "Connected to the TCP Server on port " +
-                        std::to_string(port_) +
-                        "\nType 'Q' to stop the connection.\n";
+void TCPServer::handleClient(int client_fd) {
+  sendAll(client_fd,
+          "Connected to the cpp-lab echo server on port " +
+              std::to_string(bound_port_) +
+              "\nType Q to disconnect or SHUTDOWN to stop the server.\n");
 
-  sendAll(client_fd, welcome.c_str(), welcome.size());
+  std::array<char, 1024> buffer{};
+  std::string pending;  // bytes of a line that is not complete yet
 
   while (true) {
-    // receive data from the client
-    int bytes = recv(client_fd, buffer, sizeof(buffer) - 1, 0);
-
-    if (bytes == 0) {  // : client closed connection
-      std::cout << "[TCPServer] client closed connection\n";
-      break;
+    const ssize_t received = ::recv(client_fd, buffer.data(), buffer.size(), 0);
+    if (received == 0) {
+      LOG("[TCPServer] client closed the connection");
+      return;
     }
-
-    if (bytes < 0) {  // : error
-      throw std::runtime_error("recv failed");
+    if (received < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      throwSystemError("recv");
     }
 
-    buffer[bytes] = '\0';
-
-    // print out
-    std::cout << "client " << client_fd << ": " << buffer;
-
-    sendAll(client_fd, buffer, bytes);
-
-    // stop connection if client sends 'Q'
-    std::string line(buffer, bytes);
-    line.erase(line.find_last_not_of("\r\n") + 1);  // remove \r\n
-    if (line == "Q") {
-      std::cout << "[TCPServer] client disconnected\n";
-      break;
+    const std::string_view chunk(buffer.data(),
+                                 static_cast<std::size_t>(received));
+    LOG_S("[TCPServer] fd " << client_fd << " received \""
+                            << withoutLineEnd(chunk) << "\"");
+    sendAll(client_fd, chunk);  // echo
+
+    // TCP is a byte STREAM, not a sequence of messages: one recv() may contain
+    // half a line or several lines. Collect bytes until a '\n' completes a line.
+    pending.append(chunk);
+    for (auto end = pending.find('\n'); end != std::string::npos;
+         end = pending.find('\n')) {
+      const std::string line(
+          withoutLineEnd(std::string_view(pending).substr(0, end)));
+      pending.erase(0, end + 1);
+      if (line == "Q") {
+        LOG("[TCPServer] client sent Q, closing its connection");
+        return;
+      }
+      if (line == "SHUTDOWN") {
+        LOG("[TCPServer] client sent SHUTDOWN, stopping the server");
+        stop();
+        return;
+      }
     }
   }
-
-  // close connection after the client session end
-  close(client_fd);
 }
 
-void TCPServer::start() noexcept(false) {
-  std::cout << "[TCPServer] Starting...\n";
-  createSocket();
-  bindSocket();
-  listenSocket();
-
-  running_ = true;
-
-  acceptLoop();
-}
-
-void TCPServer::stop() {
-  if (running_) {
-    // how to close client
-    close(server_fd_);
-    running_ = false;
+void TCPServer::sendAll(int fd, std::string_view data) {
+  std::size_t total = 0;
+  while (total < data.size()) {
+    // send() may transmit fewer bytes than requested. MSG_NOSIGNAL prevents a
+    // SIGPIPE (which would kill the process) when the peer has disconnected.
+    const ssize_t sent =
+        ::send(fd, data.data() + total, data.size() - total, MSG_NOSIGNAL);
+    if (sent < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      throwSystemError("send");
+    }
+    total += static_cast<std::size_t>(sent);
   }
 }
 
-uint16_t TCPServer::getPort() const {
-  return port_;
-}
-
-void TCPServer::setPort(uint16_t port) {
-  if (!running_) {
-    port_ = port;
+void TCPServer::closeServerSocket() {
+  running_ = false;
+  const int fd =
+      server_fd_.exchange(-1);  // take the fd so it is closed only once
+  if (fd >= 0) {
+    ::close(fd);
   }
 }
 
-bool TCPServer::isRunning() const {
-  return running_;
-}
-
-int TCPServer::getServerFD() const {
-  return server_fd_;
-}
-
-void TCPServer::setServerFD(int fd) {
-  server_fd_ = fd;
-}
\ No newline at end of file
+}  // namespace net
diff --git a/src/socket/simple_tcp/TCPServer.h b/src/socket/simple_tcp/TCPServer.h
index c32eaf9..d95920f 100644
--- a/src/socket/simple_tcp/TCPServer.h
+++ b/src/socket/simple_tcp/TCPServer.h
@@ -1,55 +1,68 @@
 #pragma once
+
+#include <atomic>
+#include <cstddef>
 #include <cstdint>
+#include <string_view>
+
+namespace net {
 
+/// A small, blocking, line-based TCP echo server for IPv4 loopback.
+///
+/// Lifecycle of a server socket:
+///   socket() -> setsockopt() -> bind() -> listen() -> accept() loop
+///   -> recv()/send() with each client -> close()
+///
+/// Protocol: every received byte is echoed back. A line "Q" closes the
+/// connection, a line "SHUTDOWN" stops the whole server.
 class TCPServer {
  public:
-  explicit TCPServer(uint16_t port = 80);
+  /// Port 0 lets the operating system pick a free port (see boundPort()).
+  explicit TCPServer(std::uint16_t port = 8080);
   virtual ~TCPServer();
 
-  void start() noexcept(false);
-  void stop();
+  TCPServer(const TCPServer&) = delete;
+  TCPServer& operator=(const TCPServer&) = delete;
 
-  void setPort(uint16_t port);
-  uint16_t getPort() const;
+  /// open() + serve(): blocks until stop() is called.
+  void start();
 
- private:
-  /**
-   * @brief  Create the server socket and configure basic options
-   */
-  void createSocket();
+  /// Creates the socket, binds it and starts listening. Throws std::system_error.
+  void open();
 
-  /**
-   * @brief Bind the socket to a port and network interface
-   */
-  void bindSocket() const;
+  /// Accepts and serves clients until stop() is called.
+  void serve();
 
-  /**
-   * @brief Put the socket into listening mode
-   */
-  void listenSocket() const;
+  /// Stops the accept loop. Safe to call from another thread.
+  void stop();
 
-  static void sendAll(int fd, const char* data, std::size_t len);
+  bool isRunning() const { return running_; }
+
+  /// The port actually in use (differs from the requested one for port 0).
+  std::uint16_t boundPort() const { return bound_port_; }
 
  protected:
-  /**
-   * @brief Handle communication with a single client
-   * 
-   * @param
-   *  [in] client_fd client file descriptor 
-   */
-  void handleClient(int client_fd) const;
-
-  /**
-   * @brief Loop waiting for client connections
-   */
+  /// Serves clients one after another. MultiTCPServer overrides it.
   virtual void acceptLoop();
 
-  bool isRunning() const;
-  int getServerFD() const;
-  void setServerFD(int fd);
+  /// Echo protocol for one connected client. Does not close `client_fd`.
+  void handleClient(int client_fd);
+
+  /// Sends every byte, retrying on partial sends. Throws std::system_error.
+  static void sendAll(int fd, std::string_view data);
+
+  int serverFd() const { return server_fd_; }
 
  private:
-  uint16_t port_;      // TCP ports are in 0 - 65535
-  int server_fd_{-1};  // socket descriptor
-  volatile bool running_{false};
-};
\ No newline at end of file
+  void createSocket();
+  void bindSocket();
+  void listenSocket() const;
+  void closeServerSocket();
+
+  std::uint16_t requested_port_;
+  std::uint16_t bound_port_{0};
+  std::atomic<int> server_fd_{-1};
+  std::atomic<bool> running_{false};
+};
+
+}  // namespace net
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 2b07b48..78d9006 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -1,49 +1,40 @@
 # ----------------------------------------------------------------------------------------
-# Unit testing target
+# Unit tests (GoogleTest + GoogleMock)
+#
+# Every *Test.cpp below this folder is compiled automatically - add a file, rebuild.
+#
+#   ctest --test-dir build -L unit                                    # all unit tests
+#   ./build/bin/cpp_lab_project_unit_test --gtest_filter='Registry*'   # a subset
+#
+# The smoke tests that run every example are registered in src/CMakeLists.txt (label
+# "example").
 # ----------------------------------------------------------------------------------------
 
-# Define the test executable name
-set(PROJECT_NAME_TEST ${PROJECT_NAME}_unit_test)
-
-# Test source files
-set(SOURCES
-    ${PROJECT_SOURCE_DIR}/src/DeleteMe.cpp
-)
-
-set(TEST_SOURCES
-    DeleteMeTest.cpp
-)
+include(GoogleTest)
 
-# Build the test executable
-add_executable(${PROJECT_NAME_TEST}
-    ${SOURCES}
-    ${TEST_SOURCES}
-)
+file(GLOB_RECURSE unit_test_sources CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/*Test.cpp)
 
-# Header files directory
-set(APP_HEADERS
-    ${PROJECT_SOURCE_DIR}/include
-    ${CMAKE_BINARY_DIR}/generated # cmake generated headers
+add_executable(${PROJECT_NAME}_unit_test
+    ${unit_test_sources}
+    # Code under test that is not part of the lab library
+    ${PROJECT_SOURCE_DIR}/src/controller/pid/pid.cpp
 )
 
-# Add include paths for the test target
-target_include_directories(${PROJECT_NAME_TEST}
-    PRIVATE ${APP_HEADERS}
+target_include_directories(${PROJECT_NAME}_unit_test
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}
+        ${PROJECT_SOURCE_DIR}/src
 )
 
-# Link GoogleTest and GoogleMock
-target_link_libraries(${PROJECT_NAME_TEST}
-    GTest::gtest_main
-    GTest::gmock_main
+# gmock_main provides main() and links GoogleTest as well
+target_link_libraries(${PROJECT_NAME}_unit_test
+    PRIVATE
+        cpplab::lab
+        GTest::gmock_main
 )
 
-# Register the unit test executable with CTest
-# `ctest --output-on-failure`
-add_test(
-    NAME unit_tests
-    COMMAND ${PROJECT_NAME_TEST}
+# Register every TEST() with CTest
+gtest_discover_tests(${PROJECT_NAME}_unit_test
+    DISCOVERY_TIMEOUT 30
+    PROPERTIES LABELS "unit"
 )
-
-# Automatically register tests with CTest
-include(GoogleTest)
-gtest_discover_tests(${PROJECT_NAME_TEST})
\ No newline at end of file
diff --git a/tests/DeleteMeTest.cpp b/tests/DeleteMeTest.cpp
deleted file mode 100644
index 7cdfa91..0000000
--- a/tests/DeleteMeTest.cpp
+++ /dev/null
@@ -1,99 +0,0 @@
-#include "DeleteMe.h"
-
-#include <gtest/gtest.h>
-
-/**
- * ASSERT_* versions generate fatal failures when they fail, and abort the current function
- * EXPECT_* are preferred, as they allow more than one failure to be reported in a test.
- */
-TEST(AddTest, ValidNumbers) {
-  DeleteMe calc = DeleteMe();
-
-  ASSERT_TRUE(calc.add(1, 2));
-  ASSERT_EQ(3, calc.get_last_result());
-
-  ASSERT_TRUE(calc.add(0, 5));
-  ASSERT_EQ(5, calc.get_last_result());
-
-  ASSERT_TRUE(calc.add(5, 0));
-  ASSERT_EQ(5, calc.get_last_result());
-
-  ASSERT_TRUE(calc.add(4, -6));
-  ASSERT_EQ(-2, calc.get_last_result());
-
-  ASSERT_TRUE(calc.add(-4, 6));
-  ASSERT_EQ(2, calc.get_last_result());
-
-  ASSERT_TRUE(calc.add(-4, -6));
-  ASSERT_EQ(-10, calc.get_last_result());
-}
-
-TEST(DivTest, ValidNumbers) {
-  DeleteMe calc = DeleteMe();
-
-  ASSERT_TRUE(calc.div(10, 2));
-  ASSERT_EQ(5, calc.get_last_result());
-
-  ASSERT_TRUE(calc.div(-12, 3));
-  ASSERT_EQ(-4, calc.get_last_result());
-
-  ASSERT_TRUE(calc.div(12, -3));
-  ASSERT_EQ(-4, calc.get_last_result());
-}
-
-TEST(DivTest, InvalidNumbers) {
-  DeleteMe calc = DeleteMe();
-
-  ASSERT_FALSE(calc.div(7, 0));
-  ASSERT_EQ(0, calc.get_last_result());
-}
-
-TEST(DivTest, FailureMessage) {
-  // ASSERT_FALSE(true) << "FailureMessage: ASSERT_FALSE(true)";
-}
-
-#include <gmock/gmock.h>
-#include "mock/MockTurtle.h"
-#include "mock/Painter.h"
-TEST(MockPainterTest, DrawSquare_CallsCorrectTurtleOperations) {
-  MockTurtle turtle;
-  Painter painter{turtle};
-
-  EXPECT_CALL(turtle, PenDown()).Times(1);
-
-  EXPECT_CALL(turtle, Forward(100)).Times(4);
-  EXPECT_CALL(turtle, Turn(90)).Times(4);
-
-  EXPECT_CALL(turtle, PenUp()).Times(1);
-
-  painter.DrawSquare(100);
-}
-
-#include "mock/FakeTurtle.h"
-TEST(FakePainterTest, DrawSquare_ProducesSquarePath) {
-  FakeTurtle turtle;
-  Painter painter{turtle};
-
-  painter.DrawSquare(10);
-
-  const auto& path = turtle.Path();
-
-  ASSERT_EQ(path.size(), 8);  // 4 lines → 8 points (start/end)
-
-  EXPECT_EQ(path[0], std::make_pair(0, 0));
-  EXPECT_EQ(path[1], std::make_pair(0, 10));
-
-  EXPECT_EQ(path[2], std::make_pair(0, 10));
-  EXPECT_EQ(path[3], std::make_pair(10, 10));
-
-  EXPECT_EQ(path[4], std::make_pair(10, 10));
-  EXPECT_EQ(path[5], std::make_pair(10, 0));
-
-  EXPECT_EQ(path[6], std::make_pair(10, 0));
-  EXPECT_EQ(path[7], std::make_pair(0, 0));
-}
-
-int main(int argc, char** argv) {
-  testing::InitGoogleTest(&argc, argv);
-  return RUN_ALL_TESTS();
-}
diff --git a/tests/README.md b/tests/README.md
index e1e8592..6506357 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,3 +1,21 @@
+# Tests
+
+```bash
+ctest --test-dir build -L unit --output-on-failure      # the tests below
+ctest --test-dir build -L example                       # run every example once
+./build/bin/cpp_lab_project_unit_test --gtest_filter='Calculator*'
+```
+
+| Folder | Contents |
+|---|---|
+| `gtest_primer/` | tutorial tests: `TEST`, `TEST_F`, `TEST_P`, mocks and fakes |
+| `mock/` | the Turtle interface, a mock, a fake and the `Painter` under test |
+| `lab/` | tests for the lab framework: registry, command line, menu and runner |
+| `controller/` | tests for the PID controller |
+
+Every `*Test.cpp` below `tests/` is compiled automatically - just add a file.
+
+---
 # GoogleTest
 - Ref: https://google.github.io/googletest/
 - GoogleTest helps you write better C++ tests.
diff --git a/tests/controller/PidTest.cpp b/tests/controller/PidTest.cpp
new file mode 100644
index 0000000..d77ea07
--- /dev/null
+++ b/tests/controller/PidTest.cpp
@@ -0,0 +1,47 @@
+#include "controller/pid/pid.h"
+
+#include <gtest/gtest.h>
+
+#include <cmath>
+#include <stdexcept>
+#include <utility>
+
+namespace {
+
+TEST(PidTest, ZeroErrorGivesZeroOutput) {
+  controller::PID pid(0.1, 100, -100, 0.1, 0.01, 0.5);
+  EXPECT_DOUBLE_EQ(pid.calculate(50.0, 50.0), 0.0);
+}
+
+TEST(PidTest, OutputIsClampedToTheLimits) {
+  controller::PID pid(0.1, 10, -5, 100.0, 0.0, 0.0);  // huge proportional gain
+  EXPECT_DOUBLE_EQ(pid.calculate(1000.0, 0.0), 10.0);
+  EXPECT_DOUBLE_EQ(pid.calculate(-1000.0, 0.0), -5.0);
+}
+
+TEST(PidTest, ProportionalOnlyIsKpTimesError) {
+  controller::PID pid(1.0, 100, -100, 0.5, 0.0, 0.0);
+  EXPECT_DOUBLE_EQ(pid.calculate(10.0, 4.0), 3.0);  // 0.5 * (10 - 4)
+}
+
+TEST(PidTest, ConvergesToTheSetpoint) {
+  controller::PID pid(0.1, 100, -100, 0.1, 0.01, 0.5);
+  double value = 20.0;
+  for (int step = 0; step < 200; ++step) {
+    value += pid.calculate(100.0, value);
+  }
+  EXPECT_NEAR(value, 100.0, 0.5);
+}
+
+TEST(PidTest, RejectsInvalidParameters) {
+  EXPECT_THROW(controller::PID(0.0, 1, -1, 1, 0, 0), std::invalid_argument);
+  EXPECT_THROW(controller::PID(0.1, -1, 1, 1, 0, 0), std::invalid_argument);
+}
+
+TEST(PidTest, CanBeMoved) {
+  controller::PID original(1.0, 100, -100, 1.0, 0.0, 0.0);
+  controller::PID moved = std::move(original);
+  EXPECT_DOUBLE_EQ(moved.calculate(2.0, 1.0), 1.0);
+}
+
+}  // namespace
diff --git a/tests/gtest_primer/Calculator.h b/tests/gtest_primer/Calculator.h
new file mode 100644
index 0000000..f816138
--- /dev/null
+++ b/tests/gtest_primer/Calculator.h
@@ -0,0 +1,30 @@
+#pragma once
+
+/// A deliberately tiny class to demonstrate GoogleTest (see README.md in tests/).
+class Calculator {
+ public:
+  bool add(int lhs, int rhs) {
+    last_result_ = lhs + rhs;
+    return true;
+  }
+
+  bool multiply(int lhs, int rhs) {
+    last_result_ = lhs * rhs;
+    return true;
+  }
+
+  /// Returns false (and stores 0) for a division by zero.
+  bool divide(int dividend, int divisor) {
+    if (divisor == 0) {
+      last_result_ = 0;
+      return false;
+    }
+    last_result_ = dividend / divisor;
+    return true;
+  }
+
+  int lastResult() const { return last_result_; }
+
+ private:
+  int last_result_{0};
+};
diff --git a/tests/gtest_primer/CalculatorTest.cpp b/tests/gtest_primer/CalculatorTest.cpp
new file mode 100644
index 0000000..8d2a6f8
--- /dev/null
+++ b/tests/gtest_primer/CalculatorTest.cpp
@@ -0,0 +1,65 @@
+// GoogleTest primer: TEST, TEST_F (fixtures) and TEST_P (parameterized tests).
+// See tests/README.md for an explanation of each concept.
+
+#include "gtest_primer/Calculator.h"
+
+#include <gtest/gtest.h>
+
+#include <tuple>
+
+namespace {
+
+// TEST(TestSuiteName, TestName) - for free functions and simple classes.
+//
+// ASSERT_* stops the test at the first failure (use it when continuing makes no
+// sense); EXPECT_* records the failure and continues, so one run can report
+// several problems. Prefer EXPECT_* by default.
+TEST(CalculatorAddTest, AddsPositiveAndNegativeNumbers) {
+  Calculator calculator;
+
+  ASSERT_TRUE(calculator.add(1, 2));
+  EXPECT_EQ(calculator.lastResult(), 3);
+
+  calculator.add(4, -6);
+  EXPECT_EQ(calculator.lastResult(), -2) << "a custom message explains a failure";
+
+  calculator.add(-4, -6);
+  EXPECT_EQ(calculator.lastResult(), -10);
+}
+
+// TEST_F(FixtureName, TestName) - the fixture's SetUp() runs before EVERY test,
+// so each test starts from a fresh, known state.
+class CalculatorDivideTest : public testing::Test {
+ protected:
+  void SetUp() override { calculator_.add(40, 2); }  // lastResult() == 42
+
+  Calculator calculator_;
+};
+
+TEST_F(CalculatorDivideTest, DividesAndTruncates) {
+  ASSERT_TRUE(calculator_.divide(7, 2));
+  EXPECT_EQ(calculator_.lastResult(), 3);
+}
+
+TEST_F(CalculatorDivideTest, DivisionByZeroFailsAndResetsTheResult) {
+  EXPECT_EQ(calculator_.lastResult(), 42);  // state from SetUp()
+  EXPECT_FALSE(calculator_.divide(7, 0));
+  EXPECT_EQ(calculator_.lastResult(), 0);
+}
+
+// TEST_P - one test body, many inputs.
+class CalculatorMultiplyTest : public testing::TestWithParam<std::tuple<int, int, int>> {};
+
+TEST_P(CalculatorMultiplyTest, MultipliesTwoNumbers) {
+  const auto [lhs, rhs, expected] = GetParam();
+  Calculator calculator;
+  calculator.multiply(lhs, rhs);
+  EXPECT_EQ(calculator.lastResult(), expected);
+}
+
+INSTANTIATE_TEST_SUITE_P(Values, CalculatorMultiplyTest,
+                         testing::Values(std::make_tuple(2, 3, 6), std::make_tuple(-2, 3, -6),
+                                         std::make_tuple(0, 99, 0),
+                                         std::make_tuple(-4, -5, 20)));
+
+}  // namespace
diff --git a/tests/gtest_primer/TurtleMockTest.cpp b/tests/gtest_primer/TurtleMockTest.cpp
new file mode 100644
index 0000000..1a21949
--- /dev/null
+++ b/tests/gtest_primer/TurtleMockTest.cpp
@@ -0,0 +1,66 @@
+// GoogleMock primer: mocks vs fakes.
+//
+//   Fake : a working but simplified implementation (FakeTurtle records a path).
+//          Tests check the RESULT - "what happened?".
+//   Mock : an object with expectations about the calls it receives
+//          (MockTurtle via MOCK_METHOD). Tests check the INTERACTION -
+//          "how did it happen?".
+
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+
+#include <utility>
+
+#include "mock/FakeTurtle.h"
+#include "mock/MockTurtle.h"
+#include "mock/Painter.h"
+
+namespace {
+
+using testing::InSequence;
+
+TEST(MockPainterTest, DrawSquareCallsTheTurtleOperations) {
+  MockTurtle turtle;
+  const Painter painter{turtle};
+
+  // Expectations must be set BEFORE the code under test runs.
+  EXPECT_CALL(turtle, PenDown()).Times(1);
+  EXPECT_CALL(turtle, Forward(100)).Times(4);
+  EXPECT_CALL(turtle, Turn(90)).Times(4);
+  EXPECT_CALL(turtle, PenUp()).Times(1);
+
+  painter.DrawSquare(100);
+}  // the mock verifies its expectations when it is destroyed
+
+TEST(MockPainterTest, PenGoesDownBeforeMovingAndUpAtTheEnd) {
+  MockTurtle turtle;
+  const Painter painter{turtle};
+
+  {
+    const InSequence in_order;  // the following expectations must happen in this order
+    EXPECT_CALL(turtle, PenDown());
+    EXPECT_CALL(turtle, Forward(10)).Times(4);
+    EXPECT_CALL(turtle, PenUp());
+  }
+  EXPECT_CALL(turtle, Turn(90)).Times(4);  // not part of the sequence
+
+  painter.DrawSquare(10);
+}
+
+TEST(FakePainterTest, DrawSquareProducesAClosedSquarePath) {
+  FakeTurtle turtle;
+  const Painter painter{turtle};
+
+  painter.DrawSquare(10);
+
+  const auto& path = turtle.Path();
+  ASSERT_EQ(path.size(), 8U);  // 4 lines -> 8 points (start and end of each)
+
+  EXPECT_EQ(path[0], std::make_pair(0, 0));
+  EXPECT_EQ(path[1], std::make_pair(0, 10));
+  EXPECT_EQ(path[3], std::make_pair(10, 10));
+  EXPECT_EQ(path[5], std::make_pair(10, 0));
+  EXPECT_EQ(path[7], std::make_pair(0, 0));  // back at the start
+}
+
+}  // namespace
diff --git a/tests/lab/CommandLineTest.cpp b/tests/lab/CommandLineTest.cpp
new file mode 100644
index 0000000..102c1d3
--- /dev/null
+++ b/tests/lab/CommandLineTest.cpp
@@ -0,0 +1,93 @@
+#include "lab/CommandLine.h"
+
+#include <gtest/gtest.h>
+
+#include <string_view>
+#include <vector>
+
+namespace {
+
+lab::ParseResult parse(std::vector<std::string_view> args) {
+  return lab::parseCommandLine(args);
+}
+
+TEST(CommandLineTest, NoArgumentsStartsTheMenu) {
+  const lab::ParseResult result = parse({});
+  ASSERT_TRUE(result.value.has_value()) << result.error;
+  EXPECT_EQ(result.value->command, lab::Command::kMenu);
+  EXPECT_FALSE(result.value->plain);
+  EXPECT_EQ(result.value->mode, lab::AppMode::kDev);
+}
+
+TEST(CommandLineTest, ListAcceptsAnOptionalFilter) {
+  auto without_filter = parse({"--list"});
+  ASSERT_TRUE(without_filter.value.has_value());
+  EXPECT_EQ(without_filter.value->command, lab::Command::kList);
+  EXPECT_TRUE(without_filter.value->argument.empty());
+
+  auto with_filter = parse({"-l", "pointer"});
+  ASSERT_TRUE(with_filter.value.has_value());
+  EXPECT_EQ(with_filter.value->argument, "pointer");
+}
+
+TEST(CommandLineTest, RunRequiresAnId) {
+  auto result = parse({"--run", "core/smart_pointer/Weak"});
+  ASSERT_TRUE(result.value.has_value());
+  EXPECT_EQ(result.value->command, lab::Command::kRun);
+  EXPECT_EQ(result.value->argument, "core/smart_pointer/Weak");
+
+  EXPECT_FALSE(parse({"--run"}).value.has_value());
+  EXPECT_FALSE(parse({"--run", "--plain"}).value.has_value());  // an option is not an id
+}
+
+TEST(CommandLineTest, SupportsEqualsSyntax) {
+  auto result = parse({"--run=dp/Proxy", "--mode=prod"});
+  ASSERT_TRUE(result.value.has_value()) << result.error;
+  EXPECT_EQ(result.value->argument, "dp/Proxy");
+  EXPECT_EQ(result.value->mode, lab::AppMode::kProd);
+}
+
+TEST(CommandLineTest, OptionsCanBeCombinedWithACommand) {
+  auto result = parse({"--plain", "--run-all", "dp", "--mode", "UAT"});
+  ASSERT_TRUE(result.value.has_value()) << result.error;
+  EXPECT_EQ(result.value->command, lab::Command::kRunAll);
+  EXPECT_EQ(result.value->argument, "dp");
+  EXPECT_TRUE(result.value->plain);
+  EXPECT_EQ(result.value->mode, lab::AppMode::kUat);
+}
+
+TEST(CommandLineTest, RejectsTwoCommands) {
+  const lab::ParseResult result = parse({"--list", "--run-all"});
+  EXPECT_FALSE(result.value.has_value());
+  EXPECT_NE(result.error.find("only one of"), std::string::npos);
+}
+
+TEST(CommandLineTest, RejectsUnknownOptionsAndInvalidModes) {
+  EXPECT_FALSE(parse({"--frobnicate"}).value.has_value());
+  EXPECT_FALSE(parse({"--mode", "staging"}).value.has_value());
+  EXPECT_FALSE(parse({"--mode"}).value.has_value());
+}
+
+TEST(CommandLineTest, LegacySingleDashModeStillWorks) {
+  auto result = parse({"-mode", "Prod"});
+  ASSERT_TRUE(result.value.has_value());
+  EXPECT_EQ(result.value->mode, lab::AppMode::kProd);
+}
+
+TEST(AppModeTest, RoundTripsThroughStrings) {
+  for (const lab::AppMode mode : {lab::AppMode::kDev, lab::AppMode::kUat, lab::AppMode::kProd}) {
+    const auto parsed = lab::parseAppMode(lab::toString(mode));
+    ASSERT_TRUE(parsed.has_value());
+    EXPECT_EQ(*parsed, mode);
+  }
+}
+
+TEST(UsageTest, MentionsEveryCommand) {
+  const std::string text = lab::usage("cpp_lab_project");
+  for (const char* option : {"--list", "--run", "--run-all", "--list-ids", "--plain", "--mode",
+                             "--version", "--help"}) {
+    EXPECT_NE(text.find(option), std::string::npos) << option;
+  }
+}
+
+}  // namespace
diff --git a/tests/lab/MenuRunnerTest.cpp b/tests/lab/MenuRunnerTest.cpp
new file mode 100644
index 0000000..622ba4b
--- /dev/null
+++ b/tests/lab/MenuRunnerTest.cpp
@@ -0,0 +1,108 @@
+#include <gtest/gtest.h>
+
+#include <sstream>
+#include <stdexcept>
+#include <string>
+
+#include "lab/Menu.h"
+#include "lab/Registry.h"
+#include "lab/Runner.h"
+
+namespace {
+
+int g_first_runs = 0;
+int g_second_runs = 0;
+int g_interactive_runs = 0;
+
+void first() {
+  ++g_first_runs;
+}
+void second() {
+  ++g_second_runs;
+}
+void interactive() {
+  ++g_interactive_runs;
+}
+void throws() {
+  throw std::runtime_error("boom");
+}
+
+class MenuRunnerTest : public testing::Test {
+ protected:
+  void SetUp() override {
+    g_first_runs = 0;
+    g_second_runs = 0;
+    g_interactive_runs = 0;
+    registry.add("/x/src/topic/basics/A.cpp", "First", "first example", first);
+    registry.add("/x/src/topic/advanced/B.cpp", "Second", "second example", second);
+    registry.add("/x/src/topic/advanced/C.cpp", "Server", "needs a client", interactive,
+                 lab::kInteractive);
+  }
+
+  lab::Registry registry;
+  std::ostringstream out;
+};
+
+TEST_F(MenuRunnerTest, RunExampleReportsSuccess) {
+  EXPECT_TRUE(lab::runExample(registry.examples().front(), out));
+  EXPECT_NE(out.str().find("finished"), std::string::npos);
+}
+
+TEST_F(MenuRunnerTest, RunExampleCatchesExceptions) {
+  lab::Registry failing;
+  failing.add("/x/src/topic/Bad.cpp", "Bad", "throws", throws);
+  EXPECT_FALSE(lab::runExample(failing.examples().front(), out));
+  EXPECT_NE(out.str().find("boom"), std::string::npos);
+  EXPECT_NE(out.str().find("FAILED"), std::string::npos);
+}
+
+TEST_F(MenuRunnerTest, RunAllSkipsInteractiveExamples) {
+  EXPECT_EQ(lab::runAll(registry, "", out), 0);
+  EXPECT_EQ(g_first_runs, 1);
+  EXPECT_EQ(g_second_runs, 1);
+  EXPECT_EQ(g_interactive_runs, 0);
+  EXPECT_NE(out.str().find("skipped 1 interactive"), std::string::npos);
+}
+
+TEST_F(MenuRunnerTest, RunAllHonorsTheFilter) {
+  EXPECT_EQ(lab::runAll(registry, "basics", out), 0);
+  EXPECT_EQ(g_first_runs, 1);
+  EXPECT_EQ(g_second_runs, 0);
+}
+
+TEST_F(MenuRunnerTest, MenuShowsFoldersAndQuits) {
+  std::istringstream in("q\n");
+  lab::runMenu(registry, in, out);
+  const std::string text = out.str();
+  EXPECT_NE(text.find("topic/"), std::string::npos);
+  EXPECT_NE(text.find("3 examples"), std::string::npos);
+}
+
+TEST_F(MenuRunnerTest, MenuNavigatesFoldersAndRunsAnExample) {
+  // root -> 1 (topic/) -> 2 (basics/, folders are sorted: advanced, basics)
+  //      -> 1 (First) -> Enter to continue -> quit
+  std::istringstream in("1\n2\n1\n\nq\n");
+  lab::runMenu(registry, in, out);
+  EXPECT_EQ(g_first_runs, 1);
+  EXPECT_EQ(g_second_runs, 0);
+}
+
+TEST_F(MenuRunnerTest, MenuSearchRunsTheChosenMatch) {
+  std::istringstream in("second\n1\n\nq\n");
+  lab::runMenu(registry, in, out);
+  EXPECT_EQ(g_second_runs, 1);
+}
+
+TEST_F(MenuRunnerTest, MenuEndsWhenInputEnds) {
+  std::istringstream in("1\n");  // no quit command: EOF must not loop forever
+  lab::runMenu(registry, in, out);
+  SUCCEED();
+}
+
+TEST_F(MenuRunnerTest, BackFromTheTopFolderQuits) {
+  std::istringstream in("0\n");
+  lab::runMenu(registry, in, out);
+  EXPECT_EQ(g_first_runs + g_second_runs, 0);
+}
+
+}  // namespace
diff --git a/tests/lab/RegistryTest.cpp b/tests/lab/RegistryTest.cpp
new file mode 100644
index 0000000..5aa18b8
--- /dev/null
+++ b/tests/lab/RegistryTest.cpp
@@ -0,0 +1,129 @@
+#include "lab/Registry.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <string>
+#include <vector>
+
+namespace {
+
+void noop() {}
+
+std::vector<std::string> ids(const std::vector<const lab::Example*>& examples) {
+  std::vector<std::string> result;
+  for (const lab::Example* example : examples) {
+    result.push_back(example->id);
+  }
+  return result;
+}
+
+TEST(RelativeSourcePathTest, StripsTheSourceRoot) {
+  EXPECT_EQ(lab::detail::relativeSourcePath("/repo/src/core/Weak.cpp", "/repo"),
+            "src/core/Weak.cpp");
+  EXPECT_EQ(lab::detail::relativeSourcePath("/repo/src/core/Weak.cpp", "/repo/"),
+            "src/core/Weak.cpp");
+}
+
+TEST(RelativeSourcePathTest, FallsBackToTheLastSrcDirectory) {
+  EXPECT_EQ(lab::detail::relativeSourcePath("/elsewhere/src/dp/Proxy.cpp", "/repo"),
+            "src/dp/Proxy.cpp");
+  EXPECT_EQ(lab::detail::relativeSourcePath("src/dp/Proxy.cpp", ""), "src/dp/Proxy.cpp");
+}
+
+TEST(RelativeSourcePathTest, NormalizesBackslashes) {
+  EXPECT_EQ(lab::detail::relativeSourcePath(R"(C:\repo\src\core\Weak.cpp)", R"(C:\repo)"),
+            "src/core/Weak.cpp");
+}
+
+TEST(GroupFromSourcePathTest, UsesTheDirectoryBelowSrc) {
+  EXPECT_EQ(lab::detail::groupFromSourcePath("src/core/smart_pointer/Weak.cpp"),
+            "core/smart_pointer");
+  EXPECT_EQ(lab::detail::groupFromSourcePath("src/dp/Proxy.cpp"), "dp");
+  EXPECT_EQ(lab::detail::groupFromSourcePath("tests/lab/RegistryTest.cpp"), "tests/lab");
+}
+
+TEST(GroupFromSourcePathTest, FilesWithoutADirectoryGoToMisc) {
+  EXPECT_EQ(lab::detail::groupFromSourcePath("src/main.cpp"), "misc");
+  EXPECT_EQ(lab::detail::groupFromSourcePath("main.cpp"), "misc");
+}
+
+class RegistryTest : public testing::Test {
+ protected:
+  lab::Registry registry;  // a fresh registry per test, not the global one
+};
+
+TEST_F(RegistryTest, BuildsIdGroupAndSourceFromTheFilePath) {
+  ASSERT_TRUE(registry.add("/x/src/core/smart_pointer/Weak.cpp", "Weak", "weak_ptr", noop));
+
+  ASSERT_EQ(registry.examples().size(), 1U);
+  const lab::Example& example = registry.examples().front();
+  EXPECT_EQ(example.id, "core/smart_pointer/Weak");
+  EXPECT_EQ(example.group, "core/smart_pointer");
+  EXPECT_EQ(example.name, "Weak");
+  EXPECT_EQ(example.description, "weak_ptr");
+  EXPECT_EQ(example.source, "src/core/smart_pointer/Weak.cpp");
+  EXPECT_FALSE(example.isInteractive());
+  EXPECT_TRUE(registry.errors().empty());
+}
+
+TEST_F(RegistryTest, KeepsExamplesSortedCaseInsensitively) {
+  registry.add("/x/src/b/File.cpp", "zeta", "", noop);
+  registry.add("/x/src/a/File.cpp", "Beta", "", noop);
+  registry.add("/x/src/a/File.cpp", "alpha", "", noop);
+
+  std::vector<std::string> order;
+  for (const lab::Example& example : registry.examples()) {
+    order.push_back(example.id);
+  }
+  EXPECT_EQ(order, (std::vector<std::string>{"a/alpha", "a/Beta", "b/zeta"}));
+}
+
+TEST_F(RegistryTest, RejectsDuplicateIdsIgnoringCase) {
+  EXPECT_TRUE(registry.add("/x/src/core/One.cpp", "Same", "", noop));
+  EXPECT_FALSE(registry.add("/x/src/core/Two.cpp", "same", "", noop));
+
+  EXPECT_EQ(registry.examples().size(), 1U);
+  ASSERT_EQ(registry.errors().size(), 1U);
+  EXPECT_NE(registry.errors().front().find("duplicate"), std::string::npos);
+}
+
+TEST_F(RegistryTest, RejectsInvalidNamesAndMissingFunctions) {
+  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "", "", noop));
+  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "has space", "", noop));
+  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "has/slash", "", noop));
+  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "NoFunction", "", nullptr));
+
+  EXPECT_TRUE(registry.examples().empty());
+  EXPECT_EQ(registry.errors().size(), 4U);
+}
+
+TEST_F(RegistryTest, StoresFlags) {
+  registry.add("/x/src/socket/Server.cpp", "Server", "", noop, lab::kInteractive);
+  EXPECT_TRUE(registry.examples().front().isInteractive());
+}
+
+TEST_F(RegistryTest, FindPrefersExactMatches) {
+  registry.add("/x/src/core/A.cpp", "Weak", "", noop);
+  registry.add("/x/src/other/A.cpp", "weak", "", noop);
+
+  ASSERT_NE(registry.find("core/Weak"), nullptr);
+  EXPECT_EQ(registry.find("core/Weak")->id, "core/Weak");
+  ASSERT_NE(registry.find("CORE/WEAK"), nullptr);  // case-insensitive fallback
+  EXPECT_EQ(registry.find("CORE/WEAK")->id, "core/Weak");
+  EXPECT_EQ(registry.find("core/Strong"), nullptr);
+}
+
+TEST_F(RegistryTest, MatchSearchesIdsAndDescriptions) {
+  registry.add("/x/src/core/smart_pointer/A.cpp", "Weak", "observe without owning", noop);
+  registry.add("/x/src/core/smart_pointer/B.cpp", "Unique", "exclusive ownership", noop);
+  registry.add("/x/src/dp/C.cpp", "Proxy", "a stand-in object", noop);
+
+  EXPECT_EQ(registry.match("").size(), 3U);
+  EXPECT_EQ(ids(registry.match("SMART_POINTER")),
+            (std::vector<std::string>{"core/smart_pointer/Unique", "core/smart_pointer/Weak"}));
+  EXPECT_EQ(ids(registry.match("owning")), (std::vector<std::string>{"core/smart_pointer/Weak"}));
+  EXPECT_TRUE(registry.match("nothing matches this").empty());
+}
+
+}  // namespace
diff --git a/tests/mock/MockTurtle.h b/tests/mock/MockTurtle.h
index 707979a..1386d38 100644
--- a/tests/mock/MockTurtle.h
+++ b/tests/mock/MockTurtle.h
@@ -1,13 +1,18 @@
-#include "Turtle.h" // mock test for this class
+#pragma once
+
 #include <gmock/gmock.h>  // Brings in gMock.
 
+#include "Turtle.h"  // the interface being mocked
+
 class MockTurtle : public Turtle {
  public:
-  MOCK_METHOD(void, PenUp, (), (override)); // the MOCK_METHOD macro will generate the definitions for APIs
+  // MOCK_METHOD(return type, name, (parameters), (qualifiers)) generates the
+  // implementation that records calls and checks expectations.
+  MOCK_METHOD(void, PenUp, (), (override));
   MOCK_METHOD(void, PenDown, (), (override));
   MOCK_METHOD(void, Forward, (int distance), (override));
   MOCK_METHOD(void, Turn, (int degrees), (override));
   MOCK_METHOD(void, GoTo, (int x, int y), (override));
   MOCK_METHOD(int, GetX, (), (const, override));
   MOCK_METHOD(int, GetY, (), (const, override));
-};
\ No newline at end of file
+};
diff --git a/tests/mock/Painter.h b/tests/mock/Painter.h
index 96e44d4..04e87e0 100644
--- a/tests/mock/Painter.h
+++ b/tests/mock/Painter.h
@@ -1,11 +1,14 @@
 #pragma once
+
 #include "Turtle.h"
 
+/// Code under test: depends only on the Turtle interface, so tests can pass a
+/// mock or a fake instead of a real drawing turtle.
 class Painter {
-public:
+ public:
   explicit Painter(Turtle& turtle) : turtle_(turtle) {}
 
-  void DrawSquare(int size) {
+  void DrawSquare(int size) const {
     turtle_.PenDown();
     for (int i = 0; i < 4; ++i) {
       turtle_.Forward(size);
@@ -14,6 +17,6 @@ class Painter {
     turtle_.PenUp();
   }
 
-private:
+ private:
   Turtle& turtle_;
 };
diff --git a/tests/mock/Turtle.h b/tests/mock/Turtle.h
index cf5f345..88b371d 100644
--- a/tests/mock/Turtle.h
+++ b/tests/mock/Turtle.h
@@ -1,8 +1,9 @@
 #pragma once
 
+/// Interface of a drawing turtle (the example from the gMock for Dummies guide).
 class Turtle {
  public:
-  virtual ~Turtle() {}
+  virtual ~Turtle() = default;
   virtual void PenUp() = 0;
   virtual void PenDown() = 0;
   virtual void Forward(int distance) = 0;
@@ -10,4 +11,4 @@ class Turtle {
   virtual void GoTo(int x, int y) = 0;
   virtual int GetX() const = 0;
   virtual int GetY() const = 0;
-};
\ No newline at end of file
+};

From 5e336eef634d2e36d5c75e1fb7dd72cf9bba7390 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:26:05 +0700
Subject: [PATCH 09/20] Update documentation, scripts and CI for the new
 structure

- README: quick start, menu and command line, how to add an example, build
  options, testing (including sanitizers and valgrind), static analysis,
  coverage, the standalone programs, VS Code debugging, Docker and
  troubleshooting.
- docs/adding-examples.md: the anatomy of an example, LAB_EXAMPLE, logging,
  conventions (anonymous namespaces, no undefined behavior, temp files) and
  how to add a new module.
- docs/README.md now indexes every topic; new READMEs for basics, datatype,
  function, linkage, smart_pointer, string, exception, concurrency and
  controller, and example tables in the existing ones.
- CLAUDE.md describes the framework, the house rules for examples and the
  traps found while working here (cppcheck needs -I include, .clang-format
  must stay on c++20 or it mangles digit separators).
- scripts/new_example.sh scaffolds an example from a template; run.sh also
  runs the tests; the coverage scripts use ENABLE_COVERAGE and their own
  build directory.
- CI runs cppcheck with the shared suppression list and adds a second job
  that builds with sanitizers and runs the whole suite again.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 .github/workflows/cpp-build-test-coverage.yml |  63 ++-
 CLAUDE.md                                     | 118 +++--
 README.md                                     | 489 +++++++++---------
 docs/README.md                                |  43 +-
 docs/adding-examples.md                       | 145 ++++++
 scripts/gen_coverage_gcovr.sh                 |  24 +-
 scripts/gen_coverage_lcov.sh                  |  26 +-
 scripts/new_example.sh                        |  87 ++++
 scripts/run.sh                                |  52 +-
 9 files changed, 675 insertions(+), 372 deletions(-)
 create mode 100644 docs/adding-examples.md
 create mode 100755 scripts/new_example.sh

diff --git a/.github/workflows/cpp-build-test-coverage.yml b/.github/workflows/cpp-build-test-coverage.yml
index c9f71c5..6ce4a66 100644
--- a/.github/workflows/cpp-build-test-coverage.yml
+++ b/.github/workflows/cpp-build-test-coverage.yml
@@ -3,7 +3,9 @@
 # -------------------------------------------------------------
 # Purpose:
 # Runs cppcheck (static analysis), builds your C++ project,
-# runs unit tests, and generates a coverage report.
+# runs the unit tests and one smoke test per example,
+# generates a coverage report, and repeats the tests with
+# AddressSanitizer + UndefinedBehaviorSanitizer.
 # -------------------------------------------------------------
 
 name: C++ Tests and Coverage
@@ -45,7 +47,7 @@ jobs:
       # -------------------------------------------------------
       # Step 2: Run Cppcheck (Static Analysis)
       # - Scans for common C++ issues (style, memory, logic)
-      # - You can adjust `--enable=` options as needed
+      # - -I include lets cppcheck understand the LAB_EXAMPLE macro
       # - https://cppcheck.sourceforge.io/manual.pdf
       # -------------------------------------------------------
       - name: Run static analysis with Cppcheck
@@ -56,26 +58,23 @@ jobs:
                    --quiet \
                    --inline-suppr \
                    --error-exitcode=1 \
+                   -I include \
+                   --suppressions-list=.cppcheck-suppressions \
                    ./src ./include
-    
+
       # -------------------------------------------------------
       # Step 3: Configure and build the project
       # -------------------------------------------------------
-      - name: Prepare build
+      - name: Build
         run: |
-          rm -rf build
-          mkdir build
-          cd build
-          cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON ..
-          cmake --build .
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
+          cmake --build build -j "$(nproc)"
 
       # -------------------------------------------------------
-      # Step 4: Run unit tests
+      # Step 4: Run unit tests and example smoke tests
       # -------------------------------------------------------
       - name: Run tests
-        run: |
-          cd build
-          ctest --output-on-failure
+        run: ctest --test-dir build --output-on-failure -j "$(nproc)"
 
       # -------------------------------------------------------
       # Step 5: Generate code coverage report
@@ -97,20 +96,30 @@ jobs:
           lcov --summary coverageFiltered.info >> $GITHUB_STEP_SUMMARY
 
       # # -------------------------------------------------------
-      # # Step 7: Run Clang-Tidy (experimenting , not exit)
-      # # - Modern C++ static analysis
-      # # - Enforces best practices
-      # # - Add `--warnings-as-errors=*` to exit code 1
+      # # Step 7: Run Clang-Tidy (experimenting, not enforced)
+      # # - Modern C++ static analysis, configured by .clang-tidy
       # # -------------------------------------------------------
       # - name: Run clang-tidy
-      #   # run: |
-      #   #   echo "Running clang-tidy..."
-      #   #   clang-tidy \
-      #   #     -checks='clang-analyzer-*,modernize-*,performance-*,readability-*' \
-      #   #     -p build \
-      #   #     $(find ./src -name '*.cpp')
       #   run: |
-      #       echo "Running clang-tidy using .clang-tidy options"
-      #       clang-tidy \
-      #         -p build \
-      #         -header-filter='^src/.*' $(find src -name "*.cpp")
\ No newline at end of file
+      #       clang-tidy -p build -header-filter='^src/.*' $(find src -name "*.cpp")
+
+  sanitizers:
+    # ---------------------------------------------------------
+    # Same tests with AddressSanitizer + UndefinedBehaviorSanitizer:
+    # memory errors, leaks and undefined behavior fail the job.
+    # ---------------------------------------------------------
+    runs-on: ubuntu-24.04
+    container:
+      image: urboob21/cpp-lab:latest
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Build with sanitizers
+        run: |
+          cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Debug -DCPPLAB_ENABLE_SANITIZERS=ON -DCPPLAB_BUILD_GUI=OFF
+          cmake --build build-asan -j "$(nproc)"
+
+      - name: Run tests with sanitizers
+        run: ctest --test-dir build-asan --output-on-failure -j "$(nproc)"
diff --git a/CLAUDE.md b/CLAUDE.md
index 9b3022b..83d2bd3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,64 +4,108 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this repo is
 
-A C++20 learning lab: many small, self-contained examples (language features, STL, concurrency, design patterns, sockets, a PID controller) compiled into one interactive menu-driven executable, plus a few standalone executables (GTK4 MVC/MVVM apps, a `dlopen` demo) and a bare-metal ARM example that sits outside CMake.
+A C++20 learning lab: ~100 small, self-contained examples (language features, STL, concurrency,
+design patterns, sockets, a PID controller) compiled into one menu-driven executable, plus
+standalone programs (GTK4 MVC/MVVM apps, a `dlopen` plugin demo) and a bare-metal ARM example that
+is built outside CMake.
 
-## Build & run
+## Build, run, test
 
 ```bash
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug   # configure
-cmake --build build                            # build all targets
-./build/bin/cpp_lab_project                    # interactive examples menu (optional: -mode Dev|Uat|Prod)
-./scripts/run.sh                               # build + cppcheck + run (needs private/genid.py, which is gitignored)
+cmake -S . -B build                 # Debug by default
+cmake --build build -j
+./build/bin/cpp_lab_project         # interactive menu
+ctest --test-dir build -j --output-on-failure
+./scripts/run.sh                    # build + cppcheck + tests + menu
 ```
 
-- Configuring needs **gtkmm-4.0** (`libgtkmm-4.0-dev`). `cmake/Dependencies.cmake` marks it `REQUIRED`, so configure fails without it, even if you only want the main executable. GoogleTest is fetched over the network with FetchContent on the first configure.
-- Executables go to `build/bin/` and shared libs to `build/lib/`. VS Code tasks/launch use `build/debug` instead.
-- Other targets: `ap`, `mvc_ap`, `mvvm_ap` (GTK4 GUIs in `src/ap/`) and `demo_dlopen` (loads `libsample_app.so` at runtime; see `src/demo/dlopen/README.md` for why `bridge` must stay SHARED).
-- `src/embedded/` is not part of CMake. Build and boot it in QEMU with `cd src/embedded && ./run.sh [gui|debug]` (requires `gcc-arm-none-eabi` and `qemu-system-arm`).
+Command line of the app: `--list [filter]`, `--run <id|filter>`, `--run-all [filter]`,
+`--list-ids`, `--plain` (no log prefixes/colors), `--mode dev|uat|prod`, `--version`, `--help`.
+Example ids look like `core/smart_pointer/Weak`.
 
-## Tests
+CMake options: `CPPLAB_BUILD_TESTS` (ON), `CPPLAB_BUILD_DEMOS` (ON), `CPPLAB_BUILD_GUI`
+(AUTO/ON/OFF - gtkmm-4.0 is optional), `CPPLAB_ENABLE_SANITIZERS` (OFF, ASan+UBSan),
+`CPPLAB_WARNINGS_AS_ERRORS` (OFF), `ENABLE_COVERAGE` (OFF).
 
-GoogleTest/GMock tests live in `tests/` (the target is `cpp_lab_project_unit_test`; mocks and fakes are in `tests/mock/`). **`add_subdirectory(tests)` is currently commented out in the top-level `CMakeLists.txt`**, so uncomment it before building or running tests.
+Tests: `-L unit` are the GoogleTest tests in `tests/`, `-L example` are auto-generated smoke tests
+that run every non-interactive example once (`example:<id>`). Both must stay green, also in a
+sanitizer build.
 
-```bash
-ctest --test-dir build --output-on-failure             # all tests
-ctest --test-dir build -R 'DivTest'                    # subset (tests registered via gtest_discover_tests)
-./build/bin/cpp_lab_project_unit_test --gtest_filter='DivTest.InvalidNumbers'
-./scripts/gen_coverage_lcov.sh                         # or gen_coverage_gcovr.sh; CI uses -DENABLE_COVERAGE=ON
-```
+## Architecture: the lab framework
 
-The test target compiles only the sources listed in `tests/CMakeLists.txt` (currently `src/DeleteMe.cpp`). Add any source under test to that list.
+`include/lab/` + `src/lab/` are a small framework; everything else is examples.
 
-## Static analysis & formatting
+- `LAB_EXAMPLE("Name", "description" [, lab::kInteractive]) { ... }` (lab/Example.h) declares a
+  file-local function and registers it in `lab::Registry` from a static initializer.
+- The **menu group comes from the file path**: `src/core/smart_pointer/Weak.cpp` becomes the id
+  `core/smart_pointer/Weak`. `CPPLAB_SOURCE_DIR` (a compile definition) turns `__FILE__` into a
+  repository-relative path.
+- `lab::Registry` keeps examples sorted, rejects duplicate ids and invalid names; `main.cpp`
+  reports registry errors and exits non-zero.
+- `lab::runMenu` (Menu.cpp) builds a folder tree from the ids: numbers navigate, `0` goes back,
+  text searches, `q` quits. `lab::runExample` / `lab::runAll` (Runner.cpp) print the banner, catch
+  exceptions and restore `std::cout` formatting.
+- Logging: `LOG("text")`, `LOG_S("x = " << x)`, `LOG_FUNC()` (current function signature),
+  `LOG_SECTION("Title")`. Debug builds prefix `[time][file:line][function]`; Release and `--plain`
+  print the bare message.
+- `lab/version.h` is generated from `include/lab/version.h.in`.
 
-CI (`.github/workflows/cpp-build-test-coverage.yml`, on push/PR to `master`, inside the `urboob21/cpp-lab:latest` Docker image) fails on cppcheck findings:
+## Adding an example
 
 ```bash
-cppcheck --enable=warning,style,performance,portability --inconclusive --inline-suppr --quiet --error-exitcode=1 ./src ./include
-clang-tidy -p build -header-filter='^src/.*' $(find src -name "*.cpp")   # not enforced in CI
-clang-format -i <file>                                                     # Google-based style (.clang-format)
+./scripts/new_example.sh core/utils Span "std::span: a view over contiguous memory"
 ```
 
-The `.clang-tidy` naming rules are lower_case variables and namespaces, CamelCase types, and a trailing `_` on class members. Code also uses `kName` for constants and enumerators.
+No CMake change is needed: `cpplab_add_example_module()` globs each module folder with
+`CONFIGURE_DEPENDS`, and the ctest smoke test is discovered from `--list-ids` at test time. A new
+top-level module needs one line in `src/CMakeLists.txt`. Full conventions:
+`docs/adding-examples.md`.
+
+House rules for example code (see also `docs/adding-examples.md`):
+
+- Put helpers in an anonymous namespace; all examples link into one binary, so global names would
+  clash (ODR).
+- Header comment: what it teaches, key points/pitfalls, a cppreference link.
+- Split into small functions, each starting with `LOG_SECTION`.
+- Never execute undefined behavior; describe it instead. The smoke tests run under ASan/UBSan.
+- Write files only under `std::filesystem::temp_directory_path()` and delete them; restore global
+  state (e.g. `std::set_terminate`).
+- Keep examples fast and non-interactive; mark the ones that need a user or a peer with
+  `lab::kInteractive`.
 
-## Architecture: the example registry
+## Static analysis and formatting
+
+```bash
+cppcheck --enable=warning,style,performance,portability --inconclusive --inline-suppr --quiet \
+  --error-exitcode=1 -I include --suppressions-list=.cppcheck-suppressions ./src ./include
+git ls-files '*.cpp' '*.h' | xargs clang-format -i
+clang-tidy -p build $(git ls-files 'src/*.cpp')     # configured by .clang-tidy, not enforced in CI
+```
 
-The main executable is a plugin-style registry that fills itself during static initialization:
+- `-I include` is required, otherwise cppcheck cannot expand `LAB_EXAMPLE` and reports syntax
+  errors. Intentional findings (teaching demos) are listed in `.cppcheck-suppressions`; note that a
+  line containing only `#` breaks that file.
+- `.clang-format` is Google-based with `Standard: c++20`. Do not set it back to `c++11`: the
+  formatter then mangles digit separators such as `1'000'000`.
+- Naming (`.clang-tidy`): `lower_case` variables and namespaces, `CamelCase` types, trailing `_` on
+  private members, `kName` for constants.
 
-- `include/IExample.h` is the interface. It has `group()`, `name()`, `description()`, and `execute()`.
-- `include/ExampleRegistry.h` is a singleton map `group -> name -> factory`. The `REGISTER_EXAMPLE(Class)` macro at the bottom of each example `.cpp` defines a static registrar object that registers the class before `main` runs.
-- `src/main.cpp` only renders the menu from the registry. Groups are shown sorted, but examples inside a group follow `unordered_map` order, so menu numbers are unstable and piping choices into stdin is unreliable.
+## CI
 
-**Adding an example:**
-1. Create a `.cpp` that puts its code in an anonymous namespace (often `namespace { namespace problem {...} namespace some_pattern {...} }`, each with its own `run()`).
-2. Define an `IExample` subclass and call `REGISTER_EXAMPLE(ThatClass);`.
-3. **Add the file to the module's source list** (`CORE_SOURCES`, `DP_SOURCES`, `SOCKET_SOURCES`, or `CONTROLLER_SOURCES` in `src/<module>/CMakeLists.txt`). There is no globbing, and a file missing from the list simply never shows up in the menu, with no error.
+`.github/workflows/cpp-build-test-coverage.yml` runs on push/PR to `master` inside
+`urboob21/cpp-lab:latest`: cppcheck, build with coverage, `ctest`, lcov summary, plus a second job
+that builds with `CPPLAB_ENABLE_SANITIZERS=ON` and runs the tests again.
 
-Every module's sources link into the same `cpp_lab_project` binary. Keep helpers in anonymous namespaces and give the registered example class a unique name, because many files share names like `Array.cpp` and define their own `run()`. The `group()` string sets the menu category and doesn't always match the directory (for example, `function/operator_overloading/*` registers as `core/overloading_operator`).
+## Other programs
 
-Use `LOG(msg)` / `LOG_S(a << b)` from `include/Logger.h` for output. Debug builds add a timestamp, file:line, and function; `NDEBUG` builds print plain lines. `version.h` is generated into `build/generated/` from `include/version.h.in`.
+- `src/ap/` GTK4 apps (`ap`, `mvc_ap`, `mvvm_ap`), built only when gtkmm-4.0 is found.
+- `src/demo/dlopen/` host + plugin; the plugin path is compiled in via `SAMPLE_APP_PATH`, and
+  `bridge` must stay a SHARED library (see its README).
+- `src/embedded/` bare-metal ARM firmware: `cd src/embedded && ./run.sh [gui|debug]`
+  (needs `gcc-arm-none-eabi` and `qemu-system-arm`).
 
 ## Docs
 
-`docs/README.md` indexes the per-module READMEs (`src/**/README.md`), which explain each topic and embed the draw.io UML diagrams from `docs/uml/`. When you add a design pattern example, update the matching README (and diagram if one exists).
+`docs/README.md` indexes the per-folder READMEs (`src/**/README.md`), which explain each topic and
+embed the draw.io UML diagrams in `docs/uml/`. When adding or renaming an example, update the
+README of its folder.
diff --git a/README.md b/README.md
index c219b1b..05ef958 100644
--- a/README.md
+++ b/README.md
@@ -1,271 +1,270 @@
-## 1. Overview
-**TL;DR**
+# cpp-lab
+
+A C/C++ learning lab: ~100 small, runnable examples of modern C++ (C++20), design patterns,
+concurrency, sockets and embedded basics - built with CMake, GoogleTest, cppcheck and lcov, with
+Docker and GitHub Actions for CI/CD.
+
+Every example lives in one file, explains itself in a header comment, and can be run on its own.
+
+---
+## 1. Quick start
+
+```bash
+./scripts/run.sh          # build + static analysis + tests + interactive menu
+```
+
+or step by step:
+
 ```bash
-./scripts/run.sh
+cmake -S . -B build
+cmake --build build -j
+./build/bin/cpp_lab_project           # interactive menu
+./build/bin/cpp_lab_project --help    # command line
 ```
 
-**Project Hierarchy**
+**Project hierarchy**
 ```
-includes/   -> Header files (.h, .hpp)  
-src/        -> Source files (.cpp)  
-tests/      -> GoogleTest test cases
-docs/       -> Documents
+include/lab/   framework API: LAB_EXAMPLE, LOG..., registry, menu, runner
+src/
+  lab/         framework implementation
+  main.cpp     entry point: command line and menu
+  core/        C++ language and standard library examples
+  dp/          design patterns (behavioral, creational, structural)
+  controller/  control algorithms (PID)
+  socket/      POSIX TCP sockets
+  ap/          architecture patterns (MVC, MVVM) as GTK4 apps
+  demo/        standalone demos (dlopen plugin)
+  embedded/    bare-metal ARM example (own build script)
+tests/         GoogleTest unit tests and a gtest/gmock primer
+cmake/         CMake modules and helpers
+docs/          documentation and UML diagrams
+scripts/       build, coverage and scaffolding scripts
 ```
 
 ---
-## 2. Dependencies
-Make sure the following tools are installed before building the project:
-- **g++ / gcc**
-- **CMake**
-- **Git**
-- **lcov** (for code coverage)
-- **cppcheck** (for static analysis)
-- **Optional:** Install `clang-format` to format C++ code.
-
-
-> Apply clang-format recursively to .cpp, .h, .hpp files
-    **Linux**
-    ```bash
-    sudo apt install clang-format
-    find . -regex '.*\.\(cpp\|h\|hpp\)' -exec clang-format -i {} \;
-    ```
-    **Windows**
-    ```bash
-    Get-ChildItem -Recurse -Include *.cpp, *.h, *.hpp | ForEach-Object { clang-format -i $_.FullName }
-    ```
+## 2. Using the lab
+
+### 2.1. Interactive menu
+
+The menu mirrors the folders below `src/`:
+
+```
+------------------------------------------------------------------------
+ cpp-lab / core / smart_pointer   (3 examples)
+------------------------------------------------------------------------
+   1. Shared                      std::shared_ptr: reference counting, ...
+   2. Unique                      std::unique_ptr: ownership, moves, ...
+   3. Weak                        std::weak_ptr: lock/expired, ...
+------------------------------------------------------------------------
+ <number> open    0 back    <text> search    ? help    q quit
+```
+
+Type a number to open a folder or run an example, `0` to go back, `q` to quit, or any text to
+search ids and descriptions.
+
+### 2.2. Command line
+
+```bash
+./build/bin/cpp_lab_project --list                        # every example
+./build/bin/cpp_lab_project --list pointer                # filter id or description
+./build/bin/cpp_lab_project --run core/smart_pointer/Weak # run one example by id
+./build/bin/cpp_lab_project --run weak                    # a filter matching exactly one
+./build/bin/cpp_lab_project --run-all dp/behavioral       # all examples in a folder
+./build/bin/cpp_lab_project --plain --run-all             # no log prefixes, no colors
+```
+
+Debug builds prefix every log line with `[time][file:line][function]` so you can see where output
+comes from. Release builds (`-DCMAKE_BUILD_TYPE=Release`) and `--plain` print only the message.
+
+### 2.3. Interactive examples
+
+Examples marked `[interactive]` need a human or a second process and are skipped by `--run-all`
+and by the tests. For instance, run `socket/simple_tcp/SimpleTCPServer`, then in another terminal:
+
+```bash
+telnet localhost 8080     # or: nc localhost 8080, or run socket/simple_tcp/SimpleTCPClient
+```
+
+Type lines to have them echoed, `Q` to disconnect, `SHUTDOWN` to stop the server.
+`socket/simple_tcp/LoopbackEcho` shows the same client/server exchange inside one process.
+
 ---
-## 3. Setup Environment
-### 3.1. Dev
-- **Ubuntu system**
-    * Install `gcc`, `cmake`, `git`, and `pthread` (Skip this step if you already install)
-        ```bash
-        $ sudo apt-get update
-        $ sudo apt-get install g++
-        $ sudo apt-get install lcov
-        $ sudo apt-get install cmake
-        $ sudo apt-get install git
-        $ sudo apt install valgrind
-        $ sudo apt-get install cppcheck
-        $ sudo apt-get install -y clang-tidy
-        $ sudo apt install python3-gcovr
-        $ sudo apt-get install -y libgtkmm-4.0-dev
-        ```
-    * Build the application and the tests
-        ```bash
-        $ cd build
-        $ cmake ..
-        $ cmake --build .
-        ```
-    * Run the application and the test
-        ```bash
-        $ ./bin/cpp_lab_project
-        $ ./bin/cpp_lab_project_test
-        ```
-    * Detect Memory Leak Using [valgrind](https://valgrind.org/)
-        ```bash
-        $ valgrind --leak-check=full -v ./cpp-lab 
-        ```
-    * (Optional) Run static analysis - cppcheck
-        ```bash
-        $ cppcheck "folder" / "file"
-        ```
-    * (Optional) Run static analysis - clang-tidy
-        ```bash
-        $ clang-tidy -p build -header-filter='^src/.*' $(find src -name "*.cpp")
-        ```
-    * (Optional) Run coverage - lcov
-        ```bash
-        $ ./scripts/gen_coverage_lcov.sh
-        ```
-- **Docker**
-    * Update `Dockerfile`
-    * Build the Docker image
-        ```
-        $ cd build
-        $ docker build --tag cpp-lab .
-        ```
-    * Run an interactive container
-        ```
-        $ docker run -it cpp-lab:latest /bin/bash
-        ```
-    * Inspect the environment
-        ```
-        $ printenv
-        ```
-    * *Notes:*
-        * Use the `-t` or `--tag` flag to set the name of the image to be created. (the full name is actually `cpp-lab:latest`, since latest is the default tag)
-        * Opening an interactive shell inside your Docker container to explore, test, or debug the environment built from your image.
-        * docker run to start a new container.
-        * `-it`: run it interactively:
-        * `-i`: keep STDIN open (so you can type commands)
-        * `-t`: allocate a terminal (TTY)
-        * `cpp-lab:latest`: the image you built earlier.
-        * `/bin/bash`: the command to execute inside the container (opens a Bash shell).
-
-### 3.2 Debug - C/C++ Debugging (VS Code)
-
-#### 3.2.1. Launch Configuration
-
-To debug C/C++ projects in VS Code, you must create a *launch configuration* that specifies:
-
-- The application entry point (executable)
-- How to attach to a running process
-- Environment variables needed
-- Saved debugging setup details
-
-All launch configs are stored in `.vscode/launch.json` within your workspace.
-##### a. Create `launch.json`
-- Go to `Run` → `Add Configuration...` or
-- Use VS Code chat command:
-    ```
-    /startDebugging
-    ```
-    to auto-generate a debug configuration.
-
-##### b. Start Debugging
-
-You can start a debug session in several ways:
-- **F5**
-- **Ctrl + Shift + D**: Open Debug panel, select a config, press Start
-- **Ctrl + Shift + P** → select `Debug: Select and Start Debugging`
-
-#### 3.2.2. Debug Configuration Example
-
-The most important field is the executable that will run:
-
-```json
-// .vscode/launch.json
-{
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "(gdb) Launch",
-            "type": "cppdbg",
-            "request": "launch",
-            "program": "${workspaceFolder}/build/debug/bin/cpp_lab_project",
-            "args": [],
-            "stopAtEntry": true,
-            "cwd": "${workspaceFolder}",
-            "environment": [],
-            "externalConsole": false,
-            "MIMode": "gdb",
-            "preLaunchTask": "CMake Debug Build",
-            "setupCommands": [
-                {
-                    "description": "Enable pretty printing for gdb",
-                    "text": "-enable-pretty-printing",
-                    "ignoreFailures": true
-                },
-                {
-                    "description": "Set disassembly flavor to Intel",
-                    "text": "-gdb-set disassembly-flavor intel",
-                    "ignoreFailures": true
-                }
-            ]
-        }
-    ]
-}
+## 3. Adding an example
+
+```bash
+./scripts/new_example.sh core/utils Span "std::span: a view over contiguous memory"
+cmake --build build && ./build/bin/cpp_lab_project --run core/utils/Span
 ```
 
-#### 3.2.3. Build Tasks (CMake)
-
-An example `tasks.json` for CMake builds:
-
-```json
-// .vscode/tasks.json
-{
-    "version": "2.0.0",
-    "tasks": [
-        {
-            "label": "CMake Debug Configure",
-            "type": "shell",
-            "command": "cmake",
-            "args": [
-                "-S",
-                ".",
-                "-B",
-                "build/debug",
-                "-DCMAKE_BUILD_TYPE=Debug"
-            ]
-        },
-        {
-            "label": "CMake Debug Build",
-            "type": "shell",
-            "command": "cmake",
-            "args": [
-                "--build",
-                "build/debug"
-            ],
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "presentation": {
-                "reveal": "always"
-            },
-            "dependsOn": "CMake Debug Configure"
-        }
-    ]
+By hand, a complete example is:
+
+```cpp
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+void demo() {
+  LOG_SECTION("Basics");
+  LOG_S("1 + 2 = " << 1 + 2);
 }
+}  // namespace
+
+LAB_EXAMPLE("Span", "std::span: a view over contiguous memory") { demo(); }
 ```
-#### 3.2.4. Run Steps
-
-1. **Open** your project in VS Code
-2. **Install Extension:**  
-   - *C/C++ Extension Pack*
-3. **Install GDB:**
-   ```bash
-   sudo apt update
-   sudo apt install gdb
-   ```
-4. **Start Debugging:**  
-   Press `F5`
-5. **Run Without Debugging:**  
-   Press `Ctrl + F5`
-6. **Build Project (Optional):**  
-   Press `Ctrl + Shift + B`
-
-Notes:
-| Shortcut        | Action                 |
-|-----------------|-----------------------|
-| F5              | Start debugging        |
-| Ctrl + F5       | Run without debugging  |
-| Ctrl + Shift + D| Open Debug panel       |
-| Ctrl + Shift + B| Build project          |
-
-### 3.3 Documentation with `doxygen`
-TBD - Refer to this [Documentation with doxygen](https://www.labri.fr/perso/fleury/posts/programming/using-cmake-googletests-and-gcovr-in-a-c-project.html#:~:text=of%20the%C2%A0project.-,Documentation%20with%20doxygen,-Code%20embedded%20documentation)
-
-## 4. Docker Image
+
+No CMake edit is needed: every `.cpp` in a module folder is compiled, and the menu group comes
+from the folder. See [docs/adding-examples.md](docs/adding-examples.md) for the conventions and
+[docs/README.md](docs/README.md) for the topic index.
+
+---
+## 4. Dependencies
+
+- **g++ >= 13** (or clang++ >= 16) with C++20 support, **CMake >= 3.16**, **git**
+- Optional: `libgtkmm-4.0-dev` (GUI apps), `cppcheck`, `clang-tidy`, `clang-format`, `lcov` or
+  `gcovr`, `valgrind`, `gdb`, `gcc-arm-none-eabi` + `qemu-system-arm` (bare-metal example)
+
 ```bash
-# Navigate to the project that contain your Dockerfile
-cd cpp-lab
+sudo apt-get update
+sudo apt-get install -y g++ cmake ninja-build git cppcheck clang-tidy clang-format \
+                        lcov python3-gcovr valgrind gdb libgtkmm-4.0-dev
+```
 
-# Build the project by running the following command, swapping out DOCKER_USERNAME with your username.
-docker build -t DOCKER_USERNAME/cpp-lab .
+GoogleTest is downloaded automatically at configure time (needs network on the first configure;
+use `-DCPPLAB_BUILD_TESTS=OFF` to skip it).
+
+---
+## 5. Build options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `CMAKE_BUILD_TYPE` | `Debug` | `Debug`, `Release`, `RelWithDebInfo` |
+| `CPPLAB_BUILD_TESTS` | `ON` | unit tests and one smoke test per example |
+| `CPPLAB_BUILD_DEMOS` | `ON` | standalone demos in `src/demo` |
+| `CPPLAB_BUILD_GUI` | `AUTO` | GTK4 apps in `src/ap`: `AUTO`, `ON`, `OFF` |
+| `CPPLAB_ENABLE_SANITIZERS` | `OFF` | AddressSanitizer + UndefinedBehaviorSanitizer |
+| `CPPLAB_WARNINGS_AS_ERRORS` | `OFF` | `-Werror` |
+| `ENABLE_COVERAGE` | `OFF` | `--coverage` for lcov/gcovr |
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCPPLAB_BUILD_GUI=OFF
+```
+
+---
+## 6. Testing
+
+```bash
+ctest --test-dir build -j --output-on-failure     # everything
+ctest --test-dir build -L unit                    # GoogleTest unit tests
+ctest --test-dir build -L example                 # run every example once
+ctest --test-dir build -R 'example:dp/'           # only the design patterns
+./build/bin/cpp_lab_project_unit_test --gtest_filter='Registry*'
+```
+
+- Unit tests live in `tests/`; any `*Test.cpp` file is picked up automatically. `tests/gtest_primer`
+  doubles as a GoogleTest/GoogleMock tutorial (see [tests/README.md](tests/README.md)).
+- Smoke tests (`example:<id>`) are generated from the executable itself, so a new example is
+  tested as soon as it exists.
+
+**Sanitizers** catch memory errors, leaks and undefined behavior:
+
+```bash
+cmake -S . -B build-asan -DCPPLAB_ENABLE_SANITIZERS=ON
+cmake --build build-asan -j && ctest --test-dir build-asan -j
+```
+
+**Memory leaks with valgrind**:
+
+```bash
+valgrind --leak-check=full ./build/bin/cpp_lab_project --plain --run-all core/class
+```
+
+---
+## 7. Static analysis, formatting and coverage
+
+```bash
+# cppcheck (-I include is required so the LAB_EXAMPLE macro can be expanded)
+cppcheck --enable=warning,style,performance,portability --inconclusive --inline-suppr --quiet \
+         --error-exitcode=1 -I include --suppressions-list=.cppcheck-suppressions ./src ./include
+
+# clang-tidy (configured by .clang-tidy)
+clang-tidy -p build $(git ls-files 'src/*.cpp')
+
+# clang-format (Google-based style, .clang-format)
+git ls-files '*.cpp' '*.h' | xargs clang-format -i
+
+# coverage reports
+./scripts/gen_coverage_lcov.sh      # or ./scripts/gen_coverage_gcovr.sh
+```
 
-# Verify the image exists locally
+Intentional findings in teaching examples are listed in `.cppcheck-suppressions`.
+
+---
+## 8. The other programs
+
+| Program | Run | Documentation |
+|---|---|---|
+| GTK4 apps | `./build/bin/ap`, `mvc_ap`, `mvvm_ap` | [src/ap/README.md](src/ap/README.md) |
+| dlopen plugin demo | `./build/bin/demo_dlopen` | [src/demo/dlopen/README.md](src/demo/dlopen/README.md) |
+| Bare-metal ARM (QEMU) | `cd src/embedded && ./run.sh` | [src/embedded/README.md](src/embedded/README.md) |
+
+---
+## 9. Debugging with VS Code
+
+1. Install the *C/C++ Extension Pack* and `gdb` (`sudo apt install gdb`).
+2. Press **F5**. `.vscode/launch.json` builds `build/debug` through the task in
+   `.vscode/tasks.json` and starts `build/debug/bin/cpp_lab_project` under gdb.
+
+| Shortcut | Action |
+|---|---|
+| F5 | start debugging |
+| Ctrl + F5 | run without debugging |
+| Ctrl + Shift + D | open the debug panel |
+| Ctrl + Shift + B | build |
+
+To debug a single example without the menu, set `"args": ["--run", "core/smart_pointer/Weak"]` in
+`launch.json`.
+
+---
+## 10. Docker
+
+```bash
+# Build the image (swap DOCKER_USERNAME for your account)
+docker build -t DOCKER_USERNAME/cpp-lab .
 docker image ls
 
-# To push the image
+# Open a shell inside the image
+docker run -it --rm DOCKER_USERNAME/cpp-lab:latest /bin/bash
+
+# Push it (CI uses urboob21/cpp-lab:latest)
 docker push DOCKER_USERNAME/cpp-lab
 ```
 
-## 5. TroubleShooting
-1. `push access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed`
-=> docker login / Docker Desktop login
+`-i` keeps stdin open, `-t` allocates a terminal, `--rm` removes the container when it exits.
+
+---
+## 11. Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `gtkmm-4.0 not found` | `sudo apt install libgtkmm-4.0-dev`, or configure with `-DCPPLAB_BUILD_GUI=OFF` |
+| FetchContent cannot download GoogleTest | configure with `-DCPPLAB_BUILD_TESTS=OFF` |
+| `Does not match the generator used previously` | delete the `build/` directory and configure again |
+| `registry error: duplicate example id ...` | two `LAB_EXAMPLE` names collide in one folder |
+| cppcheck reports `syntax error` on `LAB_EXAMPLE` | add `-I include` so the macro can be expanded |
+| `push access denied` when pushing the image | `docker login` first |
+
+---
+## 12. Evaluating the executable
 
-## 6. Evaluate Executable
-- List all sections:
 ```bash
-$ size ./build/cpp-lab
+size ./build/bin/cpp_lab_project
+```
+
 ```
-- The expected output should be the following:
-```bash
    text    data     bss     dec     hex filename
-  14791     792     280   15863    ./build/cpp-lab
+ xxxxxx    xxxx    xxxx  xxxxxx   xxxxx ./build/bin/cpp_lab_project
 ```
 
-- `.text`: Text Segment - the executable code size, including: complied function, inline, template, constants, string literals
-- `.data`: Initialized Data Segment - the memory for the global, static variables, has init value.
-- `.bss`: Uninitialized Data Segment - global and static variables that are not initialized
\ No newline at end of file
+- `.text`: executable code, including inlined and template code, constants and string literals
+- `.data`: initialized global and static variables
+- `.bss`: uninitialized global and static variables
diff --git a/docs/README.md b/docs/README.md
index 7f9b854..5815546 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,19 +1,27 @@
 # CPP Lab Docs
 
+Every folder below `src/` is a group in the lab's menu. The README in each folder explains the
+topic, and the examples next to it show it in code. Run any example with
+`./build/bin/cpp_lab_project --run <id>`, or browse them with the interactive menu.
+
+- [Adding examples](adding-examples.md): how the lab works and how to add your own examples
+
 ---
-## 1. Core
-
-1. [Basic](../src/core/basics/README.md)
-2. [Class](../src/core/class/README.md)
-3. [Concurrency](../src/core/concurrency/README.md)
-4. [Container](../src/core/container/README.md)
-5. [Date time](../src/core/datetime/README.md)
-6. [Exception](../src/core/exception/README.md)
-7. [Expression](../src/core/expression/README.md)
-8. [File handle](../src/core/filehandle/README.md)
-9. [Smart pointer](../src/core/smart_pointer/README.md)
-10. [String](../src/core/string/README.md)
-11. [Utilities library](../src/core/utils/README.md)
+## 1. Core (C++ language and standard library)
+
+1. [Basics](../src/core/basics/README.md): control flow, initialization, operators, const/constexpr
+2. [Data types](../src/core/datatype/README.md): fundamental types, pointers, references, enums, structs, unions, conversions
+3. [Classes](../src/core/class/README.md): constructors, destructors, Rule of 3/5/0, relationships, friends, virtual
+4. [Functions](../src/core/function/README.md): function pointers, lambdas, std::function, operator overloading
+5. [Linkage](../src/core/linkage/README.md): internal/external linkage, sharing global constants
+6. [Smart pointers](../src/core/smart_pointer/README.md): unique_ptr, shared_ptr, weak_ptr
+7. [Strings](../src/core/string/README.md): C strings, std::string, string_view, formatting
+8. [Containers](../src/core/container/README.md): sequence, associative, unordered, adapters
+9. [Exceptions](../src/core/exception/README.md): try/catch/throw, noexcept
+10. [File handling](../src/core/filehandle/README.md): streams, files, filesystem, formatting
+11. [Date and time](../src/core/datetime/README.md): `<ctime>` and `<chrono>`
+12. [Concurrency](../src/core/concurrency/README.md): threads, mutexes, condition variables, futures
+13. [Utilities](../src/core/utils/README.md): optional, algorithms, regex, type traits, variadics
 
 ---
 ## 2. Design Patterns
@@ -25,10 +33,13 @@
 ---
 ## 3. Architecture Patterns
 
-1. [MVC/MVVM](../src/ap/README.md)
+1. [MVC/MVVM](../src/ap/README.md) (GTK4 applications)
 
 ---
 ## 4. Other
 
-1. [Socket](../src/socket/README.md)
-2. [Google Test](../tests/README.md)
\ No newline at end of file
+1. [Controller (PID)](../src/controller/README.md)
+2. [Socket](../src/socket/README.md)
+3. [dlopen plugin demo](../src/demo/dlopen/README.md)
+4. [Embedded bare-metal ARM](../src/embedded/README.md)
+5. [Google Test](../tests/README.md)
diff --git a/docs/adding-examples.md b/docs/adding-examples.md
new file mode 100644
index 0000000..d8e1702
--- /dev/null
+++ b/docs/adding-examples.md
@@ -0,0 +1,145 @@
+# Adding examples
+
+The lab is built so that adding an example takes one file and no build-system changes.
+
+## 1. The quick way
+
+```bash
+./scripts/new_example.sh core/utils Span "std::span: a view over contiguous memory"
+cmake --build build
+./build/bin/cpp_lab_project --run core/utils/Span
+```
+
+The script creates `src/core/utils/Span.cpp` from a template. Edit it and rebuild. The build finds
+the new file on its own (CMake globs with `CONFIGURE_DEPENDS`).
+
+## 2. Anatomy of an example
+
+```cpp
+// -----------------------------------------------------------------------------
+// std::span (C++20)
+//
+// A non-owning view over a contiguous sequence: pointer + size.
+//
+// Key points:
+//   - Replaces "pointer + length" parameters.
+//   - Never outlives the data it views.
+//
+// Reference: https://en.cppreference.com/w/cpp/container/span
+// -----------------------------------------------------------------------------
+
+#include <span>
+#include <vector>
+
+#include "lab/Example.h"   // LAB_EXAMPLE
+#include "lab/Logger.h"    // LOG, LOG_S, LOG_FUNC, LOG_SECTION
+
+namespace {  // everything file-local: no name clashes with other examples
+
+int sum(std::span<const int> values) {
+  int total = 0;
+  for (const int value : values) {
+    total += value;
+  }
+  return total;
+}
+
+void basics() {
+  LOG_SECTION("Passing arrays and vectors as std::span");
+  const int array[] = {1, 2, 3};
+  const std::vector<int> vector{4, 5, 6};
+  LOG_S("sum(array) = " << sum(array) << ", sum(vector) = " << sum(vector));
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Span", "std::span: a view over contiguous memory") {
+  basics();
+}
+```
+
+### LAB_EXAMPLE
+
+```cpp
+LAB_EXAMPLE(name, description [, flags]) { body }
+```
+
+| Part          | Meaning                                                                           |
+|---------------|-----------------------------------------------------------------------------------|
+| `name`        | Short name shown in the menu. It must be unique in its folder and contain no spaces or `/`. |
+| `description` | One line shown next to the name and searched by `--list` and the menu search.   |
+| `flags`       | Optional. `lab::kInteractive` marks examples that need a human or another process. |
+| folder        | Taken from the file's location: `src/core/utils/Span.cpp` becomes group `core/utils`. |
+| id            | `<folder>/<name>`, e.g. `core/utils/Span`. Use it with `--run`.                     |
+
+How it works: the macro declares a file-local function and registers its address with
+`lab::Registry` from a static initializer, which runs before `main()`. The braces that follow the
+macro become the body of that function. Duplicate ids and invalid names are reported when the
+program starts.
+
+### Logging
+
+| Macro                     | Output                                                        |
+|---------------------------|---------------------------------------------------------------|
+| `LOG("text")`             | one line (anything convertible to `std::string_view`)         |
+| `LOG_S("x = " << x)`      | anything you can stream into `std::ostream`                    |
+| `LOG_FUNC()`              | the full signature of the current function (which overload ran?) |
+| `LOG_SECTION("Title")`    | a separator line that structures the output                   |
+
+Debug builds prefix each line with `[time][file:line][function]`. Release builds and `--plain`
+print only the message.
+
+## 3. Conventions
+
+- **One topic per file**, named after the topic in `CamelCase.cpp`. Put the file in the folder
+  where learners will look for it.
+- **Header comment:** what the example teaches, key points and pitfalls, and a reference link.
+- **Anonymous namespace** for all helpers. All examples are linked into one program, so two files
+  that both define `void run()` or `class Model` at global scope would break the One Definition
+  Rule.
+- **Sections:** split the example into small functions, each starting with `LOG_SECTION`.
+- **Show the problem, then the solution** when a topic fixes a problem (see the design patterns).
+- **Never execute undefined behavior on purpose.** Describe it in a comment, or build a safe
+  demonstration. The smoke tests also run with AddressSanitizer and UBSan.
+- **Clean up:** create files only in `std::filesystem::temp_directory_path()` and remove them.
+  Restore global state you change, such as `std::set_terminate`.
+- **Be fast and non-interactive** unless the topic needs otherwise. Keep sleeps short. Use
+  `std::istringstream` instead of `std::cin`. Mark examples that must wait for a user or a peer
+  with `lab::kInteractive`.
+- Format with the repository's `.clang-format` (Google-based style).
+
+## 4. Testing your example
+
+```bash
+cmake --build build
+ctest --test-dir build -R example:core/utils/Span --output-on-failure
+```
+
+Every non-interactive example automatically becomes a ctest smoke test named `example:<id>`. The
+test fails if the example throws an uncaught exception. It also fails under the sanitizer build
+if the example leaks memory or executes undefined behavior:
+
+```bash
+cmake -S . -B build-asan -DCPPLAB_ENABLE_SANITIZERS=ON
+cmake --build build-asan -j && ctest --test-dir build-asan -L example -j
+```
+
+Reusable code (not just demonstration output) deserves a real unit test in `tests/`. Any
+`tests/**/*Test.cpp` file is picked up automatically (see `tests/controller/PidTest.cpp`).
+
+## 5. A new top-level topic
+
+To start a new module such as `src/algorithms/`:
+
+1. Create the folder and add examples to it.
+2. Add one line to `src/CMakeLists.txt`:
+   ```cmake
+   cpplab_add_example_module(algorithms)
+   ```
+3. Add a `README.md` to the folder and link it from `docs/README.md`.
+
+## 6. Standalone programs
+
+Programs with their own `main()` do not use `LAB_EXAMPLE`: GUI apps, plugins, and firmware. Give
+them their own `CMakeLists.txt`, as in `src/ap` and `src/demo`, and add them with
+`add_subdirectory()` in `src/CMakeLists.txt`.
diff --git a/scripts/gen_coverage_gcovr.sh b/scripts/gen_coverage_gcovr.sh
index fa27732..a8d5d9f 100755
--- a/scripts/gen_coverage_gcovr.sh
+++ b/scripts/gen_coverage_gcovr.sh
@@ -8,27 +8,29 @@ if ! command -v gcovr >/dev/null 2>&1; then
   exit 1
 fi
 
-# Configure project (only if build folder does not exist)
-if [ ! -d build ]; then
-  cmake -S . -B build \
-    -DCMAKE_BUILD_TYPE=Debug \
-    -DCMAKE_CXX_FLAGS="--coverage -O0 -g"
-fi
+# Configure a separate coverage build (ENABLE_COVERAGE adds --coverage -O0 -g)
+cmake -S . -B build-coverage \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DENABLE_COVERAGE=ON
 
 # Build project
-cmake --build build
+cmake --build build-coverage -j "$(nproc)"
 
 # Run unit tests
-ctest --test-dir build --output-on-failure
+ctest --test-dir build-coverage --output-on-failure -j "$(nproc)"
 
 # Generate coverage report
 mkdir -p coverage_gcovr
 
-gcovr -r . build \
+gcovr -r . build-coverage \
   --branches \
   --html \
   --html-details \
   -o coverage_gcovr/index.html
 
-# Open coverage report
-xdg-open coverage_gcovr/index.html
\ No newline at end of file
+echo "Report: coverage_gcovr/index.html"
+
+# Open it in a browser when there is a desktop session
+if command -v xdg-open >/dev/null 2>&1 && [ -n "${DISPLAY:-}" ]; then
+  xdg-open coverage_gcovr/index.html
+fi
\ No newline at end of file
diff --git a/scripts/gen_coverage_lcov.sh b/scripts/gen_coverage_lcov.sh
index 5197272..239705b 100755
--- a/scripts/gen_coverage_lcov.sh
+++ b/scripts/gen_coverage_lcov.sh
@@ -8,27 +8,25 @@ if ! command -v lcov >/dev/null 2>&1; then
   exit 1
 fi
 
-# Configure project (only if build folder does not exist)
-if [ ! -d build ]; then
-  cmake -S . -B build \
-    -DCMAKE_BUILD_TYPE=Debug \
-    -DCMAKE_CXX_FLAGS="--coverage -O0 -g"
-fi
+# Configure a separate coverage build (ENABLE_COVERAGE adds --coverage -O0 -g)
+cmake -S . -B build-coverage \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DENABLE_COVERAGE=ON
 
 # Build project
-cmake --build build
+cmake --build build-coverage -j "$(nproc)"
 
 # Reset previous coverage
-lcov --directory build --zerocounters
+lcov --directory build-coverage --zerocounters
 
 # Run unit tests
-ctest --test-dir build --output-on-failure
+ctest --test-dir build-coverage --output-on-failure -j "$(nproc)"
 
 # Capture coverage
 mkdir -p coverage_lcov
 
 lcov --capture \
-     --directory build \
+     --directory build-coverage \
      --ignore-errors mismatch \
      --rc geninfo_unexecuted_blocks=1 \
      --output-file coverage_lcov/coverage.info
@@ -41,5 +39,9 @@ lcov --remove coverage_lcov/coverage.info '/usr/*' \
 genhtml coverage_lcov/coverage.info \
         --output-directory coverage_lcov
 
-# Open coverage report
-xdg-open coverage_lcov/index.html
\ No newline at end of file
+echo "Report: coverage_lcov/index.html"
+
+# Open it in a browser when there is a desktop session
+if command -v xdg-open >/dev/null 2>&1 && [ -n "${DISPLAY:-}" ]; then
+  xdg-open coverage_lcov/index.html
+fi
\ No newline at end of file
diff --git a/scripts/new_example.sh b/scripts/new_example.sh
new file mode 100755
index 0000000..fcd87be
--- /dev/null
+++ b/scripts/new_example.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Creates a new example from a template.
+#
+#   scripts/new_example.sh <folder below src> <Name> ["one-line description"]
+#   scripts/new_example.sh core/utils Span "std::span: a view over contiguous memory"
+#
+# The file src/<folder>/<Name>.cpp is picked up by CMake on the next build and
+# shows up in the menu as <folder>/<Name>. See docs/adding-examples.md.
+set -euo pipefail
+
+usage() {
+  sed -n '2,8p' "$0" | sed 's/^# \{0,1\}//'
+  exit 1
+}
+
+if [[ $# -lt 2 || $# -gt 3 ]]; then
+  usage
+fi
+
+folder="${1%/}"
+folder="${folder#src/}"
+name="$2"
+description="${3:-TODO: one-line description}"
+
+if [[ ! "$name" =~ ^[A-Za-z][A-Za-z0-9_]*$ ]]; then
+  echo "error: the name must look like an identifier, e.g. MyExample" >&2
+  exit 1
+fi
+if [[ ! "$folder" =~ ^[a-z0-9_]+(/[a-z0-9_]+)*$ ]]; then
+  echo "error: the folder must be lower_case segments separated by '/', e.g. core/utils" >&2
+  exit 1
+fi
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+module="${folder%%/*}"
+if ! grep -q "cpplab_add_example_module(${module})" "$root/src/CMakeLists.txt"; then
+  echo "error: '${module}' is not an example module." >&2
+  echo "       Add 'cpplab_add_example_module(${module})' to src/CMakeLists.txt first." >&2
+  exit 1
+fi
+
+file="$root/src/$folder/$name.cpp"
+if [[ -e "$file" ]]; then
+  echo "error: src/$folder/$name.cpp already exists" >&2
+  exit 1
+fi
+mkdir -p "$(dirname "$file")"
+
+# Escape backslashes and quotes so the description is a valid string literal.
+description="${description//\\/\\\\}"
+description="${description//\"/\\\"}"
+
+cat > "$file" <<EOF
+// -----------------------------------------------------------------------------
+// ${name}
+//
+// Explain in two or three sentences what this example teaches.
+//
+// Key points:
+//   - ...
+//   - ...
+//
+// Reference: https://en.cppreference.com/w/cpp
+// -----------------------------------------------------------------------------
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+void basics() {
+  LOG_SECTION("Basics");
+  LOG("Hello from ${name}");
+  LOG_S("values can be streamed: " << 42);
+}
+
+}  // namespace
+
+LAB_EXAMPLE("${name}", "${description}") {
+  basics();
+}
+EOF
+
+echo "created src/$folder/$name.cpp"
+echo
+echo "Build and run it:"
+echo "  cmake --build build && ./build/bin/cpp_lab_project --run $folder/$name"
diff --git a/scripts/run.sh b/scripts/run.sh
index 6383704..750bfed 100755
--- a/scripts/run.sh
+++ b/scripts/run.sh
@@ -1,23 +1,16 @@
 #!/usr/bin/env bash
-
+# Build pipeline: configure + build, static analysis, tests, then start the menu.
+#
+#   ./scripts/run.sh             full pipeline
+#   ./scripts/run.sh --no-tests  skip ctest
 set -e  # Exit immediately if a command fails
 
-PROJECT_EXEC="./build/bin/cpp_lab_project"
 BUILD_DIR="./build"
-
-# if [ ! -d "build" ]; then
-# echo "Build directory not found. Creating build directory..."
-
-# rm -rf build
-# mkdir build
-# cd build || exit
-
-# cmake ..
-# cd ..
-
-# else
-# echo "Build directory already exists."
-# fi
+PROJECT_EXEC="$BUILD_DIR/bin/cpp_lab_project"
+RUN_TESTS=1
+if [[ "${1:-}" == "--no-tests" ]]; then
+    RUN_TESTS=0
+fi
 
 clear
 echo "=============================="
@@ -25,8 +18,8 @@ echo "   Starting build pipeline... "
 echo "=============================="
 
 # Check required tools
-for tool in cmake cppcheck python3; do
-    if ! command -v $tool &> /dev/null; then
+for tool in cmake cppcheck; do
+    if ! command -v "$tool" &> /dev/null; then
         echo "[ERR]: $tool is not installed."
         exit 1
     fi
@@ -34,8 +27,8 @@ done
 
 echo ""
 echo "===========>> Building project..."
-cmake -G "Unix Makefiles" -B "$BUILD_DIR"
-cmake --build "$BUILD_DIR"
+cmake -S . -B "$BUILD_DIR" -DCMAKE_BUILD_TYPE=Debug
+cmake --build "$BUILD_DIR" -j "$(nproc)"
 
 echo ""
 echo "===========>> Running cppcheck..."
@@ -45,14 +38,25 @@ cppcheck \
     --inline-suppr \
     --quiet \
     --error-exitcode=1 \
+    -I include \
+    --suppressions-list=.cppcheck-suppressions \
     ./src ./include \
     -isrc/embedded/
 
 echo "[OK] Static analysis passed"
 
-echo ""
-echo "===========>> Generating commit id..."
-python3 ./private/genid.py
+if [[ "$RUN_TESTS" == 1 ]]; then
+    echo ""
+    echo "===========>> Running tests (unit tests + one smoke test per example)..."
+    ctest --test-dir "$BUILD_DIR" --output-on-failure -j "$(nproc)"
+fi
+
+# Optional local step: private/ is not part of the repository.
+if [[ -f ./private/genid.py ]] && command -v python3 &> /dev/null; then
+    echo ""
+    echo "===========>> Generating commit id..."
+    python3 ./private/genid.py
+fi
 
 echo ""
 echo "===========>> Running program..."
@@ -66,4 +70,4 @@ fi
 echo ""
 echo "=============================="
 echo "Pipeline finished successfully!"
-echo "=============================="
\ No newline at end of file
+echo "=============================="

From d4ee7e24c7fc02f0d7519928c4015da838746261 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:31:03 +0700
Subject: [PATCH 10/20] Fix coverage builds and report empty --run-all filters

- ENABLE_COVERAGE now compiles with -fprofile-update=atomic. The RaceCondition
  example increments a counter from several threads on purpose, which also
  raced gcov's counters and made lcov abort with "unexpected negative count".
- The coverage scripts use their own build-coverage directory, build in
  parallel, and only open the HTML report when a desktop session is present
  (and never fail because of it). lcov now reports 90.8% line coverage.
- --run-all with a filter that matches nothing says so instead of printing
  "Ran 0 example(s)".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 cmake/CompilerOptions.cmake   |  4 +++-
 scripts/gen_coverage_gcovr.sh |  2 +-
 scripts/gen_coverage_lcov.sh  |  2 +-
 src/lab/Runner.cpp            | 12 ++++++++----
 tests/lab/MenuRunnerTest.cpp  | 13 ++++++++++---
 5 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/cmake/CompilerOptions.cmake b/cmake/CompilerOptions.cmake
index 7cbed63..9f5ca1d 100644
--- a/cmake/CompilerOptions.cmake
+++ b/cmake/CompilerOptions.cmake
@@ -20,7 +20,9 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
     # Code coverage configuration (see scripts/gen_coverage_*.sh)
     if(ENABLE_COVERAGE)
         message(STATUS "Enabling coverage flags")
-        target_compile_options(cpplab_options INTERFACE --coverage -O0 -g)
+        # -fprofile-update=atomic: the RaceCondition example increments a counter from
+        # several threads on purpose, which would also corrupt gcov's own counters.
+        target_compile_options(cpplab_options INTERFACE --coverage -O0 -g -fprofile-update=atomic)
         target_link_options(cpplab_options INTERFACE --coverage)
     endif()
 
diff --git a/scripts/gen_coverage_gcovr.sh b/scripts/gen_coverage_gcovr.sh
index a8d5d9f..c17d704 100755
--- a/scripts/gen_coverage_gcovr.sh
+++ b/scripts/gen_coverage_gcovr.sh
@@ -32,5 +32,5 @@ echo "Report: coverage_gcovr/index.html"
 
 # Open it in a browser when there is a desktop session
 if command -v xdg-open >/dev/null 2>&1 && [ -n "${DISPLAY:-}" ]; then
-  xdg-open coverage_gcovr/index.html
+  xdg-open coverage_gcovr/index.html >/dev/null 2>&1 || true
 fi
\ No newline at end of file
diff --git a/scripts/gen_coverage_lcov.sh b/scripts/gen_coverage_lcov.sh
index 239705b..1c5669e 100755
--- a/scripts/gen_coverage_lcov.sh
+++ b/scripts/gen_coverage_lcov.sh
@@ -43,5 +43,5 @@ echo "Report: coverage_lcov/index.html"
 
 # Open it in a browser when there is a desktop session
 if command -v xdg-open >/dev/null 2>&1 && [ -n "${DISPLAY:-}" ]; then
-  xdg-open coverage_lcov/index.html
+  xdg-open coverage_lcov/index.html >/dev/null 2>&1 || true
 fi
\ No newline at end of file
diff --git a/src/lab/Runner.cpp b/src/lab/Runner.cpp
index 18c4c63..23c950d 100644
--- a/src/lab/Runner.cpp
+++ b/src/lab/Runner.cpp
@@ -75,10 +75,14 @@ int runAll(const Registry& registry, std::string_view filter,
     }
   }
 
-  out << '\n'
-      << std::string(kRuleWidth, '=') << '\n'
-      << "Ran " << ran << " example(s), skipped " << skipped
-      << " interactive, " << failed.size() << " failed.\n";
+  out << '\n' << std::string(kRuleWidth, '=') << '\n';
+  if (ran == 0 && skipped == 0) {
+    out << "No example matches \"" << filter << "\" (see --list).\n"
+        << std::flush;
+    return 0;
+  }
+  out << "Ran " << ran << " example(s), skipped " << skipped << " interactive, "
+      << failed.size() << " failed.\n";
   for (const std::string& id : failed) {
     out << "  FAILED: " << id << '\n';
   }
diff --git a/tests/lab/MenuRunnerTest.cpp b/tests/lab/MenuRunnerTest.cpp
index 622ba4b..3de6fa4 100644
--- a/tests/lab/MenuRunnerTest.cpp
+++ b/tests/lab/MenuRunnerTest.cpp
@@ -34,9 +34,10 @@ class MenuRunnerTest : public testing::Test {
     g_second_runs = 0;
     g_interactive_runs = 0;
     registry.add("/x/src/topic/basics/A.cpp", "First", "first example", first);
-    registry.add("/x/src/topic/advanced/B.cpp", "Second", "second example", second);
-    registry.add("/x/src/topic/advanced/C.cpp", "Server", "needs a client", interactive,
-                 lab::kInteractive);
+    registry.add("/x/src/topic/advanced/B.cpp", "Second", "second example",
+                 second);
+    registry.add("/x/src/topic/advanced/C.cpp", "Server", "needs a client",
+                 interactive, lab::kInteractive);
   }
 
   lab::Registry registry;
@@ -64,6 +65,12 @@ TEST_F(MenuRunnerTest, RunAllSkipsInteractiveExamples) {
   EXPECT_NE(out.str().find("skipped 1 interactive"), std::string::npos);
 }
 
+TEST_F(MenuRunnerTest, RunAllReportsAFilterThatMatchesNothing) {
+  EXPECT_EQ(lab::runAll(registry, "nothing matches this", out), 0);
+  EXPECT_EQ(g_first_runs + g_second_runs, 0);
+  EXPECT_NE(out.str().find("No example matches"), std::string::npos);
+}
+
 TEST_F(MenuRunnerTest, RunAllHonorsTheFilter) {
   EXPECT_EQ(lab::runAll(registry, "basics", out), 0);
   EXPECT_EQ(g_first_runs, 1);

From 1b035331a7ea0906c64ec5c65f5f90a2a8e81250 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:40:06 +0700
Subject: [PATCH 11/20] Make the sources clang-tidy clean and add a Release CI
 job

clang-tidy found real issues and a lot of noise that comes from the teaching
style of the examples.

Fixed:
- Adapter rounded money with (x + 0.5) instead of std::lround.
- Builder used rfind(..., 0) != 0 instead of starts_with, and built its
  description with temporary strings.
- Unique used reset(new T) where make_unique is the point of the example.
- Stack had a nested conditional operator; Internal.cpp and ThrowNoexcept used
  names that do not follow the project's own naming rules.
- LAB_EXAMPLE now parenthesizes its macro arguments.
- CString's strncat truncation demo silences -Wstringop-truncation locally: it
  only fires in optimized builds, and truncating is exactly what it shows.

Configured:
- .clang-tidy disables the checks that contradict the didactic style (copies
  that show a constructor call, moved-from objects that are inspected, explicit
  types, recursion, std::bind, ...) and explains each one. The explanation sits
  above the list, because a YAML folded scalar cannot contain comments - inside
  it the "comments" silently became part of the check names.
- abseil-* checks removed: this project does not use abseil.

CI gained a Release job with -Werror; optimized builds report diagnostics that
a Debug build never shows (that is how the strncat warning surfaced).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 .clang-tidy                                   | 38 ++++++++++++++++++-
 .github/workflows/cpp-build-test-coverage.yml | 20 ++++++++++
 include/lab/Example.h                         | 12 +++---
 src/core/container/adapter/Stack.cpp          |  7 +++-
 src/core/datatype/TypeConversions.cpp         |  1 +
 src/core/exception/ThrowNoexcept.cpp          |  1 +
 src/core/smart_pointer/Unique.cpp             |  2 +-
 src/core/string/CString.cpp                   | 14 ++++++-
 src/dp/creational/Builder.cpp                 |  7 +++-
 src/dp/structural/Adapter.cpp                 |  3 +-
 10 files changed, 91 insertions(+), 14 deletions(-)

diff --git a/.clang-tidy b/.clang-tidy
index e010fe1..aa9fc39 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -1,5 +1,26 @@
 ---
 # Configure clang-tidy for this project.
+#
+# cpp-lab is a teaching repository. Examples deliberately show the "before"
+# version of a pattern, copy objects so a constructor call becomes visible, read
+# moved-from objects to show what happens, and spell types out instead of using
+# auto. The following checks fight exactly that and are therefore disabled at
+# the end of the Checks list, although they stay valuable in production code
+# (note: the Checks list is a YAML folded scalar, so it cannot hold comments):
+#
+#   -misc-use-anonymous-namespace                 LAB_EXAMPLE declares a static function
+#   -readability-convert-member-functions-to-static
+#   -performance-unnecessary-copy-initialization  copies are made on purpose
+#   -performance-unnecessary-value-param          pass-by-value is demonstrated
+#   -bugprone-use-after-move                      moved-from objects are inspected
+#   -google-runtime-int                           short/long are the subject of Fundamental
+#   -modernize-use-std-numbers                    the linkage constants are illustrations
+#   -modernize-use-auto, -modernize-loop-convert  explicit code is easier to follow here
+#   -modernize-avoid-bind                         std::bind has its own example
+#   -modernize-use-constraints                    enable_if is shown next to concepts
+#   -misc-no-recursion                            recursion is the lesson (Composite, ...)
+#   -google-build-using-namespace                 chrono literals inside one function
+#   -google-explicit-constructor                  implicit conversion has its own example
 
 # Here is an explanation for why some of the checks are disabled:
 #
@@ -77,7 +98,6 @@
 #   X update.
 Checks: >
   -*,
-  abseil-*,
   bugprone-*,
   google-*,
   misc-*,
@@ -115,7 +135,21 @@ Checks: >
   -bugprone-implicit-widening-of-multiplication-result,
   -bugprone-unchecked-optional-access,
   -bugprone-unused-local-non-trivial-variable,
-  -bugprone-unused-return-value
+  -bugprone-unused-return-value,
+  -misc-use-anonymous-namespace,
+  -readability-convert-member-functions-to-static,
+  -performance-unnecessary-copy-initialization,
+  -performance-unnecessary-value-param,
+  -bugprone-use-after-move,
+  -google-runtime-int,
+  -modernize-use-std-numbers,
+  -modernize-use-auto,
+  -modernize-loop-convert,
+  -modernize-avoid-bind,
+  -modernize-use-constraints,
+  -misc-no-recursion,
+  -google-build-using-namespace,
+  -google-explicit-constructor
 
 # Turn all the warnings from the checks above into errors.
 WarningsAsErrors: "*"
diff --git a/.github/workflows/cpp-build-test-coverage.yml b/.github/workflows/cpp-build-test-coverage.yml
index 6ce4a66..d207131 100644
--- a/.github/workflows/cpp-build-test-coverage.yml
+++ b/.github/workflows/cpp-build-test-coverage.yml
@@ -103,6 +103,26 @@ jobs:
       #   run: |
       #       clang-tidy -p build -header-filter='^src/.*' $(find src -name "*.cpp")
 
+  release:
+    # ---------------------------------------------------------
+    # A Release build with warnings as errors: optimizations enable extra
+    # compiler diagnostics that a Debug build never reports.
+    # ---------------------------------------------------------
+    runs-on: ubuntu-24.04
+    container:
+      image: urboob21/cpp-lab:latest
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Build and test in Release
+        run: |
+          cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release \
+                -DCPPLAB_WARNINGS_AS_ERRORS=ON -DCPPLAB_BUILD_GUI=OFF
+          cmake --build build-release -j "$(nproc)"
+          ctest --test-dir build-release --output-on-failure -j "$(nproc)"
+
   sanitizers:
     # ---------------------------------------------------------
     # Same tests with AddressSanitizer + UndefinedBehaviorSanitizer:
diff --git a/include/lab/Example.h b/include/lab/Example.h
index 426f9b3..590bc3f 100644
--- a/include/lab/Example.h
+++ b/include/lab/Example.h
@@ -46,12 +46,14 @@ constexpr unsigned flags(unsigned value) noexcept {
 #define LAB_DETAIL_CONCAT_IMPL(a, b) a##b
 #define LAB_DETAIL_CONCAT(a, b) LAB_DETAIL_CONCAT_IMPL(a, b)
 
-#define LAB_EXAMPLE(name, description, ...)                               \
+#define LAB_EXAMPLE(name, description, ...)                              \
   LAB_DETAIL_EXAMPLE(LAB_DETAIL_CONCAT(lab_example_, __COUNTER__), name, \
                      description, ::lab::detail::flags(__VA_ARGS__))
 
-#define LAB_DETAIL_EXAMPLE(function, name, description, flags)                    \
-  static void function();                                                         \
-  [[maybe_unused]] static const bool LAB_DETAIL_CONCAT(function, _registered) =   \
-      ::lab::Registry::instance().add(__FILE__, name, description, &function, flags); \
+#define LAB_DETAIL_EXAMPLE(function, name, description, flags)         \
+  static void function();                                              \
+  [[maybe_unused]] static const bool LAB_DETAIL_CONCAT(function,       \
+                                                       _registered) =  \
+      ::lab::Registry::instance().add(__FILE__, (name), (description), \
+                                      &(function), (flags));           \
   static void function()
diff --git a/src/core/container/adapter/Stack.cpp b/src/core/container/adapter/Stack.cpp
index b60a3fe..005792a 100644
--- a/src/core/container/adapter/Stack.cpp
+++ b/src/core/container/adapter/Stack.cpp
@@ -48,7 +48,12 @@ bool isBalanced(const std::string& text) {
     if (c == '(' || c == '[' || c == '{') {
       open.push(c);
     } else if (c == ')' || c == ']' || c == '}') {
-      const char expected = c == ')' ? '(' : (c == ']' ? '[' : '{');
+      char expected = '(';
+      if (c == ']') {
+        expected = '[';
+      } else if (c == '}') {
+        expected = '{';
+      }
       if (open.empty() || open.top() != expected) {
         return false;
       }
diff --git a/src/core/datatype/TypeConversions.cpp b/src/core/datatype/TypeConversions.cpp
index c7baff1..a68842c 100644
--- a/src/core/datatype/TypeConversions.cpp
+++ b/src/core/datatype/TypeConversions.cpp
@@ -50,6 +50,7 @@ void implicitConversions() {
   const float f = 3.5F;
   const double widened = f;  // promotion: float -> double
   const bool flag = true;
+  // NOLINTNEXTLINE(readability-implicit-bool-conversion): the conversion is the point
   const int from_bool = flag;  // true -> 1
   LOG_S("'A' -> " << promoted << ", 3.5F -> " << widened << ", true -> "
                   << from_bool);
diff --git a/src/core/exception/ThrowNoexcept.cpp b/src/core/exception/ThrowNoexcept.cpp
index 90512f1..717a620 100644
--- a/src/core/exception/ThrowNoexcept.cpp
+++ b/src/core/exception/ThrowNoexcept.cpp
@@ -90,6 +90,7 @@ Counters growVector() {
   Counters counters;
   std::vector<Element<kNoexceptMove>> elements;
   for (int i = 0; i < 100; ++i) {
+    // NOLINTNEXTLINE(performance-inefficient-vector-operation): no reserve on purpose
     elements.emplace_back(counters);  // reallocates several times
   }
   return counters;
diff --git a/src/core/smart_pointer/Unique.cpp b/src/core/smart_pointer/Unique.cpp
index 06e92f2..7878870 100644
--- a/src/core/smart_pointer/Unique.cpp
+++ b/src/core/smart_pointer/Unique.cpp
@@ -57,7 +57,7 @@ void basics() {
   const Resource* observer = owner.get();  // non-owning raw pointer
   LOG_S("  get() -> " << observer->name());
 
-  owner.reset(new Resource("C"));   // deletes B, now owns C
+  owner = std::make_unique<Resource>("C");  // deletes B, now owns C
   Resource* raw = owner.release();  // gives up ownership WITHOUT deleting
   LOG_S("  after release(): owner is " << (owner ? "set" : "empty")
                                        << ", raw points to " << raw->name());
diff --git a/src/core/string/CString.cpp b/src/core/string/CString.cpp
index 23076c0..14d153e 100644
--- a/src/core/string/CString.cpp
+++ b/src/core/string/CString.cpp
@@ -44,6 +44,7 @@ void create() {
   //   pointer (stack) -> 0x4030...: 't' 'h' 'i' 's' ... '\0' (read-only data)
   const char* pointer = "this is a string literal";
   logString("pointer", pointer,
+            // NOLINTNEXTLINE(bugprone-sizeof-expression): the lesson
             sizeof(pointer));  // sizeof gives the POINTER size!
   // pointer[0] = 'T';  // error (and undefined behavior without the const)
 
@@ -74,8 +75,17 @@ void concatenate() {
   std::strcat(destination, " !!");
   logString("strcat", destination, sizeof(destination));
 
-  std::strncat(destination, "1234",
-               3);  // appends at most 3 chars, always adds '\0'
+  // Appends at most 3 characters and always adds '\0'. The source is longer,
+  // so the result is truncated - GCC points that out with -Wstringop-truncation
+  // when optimizations are on, which is exactly the lesson here.
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wstringop-truncation"
+#endif
+  std::strncat(destination, "1234", 3);
+#if defined(__GNUC__) && !defined(__clang__)
+#pragma GCC diagnostic pop
+#endif
   logString("strncat(3)", destination, sizeof(destination));
 }
 
diff --git a/src/dp/creational/Builder.cpp b/src/dp/creational/Builder.cpp
index e1545fc..bbb0c53 100644
--- a/src/dp/creational/Builder.cpp
+++ b/src/dp/creational/Builder.cpp
@@ -137,7 +137,10 @@ class HttpRequest {
   std::string describe() const {
     std::string text = method_ + " " + url_;
     for (const auto& [name, value] : headers_) {
-      text += "\n      " + name + ": " + value;
+      text += "\n      ";
+      text += name;
+      text += ": ";
+      text += value;
     }
     if (!body_.empty()) {
       text += "\n      body: " + body_;
@@ -173,7 +176,7 @@ class HttpRequest::Builder {
 
   /// Validates before handing out the product.
   HttpRequest build() const {
-    if (request_.url_.rfind("http", 0) != 0) {
+    if (!request_.url_.starts_with("http")) {
       throw std::invalid_argument("URL must start with http: " + request_.url_);
     }
     if (request_.method_ == "GET" && !request_.body_.empty()) {
diff --git a/src/dp/structural/Adapter.cpp b/src/dp/structural/Adapter.cpp
index 06f53de..537b024 100644
--- a/src/dp/structural/Adapter.cpp
+++ b/src/dp/structural/Adapter.cpp
@@ -21,6 +21,7 @@
 // UML: docs/uml/dp/structural_adapter.drawio.svg
 // -----------------------------------------------------------------------------
 
+#include <cmath>
 #include <memory>
 #include <string>
 #include <utility>
@@ -116,7 +117,7 @@ class PayPalAdapter : public PaymentProcessor {
   bool pay(const std::string& customer, double amount_eur) override {
     const std::string email =
         customer + "@example.com";  // look up the PayPal account
-    const auto cents = static_cast<long>(amount_eur * 100.0 + 0.5);
+    const auto cents = std::lround(amount_eur * 100.0);
     return sdk_.sendPayment(email, cents, "EUR") == 0;
   }
 

From 9f043a2aa153d760811f16c16d4b50fc2e30505a Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:41:17 +0700
Subject: [PATCH 12/20] Document the .clang-tidy folded-scalar trap in
 CLAUDE.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 CLAUDE.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 83d2bd3..dae6df0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -86,7 +86,10 @@ clang-tidy -p build $(git ls-files 'src/*.cpp')     # configured by .clang-tidy,
   errors. Intentional findings (teaching demos) are listed in `.cppcheck-suppressions`; note that a
   line containing only `#` breaks that file.
 - `.clang-format` is Google-based with `Standard: c++20`. Do not set it back to `c++11`: the
-  formatter then mangles digit separators such as `1'000'000`.
+  formatter then mangles digit separators such as `1'000'000` and splits `operator<=>`.
+- `.clang-tidy` has `WarningsAsErrors: "*"`, and its `Checks:` value is a YAML folded scalar, so
+  it cannot contain comments - a `#` inside the list silently becomes part of a check name.
+  Explanations therefore live in the comment block above it.
 - Naming (`.clang-tidy`): `lower_case` variables and namespaces, `CamelCase` types, trailing `_` on
   private members, `kName` for constants.
 

From a5c566d39992195efc9912b3c02fff31dfe730ce Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:42:17 +0700
Subject: [PATCH 13/20] Follow the project naming rules in the linkage and
 noexcept examples

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 src/core/exception/ThrowNoexcept.cpp | 8 ++++----
 src/core/linkage/Internal.cpp        | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/core/exception/ThrowNoexcept.cpp b/src/core/exception/ThrowNoexcept.cpp
index 717a620..26cdf85 100644
--- a/src/core/exception/ThrowNoexcept.cpp
+++ b/src/core/exception/ThrowNoexcept.cpp
@@ -66,14 +66,14 @@ struct Counters {
   int moves = 0;
 };
 
-template <bool kNoexceptMove>
+template <bool IsNoexceptMove>
 class Element {
  public:
   explicit Element(Counters& counters) : counters_{&counters} {}
   Element(const Element& other) : counters_{other.counters_} {
     ++counters_->copies;
   }
-  Element(Element&& other) noexcept(kNoexceptMove)
+  Element(Element&& other) noexcept(IsNoexceptMove)
       : counters_{other.counters_} {
     ++counters_->moves;
   }
@@ -85,10 +85,10 @@ class Element {
   Counters* counters_;
 };
 
-template <bool kNoexceptMove>
+template <bool IsNoexceptMove>
 Counters growVector() {
   Counters counters;
-  std::vector<Element<kNoexceptMove>> elements;
+  std::vector<Element<IsNoexceptMove>> elements;
   for (int i = 0; i < 100; ++i) {
     // NOLINTNEXTLINE(performance-inefficient-vector-operation): no reserve on purpose
     elements.emplace_back(counters);  // reallocates several times
diff --git a/src/core/linkage/Internal.cpp b/src/core/linkage/Internal.cpp
index 9beccb8..03a8146 100644
--- a/src/core/linkage/Internal.cpp
+++ b/src/core/linkage/Internal.cpp
@@ -19,14 +19,14 @@ static void func_internal() {
 }
 
 // 2. const and constexpr variables at namespace scope are internal by default.
-const int c_internal{100};
-constexpr int ce_internal{200};
+const int kConstInternal{100};
+constexpr int kConstexprInternal{200};
 
 /// External linkage on purpose: the one door into this file (see Linkage.cpp).
 void printInternals() {
   func_internal();
-  LOG_S("g_internal = " << g_internal << ", c_internal = " << c_internal
-                        << ", ce_internal = " << ce_internal
+  LOG_S("g_internal = " << g_internal << ", kConstInternal = " << kConstInternal
+                        << ", kConstexprInternal = " << kConstexprInternal
                         << ", ns_internal = " << ns_internal);
 }
 

From ab82fe60d79f9e22c0ae934fa479c2d877c38b21 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:42:48 +0700
Subject: [PATCH 14/20] Explain the scratch file in tests/dummy

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 tests/dummy/README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 tests/dummy/README.md

diff --git a/tests/dummy/README.md b/tests/dummy/README.md
new file mode 100644
index 0000000..e34d9d3
--- /dev/null
+++ b/tests/dummy/README.md
@@ -0,0 +1,14 @@
+# dummy
+
+Scratch files that are **not** part of the build or the test suite (the test
+target only compiles `*Test.cpp`).
+
+- `UsbHostSerial_read.cpp` - a standalone reproduction written for a pull
+  request in https://github.com/bertmelis/USBHostSerial. It has no `main()`,
+  so it only compiles to an object file:
+
+  ```bash
+  g++ -std=c++20 -c tests/dummy/UsbHostSerial_read.cpp -o /tmp/usb_read.o
+  ```
+
+  To run `testRead()`, add a `main()` that calls it.

From 0bed552f1d9900ea1d137a02921ef0cefa11911c Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 08:43:41 +0700
Subject: [PATCH 15/20] Add a suggested learning path through the examples

Eight stages from initialization to sockets and firmware, with the take away
for each example, so the lab can be worked through in a sensible order instead
of alphabetically.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 README.md             |   1 +
 docs/README.md        |   1 +
 docs/learning-path.md | 109 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+)
 create mode 100644 docs/learning-path.md

diff --git a/README.md b/README.md
index 05ef958..d9287d5 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@ concurrency, sockets and embedded basics - built with CMake, GoogleTest, cppchec
 Docker and GitHub Actions for CI/CD.
 
 Every example lives in one file, explains itself in a header comment, and can be run on its own.
+New to the material? Follow the [learning path](docs/learning-path.md).
 
 ---
 ## 1. Quick start
diff --git a/docs/README.md b/docs/README.md
index 5815546..95e2ecf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,6 +4,7 @@ Every folder below `src/` is a group in the lab's menu. The README in each folde
 topic, and the examples next to it show it in code. Run any example with
 `./build/bin/cpp_lab_project --run <id>`, or browse them with the interactive menu.
 
+- [Learning path](learning-path.md): a suggested order through the examples
 - [Adding examples](adding-examples.md): how the lab works and how to add your own examples
 
 ---
diff --git a/docs/learning-path.md b/docs/learning-path.md
new file mode 100644
index 0000000..d37b788
--- /dev/null
+++ b/docs/learning-path.md
@@ -0,0 +1,109 @@
+# A learning path through the lab
+
+The menu is organized by topic; this page suggests an order. Run an example with
+
+```bash
+./build/bin/cpp_lab_project --run <id>
+```
+
+and read its source next to the output - the header comment of each file says what it teaches.
+
+---
+## Stage 1 - the language you write every day
+
+| # | Example | Take away |
+|---|---------|-----------|
+| 1 | `core/basics/Initialization` | prefer `{}`; know what stays uninitialized |
+| 2 | `core/basics/Operations` | integer division, unsigned wrap-around, short-circuit |
+| 3 | `core/basics/ControlFlow` | if with initializer, range-for, why `goto` is rare |
+| 4 | `core/datatype/Fundamental` | sizes are minimums; use `<cstdint>` when width matters |
+| 5 | `core/datatype/Struct` | aggregates, designated initializers, padding |
+| 6 | `core/datatype/Enum` | `enum class` over plain `enum` |
+| 7 | `core/basics/TypeQualifier` | const vs constexpr vs consteval |
+
+## Stage 2 - memory and indirection
+
+| # | Example | Take away |
+|---|---------|-----------|
+| 8 | `core/datatype/Pointer` | `&`, `*`, the three const positions, pointer arithmetic |
+| 9 | `core/datatype/Reference` | references cannot be null or re-seated; `std::move` is a cast |
+| 10 | `core/datatype/Array` | arrays decay to pointers and lose their size |
+| 11 | `core/smart_pointer/Unique` | ownership belongs in the type system |
+| 12 | `core/smart_pointer/Shared` | shared ownership costs a control block |
+| 13 | `core/smart_pointer/Weak` | break reference cycles |
+
+## Stage 3 - your own types
+
+| # | Example | Take away |
+|---|---------|-----------|
+| 14 | `core/class/Encapsulation` | invariants live behind a small interface |
+| 15 | `core/class/Constructor` | initializer lists, delegating, explicit |
+| 16 | `core/class/Destructor` | destruction order and RAII |
+| 17 | `core/class/ShallowDeepCopying` | copying a pointer is not copying the data |
+| 18 | `core/class/RuleOfThreeFiveZero` | write five, or better none |
+| 19 | `core/class/Binding` | hiding vs overriding, virtual dispatch |
+| 20 | `core/class/Relationship` | composition, aggregation, association |
+| 21 | `core/function/operator_overloading/ArithmeticOperator` | operators behave like the built-in ones |
+| 22 | `core/function/operator_overloading/ComparisonOperator` | `<=>` writes the comparisons for you |
+
+## Stage 4 - the standard library
+
+| # | Example | Take away |
+|---|---------|-----------|
+| 23 | `core/string/StdString` | `std::string` and `std::string_view` |
+| 24 | `core/string/StringFormatting` | `std::format` beats streams and `printf` |
+| 25 | `core/container/sequence/Vector` | capacity, reallocation, invalidation |
+| 26 | `core/container/unordered/UnorderedMap` | `operator[]` inserts; `find`/`contains` do not |
+| 27 | `core/container/associative/Set` | sorted, unique, `lower_bound` |
+| 28 | `core/utils/Algorithm` | name the loop: algorithms and ranges |
+| 29 | `core/function/Lambda` | captures decide lifetime |
+| 30 | `core/function/Functional` | `std::function` for stored callbacks |
+| 31 | `core/utils/Optional` | say "no value" in the type |
+
+## Stage 5 - failure, files and time
+
+| # | Example | Take away |
+|---|---------|-----------|
+| 32 | `core/exception/BasicHandle` | throw by value, catch by const reference |
+| 33 | `core/exception/ThrowNoexcept` | `noexcept` moves make containers fast |
+| 34 | `core/filehandle/IOStream` | stream states and input validation |
+| 35 | `core/filehandle/FileIO` | text files with RAII |
+| 36 | `core/filehandle/Directory` | `std::filesystem` |
+| 37 | `core/datetime/Time` | `<chrono>` and the C time API |
+
+## Stage 6 - concurrency
+
+| # | Example | Take away |
+|---|---------|-----------|
+| 38 | `core/concurrency/ThreadManagement` | join or `std::jthread`, never a dangling thread |
+| 39 | `core/concurrency/SharingData` | arguments are copied unless you say otherwise |
+| 40 | `core/concurrency/RaceCondition` | see updates get lost, then fix it |
+| 41 | `core/concurrency/ConditionVariable` | wait with a predicate |
+| 42 | `core/concurrency/FuturePromise` | results and exceptions across threads |
+
+## Stage 7 - design patterns
+
+Start with the ones you will recognize immediately:
+`dp/creational/FactoryMethod`, `dp/structural/Adapter`, `dp/structural/Decorator`,
+`dp/behavioral/Strategy`, `dp/behavioral/Observer`, `dp/behavioral/Command`.
+
+Then the rest of `dp/creational`, `dp/structural` and `dp/behavioral`. Each example first shows
+the problem the pattern solves; several end with the modern C++ alternative (`std::function`,
+`std::variant`, ranges).
+
+## Stage 8 - systems and applications
+
+| Example / program | Take away |
+|---|---|
+| `core/linkage/Linkage`, `core/linkage/sharing/Sharing` | what the linker sees |
+| `socket/simple_tcp/LoopbackEcho` | sockets end to end in one process |
+| `socket/simple_tcp/SimpleTCPServer` + `SimpleTCPClient` | the same across two processes |
+| `socket/multiple_client/MultiTCPServer` | a thread per connection |
+| `controller/pid/PIDSim` | a control loop |
+| `./build/bin/mvc_ap`, `./build/bin/mvvm_ap` | the same GUI with two architectures |
+| `./build/bin/demo_dlopen` | loading a plugin at run time |
+| `src/embedded` | a firmware image booting in QEMU |
+
+---
+When something surprises you, change the example and rebuild - that is what the lab is for.
+Then write your own: see [adding-examples.md](adding-examples.md).

From e463c9ba3f9403eff563912f10ff011d31a77518 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 09:05:12 +0700
Subject: [PATCH 16/20] Fix the clang-tidy findings and format the whole tree

Replace rfind(x, 0) == 0 with starts_with, std::string_view::npos for
option.npos, rename the command line lambdas and the local error message to
lower_case, pass the MVC widget colour by value, reserve in the registry test
helper, give FakeTurtle's switch a default case, and rename the Logger's
source_location parameter to loc so the declarations fit in 80 columns.

tests/dummy keeps scratch code exactly as it is written upstream, so a local
.clang-tidy disables every check there instead of reformatting it.

Also run clang-format over the tree: nine files had drifted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 include/lab/Logger.h                         |  17 ++--
 include/lab/Registry.h                       |   9 +-
 src/ap/mvc/view/DisplayWidget.cpp            |   6 +-
 src/ap/mvc/view/DisplayWidget.h              |   2 +-
 src/core/container/adapter/PriorityQueue.cpp |  10 +-
 src/lab/CommandLine.cpp                      |  41 ++++----
 src/lab/Logger.cpp                           |  22 ++--
 src/lab/Menu.cpp                             |  22 ++--
 src/lab/Registry.cpp                         |  22 ++--
 src/socket/simple_tcp/LoopbackEcho.cpp       |  12 ++-
 tests/dummy/.clang-tidy                      |   5 +
 tests/gtest_primer/CalculatorTest.cpp        |   9 +-
 tests/gtest_primer/TurtleMockTest.cpp        |   3 +-
 tests/lab/CommandLineTest.cpp                |  10 +-
 tests/lab/MenuRunnerTest.cpp                 |  46 ++++-----
 tests/lab/RegistryTest.cpp                   | 102 +++++++++++--------
 tests/mock/FakeTurtle.h                      |   2 +
 17 files changed, 188 insertions(+), 152 deletions(-)
 create mode 100644 tests/dummy/.clang-tidy

diff --git a/include/lab/Logger.h b/include/lab/Logger.h
index 1cda0bb..eb95701 100644
--- a/include/lab/Logger.h
+++ b/include/lab/Logger.h
@@ -22,13 +22,12 @@ class Logger {
 
   /// Prints one line. A single trailing '\n' in `message` is dropped.
   void log(std::string_view message,
-           const std::source_location& location =
-               std::source_location::current());
+           const std::source_location& loc = std::source_location::current());
 
   /// Prints the full signature of the calling function. Handy to see which
   /// overload, constructor or operator the compiler picked.
-  void logFunction(const std::source_location& location =
-                       std::source_location::current());
+  void logFunction(
+      const std::source_location& loc = std::source_location::current());
 
   /// Prints a visual separator: "--- title -----------".
   void section(std::string_view title);
@@ -39,7 +38,7 @@ class Logger {
 
  private:
   Logger();
-  void write(std::string_view message, const std::source_location& location,
+  void write(std::string_view message, const std::source_location& loc,
              bool with_function);
 
   std::mutex mutex_;
@@ -53,10 +52,10 @@ class Logger {
 #define LOG(message) ::lab::Logger::instance().log(message)
 
 /// LOG_S("x = " << x) - log anything that can be streamed into std::ostream.
-#define LOG_S(...)                                   \
-  do {                                               \
-    std::ostringstream lab_log_stream_;              \
-    lab_log_stream_ << __VA_ARGS__;                  \
+#define LOG_S(...)                                        \
+  do {                                                    \
+    std::ostringstream lab_log_stream_;                   \
+    lab_log_stream_ << __VA_ARGS__;                       \
     ::lab::Logger::instance().log(lab_log_stream_.str()); \
   } while (false)
 
diff --git a/include/lab/Registry.h b/include/lab/Registry.h
index a15e155..de36dc4 100644
--- a/include/lab/Registry.h
+++ b/include/lab/Registry.h
@@ -18,10 +18,13 @@ enum ExampleFlags : unsigned {
 using ExampleFunction = void (*)();
 
 /// Metadata and entry point of one runnable example.
+///
+/// For LAB_EXAMPLE("Weak", ...) in src/core/smart_pointer/Weak.cpp the registry
+/// derives group = "core/smart_pointer" and id = "core/smart_pointer/Weak".
 struct Example {
-  std::string id;           ///< "<group>/<name>", e.g. "core/smart_pointer/Weak"
-  std::string group;        ///< source directory below src/, e.g. "core/smart_pointer"
-  std::string name;         ///< short name shown in the menu, e.g. "Weak"
+  std::string id;           ///< unique "<group>/<name>" identifier
+  std::string group;        ///< source directory below src/
+  std::string name;         ///< short name shown in the menu
   std::string description;  ///< one-line summary
   std::string source;       ///< path relative to the repository root
   ExampleFunction run{nullptr};
diff --git a/src/ap/mvc/view/DisplayWidget.cpp b/src/ap/mvc/view/DisplayWidget.cpp
index 2eb6fdc..dc121fd 100644
--- a/src/ap/mvc/view/DisplayWidget.cpp
+++ b/src/ap/mvc/view/DisplayWidget.cpp
@@ -1,9 +1,11 @@
 #include "DisplayWidget.h"
 
-DisplayWidget::DisplayWidget(const std::string& title, const std::string& color,
+#include <utility>
+
+DisplayWidget::DisplayWidget(const std::string& title, std::string color,
                              const std::string& startData)
     : Gtk::Box(Gtk::Orientation::VERTICAL),
-      color_(color),
+      color_(std::move(color)),
       innerBox_(Gtk::Orientation::VERTICAL) {
   frame_.set_label(title);
   frame_.set_margin(10);
diff --git a/src/ap/mvc/view/DisplayWidget.h b/src/ap/mvc/view/DisplayWidget.h
index 627848d..ca182a7 100644
--- a/src/ap/mvc/view/DisplayWidget.h
+++ b/src/ap/mvc/view/DisplayWidget.h
@@ -5,7 +5,7 @@
 
 class DisplayWidget : public Gtk::Box, public IObserver {
  public:
-  DisplayWidget(const std::string& title, const std::string& color,
+  DisplayWidget(const std::string& title, std::string color,
                 const std::string& startData);
 
   void onDataChanged(const std::string& newData) override;
diff --git a/src/core/container/adapter/PriorityQueue.cpp b/src/core/container/adapter/PriorityQueue.cpp
index 3a30bdc..aebd2b4 100644
--- a/src/core/container/adapter/PriorityQueue.cpp
+++ b/src/core/container/adapter/PriorityQueue.cpp
@@ -30,8 +30,8 @@ void maxAndMinHeap() {
   const std::vector<int> values{5, 1, 8, 3, 9, 2};
 
   std::priority_queue<int> max_heap(values.begin(), values.end());
-  std::priority_queue<int, std::vector<int>, std::greater<>> min_heap(values.begin(),
-                                                                      values.end());
+  std::priority_queue<int, std::vector<int>, std::greater<>> min_heap(
+      values.begin(), values.end());
 
   std::string max_order;
   std::string min_order;
@@ -65,14 +65,16 @@ void customComparator() {
   tasks.push({"code review", 5});
 
   while (!tasks.empty()) {
-    LOG_S("serve '" << tasks.top().name << "' (priority " << tasks.top().priority << ")");
+    LOG_S("serve '" << tasks.top().name << "' (priority "
+                    << tasks.top().priority << ")");
     tasks.pop();
   }
 }
 
 }  // namespace
 
-LAB_EXAMPLE("PriorityQueue", "std::priority_queue: max-heap, min-heap, custom priority") {
+LAB_EXAMPLE("PriorityQueue",
+            "std::priority_queue: max-heap, min-heap, custom priority") {
   maxAndMinHeap();
   customComparator();
 }
diff --git a/src/lab/CommandLine.cpp b/src/lab/CommandLine.cpp
index 4d68cd3..c535d1c 100644
--- a/src/lab/CommandLine.cpp
+++ b/src/lab/CommandLine.cpp
@@ -8,9 +8,9 @@ namespace {
 
 std::string toLower(std::string_view text) {
   std::string lower(text);
-  std::transform(lower.begin(), lower.end(), lower.begin(), [](unsigned char c) {
-    return static_cast<char>(std::tolower(c));
-  });
+  std::transform(
+      lower.begin(), lower.end(), lower.begin(),
+      [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
   return lower;
 }
 
@@ -55,25 +55,26 @@ ParseResult parseCommandLine(const std::vector<std::string_view>& args) {
 
     // Support both "--run id" and "--run=id".
     std::optional<std::string_view> inline_value;
-    if (option.rfind("--", 0) == 0) {
-      if (const auto equals = option.find('='); equals != option.npos) {
+    if (option.starts_with("--")) {
+      if (const auto equals = option.find('=');
+          equals != std::string_view::npos) {
         inline_value = option.substr(equals + 1);
         option = option.substr(0, equals);
       }
     }
 
     // Returns the value that follows the option, if there is one.
-    auto takeValue = [&]() -> std::optional<std::string_view> {
+    auto take_value = [&]() -> std::optional<std::string_view> {
       if (inline_value) {
         return inline_value;
       }
-      if (i + 1 < args.size() && args[i + 1].rfind('-', 0) != 0) {
+      if (i + 1 < args.size() && !args[i + 1].starts_with('-')) {
         return args[++i];
       }
       return std::nullopt;
     };
 
-    auto setCommand = [&](Command command) {
+    auto set_command = [&](Command command) {
       if (command_given) {
         return false;
       }
@@ -81,17 +82,17 @@ ParseResult parseCommandLine(const std::vector<std::string_view>& args) {
       command_given = true;
       return true;
     };
-    const std::string kOneCommand =
+    const std::string one_command_error =
         "only one of --list, --list-ids, --run, --run-all, --help and "
         "--version can be used at a time";
 
     if (option == "-h" || option == "--help") {
-      if (!setCommand(Command::kHelp)) {
-        return failure(kOneCommand);
+      if (!set_command(Command::kHelp)) {
+        return failure(one_command_error);
       }
     } else if (option == "-v" || option == "--version") {
-      if (!setCommand(Command::kVersion)) {
-        return failure(kOneCommand);
+      if (!set_command(Command::kVersion)) {
+        return failure(one_command_error);
       }
     } else if (option == "-l" || option == "--list" || option == "--list-ids" ||
                option == "-a" || option == "--run-all") {
@@ -101,17 +102,17 @@ ParseResult parseCommandLine(const std::vector<std::string_view>& args) {
       } else if (option == "--list-ids") {
         command = Command::kListIds;
       }
-      if (!setCommand(command)) {
-        return failure(kOneCommand);
+      if (!set_command(command)) {
+        return failure(one_command_error);
       }
-      if (auto value = takeValue()) {
+      if (auto value = take_value()) {
         cli.argument = std::string(*value);
       }
     } else if (option == "-r" || option == "--run") {
-      if (!setCommand(Command::kRun)) {
-        return failure(kOneCommand);
+      if (!set_command(Command::kRun)) {
+        return failure(one_command_error);
       }
-      auto value = takeValue();
+      auto value = take_value();
       if (!value || value->empty()) {
         return failure("--run needs an example id or filter");
       }
@@ -119,7 +120,7 @@ ParseResult parseCommandLine(const std::vector<std::string_view>& args) {
     } else if (option == "--plain") {
       cli.plain = true;
     } else if (option == "--mode" || option == "-mode") {
-      auto value = takeValue();
+      auto value = take_value();
       if (!value) {
         return failure("--mode needs a value: dev, uat or prod");
       }
diff --git a/src/lab/Logger.cpp b/src/lab/Logger.cpp
index 3bb3932..e8a169e 100644
--- a/src/lab/Logger.cpp
+++ b/src/lab/Logger.cpp
@@ -53,16 +53,16 @@ Logger& Logger::instance() {
 }
 
 Logger::Logger()
-    : show_location_{kShowLocationByDefault}, use_color_{stdoutSupportsColor()} {}
+    : show_location_{kShowLocationByDefault},
+      use_color_{stdoutSupportsColor()} {}
 
-void Logger::log(std::string_view message,
-                 const std::source_location& location) {
-  write(message, location, /*with_function=*/true);
+void Logger::log(std::string_view message, const std::source_location& loc) {
+  write(message, loc, /*with_function=*/true);
 }
 
-void Logger::logFunction(const std::source_location& location) {
+void Logger::logFunction(const std::source_location& loc) {
   // The function name is the message, so it is not repeated in the prefix.
-  write(location.function_name(), location, /*with_function=*/false);
+  write(loc.function_name(), loc, /*with_function=*/false);
 }
 
 void Logger::section(std::string_view title) {
@@ -83,18 +83,18 @@ void Logger::section(std::string_view title) {
   }
 }
 
-void Logger::write(std::string_view message,
-                   const std::source_location& location, bool with_function) {
+void Logger::write(std::string_view message, const std::source_location& loc,
+                   bool with_function) {
   if (!message.empty() && message.back() == '\n') {
     message.remove_suffix(1);
   }
 
   const std::lock_guard<std::mutex> lock(mutex_);
   if (show_location_) {
-    std::cout << '[' << currentTime() << "][" << fileName(location.file_name())
-              << ':' << location.line() << ']';
+    std::cout << '[' << currentTime() << "][" << fileName(loc.file_name())
+              << ':' << loc.line() << ']';
     if (with_function) {
-      std::cout << '[' << location.function_name() << ']';
+      std::cout << '[' << loc.function_name() << ']';
     }
     std::cout << ' ';
   }
diff --git a/src/lab/Menu.cpp b/src/lab/Menu.cpp
index 9cce3ae..7250a05 100644
--- a/src/lab/Menu.cpp
+++ b/src/lab/Menu.cpp
@@ -26,9 +26,9 @@ struct MenuNode {
 };
 
 MenuNode& childNamed(MenuNode& parent, const std::string& name) {
-  const auto it =
-      std::find_if(parent.children.begin(), parent.children.end(),
-                   [&name](const MenuNode& child) { return child.name == name; });
+  const auto it = std::find_if(
+      parent.children.begin(), parent.children.end(),
+      [&name](const MenuNode& child) { return child.name == name; });
   if (it != parent.children.end()) {
     return *it;
   }
@@ -40,8 +40,9 @@ MenuNode& childNamed(MenuNode& parent, const std::string& name) {
 }
 
 void sortChildren(MenuNode& node) {
-  std::sort(node.children.begin(), node.children.end(),
-            [](const MenuNode& a, const MenuNode& b) { return a.name < b.name; });
+  std::sort(
+      node.children.begin(), node.children.end(),
+      [](const MenuNode& a, const MenuNode& b) { return a.name < b.name; });
   for (MenuNode& child : node.children) {
     sortChildren(child);
   }
@@ -109,14 +110,13 @@ void printNode(const MenuNode& node, bool is_root, std::ostream& out) {
 
   std::size_t index = 1;
   for (const MenuNode& child : node.children) {
-    out << std::setw(4) << index++ << ". " << std::left
-        << std::setw(kNameWidth) << (child.name + "/") << std::right << ' '
-        << countLabel(child.total) << '\n';
+    out << std::setw(4) << index++ << ". " << std::left << std::setw(kNameWidth)
+        << (child.name + "/") << std::right << ' ' << countLabel(child.total)
+        << '\n';
   }
   for (const Example* example : node.examples) {
-    out << std::setw(4) << index++ << ". " << std::left
-        << std::setw(kNameWidth) << example->name << std::right << ' '
-        << example->description
+    out << std::setw(4) << index++ << ". " << std::left << std::setw(kNameWidth)
+        << example->name << std::right << ' ' << example->description
         << (example->isInteractive() ? "  [interactive]" : "") << '\n';
   }
   out << rule << '\n'
diff --git a/src/lab/Registry.cpp b/src/lab/Registry.cpp
index 8916c3d..358167f 100644
--- a/src/lab/Registry.cpp
+++ b/src/lab/Registry.cpp
@@ -15,9 +15,9 @@ namespace {
 
 std::string toLower(std::string_view text) {
   std::string lower(text);
-  std::transform(lower.begin(), lower.end(), lower.begin(), [](unsigned char c) {
-    return static_cast<char>(std::tolower(c));
-  });
+  std::transform(
+      lower.begin(), lower.end(), lower.begin(),
+      [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
   return lower;
 }
 
@@ -59,14 +59,14 @@ std::string relativeSourcePath(std::string_view file,
     if (root.back() != '/') {
       root.push_back('/');
     }
-    if (path.rfind(root, 0) == 0) {
+    if (path.starts_with(root)) {
       return path.substr(root.size());
     }
   }
 
   // Fallback when __FILE__ is not below the root (e.g. relative paths):
   // keep everything from the last "src/" directory on.
-  if (path.rfind("src/", 0) == 0) {
+  if (path.starts_with("src/")) {
     return path;
   }
   if (const auto pos = path.rfind("/src/"); pos != std::string::npos) {
@@ -77,7 +77,7 @@ std::string relativeSourcePath(std::string_view file,
 
 std::string groupFromSourcePath(std::string_view relative_path) {
   std::string_view path = relative_path;
-  if (path.rfind("src/", 0) == 0) {
+  if (path.starts_with("src/")) {
     path.remove_prefix(4);
   }
   const auto slash = path.rfind('/');
@@ -120,11 +120,11 @@ bool Registry::add(std::string_view file, std::string_view name,
     return false;
   }
 
-  const auto position = std::lower_bound(
-      examples_.begin(), examples_.end(), example.id,
-      [](const Example& existing, const std::string& id) {
-        return lessIgnoreCase(existing.id, id);
-      });
+  const auto position =
+      std::lower_bound(examples_.begin(), examples_.end(), example.id,
+                       [](const Example& existing, const std::string& id) {
+                         return lessIgnoreCase(existing.id, id);
+                       });
   if (position != examples_.end() &&
       equalIgnoreCase(position->id, example.id)) {
     errors_.push_back("duplicate example id '" + example.id + "' in " +
diff --git a/src/socket/simple_tcp/LoopbackEcho.cpp b/src/socket/simple_tcp/LoopbackEcho.cpp
index 9898558..0f4d1e7 100644
--- a/src/socket/simple_tcp/LoopbackEcho.cpp
+++ b/src/socket/simple_tcp/LoopbackEcho.cpp
@@ -41,12 +41,15 @@ void run() {
   net::TCPClient client{"127.0.0.1", server.boundPort()};
   if (client.connect()) {
     LOG_S("client got: " << trimmed(client.receive()));
-    for (const std::string message : {"hello", "sockets are file descriptors", "Q"}) {
+    for (const std::string message :
+         {"hello", "sockets are file descriptors", "Q"}) {
       client.send(message + "\n");
-      LOG_S("client sent \"" << message << "\", echo: \"" << trimmed(client.receive()) << '"');
+      LOG_S("client sent \"" << message << "\", echo: \""
+                             << trimmed(client.receive()) << '"');
     }
     const std::string after_quit = client.receive();
-    LOG_S("after Q the server closed the connection: " << std::boolalpha << after_quit.empty());
+    LOG_S("after Q the server closed the connection: " << std::boolalpha
+                                                       << after_quit.empty());
   }
 
   LOG_SECTION("Stopping the server");
@@ -56,6 +59,7 @@ void run() {
 
 }  // namespace
 
-LAB_EXAMPLE("LoopbackEcho", "TCP server thread and client in one process over 127.0.0.1") {
+LAB_EXAMPLE("LoopbackEcho",
+            "TCP server thread and client in one process over 127.0.0.1") {
   run();
 }
diff --git a/tests/dummy/.clang-tidy b/tests/dummy/.clang-tidy
new file mode 100644
index 0000000..8fce3cc
--- /dev/null
+++ b/tests/dummy/.clang-tidy
@@ -0,0 +1,5 @@
+---
+# tests/dummy holds scratch files that reproduce third-party code as it is
+# written upstream. They are not part of the build, and reformatting them to
+# this project's conventions would destroy that fidelity, so no check runs here.
+Checks: "-*"
diff --git a/tests/gtest_primer/CalculatorTest.cpp b/tests/gtest_primer/CalculatorTest.cpp
index 8d2a6f8..76b79b5 100644
--- a/tests/gtest_primer/CalculatorTest.cpp
+++ b/tests/gtest_primer/CalculatorTest.cpp
@@ -21,7 +21,8 @@ TEST(CalculatorAddTest, AddsPositiveAndNegativeNumbers) {
   EXPECT_EQ(calculator.lastResult(), 3);
 
   calculator.add(4, -6);
-  EXPECT_EQ(calculator.lastResult(), -2) << "a custom message explains a failure";
+  EXPECT_EQ(calculator.lastResult(), -2)
+      << "a custom message explains a failure";
 
   calculator.add(-4, -6);
   EXPECT_EQ(calculator.lastResult(), -10);
@@ -48,7 +49,8 @@ TEST_F(CalculatorDivideTest, DivisionByZeroFailsAndResetsTheResult) {
 }
 
 // TEST_P - one test body, many inputs.
-class CalculatorMultiplyTest : public testing::TestWithParam<std::tuple<int, int, int>> {};
+class CalculatorMultiplyTest
+    : public testing::TestWithParam<std::tuple<int, int, int>> {};
 
 TEST_P(CalculatorMultiplyTest, MultipliesTwoNumbers) {
   const auto [lhs, rhs, expected] = GetParam();
@@ -58,7 +60,8 @@ TEST_P(CalculatorMultiplyTest, MultipliesTwoNumbers) {
 }
 
 INSTANTIATE_TEST_SUITE_P(Values, CalculatorMultiplyTest,
-                         testing::Values(std::make_tuple(2, 3, 6), std::make_tuple(-2, 3, -6),
+                         testing::Values(std::make_tuple(2, 3, 6),
+                                         std::make_tuple(-2, 3, -6),
                                          std::make_tuple(0, 99, 0),
                                          std::make_tuple(-4, -5, 20)));
 
diff --git a/tests/gtest_primer/TurtleMockTest.cpp b/tests/gtest_primer/TurtleMockTest.cpp
index 1a21949..b245510 100644
--- a/tests/gtest_primer/TurtleMockTest.cpp
+++ b/tests/gtest_primer/TurtleMockTest.cpp
@@ -37,7 +37,8 @@ TEST(MockPainterTest, PenGoesDownBeforeMovingAndUpAtTheEnd) {
   const Painter painter{turtle};
 
   {
-    const InSequence in_order;  // the following expectations must happen in this order
+    // The expectations below must happen in this order.
+    const InSequence in_order;
     EXPECT_CALL(turtle, PenDown());
     EXPECT_CALL(turtle, Forward(10)).Times(4);
     EXPECT_CALL(turtle, PenUp());
diff --git a/tests/lab/CommandLineTest.cpp b/tests/lab/CommandLineTest.cpp
index 102c1d3..d9b13f4 100644
--- a/tests/lab/CommandLineTest.cpp
+++ b/tests/lab/CommandLineTest.cpp
@@ -37,7 +37,8 @@ TEST(CommandLineTest, RunRequiresAnId) {
   EXPECT_EQ(result.value->argument, "core/smart_pointer/Weak");
 
   EXPECT_FALSE(parse({"--run"}).value.has_value());
-  EXPECT_FALSE(parse({"--run", "--plain"}).value.has_value());  // an option is not an id
+  EXPECT_FALSE(
+      parse({"--run", "--plain"}).value.has_value());  // an option is not an id
 }
 
 TEST(CommandLineTest, SupportsEqualsSyntax) {
@@ -75,7 +76,8 @@ TEST(CommandLineTest, LegacySingleDashModeStillWorks) {
 }
 
 TEST(AppModeTest, RoundTripsThroughStrings) {
-  for (const lab::AppMode mode : {lab::AppMode::kDev, lab::AppMode::kUat, lab::AppMode::kProd}) {
+  for (const lab::AppMode mode :
+       {lab::AppMode::kDev, lab::AppMode::kUat, lab::AppMode::kProd}) {
     const auto parsed = lab::parseAppMode(lab::toString(mode));
     ASSERT_TRUE(parsed.has_value());
     EXPECT_EQ(*parsed, mode);
@@ -84,8 +86,8 @@ TEST(AppModeTest, RoundTripsThroughStrings) {
 
 TEST(UsageTest, MentionsEveryCommand) {
   const std::string text = lab::usage("cpp_lab_project");
-  for (const char* option : {"--list", "--run", "--run-all", "--list-ids", "--plain", "--mode",
-                             "--version", "--help"}) {
+  for (const char* option : {"--list", "--run", "--run-all", "--list-ids",
+                             "--plain", "--mode", "--version", "--help"}) {
     EXPECT_NE(text.find(option), std::string::npos) << option;
   }
 }
diff --git a/tests/lab/MenuRunnerTest.cpp b/tests/lab/MenuRunnerTest.cpp
index 3de6fa4..d0cf3ba 100644
--- a/tests/lab/MenuRunnerTest.cpp
+++ b/tests/lab/MenuRunnerTest.cpp
@@ -33,54 +33,54 @@ class MenuRunnerTest : public testing::Test {
     g_first_runs = 0;
     g_second_runs = 0;
     g_interactive_runs = 0;
-    registry.add("/x/src/topic/basics/A.cpp", "First", "first example", first);
-    registry.add("/x/src/topic/advanced/B.cpp", "Second", "second example",
-                 second);
-    registry.add("/x/src/topic/advanced/C.cpp", "Server", "needs a client",
-                 interactive, lab::kInteractive);
+    registry_.add("/x/src/topic/basics/A.cpp", "First", "first example", first);
+    registry_.add("/x/src/topic/advanced/B.cpp", "Second", "second example",
+                  second);
+    registry_.add("/x/src/topic/advanced/C.cpp", "Server", "needs a client",
+                  interactive, lab::kInteractive);
   }
 
-  lab::Registry registry;
-  std::ostringstream out;
+  lab::Registry registry_;
+  std::ostringstream out_;
 };
 
 TEST_F(MenuRunnerTest, RunExampleReportsSuccess) {
-  EXPECT_TRUE(lab::runExample(registry.examples().front(), out));
-  EXPECT_NE(out.str().find("finished"), std::string::npos);
+  EXPECT_TRUE(lab::runExample(registry_.examples().front(), out_));
+  EXPECT_NE(out_.str().find("finished"), std::string::npos);
 }
 
 TEST_F(MenuRunnerTest, RunExampleCatchesExceptions) {
   lab::Registry failing;
   failing.add("/x/src/topic/Bad.cpp", "Bad", "throws", throws);
-  EXPECT_FALSE(lab::runExample(failing.examples().front(), out));
-  EXPECT_NE(out.str().find("boom"), std::string::npos);
-  EXPECT_NE(out.str().find("FAILED"), std::string::npos);
+  EXPECT_FALSE(lab::runExample(failing.examples().front(), out_));
+  EXPECT_NE(out_.str().find("boom"), std::string::npos);
+  EXPECT_NE(out_.str().find("FAILED"), std::string::npos);
 }
 
 TEST_F(MenuRunnerTest, RunAllSkipsInteractiveExamples) {
-  EXPECT_EQ(lab::runAll(registry, "", out), 0);
+  EXPECT_EQ(lab::runAll(registry_, "", out_), 0);
   EXPECT_EQ(g_first_runs, 1);
   EXPECT_EQ(g_second_runs, 1);
   EXPECT_EQ(g_interactive_runs, 0);
-  EXPECT_NE(out.str().find("skipped 1 interactive"), std::string::npos);
+  EXPECT_NE(out_.str().find("skipped 1 interactive"), std::string::npos);
 }
 
 TEST_F(MenuRunnerTest, RunAllReportsAFilterThatMatchesNothing) {
-  EXPECT_EQ(lab::runAll(registry, "nothing matches this", out), 0);
+  EXPECT_EQ(lab::runAll(registry_, "nothing matches this", out_), 0);
   EXPECT_EQ(g_first_runs + g_second_runs, 0);
-  EXPECT_NE(out.str().find("No example matches"), std::string::npos);
+  EXPECT_NE(out_.str().find("No example matches"), std::string::npos);
 }
 
 TEST_F(MenuRunnerTest, RunAllHonorsTheFilter) {
-  EXPECT_EQ(lab::runAll(registry, "basics", out), 0);
+  EXPECT_EQ(lab::runAll(registry_, "basics", out_), 0);
   EXPECT_EQ(g_first_runs, 1);
   EXPECT_EQ(g_second_runs, 0);
 }
 
 TEST_F(MenuRunnerTest, MenuShowsFoldersAndQuits) {
   std::istringstream in("q\n");
-  lab::runMenu(registry, in, out);
-  const std::string text = out.str();
+  lab::runMenu(registry_, in, out_);
+  const std::string text = out_.str();
   EXPECT_NE(text.find("topic/"), std::string::npos);
   EXPECT_NE(text.find("3 examples"), std::string::npos);
 }
@@ -89,26 +89,26 @@ TEST_F(MenuRunnerTest, MenuNavigatesFoldersAndRunsAnExample) {
   // root -> 1 (topic/) -> 2 (basics/, folders are sorted: advanced, basics)
   //      -> 1 (First) -> Enter to continue -> quit
   std::istringstream in("1\n2\n1\n\nq\n");
-  lab::runMenu(registry, in, out);
+  lab::runMenu(registry_, in, out_);
   EXPECT_EQ(g_first_runs, 1);
   EXPECT_EQ(g_second_runs, 0);
 }
 
 TEST_F(MenuRunnerTest, MenuSearchRunsTheChosenMatch) {
   std::istringstream in("second\n1\n\nq\n");
-  lab::runMenu(registry, in, out);
+  lab::runMenu(registry_, in, out_);
   EXPECT_EQ(g_second_runs, 1);
 }
 
 TEST_F(MenuRunnerTest, MenuEndsWhenInputEnds) {
   std::istringstream in("1\n");  // no quit command: EOF must not loop forever
-  lab::runMenu(registry, in, out);
+  lab::runMenu(registry_, in, out_);
   SUCCEED();
 }
 
 TEST_F(MenuRunnerTest, BackFromTheTopFolderQuits) {
   std::istringstream in("0\n");
-  lab::runMenu(registry, in, out);
+  lab::runMenu(registry_, in, out_);
   EXPECT_EQ(g_first_runs + g_second_runs, 0);
 }
 
diff --git a/tests/lab/RegistryTest.cpp b/tests/lab/RegistryTest.cpp
index 5aa18b8..611380b 100644
--- a/tests/lab/RegistryTest.cpp
+++ b/tests/lab/RegistryTest.cpp
@@ -12,6 +12,7 @@ void noop() {}
 
 std::vector<std::string> ids(const std::vector<const lab::Example*>& examples) {
   std::vector<std::string> result;
+  result.reserve(examples.size());
   for (const lab::Example* example : examples) {
     result.push_back(example->id);
   }
@@ -21,18 +22,22 @@ std::vector<std::string> ids(const std::vector<const lab::Example*>& examples) {
 TEST(RelativeSourcePathTest, StripsTheSourceRoot) {
   EXPECT_EQ(lab::detail::relativeSourcePath("/repo/src/core/Weak.cpp", "/repo"),
             "src/core/Weak.cpp");
-  EXPECT_EQ(lab::detail::relativeSourcePath("/repo/src/core/Weak.cpp", "/repo/"),
-            "src/core/Weak.cpp");
+  EXPECT_EQ(
+      lab::detail::relativeSourcePath("/repo/src/core/Weak.cpp", "/repo/"),
+      "src/core/Weak.cpp");
 }
 
 TEST(RelativeSourcePathTest, FallsBackToTheLastSrcDirectory) {
-  EXPECT_EQ(lab::detail::relativeSourcePath("/elsewhere/src/dp/Proxy.cpp", "/repo"),
+  EXPECT_EQ(
+      lab::detail::relativeSourcePath("/elsewhere/src/dp/Proxy.cpp", "/repo"),
+      "src/dp/Proxy.cpp");
+  EXPECT_EQ(lab::detail::relativeSourcePath("src/dp/Proxy.cpp", ""),
             "src/dp/Proxy.cpp");
-  EXPECT_EQ(lab::detail::relativeSourcePath("src/dp/Proxy.cpp", ""), "src/dp/Proxy.cpp");
 }
 
 TEST(RelativeSourcePathTest, NormalizesBackslashes) {
-  EXPECT_EQ(lab::detail::relativeSourcePath(R"(C:\repo\src\core\Weak.cpp)", R"(C:\repo)"),
+  EXPECT_EQ(lab::detail::relativeSourcePath(R"(C:\repo\src\core\Weak.cpp)",
+                                            R"(C:\repo)"),
             "src/core/Weak.cpp");
 }
 
@@ -40,7 +45,8 @@ TEST(GroupFromSourcePathTest, UsesTheDirectoryBelowSrc) {
   EXPECT_EQ(lab::detail::groupFromSourcePath("src/core/smart_pointer/Weak.cpp"),
             "core/smart_pointer");
   EXPECT_EQ(lab::detail::groupFromSourcePath("src/dp/Proxy.cpp"), "dp");
-  EXPECT_EQ(lab::detail::groupFromSourcePath("tests/lab/RegistryTest.cpp"), "tests/lab");
+  EXPECT_EQ(lab::detail::groupFromSourcePath("tests/lab/RegistryTest.cpp"),
+            "tests/lab");
 }
 
 TEST(GroupFromSourcePathTest, FilesWithoutADirectoryGoToMisc) {
@@ -50,80 +56,86 @@ TEST(GroupFromSourcePathTest, FilesWithoutADirectoryGoToMisc) {
 
 class RegistryTest : public testing::Test {
  protected:
-  lab::Registry registry;  // a fresh registry per test, not the global one
+  lab::Registry registry_;  // a fresh registry per test, not the global one
 };
 
 TEST_F(RegistryTest, BuildsIdGroupAndSourceFromTheFilePath) {
-  ASSERT_TRUE(registry.add("/x/src/core/smart_pointer/Weak.cpp", "Weak", "weak_ptr", noop));
+  ASSERT_TRUE(registry_.add("/x/src/core/smart_pointer/Weak.cpp", "Weak",
+                            "weak_ptr", noop));
 
-  ASSERT_EQ(registry.examples().size(), 1U);
-  const lab::Example& example = registry.examples().front();
+  ASSERT_EQ(registry_.examples().size(), 1U);
+  const lab::Example& example = registry_.examples().front();
   EXPECT_EQ(example.id, "core/smart_pointer/Weak");
   EXPECT_EQ(example.group, "core/smart_pointer");
   EXPECT_EQ(example.name, "Weak");
   EXPECT_EQ(example.description, "weak_ptr");
   EXPECT_EQ(example.source, "src/core/smart_pointer/Weak.cpp");
   EXPECT_FALSE(example.isInteractive());
-  EXPECT_TRUE(registry.errors().empty());
+  EXPECT_TRUE(registry_.errors().empty());
 }
 
 TEST_F(RegistryTest, KeepsExamplesSortedCaseInsensitively) {
-  registry.add("/x/src/b/File.cpp", "zeta", "", noop);
-  registry.add("/x/src/a/File.cpp", "Beta", "", noop);
-  registry.add("/x/src/a/File.cpp", "alpha", "", noop);
+  registry_.add("/x/src/b/File.cpp", "zeta", "", noop);
+  registry_.add("/x/src/a/File.cpp", "Beta", "", noop);
+  registry_.add("/x/src/a/File.cpp", "alpha", "", noop);
 
   std::vector<std::string> order;
-  for (const lab::Example& example : registry.examples()) {
+  for (const lab::Example& example : registry_.examples()) {
     order.push_back(example.id);
   }
   EXPECT_EQ(order, (std::vector<std::string>{"a/alpha", "a/Beta", "b/zeta"}));
 }
 
 TEST_F(RegistryTest, RejectsDuplicateIdsIgnoringCase) {
-  EXPECT_TRUE(registry.add("/x/src/core/One.cpp", "Same", "", noop));
-  EXPECT_FALSE(registry.add("/x/src/core/Two.cpp", "same", "", noop));
+  EXPECT_TRUE(registry_.add("/x/src/core/One.cpp", "Same", "", noop));
+  EXPECT_FALSE(registry_.add("/x/src/core/Two.cpp", "same", "", noop));
 
-  EXPECT_EQ(registry.examples().size(), 1U);
-  ASSERT_EQ(registry.errors().size(), 1U);
-  EXPECT_NE(registry.errors().front().find("duplicate"), std::string::npos);
+  EXPECT_EQ(registry_.examples().size(), 1U);
+  ASSERT_EQ(registry_.errors().size(), 1U);
+  EXPECT_NE(registry_.errors().front().find("duplicate"), std::string::npos);
 }
 
 TEST_F(RegistryTest, RejectsInvalidNamesAndMissingFunctions) {
-  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "", "", noop));
-  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "has space", "", noop));
-  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "has/slash", "", noop));
-  EXPECT_FALSE(registry.add("/x/src/core/A.cpp", "NoFunction", "", nullptr));
+  EXPECT_FALSE(registry_.add("/x/src/core/A.cpp", "", "", noop));
+  EXPECT_FALSE(registry_.add("/x/src/core/A.cpp", "has space", "", noop));
+  EXPECT_FALSE(registry_.add("/x/src/core/A.cpp", "has/slash", "", noop));
+  EXPECT_FALSE(registry_.add("/x/src/core/A.cpp", "NoFunction", "", nullptr));
 
-  EXPECT_TRUE(registry.examples().empty());
-  EXPECT_EQ(registry.errors().size(), 4U);
+  EXPECT_TRUE(registry_.examples().empty());
+  EXPECT_EQ(registry_.errors().size(), 4U);
 }
 
 TEST_F(RegistryTest, StoresFlags) {
-  registry.add("/x/src/socket/Server.cpp", "Server", "", noop, lab::kInteractive);
-  EXPECT_TRUE(registry.examples().front().isInteractive());
+  registry_.add("/x/src/socket/Server.cpp", "Server", "", noop,
+                lab::kInteractive);
+  EXPECT_TRUE(registry_.examples().front().isInteractive());
 }
 
 TEST_F(RegistryTest, FindPrefersExactMatches) {
-  registry.add("/x/src/core/A.cpp", "Weak", "", noop);
-  registry.add("/x/src/other/A.cpp", "weak", "", noop);
-
-  ASSERT_NE(registry.find("core/Weak"), nullptr);
-  EXPECT_EQ(registry.find("core/Weak")->id, "core/Weak");
-  ASSERT_NE(registry.find("CORE/WEAK"), nullptr);  // case-insensitive fallback
-  EXPECT_EQ(registry.find("CORE/WEAK")->id, "core/Weak");
-  EXPECT_EQ(registry.find("core/Strong"), nullptr);
+  registry_.add("/x/src/core/A.cpp", "Weak", "", noop);
+  registry_.add("/x/src/other/A.cpp", "weak", "", noop);
+
+  ASSERT_NE(registry_.find("core/Weak"), nullptr);
+  EXPECT_EQ(registry_.find("core/Weak")->id, "core/Weak");
+  ASSERT_NE(registry_.find("CORE/WEAK"), nullptr);  // case-insensitive fallback
+  EXPECT_EQ(registry_.find("CORE/WEAK")->id, "core/Weak");
+  EXPECT_EQ(registry_.find("core/Strong"), nullptr);
 }
 
 TEST_F(RegistryTest, MatchSearchesIdsAndDescriptions) {
-  registry.add("/x/src/core/smart_pointer/A.cpp", "Weak", "observe without owning", noop);
-  registry.add("/x/src/core/smart_pointer/B.cpp", "Unique", "exclusive ownership", noop);
-  registry.add("/x/src/dp/C.cpp", "Proxy", "a stand-in object", noop);
-
-  EXPECT_EQ(registry.match("").size(), 3U);
-  EXPECT_EQ(ids(registry.match("SMART_POINTER")),
-            (std::vector<std::string>{"core/smart_pointer/Unique", "core/smart_pointer/Weak"}));
-  EXPECT_EQ(ids(registry.match("owning")), (std::vector<std::string>{"core/smart_pointer/Weak"}));
-  EXPECT_TRUE(registry.match("nothing matches this").empty());
+  registry_.add("/x/src/core/smart_pointer/A.cpp", "Weak",
+                "observe without owning", noop);
+  registry_.add("/x/src/core/smart_pointer/B.cpp", "Unique",
+                "exclusive ownership", noop);
+  registry_.add("/x/src/dp/C.cpp", "Proxy", "a stand-in object", noop);
+
+  EXPECT_EQ(registry_.match("").size(), 3U);
+  EXPECT_EQ(ids(registry_.match("SMART_POINTER")),
+            (std::vector<std::string>{"core/smart_pointer/Unique",
+                                      "core/smart_pointer/Weak"}));
+  EXPECT_EQ(ids(registry_.match("owning")),
+            (std::vector<std::string>{"core/smart_pointer/Weak"}));
+  EXPECT_TRUE(registry_.match("nothing matches this").empty());
 }
 
 }  // namespace
diff --git a/tests/mock/FakeTurtle.h b/tests/mock/FakeTurtle.h
index 5653466..e57f9b5 100644
--- a/tests/mock/FakeTurtle.h
+++ b/tests/mock/FakeTurtle.h
@@ -30,6 +30,8 @@ class FakeTurtle : public Turtle {
       case 270:
         x_ -= distance;
         break;  // west
+      default:
+        break;  // other angles are not used by the tests
     }
 
     if (penDown_) {

From 87d356f293a0f49965f9b8589b749c71741dc47b Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 09:05:12 +0700
Subject: [PATCH 17/20] Generate the API documentation with Doxygen

cmake/Docs.cmake adds an optional "docs" target that fills docs/Doxyfile.in
into build/Doxyfile and runs Doxygen: the README is the front page, the guides
and module READMEs become related pages, and every source file is browsable and
cross-linked. The target only exists when doxygen is installed, and it is not
part of "all".

.github/workflows/docs.yml builds the site on every push and pull request with
CPPLAB_DOCS_WARNINGS_AS_ERRORS=ON and deploys it to GitHub Pages from master.
docs/doxygen.md explains the local workflow, the one-time Pages setup and how
to point the GitHub wiki at the result; scripts/publish_wiki.sh generates that
wiki Home page.

The Markdown needed small fixes to parse cleanly: Doxygen wants a blank line
before a fenced code block, reads a bare <random> in prose as an HTML tag and
rejects a fence that hangs off a list item.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 .github/workflows/docs.yml      |  92 +++++++++++++++++++++++
 CLAUDE.md                       |  24 ++++--
 CMakeLists.txt                  |   1 +
 README.md                       |  27 +++++--
 cmake/Docs.cmake                |  67 +++++++++++++++++
 docs/Doxyfile.in                | 113 ++++++++++++++++++++++++++++
 docs/README.md                  |   1 +
 docs/doxygen.md                 | 126 ++++++++++++++++++++++++++++++++
 scripts/publish_wiki.sh         |  92 +++++++++++++++++++++++
 src/ap/README.md                |   2 +
 src/core/basics/ControlFlow.cpp |   2 +-
 src/core/class/README.md        |   8 ++
 src/core/datetime/README.md     |   4 +-
 src/core/filehandle/README.md   |   6 +-
 src/core/utils/README.md        |   1 +
 src/embedded/README.md          |  11 +++
 src/socket/README.md            |  14 +++-
 tests/README.md                 |  11 +--
 18 files changed, 580 insertions(+), 22 deletions(-)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 cmake/Docs.cmake
 create mode 100644 docs/Doxyfile.in
 create mode 100644 docs/doxygen.md
 create mode 100755 scripts/publish_wiki.sh

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..cb8f079
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,92 @@
+# -------------------------------------------------------------
+# GitHub Actions Workflow: API documentation (Doxygen)
+# -------------------------------------------------------------
+# Purpose:
+# Generates the Doxygen site from the sources on every push and
+# pull request (Doxygen warnings fail the job), and publishes it
+# to GitHub Pages when master moves.
+#
+# One-time setup: Settings -> Pages -> Build and deployment ->
+# Source: "GitHub Actions". See docs/doxygen.md.
+# -------------------------------------------------------------
+
+name: Docs
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:  # lets a maintainer run it by hand from the Actions tab
+
+# Only one Pages deployment at a time; a newer run waits instead of racing.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+
+    permissions:
+      contents: read
+      pages: write      # required by actions/deploy-pages
+      id-token: write   # required by actions/deploy-pages (OIDC)
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      # doxygen generates the site, graphviz (dot) draws the class diagrams.
+      - name: Install Doxygen and Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends doxygen graphviz cmake g++
+
+      # The docs only need the Doxyfile, so the GUI and the tests (which would
+      # download GoogleTest) stay off: configuring takes a second.
+      - name: Generate documentation
+        run: |
+          cmake -S . -B build-docs \
+                -DCPPLAB_BUILD_GUI=OFF \
+                -DCPPLAB_BUILD_TESTS=OFF \
+                -DCPPLAB_DOCS_WARNINGS_AS_ERRORS=ON
+          cmake --build build-docs --target docs
+
+      - name: Show Doxygen warnings
+        if: always()
+        run: |
+          echo "## Doxygen warnings" >> "$GITHUB_STEP_SUMMARY"
+          if [ -s build-docs/docs/doxygen-warnings.log ]; then
+            sed 's|^|    |' build-docs/docs/doxygen-warnings.log >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "None." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # Always available as a downloadable artifact, also for pull requests.
+      - name: Upload the site as a build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: doxygen-html
+          path: build-docs/docs/html
+          retention-days: 14
+
+      # --- Publish to GitHub Pages (pushes to master only) ---
+      - name: Configure GitHub Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v5
+
+      - name: Upload the Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build-docs/docs/html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        if: github.event_name != 'pull_request'
+        uses: actions/deploy-pages@v4
diff --git a/CLAUDE.md b/CLAUDE.md
index dae6df0..b169552 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,7 +24,8 @@ Command line of the app: `--list [filter]`, `--run <id|filter>`, `--run-all [fil
 Example ids look like `core/smart_pointer/Weak`.
 
 CMake options: `CPPLAB_BUILD_TESTS` (ON), `CPPLAB_BUILD_DEMOS` (ON), `CPPLAB_BUILD_GUI`
-(AUTO/ON/OFF - gtkmm-4.0 is optional), `CPPLAB_ENABLE_SANITIZERS` (OFF, ASan+UBSan),
+(AUTO/ON/OFF - gtkmm-4.0 is optional), `CPPLAB_BUILD_DOCS` (ON, needs doxygen),
+`CPPLAB_DOCS_WARNINGS_AS_ERRORS` (OFF), `CPPLAB_ENABLE_SANITIZERS` (OFF, ASan+UBSan),
 `CPPLAB_WARNINGS_AS_ERRORS` (OFF), `ENABLE_COVERAGE` (OFF).
 
 Tests: `-L unit` are the GoogleTest tests in `tests/`, `-L example` are auto-generated smoke tests
@@ -93,11 +94,24 @@ clang-tidy -p build $(git ls-files 'src/*.cpp')     # configured by .clang-tidy,
 - Naming (`.clang-tidy`): `lower_case` variables and namespaces, `CamelCase` types, trailing `_` on
   private members, `kName` for constants.
 
+## API documentation
+
+`cmake --build build --target docs` runs Doxygen (`cmake/Docs.cmake` fills `docs/Doxyfile.in` into
+`build/Doxyfile`) and writes `build/docs/html/`. The target exists only when doxygen is installed;
+`CPPLAB_DOCS_WARNINGS_AS_ERRORS=ON` (used in CI) turns Doxygen warnings into failures, so keep
+`build/docs/doxygen-warnings.log` empty. Doxygen parses the Markdown too: a fenced code block needs
+a blank line before it, and a bare `<header>` in prose is read as an HTML tag - write `` `<random>` ``.
+Public headers in `include/lab/` are documented with `///`; examples keep plain `//` comments and
+are read through the source browser.
+
 ## CI
 
-`.github/workflows/cpp-build-test-coverage.yml` runs on push/PR to `master` inside
-`urboob21/cpp-lab:latest`: cppcheck, build with coverage, `ctest`, lcov summary, plus a second job
-that builds with `CPPLAB_ENABLE_SANITIZERS=ON` and runs the tests again.
+- `.github/workflows/cpp-build-test-coverage.yml` runs on push/PR to `master` inside
+  `urboob21/cpp-lab:latest`: cppcheck, build with coverage, `ctest`, lcov summary, a Release job
+  with `CPPLAB_WARNINGS_AS_ERRORS=ON`, and a sanitizer job (`CPPLAB_ENABLE_SANITIZERS=ON`).
+- `.github/workflows/docs.yml` builds the Doxygen site (warnings are errors) and deploys it to
+  GitHub Pages from `master`. `scripts/publish_wiki.sh` refreshes the wiki Home page that links to
+  it; see `docs/doxygen.md`.
 
 ## Other programs
 
@@ -111,4 +125,4 @@ that builds with `CPPLAB_ENABLE_SANITIZERS=ON` and runs the tests again.
 
 `docs/README.md` indexes the per-folder READMEs (`src/**/README.md`), which explain each topic and
 embed the draw.io UML diagrams in `docs/uml/`. When adding or renaming an example, update the
-README of its folder.
+README of its folder. `docs/doxygen.md` covers the generated API site.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index e225b94..4da8c97 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -46,6 +46,7 @@ message(STATUS "Build type  : ${CMAKE_BUILD_TYPE}")
 include(CompilerOptions)  # cpplab::options - warnings, coverage, sanitizers
 include(Dependencies)     # Threads, GoogleTest, gtkmm-4.0
 include(CppLab)           # cpplab_add_example_module(), cpplab_discover_example_tests()
+include(Docs)             # 'docs' target - Doxygen API documentation (optional)
 
 # Enable CTest (unit tests + example smoke tests)
 enable_testing()
diff --git a/README.md b/README.md
index d9287d5..9bf558b 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@ cmake --build build -j
 ```
 
 **Project hierarchy**
+
 ```
 include/lab/   framework API: LAB_EXAMPLE, LOG..., registry, menu, runner
 src/
@@ -38,7 +39,7 @@ src/
   embedded/    bare-metal ARM example (own build script)
 tests/         GoogleTest unit tests and a gtest/gmock primer
 cmake/         CMake modules and helpers
-docs/          documentation and UML diagrams
+docs/          documentation, Doxygen config and UML diagrams
 scripts/       build, coverage and scaffolding scripts
 ```
 
@@ -142,6 +143,8 @@ use `-DCPPLAB_BUILD_TESTS=OFF` to skip it).
 | `CPPLAB_BUILD_TESTS` | `ON` | unit tests and one smoke test per example |
 | `CPPLAB_BUILD_DEMOS` | `ON` | standalone demos in `src/demo` |
 | `CPPLAB_BUILD_GUI` | `AUTO` | GTK4 apps in `src/ap`: `AUTO`, `ON`, `OFF` |
+| `CPPLAB_BUILD_DOCS` | `ON` | add the `docs` target when doxygen is installed |
+| `CPPLAB_DOCS_WARNINGS_AS_ERRORS` | `OFF` | fail the `docs` target on Doxygen warnings |
 | `CPPLAB_ENABLE_SANITIZERS` | `OFF` | AddressSanitizer + UndefinedBehaviorSanitizer |
 | `CPPLAB_WARNINGS_AS_ERRORS` | `OFF` | `-Werror` |
 | `ENABLE_COVERAGE` | `OFF` | `--coverage` for lcov/gcovr |
@@ -200,7 +203,19 @@ git ls-files '*.cpp' '*.h' | xargs clang-format -i
 Intentional findings in teaching examples are listed in `.cppcheck-suppressions`.
 
 ---
-## 8. The other programs
+## 8. API documentation (Doxygen)
+
+```bash
+sudo apt-get install doxygen graphviz     # graphviz is optional (class diagrams)
+cmake --build build --target docs         # -> build/docs/html/index.html
+```
+
+The site has the README as its front page, the guides as "Related Pages" and every source file
+browsable and cross-linked. `.github/workflows/docs.yml` regenerates it on every push and publishes
+it to GitHub Pages from `master`. Setup and the wiki recipe: [docs/doxygen.md](docs/doxygen.md).
+
+---
+## 9. The other programs
 
 | Program | Run | Documentation |
 |---|---|---|
@@ -209,7 +224,7 @@ Intentional findings in teaching examples are listed in `.cppcheck-suppressions`
 | Bare-metal ARM (QEMU) | `cd src/embedded && ./run.sh` | [src/embedded/README.md](src/embedded/README.md) |
 
 ---
-## 9. Debugging with VS Code
+## 10. Debugging with VS Code
 
 1. Install the *C/C++ Extension Pack* and `gdb` (`sudo apt install gdb`).
 2. Press **F5**. `.vscode/launch.json` builds `build/debug` through the task in
@@ -226,7 +241,7 @@ To debug a single example without the menu, set `"args": ["--run", "core/smart_p
 `launch.json`.
 
 ---
-## 10. Docker
+## 11. Docker
 
 ```bash
 # Build the image (swap DOCKER_USERNAME for your account)
@@ -243,7 +258,7 @@ docker push DOCKER_USERNAME/cpp-lab
 `-i` keeps stdin open, `-t` allocates a terminal, `--rm` removes the container when it exits.
 
 ---
-## 11. Troubleshooting
+## 12. Troubleshooting
 
 | Symptom | Fix |
 |---|---|
@@ -255,7 +270,7 @@ docker push DOCKER_USERNAME/cpp-lab
 | `push access denied` when pushing the image | `docker login` first |
 
 ---
-## 12. Evaluating the executable
+## 13. Evaluating the executable
 
 ```bash
 size ./build/bin/cpp_lab_project
diff --git a/cmake/Docs.cmake b/cmake/Docs.cmake
new file mode 100644
index 0000000..4d1d160
--- /dev/null
+++ b/cmake/Docs.cmake
@@ -0,0 +1,67 @@
+# ---------------------------------------------------------------------------
+# Docs.cmake - the "docs" target: API documentation generated with Doxygen.
+#
+#   cmake -S . -B build
+#   cmake --build build --target docs
+#   xdg-open build/docs/html/index.html
+#
+# Doxygen is optional: without it the target is simply not created and the
+# rest of the build is unaffected. See docs/doxygen.md.
+# ---------------------------------------------------------------------------
+
+option(CPPLAB_BUILD_DOCS "Add the 'docs' target (needs doxygen; graphviz is optional)" ON)
+option(CPPLAB_DOCS_WARNINGS_AS_ERRORS "Fail the 'docs' target on Doxygen warnings" OFF)
+
+if(NOT CPPLAB_BUILD_DOCS)
+    return()
+endif()
+
+# Doxygen::doxygen and Doxygen_dot_FOUND come from CMake's FindDoxygen module.
+find_package(Doxygen OPTIONAL_COMPONENTS dot)
+
+if(NOT DOXYGEN_FOUND)
+    message(STATUS "Doxygen     : not found (no 'docs' target; install doxygen graphviz)")
+    return()
+endif()
+
+# Values substituted into docs/Doxyfile.in.
+set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/docs")
+
+# Quoted so that paths with spaces survive; Doxygen accepts a quoted list.
+# README.md is the front page; the other markdown files (docs/ and the module
+# READMEs under src/ and tests/) become "Related Pages", so the links between
+# them keep working inside the generated site.
+set(DOXYGEN_INPUT
+    "\"${PROJECT_SOURCE_DIR}/README.md\" \\
+                         \"${PROJECT_SOURCE_DIR}/docs\" \\
+                         \"${PROJECT_SOURCE_DIR}/include\" \\
+                         \"${PROJECT_SOURCE_DIR}/src\" \\
+                         \"${PROJECT_SOURCE_DIR}/tests\"")
+
+# tests/dummy is scratch code kept as it is written upstream.
+set(DOXYGEN_EXCLUDE "\"${PROJECT_SOURCE_DIR}/tests/dummy\"")
+
+if(Doxygen_dot_FOUND)
+    set(DOXYGEN_HAVE_DOT YES)
+else()
+    set(DOXYGEN_HAVE_DOT NO)
+endif()
+
+if(CPPLAB_DOCS_WARNINGS_AS_ERRORS)
+    set(DOXYGEN_WARN_AS_ERROR FAIL_ON_WARNINGS)
+else()
+    set(DOXYGEN_WARN_AS_ERROR NO)
+endif()
+
+set(cpplab_doxyfile "${CMAKE_BINARY_DIR}/Doxyfile")
+configure_file("${PROJECT_SOURCE_DIR}/docs/Doxyfile.in" "${cpplab_doxyfile}" @ONLY)
+
+# Not part of ALL: documentation is generated on demand, not on every build.
+add_custom_target(docs
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${DOXYGEN_OUTPUT_DIRECTORY}"
+    COMMAND Doxygen::doxygen "${cpplab_doxyfile}"
+    WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
+    COMMENT "Generating API documentation with Doxygen -> ${DOXYGEN_OUTPUT_DIRECTORY}/html/index.html"
+    VERBATIM)
+
+message(STATUS "Doxygen     : ${DOXYGEN_VERSION} (target 'docs', dot: ${DOXYGEN_HAVE_DOT})")
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
new file mode 100644
index 0000000..6a31d74
--- /dev/null
+++ b/docs/Doxyfile.in
@@ -0,0 +1,113 @@
+# ---------------------------------------------------------------------------
+# Doxygen configuration for cpp-lab.
+#
+# CMake turns this file into build/Doxyfile (see cmake/Docs.cmake), so the
+# @VAR@ placeholders below are filled in with real paths. Only the settings
+# that differ from the Doxygen defaults are listed; run
+# `doxygen -g -` to see the full set with documentation.
+# ---------------------------------------------------------------------------
+
+# --- Project identity ------------------------------------------------------
+PROJECT_NAME           = "@PROJECT_NAME@"
+PROJECT_NUMBER         = "@PROJECT_VERSION@"
+PROJECT_BRIEF          = "A C++20 learning lab: ~100 runnable, self-contained examples"
+OUTPUT_DIRECTORY       = "@DOXYGEN_OUTPUT_DIRECTORY@"
+OUTPUT_LANGUAGE        = English
+
+# --- What to read ----------------------------------------------------------
+# The markdown pages come first: README.md becomes the front page, the guides
+# below it become "Related Pages".
+INPUT                  = @DOXYGEN_INPUT@
+FILE_PATTERNS          = *.h *.hpp *.cpp *.md
+RECURSIVE              = YES
+EXCLUDE                = @DOXYGEN_EXCLUDE@
+EXCLUDE_PATTERNS       = */build*/* */_deps/* */.git/*
+IMAGE_PATH             = "@PROJECT_SOURCE_DIR@/docs"
+USE_MDFILE_AS_MAINPAGE = "@PROJECT_SOURCE_DIR@/README.md"
+STRIP_FROM_PATH        = "@PROJECT_SOURCE_DIR@"
+STRIP_FROM_INC_PATH    = "@PROJECT_SOURCE_DIR@/include"
+
+# --- What to document ------------------------------------------------------
+# The lab is teaching material: show everything, including the helpers that
+# examples keep in anonymous namespaces, so a reader can follow the code.
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+EXTRACT_ANON_NSPACES   = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_PRIV_VIRTUAL   = YES
+HIDE_UNDOC_MEMBERS     = NO
+INTERNAL_DOCS          = YES
+SHOW_USED_FILES        = YES
+
+# --- Comment style ---------------------------------------------------------
+# Doxygen reads ///, /** */ and //!. The framework headers in include/lab use
+# ///; the examples explain themselves in plain // comments, which show up in
+# the source browser instead.
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = YES
+MULTILINE_CPP_IS_BRIEF = NO
+TAB_SIZE               = 2
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = YES
+SORT_MEMBER_DOCS       = NO
+SORT_BRIEF_DOCS        = NO
+
+# --- Preprocessing ---------------------------------------------------------
+# LAB_EXAMPLE(...) { ... } expands to a function definition. Doxygen skips
+# function-like macros by default (SKIP_FUNCTION_MACROS), which is what we
+# want: the example body is shown in the source browser, not as an API entry.
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+SKIP_FUNCTION_MACROS   = YES
+INCLUDE_PATH           = "@PROJECT_SOURCE_DIR@/include"
+PREDEFINED             = CPPLAB_SOURCE_DIR=""
+
+# --- Source browser --------------------------------------------------------
+# The point of the lab is the code, so make every file browsable and linked.
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = NO
+VERBATIM_HEADERS       = YES
+
+# --- HTML output -----------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+GENERATE_TREEVIEW      = YES
+FULL_SIDEBAR           = NO
+HTML_COLORSTYLE        = AUTO_LIGHT
+DISABLE_INDEX          = NO
+SEARCHENGINE           = YES
+HTML_DYNAMIC_SECTIONS  = YES
+
+# --- Other formats ---------------------------------------------------------
+GENERATE_LATEX         = NO
+GENERATE_MAN           = NO
+GENERATE_XML           = NO
+
+# --- Diagrams (graphviz) ---------------------------------------------------
+# HAVE_DOT is YES only when CMake found the `dot` tool from graphviz.
+HAVE_DOT               = @DOXYGEN_HAVE_DOT@
+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = NO
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+DOT_GRAPH_MAX_NODES    = 60
+
+# --- Warnings --------------------------------------------------------------
+# Undocumented code is fine here (most examples are plain // comments), but a
+# broken \param or a dangling link is a real mistake, so it is reported.
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = @DOXYGEN_WARN_AS_ERROR@
+WARN_LOGFILE           = "@DOXYGEN_OUTPUT_DIRECTORY@/doxygen-warnings.log"
diff --git a/docs/README.md b/docs/README.md
index 95e2ecf..dbac90b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,6 +6,7 @@ topic, and the examples next to it show it in code. Run any example with
 
 - [Learning path](learning-path.md): a suggested order through the examples
 - [Adding examples](adding-examples.md): how the lab works and how to add your own examples
+- [API documentation](doxygen.md): generating the Doxygen site and publishing it to Pages or the wiki
 
 ---
 ## 1. Core (C++ language and standard library)
diff --git a/docs/doxygen.md b/docs/doxygen.md
new file mode 100644
index 0000000..0557b94
--- /dev/null
+++ b/docs/doxygen.md
@@ -0,0 +1,126 @@
+# API documentation with Doxygen
+
+The framework headers in `include/lab/` are documented with `///` comments, and every example is
+browsable as source. Doxygen turns both into a searchable HTML site: the front page is the project
+[README](../README.md), the guides become "Related Pages", and "Files" lets you read any example
+with cross-linked identifiers.
+
+---
+## 1. Generate it locally
+
+```bash
+sudo apt-get install doxygen graphviz        # graphviz (dot) is optional: it draws the class graphs
+cmake -S . -B build
+cmake --build build --target docs
+xdg-open build/docs/html/index.html
+```
+
+The target is created only when Doxygen is found, and it is not part of `all`, so a normal build
+never pays for it. Everything lands in `build/docs/` (git-ignored):
+
+| Path                                | Content                                  |
+| ----------------------------------- | ---------------------------------------- |
+| `build/Doxyfile`                     | generated from `docs/Doxyfile.in`        |
+| `build/docs/html/index.html`         | the site                                 |
+| `build/docs/doxygen-warnings.log`    | warnings (empty when everything is fine) |
+
+CMake options:
+
+| Option                            | Default | Meaning                                        |
+| --------------------------------- | ------- | ---------------------------------------------- |
+| `CPPLAB_BUILD_DOCS`               | `ON`    | add the `docs` target when Doxygen is installed |
+| `CPPLAB_DOCS_WARNINGS_AS_ERRORS`  | `OFF`   | fail the target on Doxygen warnings (CI uses `ON`) |
+
+To run Doxygen without CMake, use the generated file: `doxygen build/Doxyfile`. Do not edit it,
+it is overwritten on every configure; change `docs/Doxyfile.in` instead.
+
+---
+## 2. How the sources are documented
+
+Doxygen reads `///`, `//!` and `/** ... */` comments. The lab uses them like this:
+
+```cpp
+/// Collection of all examples.
+///
+/// Examples register themselves through LAB_EXAMPLE while the program starts.
+class Registry {
+ public:
+  /// Registers one example.
+  /// @param file        __FILE__ of the calling source file.
+  /// @param name        short name shown in the menu.
+  /// @return false when the example was rejected (see errors()).
+  bool add(std::string_view file, std::string_view name, ...);
+};
+```
+
+Useful commands inside a comment: `@brief`, `@param`, `@return`, `@note`, `@warning`, `@see`,
+`@code ... @endcode`, `@ref other-page`.
+
+The ~100 example files deliberately keep their teaching text in plain `//` comments: they explain a
+concept in order, not an API. `EXTRACT_ALL` and `SOURCE_BROWSER` are on, so those files still appear
+under "Files" with their comments intact - no rewriting needed. When you add a header to
+`include/lab/`, document it with `///`, because that is what becomes the public API reference.
+
+---
+## 3. CI: publish to GitHub Pages
+
+`.github/workflows/docs.yml` builds the site on every push and pull request (warnings are errors
+there) and, on pushes to `master`, deploys it to GitHub Pages.
+
+**One-time setup in the repository (a maintainer has to do this once):**
+
+1. Open **Settings -> Pages**.
+2. Under **Build and deployment -> Source**, choose **GitHub Actions**.
+3. Push to `master` (or run the workflow manually from the **Actions** tab).
+
+The site is then served at `https://<owner>.github.io/<repo>/` - for this repository,
+<https://urbytes21.github.io/cpp-lab/>. The workflow needs no token: it uses the `pages: write`
+and `id-token: write` permissions declared in the job.
+
+If the deploy step fails with "Pages is not enabled", step 2 above has not been done yet. The build
+step still succeeds and uploads the site as a workflow artifact, so you can download it from the
+run page.
+
+---
+## 4. Link it from the GitHub wiki
+
+The wiki only stores Markdown - it cannot host the generated HTML - so the usual approach is to
+keep the wiki as the hand-written entry point and link it to the generated site.
+
+**Manually:**
+
+1. Open the **Wiki** tab and create the **Home** page (this also creates the wiki repository).
+2. Paste something like:
+
+   ```markdown
+   # cpp-lab
+
+   - [API documentation](https://urbytes21.github.io/cpp-lab/) (generated with Doxygen on every push to master)
+   - [Learning path](https://github.com/urbytes21/cpp-lab/blob/master/docs/learning-path.md)
+   - [Adding examples](https://github.com/urbytes21/cpp-lab/blob/master/docs/adding-examples.md)
+   ```
+
+**Automatically**, with the helper script:
+
+```bash
+./scripts/publish_wiki.sh                      # uses the origin remote
+./scripts/publish_wiki.sh https://github.com/<owner>/<repo>.wiki.git
+```
+
+It clones `<repo>.wiki.git`, regenerates `Home.md` from the repository documentation (the docs
+index plus a link to the Pages site) and pushes if anything changed. The wiki is a normal git
+repository, so a push needs credentials with write access to the repository.
+
+> To run it from CI as well, add a step that calls the script with a personal access token in the
+> URL (`https://x-access-token:${{ secrets.WIKI_TOKEN }}@github.com/<owner>/<repo>.wiki.git`). The
+> default `GITHUB_TOKEN` cannot write to the wiki.
+
+---
+## 5. Troubleshooting
+
+| Symptom                                  | Cause and fix                                                      |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| No `docs` target                          | Doxygen is not installed, or `-DCPPLAB_BUILD_DOCS=OFF`             |
+| No class diagrams                         | graphviz is missing; install it and re-run `cmake -S . -B build`    |
+| `warning: ... does not exist`             | a path in `DOXYGEN_INPUT` (`cmake/Docs.cmake`) points at a deleted file |
+| CI docs job fails but the site looks fine | a real Doxygen warning: read `build/docs/doxygen-warnings.log`      |
diff --git a/scripts/publish_wiki.sh b/scripts/publish_wiki.sh
new file mode 100755
index 0000000..861663c
--- /dev/null
+++ b/scripts/publish_wiki.sh
@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Publish a Home page to the GitHub wiki that points at the generated
+# documentation.
+#
+#   ./scripts/publish_wiki.sh                                  # wiki of the 'origin' remote
+#   ./scripts/publish_wiki.sh https://github.com/me/repo.wiki.git
+#   DRY_RUN=1 ./scripts/publish_wiki.sh                        # only print the page
+#
+# The GitHub wiki stores Markdown, so it cannot host the Doxygen HTML itself.
+# This script writes a Home page that links to the GitHub Pages site (published
+# by .github/workflows/docs.yml) and to the documentation in the repository.
+# See docs/doxygen.md.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WIKI_URL="${1:-}"
+
+# Derive the wiki URL and the Pages URL from the origin remote when not given.
+origin="$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || true)"
+if [[ -z "$origin" ]]; then
+    echo "[ERR] no 'origin' remote; pass the wiki URL as an argument" >&2
+    exit 1
+fi
+
+# https://github.com/<owner>/<repo>[.git] or git@github.com:<owner>/<repo>.git
+slug="${origin##*github.com}"
+slug="${slug#[:/]}"
+slug="${slug%.git}"
+owner="${slug%%/*}"
+repo="${slug##*/}"
+
+if [[ -z "$owner" || -z "$repo" || "$owner" == "$slug" ]]; then
+    echo "[ERR] origin is not a GitHub remote ($origin); pass the wiki URL as an argument" >&2
+    exit 1
+fi
+
+WIKI_URL="${WIKI_URL:-https://github.com/$owner/$repo.wiki.git}"
+PAGES_URL="https://$owner.github.io/$repo/"
+BLOB="https://github.com/$owner/$repo/blob/master"
+
+page="$(cat <<PAGE
+# $repo
+
+*This page is generated by \`scripts/publish_wiki.sh\`. Edits made here are overwritten.*
+
+## Documentation
+
+- **[API documentation]($PAGES_URL)** - generated with Doxygen on every push to \`master\`
+- [Learning path]($BLOB/docs/learning-path.md) - a suggested order through the examples
+- [Adding examples]($BLOB/docs/adding-examples.md) - how the lab works and how to extend it
+- [Topic index]($BLOB/docs/README.md) - every module and what it covers
+- [Doxygen setup]($BLOB/docs/doxygen.md) - generating and publishing these pages
+
+## Quick start
+
+\`\`\`bash
+git clone https://github.com/$owner/$repo.git
+cd $repo
+cmake -S . -B build
+cmake --build build -j
+./build/bin/cpp_lab_project          # interactive menu
+./build/bin/cpp_lab_project --help   # command line
+\`\`\`
+PAGE
+)"
+
+if [[ -n "${DRY_RUN:-}" ]]; then
+    echo "$page"
+    exit 0
+fi
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+echo "[INFO] cloning $WIKI_URL"
+if ! git clone --quiet --depth 1 "$WIKI_URL" "$work/wiki"; then
+    echo "[ERR] could not clone the wiki." >&2
+    echo "      Create it first: open the repository's Wiki tab and save any page." >&2
+    exit 1
+fi
+
+echo "$page" > "$work/wiki/Home.md"
+
+if git -C "$work/wiki" diff --quiet; then
+    echo "[OK] the wiki is already up to date"
+    exit 0
+fi
+
+git -C "$work/wiki" add Home.md
+git -C "$work/wiki" commit --quiet -m "Update Home from scripts/publish_wiki.sh"
+git -C "$work/wiki" push --quiet
+echo "[OK] published https://github.com/$owner/$repo/wiki"
diff --git a/src/ap/README.md b/src/ap/README.md
index b5b80a4..38e6e43 100644
--- a/src/ap/README.md
+++ b/src/ap/README.md
@@ -19,6 +19,7 @@
     4. The `Model` fetches or updates the data (e.g., from an API or database).
     5. The `Model` sends data back to the `ViewModel`.
     6. The `ViewModel` updates the observable data, which automatically updates the `View` through `data binding or observers`.
+
 ```bash
 User
  |
@@ -42,6 +43,7 @@ View <-> ViewModel <-> Model    # view automatically update
     3. The `Controller` processes the input, performs business logic, and may update the `Model`.
     4. The `Model` updates its data (e.g., saves to a database or gets data from an API).
     5. The `Controller` then updates the `View` based on the new `Model` data.
+
 ```bash
 User
  |
diff --git a/src/core/basics/ControlFlow.cpp b/src/core/basics/ControlFlow.cpp
index a985879..ab3e007 100644
--- a/src/core/basics/ControlFlow.cpp
+++ b/src/core/basics/ControlFlow.cpp
@@ -19,7 +19,7 @@
 
 namespace {
 
-/// std::rand() is simple but low quality; <random> is the modern way.
+/// std::rand() is simple but low quality; `<random>` is the modern way.
 int randomInt(int min, int max) {
   static std::mt19937 engine{std::random_device{}()};
   std::uniform_int_distribution<int> distribution(min, max);
diff --git a/src/core/class/README.md b/src/core/class/README.md
index f467c1b..09d6a6e 100644
--- a/src/core/class/README.md
+++ b/src/core/class/README.md
@@ -33,6 +33,7 @@
 ### 1.1. Non Member Function
 - It serves the same kind of role as the package access specifier in Java.
 - `a << b` C++ tries in this order:
+
 ```cpp
 a.operator<<(b)
 operator<<(a, b) (non-member function)
@@ -56,6 +57,7 @@ operator OP (type_of_X, type_of_Y)
 - The member does not know about the existence of the class
 
 - UML:
+
 ```cpp
 +------------------------+
 |          Car           |
@@ -98,6 +100,7 @@ public:
 - The member does not know about the existence of the class
 
 - UML:
+
 ```cpp
 +-----------------------------+
 |        Department           |
@@ -137,6 +140,7 @@ public:
 - The associated member does not have its existence managed by the class
 - The associated member may or may not know about the existence of the class
 - UML
+
 ```cpp
 +---------------------+                 +---------------------+
 |       Doctor        |-----------------|       Patient       |
@@ -165,6 +169,7 @@ public:
 -  One class uses another class to perform a task. 
 -  It is temporarily created, used, and then destroyed, or passed into a member function from an external source.
 - UML
+
 ```cpp
 +---------------------+
 |         Car         |
@@ -200,6 +205,7 @@ public:
 ### 2.5. Container
 -  The class one class provides a container to hold multiple objects of another type
 - UML
+
 ```cpp
 #include <vector>
 
@@ -241,6 +247,7 @@ private:
 
 ## 2.6. Inheritance
 - **Is-a**
+
 ```cpp
 +----------------------+
 |        Animal        |
@@ -270,6 +277,7 @@ public:
 
 ## 2.7 Embedded a.k.a Nested/Inner Class
 - Type-level containment
+
 ```cpp
 +----------------------+
 |        Car           |
diff --git a/src/core/datetime/README.md b/src/core/datetime/README.md
index bfe94c5..18ed370 100644
--- a/src/core/datetime/README.md
+++ b/src/core/datetime/README.md
@@ -8,9 +8,9 @@ See also `core/concurrency/Timing` for measuring elapsed time with `<chrono>`.
 
 ---
 # Date and Time
-- <ctime> : provides functions and types to work with date and time values including parsing and formatting (inherited from C)
+- `<ctime>`: provides functions and types to work with date and time values including parsing and formatting (inherited from C)
 
-- <chrono>: provides facilities to deal with the duration time points and clocks (std11), it is more modern and type-safe approach
+- `<chrono>`: provides facilities to deal with the duration time points and clocks (std11), it is more modern and type-safe approach
 
 ## ctime
 - Data Types:
diff --git a/src/core/filehandle/README.md b/src/core/filehandle/README.md
index 3ff7f7d..25539c9 100644
--- a/src/core/filehandle/README.md
+++ b/src/core/filehandle/README.md
@@ -37,7 +37,7 @@
 
 ## 2. Input with istream
 - Use `extraction operator (>>)` to read information from an input stream. It skips **whitespace (blanks, tabs, and newlines)**. Use `get(), getLine()` to not discard the whitespace.
-- `manipulator` is an object that is used to modify a stream when applied with the `extraction (>>)` or `insertion (<<)` operators. <iomanip>
+- `manipulator` is an object that is used to modify a stream when applied with the `extraction (>>)` or `insertion (<<)` operators (`<iomanip>`).
 
 ## 1.3. Output with ostream
 - There are two ways to change the formatting options:
@@ -58,6 +58,7 @@
   - Clear a string stream
 
 - e.g:
+
 ```cpp
 #include <sstream>
 #include <string>
@@ -105,6 +106,7 @@ https://www.learncpp.com/cpp-tutorial/stream-states-and-input-validation/
 <br>
 
 - **File output:**
+
 ```cpp
 #include <fstream>
 #include <iostream>
@@ -157,6 +159,7 @@ static void fileOutput() {
 <br>
 
 - **File input:**
+
 ```cpp
 static void fileInput() {
   std::ifstream inFile{"grs_bytes.csv"};
@@ -214,6 +217,7 @@ iofile.seekg(iofile.tellg(), std::ios::beg); // seek to current file position
 
 ## 1.8 Binary File
 - e.g.
+
 ```cpp
 #include <string>
 #include <iostream>
diff --git a/src/core/utils/README.md b/src/core/utils/README.md
index 6a2e00c..57cf747 100644
--- a/src/core/utils/README.md
+++ b/src/core/utils/README.md
@@ -25,6 +25,7 @@ There are several ways to represent **"no value"**:
 
 
 **`optional`** was introduced to represent data that may be absent when that absence is part of the domain logic.
+
 ```cpp
 std::optional<std::string> name_opt = std::nullopt;
 ```
diff --git a/src/embedded/README.md b/src/embedded/README.md
index 917b832..2df3dcc 100644
--- a/src/embedded/README.md
+++ b/src/embedded/README.md
@@ -1,11 +1,13 @@
 # Embedded Bare-Metal: Build, Link, Boot, and Debug
 #### Env
+
 ```bash
 $ sudo apt install gcc-arm-none-eabi
 $ apt-get install qemu-system
 ```
 
 ## 1. Building Process
+
 ```bash
 #Sources files      #Toolchain                 #Object files
 +-----------+       +------------------+       +-----------+
@@ -32,6 +34,7 @@ $ apt-get install qemu-system
 ```
 ### 1.1. Compiler
 A compiler is a software program that translates source code written in a high-level programming language into a lower-level form, such as assembly code, object code, or machine code, while preserving the program's functionality.
+
 ```bash
 $ gcc # native
 $ g++
@@ -43,6 +46,7 @@ $ aarch64-none-elf-gcc
 ### 1.2. Cross Compiler
 A cross compiler is a compiler that runs on one platform (host) but generates executable code for a different platform (target).
 An ARM cross compiler can run on a Linux PC and generate binaries that execute on an ARM-based embedded system.
+
 ```bash
 $ arm-none-eabi-gcc
 $ aarch64-none-elf-gcc
@@ -51,6 +55,7 @@ $ aarch64-none-elf-gcc
 ### 1.3. Toolchain
 A toolchain is a collection of software development tools used to build, debug, and analyze software.
 A typical embedded ARM toolchain includes:
+
 ```bash
 $ arm-none-eabi-gcc      # Compiler
 $ arm-none-eabi-as       # Assembler
@@ -110,6 +115,7 @@ A microcontroller does not start executing from `main()` after power-up or reset
 
 ---
 ### 2. Flashing Process
+
 ```bash
 
                                             +----------------+
@@ -169,6 +175,7 @@ A microcontroller does not start executing from `main()` after power-up or reset
 
 ### 2.1. Build executable
 Compile the source files and link them into the `firmware.elf`
+
 ```bash
 $ arm-none-eabi-gcc \
     -mcpu=cortex-m3 \
@@ -191,6 +198,7 @@ $ arm-none-eabi-gcc \
 - **ELF file** does include symbol tables, debug information, or other metadata.
 ### 2.2. Generate a Binary Image
 Convert the ELF executable into a raw binary image that contains only the program data that will be stored in Flash memory.
+
 ```bash
 $ arm-none-eabi-objcopy \
     -O binary \
@@ -201,6 +209,7 @@ $ arm-none-eabi-objcopy \
 ### 2.3. Boot and Debug with QEMU
 QEMU can emulate the `STM32VLDISCOVERY` board and load firmware
 #### Start QEMU
+
 ```bash
 $ qemu-system-arm \
     -M stm32vldiscovery \
@@ -234,6 +243,7 @@ $ qemu-system-arm \
     ```
 
 - **Useful commands:**
+
 ```bash
 monitor reset     # Reset the emulated target
 load              # Load firmware into target memory
@@ -247,6 +257,7 @@ continue
 
 ### Quit QEMU
 When running QEMU with `-nographic`, use:
+
 ```text
 Ctrl + A, then X
 
diff --git a/src/socket/README.md b/src/socket/README.md
index 84cf187..5571f2a 100644
--- a/src/socket/README.md
+++ b/src/socket/README.md
@@ -51,6 +51,7 @@ The classes are `net::TCPServer` and `net::TCPClient` in `simple_tcp/`.
   - Each packet is sent independently.
 
 - Sending data typically works like this:
+
 ```
   1. Build a packet (datagram)
   2. Add a UDP header
@@ -85,6 +86,7 @@ The classes are `net::TCPServer` and `net::TCPClient` in `simple_tcp/`.
     - e.g. 2001:db8:85a3::8a2e:370:7334
 - **Real-world examples**
 To get your IPAddress:
+
 ```bash
 #linux
 ip addr
@@ -125,6 +127,7 @@ The User Datagram Protocol, or UDP, is another widely used transport protocol. I
 
 - **Real-world examples**
 Ping localhost
+
 ```bash
 # ping
 ping 127.0.0.1
@@ -145,6 +148,7 @@ telnet localhost 8080
   - **1024 to 49151** – Registered ports; meaning they can be registered to specific protocols by software corporations.
   - **49152 to 65536** – Dynamic or private ports; meaning that they can be used by just about anybody.
 - **Examples**
+
 ```bash
 22   → SSH  
 25   → SMTP  
@@ -162,8 +166,8 @@ https://example.com:443 -> This connects to the **HTTPS service** on port **443*
 - This process is called **DNS resolution**.
 - For example, a hostname such as: `www.example.com` may be translated into an IP address such as: `93.184.216.34`
 
-- **Examples**
-Queries DNS servers and returns the IP address of the domain."
+- **Examples**: query a DNS server and print the IP address of a domain.
+
 ```bash
 nslookup google.com
 dig google.com
@@ -187,6 +191,7 @@ HTTP follows a **client–server model**:
     4. The server returns an **HTTP response** containing the requested resource.
 
 - **Example**:
+
 ```bash
 # When you open:
 https://google.com
@@ -215,6 +220,7 @@ Content-Length: 1024
 **1.1. HTTP Request**
 - Sent by the client to request a resource.
 - Structure:
+
 ```bash
 Method  
 Headers  
@@ -234,6 +240,7 @@ Content-Type: application/json
 Sent by the server to return the result.
 
 Structure:
+
 ```bash
 Status line  
 Headers  
@@ -250,6 +257,7 @@ Content-Type: text/html
 
 **2. HTTP Headers:**
 - HTTP headers provide **additional information about the request or response**.
+
 ```bash
 Host  
 User-Agent  
@@ -307,6 +315,7 @@ IP: 93.184.216.34
 Port: 80 (HTTP) or 443 (HTTPS).
 -> 2. The browser sends an HTTP request.
 -> 3. The server sends back the HTML page.
+
 ```
 Browser (Client)  --->  Web Server
       socket           listening socket
@@ -324,6 +333,7 @@ o	`Connect`: Actively attempt to establish a connection
 o	`Send`: Send some data over a connection
 o	`Receive`: Receive some data over a connection
 o	`Close`: Release the connection
+
 ```cpp
 //  start()
 //  ├── createSocket()
diff --git a/tests/README.md b/tests/README.md
index 6506357..09ad18f 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -35,11 +35,11 @@ Every `*Test.cpp` below `tests/` is compiled automatically - just add a file.
 
 ## 2. Test Fixtures: Using the Same Data Configuration for Multiple Tests
 - To create a fixture class:
-   - derive a class from `testing::Test` with protected body
-   - declare used objects
-   - write a default constructor or `Setup()` function to prepare the object for each test.
- - write a default destructor or `TearDown()` function to release resources.
- - use `TEST_F(TestFixtureClassName, TestName)` instead of `TEST()`
+   - derive a class from `testing::Test` with a protected body
+   - declare the objects the tests share
+   - write a default constructor or a `SetUp()` function to prepare them for each test
+   - write a destructor or a `TearDown()` function to release resources
+   - use `TEST_F(TestFixtureClassName, TestName)` instead of `TEST()`
 
 > All documentation is covered in the official github repo. The primer documentation also covers a lot of information regarding the test macros. You could use the following summary and the examples linked to choose what you want to use. (https://stackoverflow.com/questions/58600728/what-is-the-difference-between-test-test-f-and-test-p)
 
@@ -48,6 +48,7 @@ Every `*Test.cpp` below `tests/` is compiled automatically - just add a file.
 - **TEST_P()** is useful when you want to write tests with a parameter. Instead of writing multiple tests with different values of the parameter, you can write one test using TEST_P() which uses GetParam() and can be instantiated using INSTANTIATE_TEST_SUITE_P().
 
 - e.g.
+
 ```cpp
 #include "this/package/foo.h"
 

From f024c23a79c09ade802af9623204226d062a8d8f Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 09:17:45 +0700
Subject: [PATCH 18/20] Scaffold the missing C++11-C++23 topics as draft
 examples

Audit of every module against the feature lists of C++11 to C++23, written up
in docs/cpp-standards-coverage.md: 48 topics had no example. Each one now has a
file that states what it should teach, prints that outline when it runs, and is
registered with the new lab::kDraft flag, so the menu and --list mark it
[draft] and the ctest smoke tests still cover it.

The gaps were, by module: a whole templates module (function and class
templates, specialization, NTTPs, concepts, SFINAE, CRTP, variable templates,
two-phase lookup), move semantics and perfect forwarding, inheritance,
abstract interfaces, static members, deducing this, attributes, literals,
std::byte and <bit>, list/forward_list/map/multimap/unordered_set/flat_map,
tuple, any, bitset, random, expected, numeric, ranges, source_location, span,
mdspan, the <utility> helpers, atomic, shared_mutex, latches and barriers,
coroutines, parallel algorithms, error codes, the ODR, modules, std::print,
the Interpreter pattern and the pImpl and type-erasure idioms.

scripts/new_example.sh --draft scaffolds the same shape for a new topic.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 CLAUDE.md                                     |   8 +
 README.md                                     |   6 +-
 docs/README.md                                |  21 ++-
 docs/adding-examples.md                       |   9 +-
 docs/cpp-standards-coverage.md                | 164 ++++++++++++++++++
 include/lab/Example.h                         |   4 +
 include/lab/Registry.h                        |   9 +
 scripts/new_example.sh                        |  63 ++++++-
 src/core/basics/Attributes.cpp                |  54 ++++++
 src/core/basics/README.md                     |   1 +
 src/core/class/AbstractInterface.cpp          |  53 ++++++
 src/core/class/DeducingThis.cpp               |  52 ++++++
 src/core/class/Inheritance.cpp                |  52 ++++++
 src/core/class/MoveSemantics.cpp              |  52 ++++++
 src/core/class/README.md                      |   5 +
 src/core/class/StaticMember.cpp               |  52 ++++++
 src/core/concurrency/Atomic.cpp               |  52 ++++++
 src/core/concurrency/Coroutine.cpp            |  53 ++++++
 src/core/concurrency/ParallelAlgorithm.cpp    |  52 ++++++
 src/core/concurrency/README.md                |   5 +
 src/core/concurrency/SharedMutex.cpp          |  52 ++++++
 src/core/concurrency/Synchronization.cpp      |  52 ++++++
 src/core/container/README.md                  |   6 +
 src/core/container/adapter/FlatMap.cpp        |  52 ++++++
 src/core/container/associative/Map.cpp        |  52 ++++++
 src/core/container/associative/MultiMap.cpp   |  52 ++++++
 src/core/container/sequence/ForwardList.cpp   |  52 ++++++
 src/core/container/sequence/List.cpp          |  52 ++++++
 src/core/container/unordered/UnorderedSet.cpp |  52 ++++++
 src/core/datatype/BitOperations.cpp           |  52 ++++++
 src/core/datatype/Byte.cpp                    |  50 ++++++
 src/core/datatype/README.md                   |   3 +
 src/core/datatype/UserDefinedLiteral.cpp      |  52 ++++++
 src/core/exception/ErrorCode.cpp              |  52 ++++++
 src/core/exception/README.md                  |   1 +
 src/core/filehandle/Print.cpp                 |  52 ++++++
 src/core/filehandle/README.md                 |   1 +
 src/core/function/PerfectForwarding.cpp       |  53 ++++++
 src/core/function/README.md                   |   1 +
 src/core/linkage/Modules.cpp                  |  53 ++++++
 src/core/linkage/OneDefinitionRule.cpp        |  54 ++++++
 src/core/linkage/README.md                    |   2 +
 src/core/template/ClassTemplate.cpp           |  52 ++++++
 src/core/template/Concepts.cpp                |  53 ++++++
 src/core/template/Crtp.cpp                    |  54 ++++++
 src/core/template/FunctionTemplate.cpp        |  52 ++++++
 src/core/template/NonTypeParameter.cpp        |  52 ++++++
 src/core/template/README.md                   |  58 +++++++
 src/core/template/Sfinae.cpp                  |  53 ++++++
 src/core/template/Specialization.cpp          |  52 ++++++
 src/core/template/TwoPhaseLookup.cpp          |  54 ++++++
 src/core/template/VariableTemplate.cpp        |  52 ++++++
 src/core/utils/Any.cpp                        |  52 ++++++
 src/core/utils/Bitset.cpp                     |  52 ++++++
 src/core/utils/Expected.cpp                   |  52 ++++++
 src/core/utils/Mdspan.cpp                     |  53 ++++++
 src/core/utils/Numeric.cpp                    |  52 ++++++
 src/core/utils/README.md                      |  11 ++
 src/core/utils/Random.cpp                     |  52 ++++++
 src/core/utils/Ranges.cpp                     |  53 ++++++
 src/core/utils/SourceLocation.cpp             |  53 ++++++
 src/core/utils/Span.cpp                       |  52 ++++++
 src/core/utils/Tuple.cpp                      |  52 ++++++
 src/core/utils/Utility.cpp                    |  52 ++++++
 src/dp/behavioral/Interpreter.cpp             |  52 ++++++
 src/dp/behavioral/README.md                   |   6 +-
 src/dp/idiom/Pimpl.cpp                        |  53 ++++++
 src/dp/idiom/README.md                        |  24 +++
 src/dp/idiom/TypeErasure.cpp                  |  53 ++++++
 src/lab/Menu.cpp                              |   2 +-
 src/lab/Registry.cpp                          |  11 ++
 src/lab/Runner.cpp                            |   3 +-
 src/main.cpp                                  |   3 +-
 tests/lab/RegistryTest.cpp                    |  14 ++
 74 files changed, 2933 insertions(+), 21 deletions(-)
 create mode 100644 docs/cpp-standards-coverage.md
 create mode 100644 src/core/basics/Attributes.cpp
 create mode 100644 src/core/class/AbstractInterface.cpp
 create mode 100644 src/core/class/DeducingThis.cpp
 create mode 100644 src/core/class/Inheritance.cpp
 create mode 100644 src/core/class/MoveSemantics.cpp
 create mode 100644 src/core/class/StaticMember.cpp
 create mode 100644 src/core/concurrency/Atomic.cpp
 create mode 100644 src/core/concurrency/Coroutine.cpp
 create mode 100644 src/core/concurrency/ParallelAlgorithm.cpp
 create mode 100644 src/core/concurrency/SharedMutex.cpp
 create mode 100644 src/core/concurrency/Synchronization.cpp
 create mode 100644 src/core/container/adapter/FlatMap.cpp
 create mode 100644 src/core/container/associative/Map.cpp
 create mode 100644 src/core/container/associative/MultiMap.cpp
 create mode 100644 src/core/container/sequence/ForwardList.cpp
 create mode 100644 src/core/container/sequence/List.cpp
 create mode 100644 src/core/container/unordered/UnorderedSet.cpp
 create mode 100644 src/core/datatype/BitOperations.cpp
 create mode 100644 src/core/datatype/Byte.cpp
 create mode 100644 src/core/datatype/UserDefinedLiteral.cpp
 create mode 100644 src/core/exception/ErrorCode.cpp
 create mode 100644 src/core/filehandle/Print.cpp
 create mode 100644 src/core/function/PerfectForwarding.cpp
 create mode 100644 src/core/linkage/Modules.cpp
 create mode 100644 src/core/linkage/OneDefinitionRule.cpp
 create mode 100644 src/core/template/ClassTemplate.cpp
 create mode 100644 src/core/template/Concepts.cpp
 create mode 100644 src/core/template/Crtp.cpp
 create mode 100644 src/core/template/FunctionTemplate.cpp
 create mode 100644 src/core/template/NonTypeParameter.cpp
 create mode 100644 src/core/template/README.md
 create mode 100644 src/core/template/Sfinae.cpp
 create mode 100644 src/core/template/Specialization.cpp
 create mode 100644 src/core/template/TwoPhaseLookup.cpp
 create mode 100644 src/core/template/VariableTemplate.cpp
 create mode 100644 src/core/utils/Any.cpp
 create mode 100644 src/core/utils/Bitset.cpp
 create mode 100644 src/core/utils/Expected.cpp
 create mode 100644 src/core/utils/Mdspan.cpp
 create mode 100644 src/core/utils/Numeric.cpp
 create mode 100644 src/core/utils/Random.cpp
 create mode 100644 src/core/utils/Ranges.cpp
 create mode 100644 src/core/utils/SourceLocation.cpp
 create mode 100644 src/core/utils/Span.cpp
 create mode 100644 src/core/utils/Tuple.cpp
 create mode 100644 src/core/utils/Utility.cpp
 create mode 100644 src/dp/behavioral/Interpreter.cpp
 create mode 100644 src/dp/idiom/Pimpl.cpp
 create mode 100644 src/dp/idiom/README.md
 create mode 100644 src/dp/idiom/TypeErasure.cpp

diff --git a/CLAUDE.md b/CLAUDE.md
index b169552..64adb07 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,6 +51,14 @@ sanitizer build.
   print the bare message.
 - `lab/version.h` is generated from `include/lab/version.h.in`.
 
+## Drafts
+
+`LAB_EXAMPLE(name, description, lab::kDraft)` marks a scaffold: the header comment lists what the
+example should teach, `outline()` prints that list, and the menu shows `[draft]`. They still build
+and run as ctest smoke tests. `docs/cpp-standards-coverage.md` is the audit of C++11 - C++23
+against the lab and tracks every open draft; update it (and the folder README) when a draft is
+finished and `lab::kDraft` is removed.
+
 ## Adding an example
 
 ```bash
diff --git a/README.md b/README.md
index 9bf558b..4b57438 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,9 @@ concurrency, sockets and embedded basics - built with CMake, GoogleTest, cppchec
 Docker and GitHub Actions for CI/CD.
 
 Every example lives in one file, explains itself in a header comment, and can be run on its own.
-New to the material? Follow the [learning path](docs/learning-path.md).
+New to the material? Follow the [learning path](docs/learning-path.md). Examples marked `[draft]`
+are scaffolds waiting to be written - [docs/cpp-standards-coverage.md](docs/cpp-standards-coverage.md)
+lists what C++11 - C++23 features the lab covers and which ones are still open.
 
 ---
 ## 1. Quick start
@@ -30,7 +32,7 @@ include/lab/   framework API: LAB_EXAMPLE, LOG..., registry, menu, runner
 src/
   lab/         framework implementation
   main.cpp     entry point: command line and menu
-  core/        C++ language and standard library examples
+  core/        C++ language and standard library examples (incl. templates)
   dp/          design patterns (behavioral, creational, structural)
   controller/  control algorithms (PID)
   socket/      POSIX TCP sockets
diff --git a/docs/README.md b/docs/README.md
index dbac90b..d8cce24 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@ topic, and the examples next to it show it in code. Run any example with
 - [Learning path](learning-path.md): a suggested order through the examples
 - [Adding examples](adding-examples.md): how the lab works and how to add your own examples
 - [API documentation](doxygen.md): generating the Doxygen site and publishing it to Pages or the wiki
+- [Standard coverage](cpp-standards-coverage.md): what the lab shows of C++11 - C++23, and what is still a draft
 
 ---
 ## 1. Core (C++ language and standard library)
@@ -15,15 +16,16 @@ topic, and the examples next to it show it in code. Run any example with
 2. [Data types](../src/core/datatype/README.md): fundamental types, pointers, references, enums, structs, unions, conversions
 3. [Classes](../src/core/class/README.md): constructors, destructors, Rule of 3/5/0, relationships, friends, virtual
 4. [Functions](../src/core/function/README.md): function pointers, lambdas, std::function, operator overloading
-5. [Linkage](../src/core/linkage/README.md): internal/external linkage, sharing global constants
-6. [Smart pointers](../src/core/smart_pointer/README.md): unique_ptr, shared_ptr, weak_ptr
-7. [Strings](../src/core/string/README.md): C strings, std::string, string_view, formatting
-8. [Containers](../src/core/container/README.md): sequence, associative, unordered, adapters
-9. [Exceptions](../src/core/exception/README.md): try/catch/throw, noexcept
-10. [File handling](../src/core/filehandle/README.md): streams, files, filesystem, formatting
-11. [Date and time](../src/core/datetime/README.md): `<ctime>` and `<chrono>`
-12. [Concurrency](../src/core/concurrency/README.md): threads, mutexes, condition variables, futures
-13. [Utilities](../src/core/utils/README.md): optional, algorithms, regex, type traits, variadics
+5. [Templates](../src/core/template/README.md): function and class templates, specialization, concepts, CRTP
+6. [Linkage](../src/core/linkage/README.md): internal/external linkage, sharing global constants
+7. [Smart pointers](../src/core/smart_pointer/README.md): unique_ptr, shared_ptr, weak_ptr
+8. [Strings](../src/core/string/README.md): C strings, std::string, string_view, formatting
+9. [Containers](../src/core/container/README.md): sequence, associative, unordered, adapters
+10. [Exceptions](../src/core/exception/README.md): try/catch/throw, noexcept
+11. [File handling](../src/core/filehandle/README.md): streams, files, filesystem, formatting
+12. [Date and time](../src/core/datetime/README.md): `<ctime>` and `<chrono>`
+13. [Concurrency](../src/core/concurrency/README.md): threads, mutexes, condition variables, futures
+14. [Utilities](../src/core/utils/README.md): optional, algorithms, regex, type traits, variadics
 
 ---
 ## 2. Design Patterns
@@ -31,6 +33,7 @@ topic, and the examples next to it show it in code. Run any example with
 1. [Behavioral](../src/dp/behavioral/README.md)
 2. [Structural](../src/dp/structural/README.md)
 3. [Creational](../src/dp/creational/README.md)
+4. [C++ idioms](../src/dp/idiom/README.md): pImpl, type erasure
 
 ---
 ## 3. Architecture Patterns
diff --git a/docs/adding-examples.md b/docs/adding-examples.md
index d8e1702..09e2975 100644
--- a/docs/adding-examples.md
+++ b/docs/adding-examples.md
@@ -8,6 +8,9 @@ The lab is built so that adding an example takes one file and no build-system ch
 ./scripts/new_example.sh core/utils Span "std::span: a view over contiguous memory"
 cmake --build build
 ./build/bin/cpp_lab_project --run core/utils/Span
+
+# --draft scaffolds a topic you want to write later
+./scripts/new_example.sh --draft core/utils Mdspan "std::mdspan: multidimensional views"
 ```
 
 The script creates `src/core/utils/Span.cpp` from a template. Edit it and rebuild. The build finds
@@ -68,7 +71,7 @@ LAB_EXAMPLE(name, description [, flags]) { body }
 |---------------|-----------------------------------------------------------------------------------|
 | `name`        | Short name shown in the menu. It must be unique in its folder and contain no spaces or `/`. |
 | `description` | One line shown next to the name and searched by `--list` and the menu search.   |
-| `flags`       | Optional. `lab::kInteractive` marks examples that need a human or another process. |
+| `flags`       | Optional, combine with `|`. `lab::kInteractive` marks examples that need a human or another process; `lab::kDraft` marks a scaffold that is not written yet. |
 | folder        | Taken from the file's location: `src/core/utils/Span.cpp` becomes group `core/utils`. |
 | id            | `<folder>/<name>`, e.g. `core/utils/Span`. Use it with `--run`.                     |
 
@@ -107,6 +110,10 @@ print only the message.
   `std::istringstream` instead of `std::cin`. Mark examples that must wait for a user or a peer
   with `lab::kInteractive`.
 - Format with the repository's `.clang-format` (Google-based style).
+- **Drafts:** an example that only describes what it should teach keeps `lab::kDraft`. The menu
+  shows it as `[draft]`, and running it prints the outline from its header comment. Remove the flag
+  in the same commit that writes the code. The open ones are listed in
+  [cpp-standards-coverage.md](cpp-standards-coverage.md).
 
 ## 4. Testing your example
 
diff --git a/docs/cpp-standards-coverage.md b/docs/cpp-standards-coverage.md
new file mode 100644
index 0000000..13a576a
--- /dev/null
+++ b/docs/cpp-standards-coverage.md
@@ -0,0 +1,164 @@
+# Standard coverage: C++11 -> C++23
+
+What the lab already teaches, and what is still missing. The checklist follows the feature lists of
+each standard, cross-checked against the syllabus of
+[federico-busato/Modern-CPP-Programming](https://github.com/federico-busato/Modern-CPP-Programming)
+(chapters 3-22 map onto the `core/` modules, 26-27 onto `dp/`).
+
+Legend:
+
+| | Meaning |
+|---|---|
+| **done** | a finished example demonstrates it |
+| **draft** | the file exists, lists what it should show and prints that outline; the code is not written yet (marked `[draft]` in the menu) |
+| **partial** | touched inside another example, no example of its own |
+
+List every unfinished example with:
+
+```bash
+./build/bin/cpp_lab_project --list | grep draft
+```
+
+---
+## 1. C++11
+
+| Feature | Status | Example |
+|---|---|---|
+| `auto`, `decltype`, trailing return types | done | `core/datatype/TypeConversions` |
+| Range-based `for`, `nullptr`, uniform init | done | `core/basics/ControlFlow`, `core/basics/Initialization` |
+| Scoped enums, underlying types | done | `core/datatype/Enum` |
+| `constexpr`, `static_assert` | done | `core/basics/TypeQualifier` |
+| Lambdas and closures | done | `core/function/Lambda` |
+| Rvalue references, `std::move` | done | `core/datatype/Reference` |
+| Move constructor / move assignment | **draft** | `core/class/MoveSemantics` |
+| Perfect forwarding, reference collapsing | **draft** | `core/function/PerfectForwarding` |
+| Variadic templates, parameter packs | done | `core/utils/Variadic` |
+| Defaulted / deleted / delegating constructors | done | `core/class/Constructor` |
+| `override`, `final`, inheriting constructors | **draft** | `core/class/Inheritance` |
+| Smart pointers | done | `core/smart_pointer/{Unique,Shared,Weak}` |
+| `std::function`, `std::bind` | done | `core/function/Functional` |
+| `std::array`, unordered containers | done | `core/container/...` |
+| `std::tuple`, `std::tie` | **draft** | `core/utils/Tuple` |
+| `<chrono>` | done | `core/concurrency/Timing`, `core/datetime/Time` |
+| `<random>` | **draft** | `core/utils/Random` (used in passing by `core/basics/ControlFlow`) |
+| `<regex>` | done | `core/utils/Regex` |
+| `<type_traits>` | done | `core/utils/TypeTraits` |
+| Threads, mutex, condition variable, futures | done | `core/concurrency/*` |
+| `std::atomic`, memory orders | **draft** | `core/concurrency/Atomic` (a counter appears in `RaceCondition`) |
+| `thread_local` | done | `core/concurrency/SharingData` |
+| `noexcept` | done | `core/exception/ThrowNoexcept` |
+| Raw string literals, user-defined literals | **draft** | `core/datatype/UserDefinedLiteral` |
+| Alias templates (`using`) | done | `core/datatype/TypeConversions` |
+| Attributes (`[[noreturn]]`, ...) | **draft** | `core/basics/Attributes` |
+| Function / class templates, specialization | **draft** | `core/template/*` (nine drafts) |
+
+## 2. C++14
+
+| Feature | Status | Example |
+|---|---|---|
+| Generic lambdas, init captures | done | `core/function/Lambda` |
+| `std::make_unique` | done | `core/smart_pointer/Unique` |
+| Binary literals, digit separators | done | `core/basics/Operations` |
+| Return type deduction, relaxed `constexpr` | **draft** | `core/template/FunctionTemplate` |
+| Variable templates | **draft** | `core/template/VariableTemplate` |
+| `std::exchange` | partial | used by `core/class/RuleOfThreeFiveZero`, explained in `core/utils/Utility` *(draft)* |
+| `std::shared_timed_mutex` | **draft** | `core/concurrency/SharedMutex` |
+| `[[deprecated]]` | **draft** | `core/basics/Attributes` |
+
+## 3. C++17
+
+| Feature | Status | Example |
+|---|---|---|
+| Structured bindings | done | `core/datatype/Struct` |
+| `if` / `switch` with initializer | done | `core/basics/ControlFlow` |
+| `if constexpr` | partial | `core/basics/TypeQualifier`; in depth in `core/template/Sfinae` *(draft)* |
+| Fold expressions | done | `core/utils/Variadic` |
+| Class template argument deduction, deduction guides | **draft** | `core/template/ClassTemplate` |
+| Inline variables | done | `core/linkage/sharing/Sharing` |
+| `std::optional` | done | `core/utils/Optional` |
+| `std::variant` | done | `core/datatype/Union` |
+| `std::any` | **draft** | `core/utils/Any` |
+| `std::string_view` | done | `core/string/StdString` |
+| `std::filesystem` | done | `core/filehandle/Directory` |
+| `std::byte` | **draft** | `core/datatype/Byte` |
+| `std::apply`, `std::make_from_tuple` | **draft** | `core/utils/Tuple` |
+| `std::invoke` | done | `core/function/Functional` |
+| `std::shared_mutex`, `std::scoped_lock` | **draft** | `core/concurrency/SharedMutex` |
+| Parallel algorithms (execution policies) | **draft** | `core/concurrency/ParallelAlgorithm` |
+| `reduce`, `transform_reduce`, scans | **draft** | `core/utils/Numeric` |
+| Map/set improvements (`try_emplace`, `extract`, `merge`) | **draft** | `core/container/associative/Map` |
+| Guaranteed copy elision | **draft** | `core/class/MoveSemantics` |
+| `[[nodiscard]]`, `[[maybe_unused]]`, `[[fallthrough]]` | **draft** | `core/basics/Attributes` |
+
+## 4. C++20
+
+| Feature | Status | Example |
+|---|---|---|
+| Concepts | partial | `core/utils/TypeTraits`; in depth in `core/template/Concepts` *(draft)* |
+| Ranges and views | partial | `core/utils/Algorithm`; in depth in `core/utils/Ranges` *(draft)* |
+| `std::format` | done | `core/string/StringFormatting`, `core/filehandle/OutputFormatting` |
+| Three-way comparison `<=>` | done | `core/function/operator_overloading/ComparisonOperator` |
+| Designated initializers | done | `core/basics/Initialization` |
+| `consteval`, `constinit` | done | `core/basics/TypeQualifier` |
+| `std::span` | partial | `core/datatype/Array`; in depth in `core/utils/Span` *(draft)* |
+| `std::jthread`, `std::stop_token` | done | `core/concurrency/ThreadManagement` |
+| `std::latch`, `std::barrier`, semaphores | **draft** | `core/concurrency/Synchronization` |
+| `std::atomic_ref`, wait/notify | **draft** | `core/concurrency/Atomic` |
+| Coroutines (`co_await`, `co_yield`) | **draft** | `core/concurrency/Coroutine` |
+| Modules | **draft** | `core/linkage/Modules` (documentation only: modules need extra build support) |
+| `std::bit_cast` | done | `core/datatype/Union` |
+| `<bit>`: `popcount`, `rotl`, `bit_width` | **draft** | `core/datatype/BitOperations` |
+| Calendar and time zones in `<chrono>` | done | `core/datetime/Time` |
+| `std::source_location` | partial | used by `lab/Logger`; explained in `core/utils/SourceLocation` *(draft)* |
+| `starts_with` / `ends_with`, `erase_if` | done | `core/string/StdString`, `core/container/sequence/Vector` |
+| `using enum` | done | `core/datatype/Enum` |
+| `std::cmp_less` and friends | **draft** | `core/utils/Utility` |
+| Abbreviated function templates (`auto` parameters) | **draft** | `core/template/FunctionTemplate` |
+| `[[likely]]`, `[[unlikely]]` | **draft** | `core/basics/Attributes` |
+
+## 5. C++23
+
+| Feature | Status | Example |
+|---|---|---|
+| `std::expected` | **draft** | `core/utils/Expected` |
+| `std::print`, `std::println` | **draft** | `core/filehandle/Print` |
+| Deducing `this` (explicit object parameter) | **draft** | `core/class/DeducingThis` |
+| `std::mdspan` | **draft** | `core/utils/Mdspan` |
+| `std::flat_map`, `std::flat_set` | **draft** | `core/container/adapter/FlatMap` |
+| `std::generator` | **draft** | `core/concurrency/Coroutine` |
+| `ranges::to`, `zip`, `chunk`, `adjacent` | **draft** | `core/utils/Ranges` |
+| `std::to_underlying` | partial | used by `core/datatype/Enum`, listed in `core/utils/Utility` *(draft)* |
+| `std::byteswap` | **draft** | `core/datatype/BitOperations` |
+| `std::stacktrace` | **draft** | `core/utils/SourceLocation` |
+| `[[assume]]`, `if consteval` | **draft** | `core/basics/Attributes` |
+| Multidimensional subscript `m[i, j]` | **draft** | `core/utils/Mdspan` |
+
+Several C++23 library features need a recent toolchain (GCC 13/14, Clang 16/18). Each draft names
+the version it needs; check before writing the code, and guard with a feature-test macro
+(`__cpp_lib_expected`, `__cpp_lib_print`, ...) if the example must build everywhere.
+
+## 6. Design patterns and idioms
+
+The 23 Gang of Four patterns were complete except **Interpreter**, which is now a draft under
+`dp/behavioral`. The new `dp/idiom/` folder collects C++-specific patterns: `Pimpl` and
+`TypeErasure` *(both drafts)*; RAII, rule of 0/3/5, copy-and-swap, CRTP and the Meyers singleton are
+already shown elsewhere (see [src/dp/idiom/README.md](../src/dp/idiom/README.md)).
+
+## 7. Deliberately out of scope
+
+- **C++26**: still moving (reflection, contracts, `std::execution`). Nothing is planned yet.
+- **Modules as a build feature**: the lab stays header-based; `core/linkage/Modules` explains the
+  syntax and what it would take to switch.
+- **Compiler internals and optimisation** (chapters 23-25 of the reference course): benchmarking
+  belongs in a separate project, not in a single-process menu of examples.
+
+---
+## 8. Filling in a draft
+
+1. Run it: `./build/bin/cpp_lab_project --run core/utils/Expected` - it prints its own outline.
+2. Open the file, replace `outline()` with real demonstrations (keep helpers in the anonymous
+   namespace, structure the output with `LOG_SECTION`).
+3. Remove `lab::kDraft` from `LAB_EXAMPLE` and update the table in the folder's `README.md`.
+4. `cmake --build build && ctest --test-dir build -R "example:core/utils/Expected"`.
+
+Conventions and the full checklist: [adding-examples.md](adding-examples.md).
diff --git a/include/lab/Example.h b/include/lab/Example.h
index 590bc3f..4074ddf 100644
--- a/include/lab/Example.h
+++ b/include/lab/Example.h
@@ -22,6 +22,10 @@
 //   LAB_EXAMPLE("EchoServer", "TCP echo server on port 8080", lab::kInteractive)
 //   { ... }
 //
+// - Pass lab::kDraft while an example is still a scaffold: a file that lists
+//   what the topic should show but has no code yet. It runs (it prints its
+//   outline) and the menu marks it [draft]. Remove the flag once it is done.
+//
 // How it works: the macro declares a file-local function, registers its
 // address in lab::Registry from a static initializer (which runs before
 // main()), and then lets the braces that follow become the function body.
diff --git a/include/lab/Registry.h b/include/lab/Registry.h
index de36dc4..558b113 100644
--- a/include/lab/Registry.h
+++ b/include/lab/Registry.h
@@ -13,6 +13,10 @@ enum ExampleFlags : unsigned {
   /// network peer, or never returns. `--run-all` and the ctest smoke tests
   /// skip these examples.
   kInteractive = 1U << 0U,
+  /// A scaffold: the topic is planned and the file lists what it should show,
+  /// but the code is not written yet. Draft examples still run (they print
+  /// their outline), and the menu marks them as [draft].
+  kDraft = 1U << 1U,
 };
 
 using ExampleFunction = void (*)();
@@ -31,6 +35,11 @@ struct Example {
   unsigned flags{kNone};
 
   bool isInteractive() const { return (flags & kInteractive) != 0U; }
+  bool isDraft() const { return (flags & kDraft) != 0U; }
+
+  /// Tags to print after the description: "  [draft]", "  [interactive]", both
+  /// or nothing.
+  std::string labels() const;
 };
 
 /// Collection of all examples.
diff --git a/scripts/new_example.sh b/scripts/new_example.sh
index fcd87be..291ee32 100755
--- a/scripts/new_example.sh
+++ b/scripts/new_example.sh
@@ -1,18 +1,28 @@
 #!/usr/bin/env bash
 # Creates a new example from a template.
 #
-#   scripts/new_example.sh <folder below src> <Name> ["one-line description"]
+#   scripts/new_example.sh [--draft] <folder below src> <Name> ["description"]
 #   scripts/new_example.sh core/utils Span "std::span: a view over contiguous memory"
+#   scripts/new_example.sh --draft core/utils Mdspan "std::mdspan: multidimensional views"
+#
+# --draft scaffolds a topic to write later: it registers with lab::kDraft, so
+# the menu marks it [draft] and running it prints its own outline.
 #
 # The file src/<folder>/<Name>.cpp is picked up by CMake on the next build and
 # shows up in the menu as <folder>/<Name>. See docs/adding-examples.md.
 set -euo pipefail
 
 usage() {
-  sed -n '2,8p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'
   exit 1
 }
 
+draft=0
+if [[ "${1:-}" == "--draft" ]]; then
+  draft=1
+  shift
+fi
+
 if [[ $# -lt 2 || $# -gt 3 ]]; then
   usage
 fi
@@ -50,6 +60,53 @@ mkdir -p "$(dirname "$file")"
 description="${description//\\/\\\\}"
 description="${description//\"/\\\"}"
 
+if [[ $draft -eq 1 ]]; then
+cat > "$file" <<EOF
+// -----------------------------------------------------------------------------
+// ${name}
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop \`lab::kDraft\` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - ...
+//   - ...
+//
+// Reference: https://en.cppreference.com/w/cpp
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 2> kPlanned{
+    "...",
+    "...",
+};
+
+void outline() {
+  LOG_SECTION("${name} - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("${name}", "${description}", lab::kDraft) {
+  outline();
+}
+EOF
+else
 cat > "$file" <<EOF
 // -----------------------------------------------------------------------------
 // ${name}
@@ -81,6 +138,8 @@ LAB_EXAMPLE("${name}", "${description}") {
 }
 EOF
 
+fi
+
 echo "created src/$folder/$name.cpp"
 echo
 echo "Build and run it:"
diff --git a/src/core/basics/Attributes.cpp b/src/core/basics/Attributes.cpp
new file mode 100644
index 0000000..c6d9bd7
--- /dev/null
+++ b/src/core/basics/Attributes.cpp
@@ -0,0 +1,54 @@
+// -----------------------------------------------------------------------------
+// Standard attributes (C++11 - C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - [[nodiscard]] on a function and on a type, with a reason string (C++20)
+//   - [[maybe_unused]] for parameters and variables that only exist in one build
+//   - [[fallthrough]] to document an intentional switch fall-through
+//   - [[deprecated("use X instead")]] and what the compiler prints
+//   - [[likely]] / [[unlikely]] (C++20) and [[assume]] (C++23): hints, not guarantees
+//
+// Reference: https://en.cppreference.com/w/cpp/language/attributes
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "[[nodiscard]] on a function and on a type, with a reason string (C++20)",
+    "[[maybe_unused]] for parameters and variables that only exist in one "
+    "build",
+    "[[fallthrough]] to document an intentional switch fall-through",
+    "[[deprecated(\"use X instead\")]] and what the compiler prints",
+    "[[likely]] / [[unlikely]] (C++20) and [[assume]] (C++23): hints, not "
+    "guarantees",
+};
+
+void outline() {
+  LOG_SECTION("Standard attributes (C++11 - C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Attributes",
+            "[[nodiscard]], [[maybe_unused]], [[fallthrough]], [[deprecated]], "
+            "[[likely]], [[assume]]",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/basics/README.md b/src/core/basics/README.md
index c4d9087..3dfa20c 100644
--- a/src/core/basics/README.md
+++ b/src/core/basics/README.md
@@ -6,6 +6,7 @@
 | `Initialization` | default, value, direct, copy, list and aggregate initialization      |
 | `Operations`     | arithmetic, logical (short-circuit) and bitwise operators            |
 | `TypeQualifier`  | `const`, `constexpr`, `consteval`, `constinit`, `mutable`, `volatile` |
+| `Attributes` | [[nodiscard]], [[maybe_unused]], [[fallthrough]], [[deprecated]], [[likely]], [[assume]] *(draft)* |
 
 ## 1. Initialization
 
diff --git a/src/core/class/AbstractInterface.cpp b/src/core/class/AbstractInterface.cpp
new file mode 100644
index 0000000..0721425
--- /dev/null
+++ b/src/core/class/AbstractInterface.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Abstract classes and interfaces (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - = 0 makes a class abstract: it cannot be instantiated
+//   - a pure virtual function may still have a definition, and why that is useful
+//   - an interface: only pure virtual functions plus a virtual destructor
+//   - the non-virtual interface idiom: public non-virtual, private virtual
+//   - programming against an interface: swap the implementation in one line
+//
+// Reference: https://en.cppreference.com/w/cpp/language/abstract_class
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "= 0 makes a class abstract: it cannot be instantiated",
+    "a pure virtual function may still have a definition, and why that is "
+    "useful",
+    "an interface: only pure virtual functions plus a virtual destructor",
+    "the non-virtual interface idiom: public non-virtual, private virtual",
+    "programming against an interface: swap the implementation in one line",
+};
+
+void outline() {
+  LOG_SECTION("Abstract classes and interfaces (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "AbstractInterface",
+    "pure virtual functions, abstract bases, the non-virtual interface idiom",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/class/DeducingThis.cpp b/src/core/class/DeducingThis.cpp
new file mode 100644
index 0000000..55f1e0e
--- /dev/null
+++ b/src/core/class/DeducingThis.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Deducing this (C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - auto&& self replaces the four const/ref overloads of a getter
+//   - how the deduced type propagates const and value category
+//   - recursive lambdas without the Y-combinator trick
+//   - CRTP-free static polymorphism with a deduced self type
+//   - compiler support: this example needs GCC 14 / Clang 18 or newer
+//
+// Reference: https://en.cppreference.com/w/cpp/language/member_functions
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "auto&& self replaces the four const/ref overloads of a getter",
+    "how the deduced type propagates const and value category",
+    "recursive lambdas without the Y-combinator trick",
+    "CRTP-free static polymorphism with a deduced self type",
+    "compiler support: this example needs GCC 14 / Clang 18 or newer",
+};
+
+void outline() {
+  LOG_SECTION("Deducing this (C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("DeducingThis",
+            "explicit object parameters: one member function instead of "
+            "const/non-const pairs",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/class/Inheritance.cpp b/src/core/class/Inheritance.cpp
new file mode 100644
index 0000000..94ffc8e
--- /dev/null
+++ b/src/core/class/Inheritance.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Inheritance (C++98/C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - what public, protected and private inheritance mean for the interface
+//   - override and final: let the compiler catch a wrong signature
+//   - inheriting constructors with using Base::Base (C++11)
+//   - name hiding: a derived overload hides every base overload
+//   - when to prefer composition over inheritance
+//
+// Reference: https://en.cppreference.com/w/cpp/language/derived_class
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "what public, protected and private inheritance mean for the interface",
+    "override and final: let the compiler catch a wrong signature",
+    "inheriting constructors with using Base::Base (C++11)",
+    "name hiding: a derived overload hides every base overload",
+    "when to prefer composition over inheritance",
+};
+
+void outline() {
+  LOG_SECTION("Inheritance (C++98/C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Inheritance",
+            "public, protected and private inheritance, override, final and "
+            "inheriting constructors",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/class/MoveSemantics.cpp b/src/core/class/MoveSemantics.cpp
new file mode 100644
index 0000000..4abc4a5
--- /dev/null
+++ b/src/core/class/MoveSemantics.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Move semantics (C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - a class with an owning pointer: copy vs move, counted with log lines
+//   - std::move is a cast: it only marks an object as movable
+//   - what a moved-from object may be used for (valid but unspecified)
+//   - noexcept moves and why std::vector needs them to move on reallocation
+//   - guaranteed copy elision (C++17): the move that never happens
+//
+// Reference: https://en.cppreference.com/w/cpp/language/move_constructor
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "a class with an owning pointer: copy vs move, counted with log lines",
+    "std::move is a cast: it only marks an object as movable",
+    "what a moved-from object may be used for (valid but unspecified)",
+    "noexcept moves and why std::vector needs them to move on reallocation",
+    "guaranteed copy elision (C++17): the move that never happens",
+};
+
+void outline() {
+  LOG_SECTION("Move semantics (C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("MoveSemantics",
+            "move constructor and assignment, when moves happen, moved-from "
+            "state, copy elision",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/class/README.md b/src/core/class/README.md
index 09d6a6e..1cae2a1 100644
--- a/src/core/class/README.md
+++ b/src/core/class/README.md
@@ -11,6 +11,11 @@
 | `Friend` | friend functions, friend members, friend classes |
 | `Binding` | early (static) vs late (virtual) binding, hiding vs overriding |
 | `VirtualBase` | the diamond problem and virtual inheritance |
+| `Inheritance` | public, protected and private inheritance, override, final and inheriting constructors *(draft)* |
+| `AbstractInterface` | pure virtual functions, abstract bases, the non-virtual interface idiom *(draft)* |
+| `StaticMember` | static data members and functions, inline static, constexpr static and instance counters *(draft)* |
+| `MoveSemantics` | move constructor and assignment, when moves happen, moved-from state, copy elision *(draft)* |
+| `DeducingThis` | explicit object parameters: one member function instead of const/non-const pairs *(draft)* |
 
 ---
 # Classes
diff --git a/src/core/class/StaticMember.cpp b/src/core/class/StaticMember.cpp
new file mode 100644
index 0000000..7b5b9ae
--- /dev/null
+++ b/src/core/class/StaticMember.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Static members (C++98/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - a static data member is shared by every object, and needs one definition
+//   - inline static (C++17) removes the out-of-class definition
+//   - static constexpr members as compile-time constants
+//   - static member functions: no this, callable without an object
+//   - a counter of live instances, incremented in the constructors
+//
+// Reference: https://en.cppreference.com/w/cpp/language/static
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "a static data member is shared by every object, and needs one definition",
+    "inline static (C++17) removes the out-of-class definition",
+    "static constexpr members as compile-time constants",
+    "static member functions: no this, callable without an object",
+    "a counter of live instances, incremented in the constructors",
+};
+
+void outline() {
+  LOG_SECTION("Static members (C++98/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("StaticMember",
+            "static data members and functions, inline static, constexpr "
+            "static and instance counters",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/concurrency/Atomic.cpp b/src/core/concurrency/Atomic.cpp
new file mode 100644
index 0000000..0a6176b
--- /dev/null
+++ b/src/core/concurrency/Atomic.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::atomic (C++11/C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - atomic<int> as a shared counter: no mutex, no data race
+//   - load, store, fetch_add and the read-modify-write operations
+//   - compare_exchange_weak in a lock-free update loop
+//   - memory orders: relaxed, acquire/release, seq_cst - what each guarantees
+//   - is_lock_free, atomic_flag and std::atomic_ref (C++20)
+//
+// Reference: https://en.cppreference.com/w/cpp/atomic/atomic
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "atomic<int> as a shared counter: no mutex, no data race",
+    "load, store, fetch_add and the read-modify-write operations",
+    "compare_exchange_weak in a lock-free update loop",
+    "memory orders: relaxed, acquire/release, seq_cst - what each guarantees",
+    "is_lock_free, atomic_flag and std::atomic_ref (C++20)",
+};
+
+void outline() {
+  LOG_SECTION("std::atomic (C++11/C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Atomic",
+            "atomic counters and flags, compare_exchange, memory orders and "
+            "std::atomic_ref",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/concurrency/Coroutine.cpp b/src/core/concurrency/Coroutine.cpp
new file mode 100644
index 0000000..b052202
--- /dev/null
+++ b/src/core/concurrency/Coroutine.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Coroutines (C++20/C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - what makes a function a coroutine, and where its frame lives
+//   - a lazy generator with co_yield, consumed by a range-for
+//   - the promise_type: initial_suspend, final_suspend, yield_value, return_value
+//   - co_await and a trivial awaitable
+//   - std::generator (C++23) instead of hand-writing the plumbing
+//
+// Reference: https://en.cppreference.com/w/cpp/language/coroutines
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "what makes a function a coroutine, and where its frame lives",
+    "a lazy generator with co_yield, consumed by a range-for",
+    "the promise_type: initial_suspend, final_suspend, yield_value, "
+    "return_value",
+    "co_await and a trivial awaitable",
+    "std::generator (C++23) instead of hand-writing the plumbing",
+};
+
+void outline() {
+  LOG_SECTION("Coroutines (C++20/C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Coroutine",
+    "co_await, co_yield, co_return, the promise type, and std::generator",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/concurrency/ParallelAlgorithm.cpp b/src/core/concurrency/ParallelAlgorithm.cpp
new file mode 100644
index 0000000..d5f6d3b
--- /dev/null
+++ b/src/core/concurrency/ParallelAlgorithm.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Parallel algorithms (C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::sort(std::execution::par, ...) - one argument, many threads
+//   - seq, par, par_unseq and unseq (C++20): what each allows
+//   - the element operations must be safe to run concurrently
+//   - measuring: parallelism only pays above a certain problem size
+//   - libstdc++ needs TBB (-ltbb); check before relying on it
+//
+// Reference: https://en.cppreference.com/w/cpp/algorithm/execution_policy_tag_t
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::sort(std::execution::par, ...) - one argument, many threads",
+    "seq, par, par_unseq and unseq (C++20): what each allows",
+    "the element operations must be safe to run concurrently",
+    "measuring: parallelism only pays above a certain problem size",
+    "libstdc++ needs TBB (-ltbb); check before relying on it",
+};
+
+void outline() {
+  LOG_SECTION("Parallel algorithms (C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("ParallelAlgorithm",
+            "execution policies: par, par_unseq, when parallelism pays off and "
+            "what it costs",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/concurrency/README.md b/src/core/concurrency/README.md
index 85a8920..1c36e0e 100644
--- a/src/core/concurrency/README.md
+++ b/src/core/concurrency/README.md
@@ -8,6 +8,11 @@
 | `ConditionVariable` | waiting for a condition, producer/consumer queue               |
 | `FuturePromise`     | `std::async`, `std::promise`, `std::packaged_task`, exceptions across threads |
 | `Timing`            | `<chrono>` clocks and durations, measuring elapsed time        |
+| `Atomic` | atomic counters and flags, compare_exchange, memory orders and std::atomic_ref *(draft)* |
+| `SharedMutex` | shared_mutex, scoped_lock, unique_lock options, recursive locks and std::call_once *(draft)* |
+| `Synchronization` | std::latch, std::barrier and std::counting_semaphore as coordination primitives *(draft)* |
+| `Coroutine` | co_await, co_yield, co_return, the promise type, and std::generator *(draft)* |
+| `ParallelAlgorithm` | execution policies: par, par_unseq, when parallelism pays off and what it costs *(draft)* |
 
 ## 1. Threads
 
diff --git a/src/core/concurrency/SharedMutex.cpp b/src/core/concurrency/SharedMutex.cpp
new file mode 100644
index 0000000..7132216
--- /dev/null
+++ b/src/core/concurrency/SharedMutex.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Locks beyond std::mutex (C++14/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - shared_lock for many readers, unique_lock for one writer
+//   - std::scoped_lock locks several mutexes without deadlock (C++17)
+//   - unique_lock: defer_lock, try_to_lock, adopt_lock and unlocking early
+//   - std::once_flag and std::call_once for one-time initialisation
+//   - recursive_mutex and timed mutexes: what they are for, and the cost
+//
+// Reference: https://en.cppreference.com/w/cpp/thread/shared_mutex
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "shared_lock for many readers, unique_lock for one writer",
+    "std::scoped_lock locks several mutexes without deadlock (C++17)",
+    "unique_lock: defer_lock, try_to_lock, adopt_lock and unlocking early",
+    "std::once_flag and std::call_once for one-time initialisation",
+    "recursive_mutex and timed mutexes: what they are for, and the cost",
+};
+
+void outline() {
+  LOG_SECTION("Locks beyond std::mutex (C++14/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("SharedMutex",
+            "shared_mutex, scoped_lock, unique_lock options, recursive locks "
+            "and std::call_once",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/concurrency/Synchronization.cpp b/src/core/concurrency/Synchronization.cpp
new file mode 100644
index 0000000..c5f79f1
--- /dev/null
+++ b/src/core/concurrency/Synchronization.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Latches, barriers and semaphores (C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::latch: a one-shot countdown that threads wait on
+//   - std::barrier: a reusable rendezvous with a completion function
+//   - std::counting_semaphore and binary_semaphore for permits
+//   - comparison with condition_variable: less code, fewer mistakes
+//   - a worker pool that starts together and reports when all are done
+//
+// Reference: https://en.cppreference.com/w/cpp/thread/latch
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::latch: a one-shot countdown that threads wait on",
+    "std::barrier: a reusable rendezvous with a completion function",
+    "std::counting_semaphore and binary_semaphore for permits",
+    "comparison with condition_variable: less code, fewer mistakes",
+    "a worker pool that starts together and reports when all are done",
+};
+
+void outline() {
+  LOG_SECTION("Latches, barriers and semaphores (C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Synchronization",
+            "std::latch, std::barrier and std::counting_semaphore as "
+            "coordination primitives",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/container/README.md b/src/core/container/README.md
index 8221d77..fcc9f43 100644
--- a/src/core/container/README.md
+++ b/src/core/container/README.md
@@ -5,11 +5,17 @@
 | `sequence/Array` | `std::array` - fixed size, on the stack |
 | `sequence/Vector` | `std::vector` - dynamic array, growth and invalidation |
 | `sequence/Deque` | `std::deque` - fast at both ends, stable references |
+| `sequence/List` | std::list: doubly linked storage, splice, stable iterators and when not to use it *(draft)* |
+| `sequence/ForwardList` | std::forward_list: a singly linked list with before_begin and insert_after *(draft)* |
 | `associative/Set` | `std::set` - sorted unique keys, ranges, `std::multiset` |
+| `associative/Map` | std::map: sorted keys, operator[] vs at vs insert vs try_emplace, lower_bound, custom comparator *(draft)* |
+| `associative/MultiMap` | duplicate keys: equal_range, count and erasing one of several equal entries *(draft)* |
 | `unordered/UnorderedMap` | `std::unordered_map` - hash table, lookup pitfalls |
+| `unordered/UnorderedSet` | hash sets: custom hash and equality, load factor, and hashing a user-defined type *(draft)* |
 | `adapter/Stack` | `std::stack` - LIFO |
 | `adapter/Queue` | `std::queue` - FIFO |
 | `adapter/PriorityQueue` | `std::priority_queue` - heap, custom priority |
+| `adapter/FlatMap` | sorted vectors behind a map interface: fast lookup and iteration, slow insertion *(draft)* |
 
 Choosing a container:
 
diff --git a/src/core/container/adapter/FlatMap.cpp b/src/core/container/adapter/FlatMap.cpp
new file mode 100644
index 0000000..7099de4
--- /dev/null
+++ b/src/core/container/adapter/FlatMap.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::flat_map and std::flat_set (C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - a flat_map is two vectors: keys and values, kept sorted
+//   - lookup is a binary search, iteration is cache friendly
+//   - insertion and erasure move elements: O(n), unlike std::map
+//   - constructing from sorted input with std::sorted_unique
+//   - check compiler support before using it; the sorted-vector idiom by hand
+//
+// Reference: https://en.cppreference.com/w/cpp/container/flat_map
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "a flat_map is two vectors: keys and values, kept sorted",
+    "lookup is a binary search, iteration is cache friendly",
+    "insertion and erasure move elements: O(n), unlike std::map",
+    "constructing from sorted input with std::sorted_unique",
+    "check compiler support before using it; the sorted-vector idiom by hand",
+};
+
+void outline() {
+  LOG_SECTION("std::flat_map and std::flat_set (C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("FlatMap",
+            "sorted vectors behind a map interface: fast lookup and iteration, "
+            "slow insertion",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/container/associative/Map.cpp b/src/core/container/associative/Map.cpp
new file mode 100644
index 0000000..9299a7d
--- /dev/null
+++ b/src/core/container/associative/Map.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::map (C++98/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - operator[] default-constructs a missing value - at() throws instead
+//   - insert vs insert_or_assign vs emplace vs try_emplace (C++17)
+//   - structured bindings over the pairs, and extract/merge (C++17)
+//   - lower_bound / upper_bound / equal_range on sorted keys
+//   - a custom comparator, and heterogeneous lookup with is_transparent
+//
+// Reference: https://en.cppreference.com/w/cpp/container/map
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "operator[] default-constructs a missing value - at() throws instead",
+    "insert vs insert_or_assign vs emplace vs try_emplace (C++17)",
+    "structured bindings over the pairs, and extract/merge (C++17)",
+    "lower_bound / upper_bound / equal_range on sorted keys",
+    "a custom comparator, and heterogeneous lookup with is_transparent",
+};
+
+void outline() {
+  LOG_SECTION("std::map (C++98/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Map",
+            "std::map: sorted keys, operator[] vs at vs insert vs try_emplace, "
+            "lower_bound, custom comparator",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/container/associative/MultiMap.cpp b/src/core/container/associative/MultiMap.cpp
new file mode 100644
index 0000000..8c2efcc
--- /dev/null
+++ b/src/core/container/associative/MultiMap.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::multimap and std::multiset (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - insert never fails: a multimap keeps every duplicate
+//   - equal_range to walk all values of one key
+//   - erase(key) removes every match - erase(iterator) removes one
+//   - a multiset as a sorted bag, and count() as a frequency table
+//   - when a map<K, vector<V>> is the better model
+//
+// Reference: https://en.cppreference.com/w/cpp/container/multimap
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "insert never fails: a multimap keeps every duplicate",
+    "equal_range to walk all values of one key",
+    "erase(key) removes every match - erase(iterator) removes one",
+    "a multiset as a sorted bag, and count() as a frequency table",
+    "when a map<K, vector<V>> is the better model",
+};
+
+void outline() {
+  LOG_SECTION("std::multimap and std::multiset (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("MultiMap",
+            "duplicate keys: equal_range, count and erasing one of several "
+            "equal entries",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/container/sequence/ForwardList.cpp b/src/core/container/sequence/ForwardList.cpp
new file mode 100644
index 0000000..29a78eb
--- /dev/null
+++ b/src/core/container/sequence/ForwardList.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::forward_list (C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - no size(), no back(), no push_back: the minimal linked list
+//   - before_begin() and why insert_after / erase_after exist
+//   - building a list front to back and reversing it
+//   - memory footprint compared with std::list
+//   - when a singly linked list is the right data structure
+//
+// Reference: https://en.cppreference.com/w/cpp/container/forward_list
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "no size(), no back(), no push_back: the minimal linked list",
+    "before_begin() and why insert_after / erase_after exist",
+    "building a list front to back and reversing it",
+    "memory footprint compared with std::list",
+    "when a singly linked list is the right data structure",
+};
+
+void outline() {
+  LOG_SECTION("std::forward_list (C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("ForwardList",
+            "std::forward_list: a singly linked list with before_begin and "
+            "insert_after",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/container/sequence/List.cpp b/src/core/container/sequence/List.cpp
new file mode 100644
index 0000000..83f6c5f
--- /dev/null
+++ b/src/core/container/sequence/List.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::list (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - insert and erase in the middle in O(1), but no random access
+//   - iterators and references stay valid across insertions and erasures
+//   - splice: move elements between lists without copying
+//   - member sort, merge, unique and remove_if instead of the algorithms
+//   - why std::vector still wins in most benchmarks (cache locality)
+//
+// Reference: https://en.cppreference.com/w/cpp/container/list
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "insert and erase in the middle in O(1), but no random access",
+    "iterators and references stay valid across insertions and erasures",
+    "splice: move elements between lists without copying",
+    "member sort, merge, unique and remove_if instead of the algorithms",
+    "why std::vector still wins in most benchmarks (cache locality)",
+};
+
+void outline() {
+  LOG_SECTION("std::list (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("List",
+            "std::list: doubly linked storage, splice, stable iterators and "
+            "when not to use it",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/container/unordered/UnorderedSet.cpp b/src/core/container/unordered/UnorderedSet.cpp
new file mode 100644
index 0000000..156de66
--- /dev/null
+++ b/src/core/container/unordered/UnorderedSet.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::unordered_set (C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - insert returns a pair: was the element new?
+//   - specializing std::hash for a user type, or passing a hash functor
+//   - the equality functor must agree with the hash
+//   - bucket_count, load_factor, max_load_factor and rehash/reserve
+//   - unordered_set vs set: order, complexity and iteration cost
+//
+// Reference: https://en.cppreference.com/w/cpp/container/unordered_set
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "insert returns a pair: was the element new?",
+    "specializing std::hash for a user type, or passing a hash functor",
+    "the equality functor must agree with the hash",
+    "bucket_count, load_factor, max_load_factor and rehash/reserve",
+    "unordered_set vs set: order, complexity and iteration cost",
+};
+
+void outline() {
+  LOG_SECTION("std::unordered_set (C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("UnorderedSet",
+            "hash sets: custom hash and equality, load factor, and hashing a "
+            "user-defined type",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/datatype/BitOperations.cpp b/src/core/datatype/BitOperations.cpp
new file mode 100644
index 0000000..a69b54f
--- /dev/null
+++ b/src/core/datatype/BitOperations.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Bit manipulation (C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::popcount, std::countl_zero, std::countr_zero, std::bit_width
+//   - std::has_single_bit, std::bit_ceil, std::bit_floor for power-of-two sizes
+//   - std::rotl / std::rotr instead of hand-written shift pairs
+//   - std::endian::native and byte swapping (std::byteswap, C++23)
+//   - the classic hand-written equivalents and how the compiler optimises them
+//
+// Reference: https://en.cppreference.com/w/cpp/header/bit
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::popcount, std::countl_zero, std::countr_zero, std::bit_width",
+    "std::has_single_bit, std::bit_ceil, std::bit_floor for power-of-two sizes",
+    "std::rotl / std::rotr instead of hand-written shift pairs",
+    "std::endian::native and byte swapping (std::byteswap, C++23)",
+    "the classic hand-written equivalents and how the compiler optimises them",
+};
+
+void outline() {
+  LOG_SECTION("Bit manipulation (C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("BitOperations",
+            "the <bit> header: popcount, countl_zero, bit_width, rotl, endian "
+            "and bit_cast",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/datatype/Byte.cpp b/src/core/datatype/Byte.cpp
new file mode 100644
index 0000000..48bb31c
--- /dev/null
+++ b/src/core/datatype/Byte.cpp
@@ -0,0 +1,50 @@
+// -----------------------------------------------------------------------------
+// std::byte (C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::byte is not a number: no arithmetic, only bitwise operators
+//   - std::to_integer<int>(b) and constructing from an integer
+//   - reading and writing a buffer of std::byte
+//   - why char has three flavours and which one to use for text
+//   - std::as_bytes / std::as_writable_bytes over a std::span (C++20)
+//
+// Reference: https://en.cppreference.com/w/cpp/types/byte
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::byte is not a number: no arithmetic, only bitwise operators",
+    "std::to_integer<int>(b) and constructing from an integer",
+    "reading and writing a buffer of std::byte",
+    "why char has three flavours and which one to use for text",
+    "std::as_bytes / std::as_writable_bytes over a std::span (C++20)",
+};
+
+void outline() {
+  LOG_SECTION("std::byte (C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Byte", "std::byte as raw memory, versus char and unsigned char",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/datatype/README.md b/src/core/datatype/README.md
index ea75d37..6a22615 100644
--- a/src/core/datatype/README.md
+++ b/src/core/datatype/README.md
@@ -10,6 +10,9 @@
 | `Struct`          | aggregates, designated initializers, padding and alignment      |
 | `Union`           | the active member rule, `std::bit_cast`, `std::variant`          |
 | `TypeConversions` | implicit conversions, the four casts, slicing, `auto`/`decltype` |
+| `UserDefinedLiteral` | raw string literals, standard literal suffixes and user-defined literals *(draft)* |
+| `Byte` | std::byte as raw memory, versus char and unsigned char *(draft)* |
+| `BitOperations` | the `<bit>` header: popcount, countl_zero, bit_width, rotl, endian and bit_cast *(draft)* |
 
 ## 1. Fundamental types
 
diff --git a/src/core/datatype/UserDefinedLiteral.cpp b/src/core/datatype/UserDefinedLiteral.cpp
new file mode 100644
index 0000000..1db58e5
--- /dev/null
+++ b/src/core/datatype/UserDefinedLiteral.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Literals (C++11/C++14)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - R"(raw \n string)" and the R"delim( ... )delim" form
+//   - standard suffixes: 42s, 1.5f, 10ms, "text"s, "view"sv
+//   - writing operator""_km and operator""_deg for a unit type
+//   - cooked vs raw literal operators, and the template form for digits
+//   - why user-defined suffixes must start with an underscore
+//
+// Reference: https://en.cppreference.com/w/cpp/language/user_literal
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "R\"(raw \\n string)\" and the R\"delim( ... )delim\" form",
+    R"(standard suffixes: 42s, 1.5f, 10ms, "text"s, "view"sv)",
+    R"(writing operator""_km and operator""_deg for a unit type)",
+    "cooked vs raw literal operators, and the template form for digits",
+    "why user-defined suffixes must start with an underscore",
+};
+
+void outline() {
+  LOG_SECTION("Literals (C++11/C++14) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "UserDefinedLiteral",
+    "raw string literals, standard literal suffixes and user-defined literals",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/exception/ErrorCode.cpp b/src/core/exception/ErrorCode.cpp
new file mode 100644
index 0000000..676d695
--- /dev/null
+++ b/src/core/exception/ErrorCode.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Error codes and exception safety (C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - error_code + error_condition: a portable errno
+//   - std::system_error: an exception that carries an error_code
+//   - the filesystem API offers both: throwing and error_code overloads
+//   - the guarantees: nothrow, strong, basic - and what each promises
+//   - copy-and-swap as a recipe for the strong guarantee
+//
+// Reference: https://en.cppreference.com/w/cpp/error/error_code
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "error_code + error_condition: a portable errno",
+    "std::system_error: an exception that carries an error_code",
+    "the filesystem API offers both: throwing and error_code overloads",
+    "the guarantees: nothrow, strong, basic - and what each promises",
+    "copy-and-swap as a recipe for the strong guarantee",
+};
+
+void outline() {
+  LOG_SECTION("Error codes and exception safety (C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("ErrorCode",
+            "std::error_code, std::system_error, errno, and the exception "
+            "safety guarantees",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/exception/README.md b/src/core/exception/README.md
index 9e3ec51..87c0904 100644
--- a/src/core/exception/README.md
+++ b/src/core/exception/README.md
@@ -4,6 +4,7 @@
 |-----------------|------------------------------------------------------------------|
 | `BasicHandle`   | try/catch/throw, custom exceptions, catch order, rethrow, nested exceptions |
 | `ThrowNoexcept` | `noexcept` specifier and operator, `std::terminate`, `noexcept` moves in `std::vector` |
+| `ErrorCode` | std::error_code, std::system_error, errno, and the exception safety guarantees *(draft)* |
 
 ## 1. The mechanism
 
diff --git a/src/core/filehandle/Print.cpp b/src/core/filehandle/Print.cpp
new file mode 100644
index 0000000..67217ac
--- /dev/null
+++ b/src/core/filehandle/Print.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::print and std::println (C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::println("{} scored {}", name, points)
+//   - printing to a file stream or to stderr
+//   - std::format_to and std::format_to_n into an existing buffer
+//   - why print is faster and safer than printf, and shorter than cout
+//   - compiler support: GCC 14 / Clang 18; the std::format fallback
+//
+// Reference: https://en.cppreference.com/w/cpp/io/print
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::println(\"{} scored {}\", name, points)",
+    "printing to a file stream or to stderr",
+    "std::format_to and std::format_to_n into an existing buffer",
+    "why print is faster and safer than printf, and shorter than cout",
+    "compiler support: GCC 14 / Clang 18; the std::format fallback",
+};
+
+void outline() {
+  LOG_SECTION("std::print and std::println (C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Print",
+            "formatted output without iostreams, and how it compares with "
+            "printf and cout",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/filehandle/README.md b/src/core/filehandle/README.md
index 25539c9..9131c52 100644
--- a/src/core/filehandle/README.md
+++ b/src/core/filehandle/README.md
@@ -9,6 +9,7 @@
 | `BinaryFileHandling` | binary records, serializing strings, random access |
 | `Directory` | `std::filesystem`: paths, creating, listing, removing |
 | `TerminalColor` | ANSI escape codes for colors and text effects |
+| `Print` | formatted output without iostreams, and how it compares with printf and cout *(draft)* |
 
 ---
 ## 1. I/O Streams
diff --git a/src/core/function/PerfectForwarding.cpp b/src/core/function/PerfectForwarding.cpp
new file mode 100644
index 0000000..82687aa
--- /dev/null
+++ b/src/core/function/PerfectForwarding.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Perfect forwarding (C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - T&& in a deduced context is a forwarding reference, not an rvalue reference
+//   - reference collapsing: & + && = &
+//   - std::forward<T> keeps the value category, std::move always moves
+//   - a make_unique-style factory that forwards any argument list
+//   - the classic mistakes: forwarding twice, std::forward without a template
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/forward
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "T&& in a deduced context is a forwarding reference, not an rvalue "
+    "reference",
+    "reference collapsing: & + && = &",
+    "std::forward<T> keeps the value category, std::move always moves",
+    "a make_unique-style factory that forwards any argument list",
+    "the classic mistakes: forwarding twice, std::forward without a template",
+};
+
+void outline() {
+  LOG_SECTION("Perfect forwarding (C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("PerfectForwarding",
+            "forwarding references, std::forward, reference collapsing and "
+            "forwarding factories",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/function/README.md b/src/core/function/README.md
index f0153ff..dd234c2 100644
--- a/src/core/function/README.md
+++ b/src/core/function/README.md
@@ -5,6 +5,7 @@
 | `FunctionPointer` | function pointer syntax, comparators, dispatch tables, member function pointers |
 | `Lambda`          | captures, `mutable`, init captures, generic lambdas, closures  |
 | `Functional`      | `std::function`, function objects, `std::bind`, `std::invoke`   |
+| `PerfectForwarding` | forwarding references, std::forward, reference collapsing and forwarding factories *(draft)* |
 
 Operator overloading is in the [operator_overloading](operator_overloading) folder.
 
diff --git a/src/core/linkage/Modules.cpp b/src/core/linkage/Modules.cpp
new file mode 100644
index 0000000..e3f2b16
--- /dev/null
+++ b/src/core/linkage/Modules.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Modules (C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - export module math; and import math; instead of a header
+//   - what a module interface unit exports, and what stays private
+//   - module partitions and implementation units
+//   - no macros leak, no include order, faster builds in principle
+//   - tooling status: modules need extra CMake and compiler support, so this lab still uses headers
+//
+// Reference: https://en.cppreference.com/w/cpp/language/modules
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "export module math; and import math; instead of a header",
+    "what a module interface unit exports, and what stays private",
+    "module partitions and implementation units",
+    "no macros leak, no include order, faster builds in principle",
+    "tooling status: modules need extra CMake and compiler support, so this "
+    "lab still uses headers",
+};
+
+void outline() {
+  LOG_SECTION("Modules (C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Modules",
+    "export module, import, partitions, and what changes compared with headers",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/linkage/OneDefinitionRule.cpp b/src/core/linkage/OneDefinitionRule.cpp
new file mode 100644
index 0000000..460eef0
--- /dev/null
+++ b/src/core/linkage/OneDefinitionRule.cpp
@@ -0,0 +1,54 @@
+// -----------------------------------------------------------------------------
+// The One Definition Rule (C++98/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - one definition per program for functions and variables, one per translation unit for types
+//   - inline functions and inline variables (C++17): identical definitions allowed
+//   - templates and class member functions defined in the header
+//   - typical ODR violations: differing struct layouts behind an #ifdef
+//   - what the linker reports, and what silently goes wrong
+//
+// Reference: https://en.cppreference.com/w/cpp/language/definition
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "one definition per program for functions and variables, one per "
+    "translation unit for types",
+    "inline functions and inline variables (C++17): identical definitions "
+    "allowed",
+    "templates and class member functions defined in the header",
+    "typical ODR violations: differing struct layouts behind an #ifdef",
+    "what the linker reports, and what silently goes wrong",
+};
+
+void outline() {
+  LOG_SECTION("The One Definition Rule (C++98/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("OneDefinitionRule",
+            "what may appear once, what may be repeated, and how inline and "
+            "templates fit in",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/linkage/README.md b/src/core/linkage/README.md
index 7cc7eb4..08a34d4 100644
--- a/src/core/linkage/README.md
+++ b/src/core/linkage/README.md
@@ -4,6 +4,8 @@
 |--------------------------|----------------------------------------------|
 | `Linkage`                | `Linkage.cpp`, `External.h/.cpp`, `Internal.cpp` |
 | `sharing/Sharing`        | `sharing/Sharing.cpp` and the three `constants` variants |
+| `OneDefinitionRule`      | `OneDefinitionRule.cpp` - the ODR, `inline` and templates *(draft)* |
+| `Modules`                | `Modules.cpp` - C++20 `export module` / `import` *(draft)* |
 
 ## 1. Translation units and the linker
 
diff --git a/src/core/template/ClassTemplate.cpp b/src/core/template/ClassTemplate.cpp
new file mode 100644
index 0000000..223df06
--- /dev/null
+++ b/src/core/template/ClassTemplate.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Class templates (C++98/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - a small Stack<T> or Matrix<T>: where member functions must live
+//   - default template arguments and template template parameters
+//   - class template argument deduction: std::vector v{1, 2, 3} (C++17)
+//   - writing a deduction guide when CTAD picks the wrong type
+//   - member function templates and why they cannot be virtual
+//
+// Reference: https://en.cppreference.com/w/cpp/language/class_template
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "a small Stack<T> or Matrix<T>: where member functions must live",
+    "default template arguments and template template parameters",
+    "class template argument deduction: std::vector v{1, 2, 3} (C++17)",
+    "writing a deduction guide when CTAD picks the wrong type",
+    "member function templates and why they cannot be virtual",
+};
+
+void outline() {
+  LOG_SECTION("Class templates (C++98/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("ClassTemplate",
+            "class templates: member functions, default arguments, CTAD and "
+            "deduction guides",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/Concepts.cpp b/src/core/template/Concepts.cpp
new file mode 100644
index 0000000..cabd702
--- /dev/null
+++ b/src/core/template/Concepts.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Concepts (C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - concept Addable = requires(T a, T b) { a + b; };
+//   - the four ways to constrain: requires clause, trailing requires, auto, shorthand
+//   - standard concepts: std::integral, std::ranges::range, std::invocable
+//   - subsumption: the most constrained overload wins
+//   - compare the error message of a failed concept with a raw template error
+//
+// Reference: https://en.cppreference.com/w/cpp/language/constraints
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "concept Addable = requires(T a, T b) { a + b; };",
+    "the four ways to constrain: requires clause, trailing requires, auto, "
+    "shorthand",
+    "standard concepts: std::integral, std::ranges::range, std::invocable",
+    "subsumption: the most constrained overload wins",
+    "compare the error message of a failed concept with a raw template error",
+};
+
+void outline() {
+  LOG_SECTION("Concepts (C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Concepts",
+            "concepts: requires clauses, requires expressions, standard "
+            "concepts and better errors",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/Crtp.cpp b/src/core/template/Crtp.cpp
new file mode 100644
index 0000000..540abaa
--- /dev/null
+++ b/src/core/template/Crtp.cpp
@@ -0,0 +1,54 @@
+// -----------------------------------------------------------------------------
+// The CRTP idiom (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - class Derived : public Base<Derived> - what that buys
+//   - static dispatch: static_cast<Derived*>(this)->impl()
+//   - mixins: adding comparison or printing to any class
+//   - cost comparison with a virtual interface (no vtable, but no runtime dispatch)
+//   - C++23 deducing this as the modern alternative (see core/class/DeducingThis)
+//
+// Reference: https://en.cppreference.com/w/cpp/language/crtp
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "class Derived : public Base<Derived> - what that buys",
+    "static dispatch: static_cast<Derived*>(this)->impl()",
+    "mixins: adding comparison or printing to any class",
+    "cost comparison with a virtual interface (no vtable, but no runtime "
+    "dispatch)",
+    "C++23 deducing this as the modern alternative (see "
+    "core/class/DeducingThis)",
+};
+
+void outline() {
+  LOG_SECTION("The CRTP idiom (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Crtp",
+            "curiously recurring template pattern: static polymorphism and "
+            "mixins without virtual calls",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/FunctionTemplate.cpp b/src/core/template/FunctionTemplate.cpp
new file mode 100644
index 0000000..f28a420
--- /dev/null
+++ b/src/core/template/FunctionTemplate.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Function templates (C++98/C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - template<typename T> and the difference between deduction and explicit T
+//   - how deduction strips references and const, and when it fails
+//   - overloading a template with a non-template function: which one wins
+//   - abbreviated function templates: void print(auto value) (C++20)
+//   - constraints in one line: void print(std::integral auto value) (C++20)
+//
+// Reference: https://en.cppreference.com/w/cpp/language/function_template
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "template<typename T> and the difference between deduction and explicit T",
+    "how deduction strips references and const, and when it fails",
+    "overloading a template with a non-template function: which one wins",
+    "abbreviated function templates: void print(auto value) (C++20)",
+    "constraints in one line: void print(std::integral auto value) (C++20)",
+};
+
+void outline() {
+  LOG_SECTION("Function templates (C++98/C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("FunctionTemplate",
+            "function templates: argument deduction, explicit arguments, "
+            "overloading, auto parameters",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/NonTypeParameter.cpp b/src/core/template/NonTypeParameter.cpp
new file mode 100644
index 0000000..20e2251
--- /dev/null
+++ b/src/core/template/NonTypeParameter.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Non-type template parameters (C++11/C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - template<std::size_t N> class FixedBuffer: the size is part of the type
+//   - why std::array<int, 4> and std::array<int, 5> are unrelated types
+//   - auto as a non-type parameter (C++17)
+//   - structural types as NTTPs, including a compile-time string (C++20)
+//   - NTTPs vs constructor arguments: what moves work to compile time
+//
+// Reference: https://en.cppreference.com/w/cpp/language/template_parameters
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "template<std::size_t N> class FixedBuffer: the size is part of the type",
+    "why std::array<int, 4> and std::array<int, 5> are unrelated types",
+    "auto as a non-type parameter (C++17)",
+    "structural types as NTTPs, including a compile-time string (C++20)",
+    "NTTPs vs constructor arguments: what moves work to compile time",
+};
+
+void outline() {
+  LOG_SECTION("Non-type template parameters (C++11/C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "NonTypeParameter",
+    "non-type template parameters, auto NTTPs and compile-time sized types",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/README.md b/src/core/template/README.md
new file mode 100644
index 0000000..075d6b7
--- /dev/null
+++ b/src/core/template/README.md
@@ -0,0 +1,58 @@
+# Templates
+
+| Example | Topic |
+|---|---|
+| `FunctionTemplate` | argument deduction, explicit arguments, overloading, `auto` parameters *(draft)* |
+| `ClassTemplate` | member functions, default arguments, CTAD and deduction guides *(draft)* |
+| `Specialization` | full and partial specialization, and why functions overload instead *(draft)* |
+| `NonTypeParameter` | non-type template parameters, `auto` NTTPs, compile-time strings *(draft)* |
+| `Concepts` | `requires` clauses and expressions, standard concepts, subsumption *(draft)* |
+| `Sfinae` | `enable_if`, `void_t`, and how `if constexpr` and concepts replace them *(draft)* |
+| `Crtp` | static polymorphism and mixins without virtual calls *(draft)* |
+| `VariableTemplate` | variable templates, `constexpr` and `inline` variables *(draft)* |
+| `TwoPhaseLookup` | dependent names, `typename`/`template`, explicit instantiation *(draft)* |
+
+> Every example in this folder is still a **draft**: the file lists what it should teach and prints
+> that outline when you run it. See [docs/adding-examples.md](../../../docs/adding-examples.md).
+
+---
+## 1. What a template is
+
+A template is not code - it is a recipe the compiler uses to *generate* code. Nothing is compiled
+until the template is **instantiated** with concrete arguments:
+
+```cpp
+template <typename T>
+T max(T a, T b) { return a < b ? b : a; }
+
+max(1, 2);        // instantiates max<int>
+max(1.0, 2.0);    // instantiates max<double>
+max(1, 2.0);      // error: T cannot be both int and double - deduction conflict
+```
+
+Consequences that surprise newcomers:
+
+- Template definitions normally live in **headers**: the compiler needs the body at the point of
+  instantiation (the alternative is explicit instantiation, see `TwoPhaseLookup`).
+- Errors appear at instantiation, often deep inside the standard library. **Concepts** (C++20) move
+  those errors back to the call site - that is their main practical benefit.
+- Every distinct set of arguments produces distinct code, which grows the binary. That is the
+  trade-off for having no runtime dispatch.
+
+## 2. Compile time vs run time
+
+| Question | Templates | Virtual functions |
+|---|---|---|
+| When is the type chosen? | compile time | run time |
+| Cost per call | none (inlinable) | one indirect call |
+| Can the set of types grow after compilation? | no | yes (also with `dlopen`) |
+| Binary size | one copy per type | one implementation |
+
+`Crtp` shows the template answer to polymorphism, `core/class/AbstractInterface` the virtual one,
+and `dp/idiom/TypeErasure` the hybrid that `std::function` uses.
+
+## 3. Where to look next
+
+- `core/utils/TypeTraits` - `<type_traits>`, the detection idiom and concepts in practice
+- `core/utils/Variadic` - parameter packs and fold expressions
+- `core/function/PerfectForwarding` - forwarding references, which only exist in templates
diff --git a/src/core/template/Sfinae.cpp b/src/core/template/Sfinae.cpp
new file mode 100644
index 0000000..8946953
--- /dev/null
+++ b/src/core/template/Sfinae.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// SFINAE and if constexpr (C++11/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - substitution failure is not an error: the compiler drops the overload
+//   - std::enable_if_t in the return type, in a parameter and as a template argument
+//   - the void_t detection idiom: does T have a .size() member?
+//   - if constexpr (C++17) instead of two overloads
+//   - the same check written as a C++20 concept, side by side
+//
+// Reference: https://en.cppreference.com/w/cpp/language/sfinae
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "substitution failure is not an error: the compiler drops the overload",
+    "std::enable_if_t in the return type, in a parameter and as a template "
+    "argument",
+    "the void_t detection idiom: does T have a .size() member?",
+    "if constexpr (C++17) instead of two overloads",
+    "the same check written as a C++20 concept, side by side",
+};
+
+void outline() {
+  LOG_SECTION("SFINAE and if constexpr (C++11/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Sfinae",
+            "SFINAE with enable_if and void_t, and how if constexpr and "
+            "concepts replace it",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/Specialization.cpp b/src/core/template/Specialization.cpp
new file mode 100644
index 0000000..6f1c26a
--- /dev/null
+++ b/src/core/template/Specialization.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Template specialization (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - full specialization of a class template: Serializer<bool>
+//   - partial specialization: Serializer<T*>, Serializer<std::vector<T>>
+//   - function templates cannot be partially specialized - overload instead
+//   - tag dispatch as the older alternative to if constexpr
+//   - specializing std::hash for a user-defined type
+//
+// Reference: https://en.cppreference.com/w/cpp/language/template_specialization
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "full specialization of a class template: Serializer<bool>",
+    "partial specialization: Serializer<T*>, Serializer<std::vector<T>>",
+    "function templates cannot be partially specialized - overload instead",
+    "tag dispatch as the older alternative to if constexpr",
+    "specializing std::hash for a user-defined type",
+};
+
+void outline() {
+  LOG_SECTION("Template specialization (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Specialization",
+            "full and partial specialization, and why function templates use "
+            "overloading instead",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/TwoPhaseLookup.cpp b/src/core/template/TwoPhaseLookup.cpp
new file mode 100644
index 0000000..472011a
--- /dev/null
+++ b/src/core/template/TwoPhaseLookup.cpp
@@ -0,0 +1,54 @@
+// -----------------------------------------------------------------------------
+// Two-phase lookup and dependent names (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - what the compiler checks at definition time and what waits for instantiation
+//   - typename T::value_type: why the keyword is needed (optional since C++20 in some places)
+//   - obj.template get<0>() and Base<T>::template rebind<U>
+//   - why members of a dependent base need this-> or a using declaration
+//   - declaration in a header, definition in a .cpp plus explicit instantiation
+//
+// Reference: https://en.cppreference.com/w/cpp/language/dependent_name
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "what the compiler checks at definition time and what waits for "
+    "instantiation",
+    "typename T::value_type: why the keyword is needed (optional since C++20 "
+    "in some places)",
+    "obj.template get<0>() and Base<T>::template rebind<U>",
+    "why members of a dependent base need this-> or a using declaration",
+    "declaration in a header, definition in a .cpp plus explicit instantiation",
+};
+
+void outline() {
+  LOG_SECTION("Two-phase lookup and dependent names (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("TwoPhaseLookup",
+            "typename and template disambiguators, dependent names, explicit "
+            "instantiation",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/template/VariableTemplate.cpp b/src/core/template/VariableTemplate.cpp
new file mode 100644
index 0000000..2c1265b
--- /dev/null
+++ b/src/core/template/VariableTemplate.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Variable templates (C++14/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - template<typename T> constexpr T pi = T(3.14159265358979);
+//   - the _v trait shorthands: std::is_integral_v<T> is a variable template
+//   - specializing a variable template
+//   - inline variables (C++17): one definition shared by every translation unit
+//   - how this differs from a constexpr function
+//
+// Reference: https://en.cppreference.com/w/cpp/language/variable_template
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "template<typename T> constexpr T pi = T(3.14159265358979);",
+    "the _v trait shorthands: std::is_integral_v<T> is a variable template",
+    "specializing a variable template",
+    "inline variables (C++17): one definition shared by every translation unit",
+    "how this differs from a constexpr function",
+};
+
+void outline() {
+  LOG_SECTION("Variable templates (C++14/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "VariableTemplate",
+    "variable templates, constexpr and inline variables at namespace scope",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Any.cpp b/src/core/utils/Any.cpp
new file mode 100644
index 0000000..9a05dbb
--- /dev/null
+++ b/src/core/utils/Any.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::any (C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::any holds one value of any copyable type, with its type_info
+//   - any_cast<T>: the reference form throws, the pointer form returns nullptr
+//   - has_value, reset, emplace and small-object optimisation
+//   - any vs variant: open set of types vs a closed, checked one
+//   - a realistic use: a heterogeneous settings map
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/any
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::any holds one value of any copyable type, with its type_info",
+    "any_cast<T>: the reference form throws, the pointer form returns nullptr",
+    "has_value, reset, emplace and small-object optimisation",
+    "any vs variant: open set of types vs a closed, checked one",
+    "a realistic use: a heterogeneous settings map",
+};
+
+void outline() {
+  LOG_SECTION("std::any (C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Any",
+            "type-erased storage for a single value of any type, and when "
+            "variant or optional fit better",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Bitset.cpp b/src/core/utils/Bitset.cpp
new file mode 100644
index 0000000..e2bb54a
--- /dev/null
+++ b/src/core/utils/Bitset.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::bitset (C++98)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - set, reset, flip, test and operator[]
+//   - count, any, all, none
+//   - conversion: to_string, to_ulong, to_ullong and constructing from both
+//   - bitwise operators between bitsets, and shifting
+//   - bitset vs vector<bool> vs an enum of bit flags (see core/datatype/Enum)
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/bitset
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "set, reset, flip, test and operator[]",
+    "count, any, all, none",
+    "conversion: to_string, to_ulong, to_ullong and constructing from both",
+    "bitwise operators between bitsets, and shifting",
+    "bitset vs vector<bool> vs an enum of bit flags (see core/datatype/Enum)",
+};
+
+void outline() {
+  LOG_SECTION("std::bitset (C++98) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Bitset",
+            "a fixed-size sequence of bits: flags, counting, and conversion to "
+            "strings and integers",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Expected.cpp b/src/core/utils/Expected.cpp
new file mode 100644
index 0000000..533d2fd
--- /dev/null
+++ b/src/core/utils/Expected.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::expected (C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - expected<T, E> carries either a result or an error, unlike optional
+//   - has_value, value, error, value_or and std::unexpected
+//   - chaining with and_then, transform, or_else and transform_error
+//   - expected vs exceptions: cost, visibility in the signature, nodiscard
+//   - compiler support: needs GCC 13 / Clang 16 or newer
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/expected
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "expected<T, E> carries either a result or an error, unlike optional",
+    "has_value, value, error, value_or and std::unexpected",
+    "chaining with and_then, transform, or_else and transform_error",
+    "expected vs exceptions: cost, visibility in the signature, nodiscard",
+    "compiler support: needs GCC 13 / Clang 16 or newer",
+};
+
+void outline() {
+  LOG_SECTION("std::expected (C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Expected",
+            "errors as values: expected<T, E>, and_then/transform, compared "
+            "with optional and exceptions",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Mdspan.cpp b/src/core/utils/Mdspan.cpp
new file mode 100644
index 0000000..bad36f8
--- /dev/null
+++ b/src/core/utils/Mdspan.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// std::mdspan (C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - a flat vector viewed as a 2D matrix: m[row, col] (C++23 subscript)
+//   - static and dynamic extents
+//   - layout_right vs layout_left: row major and column major over the same data
+//   - submdspan and slicing
+//   - compiler support, and the hand-written index arithmetic it replaces
+//
+// Reference: https://en.cppreference.com/w/cpp/container/mdspan
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "a flat vector viewed as a 2D matrix: m[row, col] (C++23 subscript)",
+    "static and dynamic extents",
+    "layout_right vs layout_left: row major and column major over the same "
+    "data",
+    "submdspan and slicing",
+    "compiler support, and the hand-written index arithmetic it replaces",
+};
+
+void outline() {
+  LOG_SECTION("std::mdspan (C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Mdspan",
+    "multidimensional views over flat storage: extents, layouts and accessors",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Numeric.cpp b/src/core/utils/Numeric.cpp
new file mode 100644
index 0000000..b1b9a7e
--- /dev/null
+++ b/src/core/utils/Numeric.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// The numeric algorithms (C++11/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::iota to fill a range with increasing values
+//   - accumulate is sequential and ordered; reduce may reorder (C++17)
+//   - transform_reduce: the map-reduce pair in one call
+//   - partial_sum, adjacent_difference and inclusive/exclusive_scan
+//   - std::gcd, std::lcm and std::midpoint (why (a+b)/2 can overflow)
+//
+// Reference: https://en.cppreference.com/w/cpp/header/numeric
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::iota to fill a range with increasing values",
+    "accumulate is sequential and ordered; reduce may reorder (C++17)",
+    "transform_reduce: the map-reduce pair in one call",
+    "partial_sum, adjacent_difference and inclusive/exclusive_scan",
+    "std::gcd, std::lcm and std::midpoint (why (a+b)/2 can overflow)",
+};
+
+void outline() {
+  LOG_SECTION("The numeric algorithms (C++11/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Numeric",
+            "<numeric>: iota, accumulate vs reduce, inner_product, "
+            "partial_sum, gcd, lcm, midpoint",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/README.md b/src/core/utils/README.md
index 57cf747..3ff4b1b 100644
--- a/src/core/utils/README.md
+++ b/src/core/utils/README.md
@@ -7,6 +7,17 @@
 | `Regex` | `<regex>`: match, search, capture groups, replace |
 | `TypeTraits` | `<type_traits>`, the detection idiom, `enable_if`, C++20 concepts |
 | `Variadic` | C-style `va_list` vs variadic templates and fold expressions |
+| `Tuple` | tuples: make_tuple, get, tie, structured bindings, std::apply and returning several values *(draft)* |
+| `Any` | type-erased storage for a single value of any type, and when variant or optional fit better *(draft)* |
+| `Bitset` | a fixed-size sequence of bits: flags, counting, and conversion to strings and integers *(draft)* |
+| `Random` | `<random>`: engines, seeding, distributions, and why std::rand is not enough *(draft)* |
+| `Expected` | errors as values: expected<T, E>, and_then/transform, compared with optional and exceptions *(draft)* |
+| `Numeric` | `<numeric>`: iota, accumulate vs reduce, inner_product, partial_sum, gcd, lcm, midpoint *(draft)* |
+| `Ranges` | range algorithms, lazy views, pipelines, projections and ranges::to *(draft)* |
+| `SourceLocation` | capture the call site without macros, and print a stack trace *(draft)* |
+| `Span` | a non-owning view over contiguous memory: pointer + size in one type *(draft)* |
+| `Mdspan` | multidimensional views over flat storage: extents, layouts and accessors *(draft)* |
+| `Utility` | std::swap, std::exchange, std::as_const, integer comparisons and std::to_underlying *(draft)* |
 
 ---
 ## Utilities library
diff --git a/src/core/utils/Random.cpp b/src/core/utils/Random.cpp
new file mode 100644
index 0000000..5b6a668
--- /dev/null
+++ b/src/core/utils/Random.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Random numbers (C++11)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - engine + distribution: std::mt19937 and std::uniform_int_distribution
+//   - seeding from std::random_device, and seeding fixed for reproducible runs
+//   - uniform_real, normal, bernoulli and discrete distributions
+//   - why rand() % n is biased, and what modulo does to the distribution
+//   - std::shuffle and std::sample instead of hand-rolled picking
+//
+// Reference: https://en.cppreference.com/w/cpp/numeric/random
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "engine + distribution: std::mt19937 and std::uniform_int_distribution",
+    "seeding from std::random_device, and seeding fixed for reproducible runs",
+    "uniform_real, normal, bernoulli and discrete distributions",
+    "why rand() % n is biased, and what modulo does to the distribution",
+    "std::shuffle and std::sample instead of hand-rolled picking",
+};
+
+void outline() {
+  LOG_SECTION("Random numbers (C++11) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Random",
+            "<random>: engines, seeding, distributions, and why std::rand is "
+            "not enough",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Ranges.cpp b/src/core/utils/Ranges.cpp
new file mode 100644
index 0000000..82dc510
--- /dev/null
+++ b/src/core/utils/Ranges.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Ranges and views (C++20/C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::ranges::sort(v) instead of sort(v.begin(), v.end())
+//   - projections: sort people by .age without a comparator
+//   - views are lazy and cheap: filter, transform, take, drop, reverse
+//   - composing a pipeline with operator| and where the work actually happens
+//   - materialising with std::ranges::to<std::vector> (C++23); zip, chunk, adjacent
+//
+// Reference: https://en.cppreference.com/w/cpp/ranges
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::ranges::sort(v) instead of sort(v.begin(), v.end())",
+    "projections: sort people by .age without a comparator",
+    "views are lazy and cheap: filter, transform, take, drop, reverse",
+    "composing a pipeline with operator| and where the work actually happens",
+    "materialising with std::ranges::to<std::vector> (C++23); zip, chunk, "
+    "adjacent",
+};
+
+void outline() {
+  LOG_SECTION("Ranges and views (C++20/C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Ranges",
+    "range algorithms, lazy views, pipelines, projections and ranges::to",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/SourceLocation.cpp b/src/core/utils/SourceLocation.cpp
new file mode 100644
index 0000000..b7c4be9
--- /dev/null
+++ b/src/core/utils/SourceLocation.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// std::source_location and std::stacktrace (C++20/C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::source_location::current() as a default argument
+//   - file_name, line, column and function_name
+//   - a logging helper that reports its caller (this is how lab/Logger.h works)
+//   - why this replaces __FILE__ / __LINE__ macros
+//   - std::stacktrace (C++23) and linking with -lstdc++exp
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/source_location
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::source_location::current() as a default argument",
+    "file_name, line, column and function_name",
+    "a logging helper that reports its caller (this is how lab/Logger.h works)",
+    "why this replaces __FILE__ / __LINE__ macros",
+    "std::stacktrace (C++23) and linking with -lstdc++exp",
+};
+
+void outline() {
+  LOG_SECTION(
+      "std::source_location and std::stacktrace (C++20/C++23) - planned "
+      "content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("SourceLocation",
+            "capture the call site without macros, and print a stack trace",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Span.cpp b/src/core/utils/Span.cpp
new file mode 100644
index 0000000..012fcbe
--- /dev/null
+++ b/src/core/utils/Span.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::span (C++20)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - one function signature for arrays, vectors and std::array
+//   - static vs dynamic extent, and what that costs
+//   - first, last, subspan without copying
+//   - span is a view: the referenced storage must outlive it
+//   - as_bytes for a raw view, and span vs string_view
+//
+// Reference: https://en.cppreference.com/w/cpp/container/span
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "one function signature for arrays, vectors and std::array",
+    "static vs dynamic extent, and what that costs",
+    "first, last, subspan without copying",
+    "span is a view: the referenced storage must outlive it",
+    "as_bytes for a raw view, and span vs string_view",
+};
+
+void outline() {
+  LOG_SECTION("std::span (C++20) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Span",
+    "a non-owning view over contiguous memory: pointer + size in one type",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Tuple.cpp b/src/core/utils/Tuple.cpp
new file mode 100644
index 0000000..67a0bd5
--- /dev/null
+++ b/src/core/utils/Tuple.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// std::tuple and std::pair (C++11/C++17)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::pair and std::tuple: heterogeneous fixed-size collections
+//   - std::get<0> and std::get<Type>, and why the index must be a constant
+//   - returning several values: tuple + structured bindings vs a small struct
+//   - std::tie for assignment and for lexicographic comparison
+//   - std::apply and std::make_from_tuple (C++17)
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/tuple
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::pair and std::tuple: heterogeneous fixed-size collections",
+    "std::get<0> and std::get<Type>, and why the index must be a constant",
+    "returning several values: tuple + structured bindings vs a small struct",
+    "std::tie for assignment and for lexicographic comparison",
+    "std::apply and std::make_from_tuple (C++17)",
+};
+
+void outline() {
+  LOG_SECTION("std::tuple and std::pair (C++11/C++17) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Tuple",
+            "tuples: make_tuple, get, tie, structured bindings, std::apply and "
+            "returning several values",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/core/utils/Utility.cpp b/src/core/utils/Utility.cpp
new file mode 100644
index 0000000..e26fbc2
--- /dev/null
+++ b/src/core/utils/Utility.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Small utilities of <utility> (C++11 - C++23)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::swap, and why a member swap can be faster
+//   - std::exchange: assign and return the old value in one step
+//   - std::as_const to force the const overload
+//   - std::cmp_less and friends (C++20): comparing signed with unsigned safely
+//   - std::to_underlying (C++23) instead of static_cast on a scoped enum
+//
+// Reference: https://en.cppreference.com/w/cpp/header/utility
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::swap, and why a member swap can be faster",
+    "std::exchange: assign and return the old value in one step",
+    "std::as_const to force the const overload",
+    "std::cmp_less and friends (C++20): comparing signed with unsigned safely",
+    "std::to_underlying (C++23) instead of static_cast on a scoped enum",
+};
+
+void outline() {
+  LOG_SECTION("Small utilities of <utility> (C++11 - C++23) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE("Utility",
+            "std::swap, std::exchange, std::as_const, integer comparisons and "
+            "std::to_underlying",
+            lab::kDraft) {
+  outline();
+}
diff --git a/src/dp/behavioral/Interpreter.cpp b/src/dp/behavioral/Interpreter.cpp
new file mode 100644
index 0000000..267d1e8
--- /dev/null
+++ b/src/dp/behavioral/Interpreter.cpp
@@ -0,0 +1,52 @@
+// -----------------------------------------------------------------------------
+// Interpreter (GoF)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - an expression tree: numbers, variables and binary operators
+//   - one class per grammar rule, each with interpret(context)
+//   - the context: variable bindings passed down the tree
+//   - parsing a string into the tree (a tiny recursive descent parser)
+//   - when a real parser generator or std::variant visitor is the better answer
+//
+// Reference: https://refactoring.guru/design-patterns
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "an expression tree: numbers, variables and binary operators",
+    "one class per grammar rule, each with interpret(context)",
+    "the context: variable bindings passed down the tree",
+    "parsing a string into the tree (a tiny recursive descent parser)",
+    "when a real parser generator or std::variant visitor is the better answer",
+};
+
+void outline() {
+  LOG_SECTION("Interpreter (GoF) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Interpreter",
+    "represent a small grammar as a class per rule and evaluate expressions",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/dp/behavioral/README.md b/src/dp/behavioral/README.md
index 0935281..0e68c94 100644
--- a/src/dp/behavioral/README.md
+++ b/src/dp/behavioral/README.md
@@ -1,6 +1,8 @@
-> Examples: `dp/behavioral/{ChainOfResponsibility, Command, Iterator, Mediator, Memento, Observer,
-> State, Strategy, TemplateMethod, Visitor}` - run one with
+> Examples: `dp/behavioral/{ChainOfResponsibility, Command, Interpreter, Iterator, Mediator,
+> Memento, Observer, State, Strategy, TemplateMethod, Visitor}` - run one with
 > `./build/bin/cpp_lab_project --run dp/behavioral/Observer`
+>
+> `Interpreter` is still a draft: the file lists what it should teach and prints that outline.
 
 # Behavioral Design Patterns
 
diff --git a/src/dp/idiom/Pimpl.cpp b/src/dp/idiom/Pimpl.cpp
new file mode 100644
index 0000000..ffe8854
--- /dev/null
+++ b/src/dp/idiom/Pimpl.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// The pImpl idiom (C++ idiom)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - class Widget { struct Impl; std::unique_ptr<Impl> impl_; };
+//   - the destructor must be defined where Impl is complete
+//   - what it buys: no private members in the header, fewer rebuilds, stable ABI
+//   - what it costs: an allocation and an indirection per object
+//   - copy semantics: they have to be written by hand
+//
+// Reference: https://en.cppreference.com/w/cpp/language/pimpl
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "class Widget { struct Impl; std::unique_ptr<Impl> impl_; };",
+    "the destructor must be defined where Impl is complete",
+    "what it buys: no private members in the header, fewer rebuilds, stable "
+    "ABI",
+    "what it costs: an allocation and an indirection per object",
+    "copy semantics: they have to be written by hand",
+};
+
+void outline() {
+  LOG_SECTION("The pImpl idiom (C++ idiom) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "Pimpl",
+    "hide the implementation behind a pointer: stable ABI and faster rebuilds",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/dp/idiom/README.md b/src/dp/idiom/README.md
new file mode 100644
index 0000000..62f6e96
--- /dev/null
+++ b/src/dp/idiom/README.md
@@ -0,0 +1,24 @@
+# C++ Idioms
+
+Patterns that are not in the Gang of Four book but that every C++ codebase runs into.
+
+| Example | Topic |
+|---|---|
+| `Pimpl` | hide the implementation behind a pointer: stable ABI, faster rebuilds *(draft)* |
+| `TypeErasure` | store any type that satisfies an interface, without a common base *(draft)* |
+
+> Both examples are still **drafts**: the file lists what it should teach and prints that outline
+> when you run it.
+
+---
+## Idioms already shown elsewhere in the lab
+
+| Idiom | Where |
+|---|---|
+| RAII | `core/class/Destructor`, `core/smart_pointer/Unique` |
+| Rule of 0/3/5 | `core/class/RuleOfThreeFiveZero` |
+| Copy and swap | `core/function/operator_overloading/AssignmentOperator` |
+| Non-virtual interface | `core/class/AbstractInterface` *(draft)* |
+| CRTP | `core/template/Crtp` *(draft)* |
+| Meyers' singleton | `dp/creational/Singleton` |
+| SFINAE / detection idiom | `core/utils/TypeTraits`, `core/template/Sfinae` *(draft)* |
diff --git a/src/dp/idiom/TypeErasure.cpp b/src/dp/idiom/TypeErasure.cpp
new file mode 100644
index 0000000..8e44a5f
--- /dev/null
+++ b/src/dp/idiom/TypeErasure.cpp
@@ -0,0 +1,53 @@
+// -----------------------------------------------------------------------------
+// Type erasure (C++ idiom)
+//
+// DRAFT - a scaffold, not a finished example: it says what this topic should
+// show, but the code is not written yet. Replace outline() with real
+// demonstrations and drop `lab::kDraft` from LAB_EXAMPLE at the bottom.
+//
+// Planned content:
+//   - std::function is type erasure: any callable with the right signature
+//   - the three parts: a concept struct, a templated model, a handle that owns it
+//   - a Drawable that accepts any type with a draw() member
+//   - cost: one allocation and one virtual call, like an interface
+//   - alternatives: std::variant (closed set) and templates (compile time)
+//
+// Reference: https://en.cppreference.com/w/cpp/utility/functional/function
+// -----------------------------------------------------------------------------
+
+#include <array>
+#include <string_view>
+
+#include "lab/Example.h"
+#include "lab/Logger.h"
+
+namespace {
+
+// The same list as in the header comment, so that running the draft shows what
+// is still missing.
+constexpr std::array<std::string_view, 5> kPlanned{
+    "std::function is type erasure: any callable with the right signature",
+    "the three parts: a concept struct, a templated model, a handle that owns "
+    "it",
+    "a Drawable that accepts any type with a draw() member",
+    "cost: one allocation and one virtual call, like an interface",
+    "alternatives: std::variant (closed set) and templates (compile time)",
+};
+
+void outline() {
+  LOG_SECTION("Type erasure (C++ idiom) - planned content");
+  for (const std::string_view point : kPlanned) {
+    LOG_S("  - " << point);
+  }
+  LOG("");
+  LOG("This example is still a draft. Write it, then remove lab::kDraft.");
+}
+
+}  // namespace
+
+LAB_EXAMPLE(
+    "TypeErasure",
+    "store any type that satisfies an interface, without a common base class",
+    lab::kDraft) {
+  outline();
+}
diff --git a/src/lab/Menu.cpp b/src/lab/Menu.cpp
index 7250a05..418188f 100644
--- a/src/lab/Menu.cpp
+++ b/src/lab/Menu.cpp
@@ -117,7 +117,7 @@ void printNode(const MenuNode& node, bool is_root, std::ostream& out) {
   for (const Example* example : node.examples) {
     out << std::setw(4) << index++ << ". " << std::left << std::setw(kNameWidth)
         << example->name << std::right << ' ' << example->description
-        << (example->isInteractive() ? "  [interactive]" : "") << '\n';
+        << example->labels() << '\n';
   }
   out << rule << '\n'
       << " <number> open    0 " << (is_root ? "quit" : "back")
diff --git a/src/lab/Registry.cpp b/src/lab/Registry.cpp
index 358167f..d54da3e 100644
--- a/src/lab/Registry.cpp
+++ b/src/lab/Registry.cpp
@@ -46,6 +46,17 @@ bool isValidName(std::string_view name) {
 
 }  // namespace
 
+std::string Example::labels() const {
+  std::string text;
+  if (isDraft()) {
+    text += "  [draft]";
+  }
+  if (isInteractive()) {
+    text += "  [interactive]";
+  }
+  return text;
+}
+
 namespace detail {
 
 std::string relativeSourcePath(std::string_view file,
diff --git a/src/lab/Runner.cpp b/src/lab/Runner.cpp
index 23c950d..88fe178 100644
--- a/src/lab/Runner.cpp
+++ b/src/lab/Runner.cpp
@@ -19,8 +19,7 @@ bool runExample(const Example& example, std::ostream& out) {
 
   out << '\n'
       << heavy_rule << '\n'
-      << "> " << example.id
-      << (example.isInteractive() ? "  [interactive]" : "") << '\n'
+      << "> " << example.id << example.labels() << '\n'
       << "  " << example.description << '\n'
       << "  source: " << example.source << '\n'
       << heavy_rule << '\n'
diff --git a/src/main.cpp b/src/main.cpp
index c74c584..081e7c3 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -59,8 +59,7 @@ void listExamples(const lab::Registry& registry, std::string_view filter) {
 
   for (const lab::Example* example : matches) {
     std::cout << std::left << std::setw(static_cast<int>(width)) << example->id
-              << "  " << example->description
-              << (example->isInteractive() ? "  [interactive]" : "") << '\n';
+              << "  " << example->description << example->labels() << '\n';
   }
   std::cout << std::right << matches.size() << " example(s)\n";
 }
diff --git a/tests/lab/RegistryTest.cpp b/tests/lab/RegistryTest.cpp
index 611380b..71178ce 100644
--- a/tests/lab/RegistryTest.cpp
+++ b/tests/lab/RegistryTest.cpp
@@ -109,6 +109,20 @@ TEST_F(RegistryTest, StoresFlags) {
   registry_.add("/x/src/socket/Server.cpp", "Server", "", noop,
                 lab::kInteractive);
   EXPECT_TRUE(registry_.examples().front().isInteractive());
+  EXPECT_FALSE(registry_.examples().front().isDraft());
+  EXPECT_EQ(registry_.examples().front().labels(), "  [interactive]");
+}
+
+TEST_F(RegistryTest, LabelsDraftAndInteractiveExamples) {
+  registry_.add("/x/src/core/A.cpp", "Plain", "", noop);
+  registry_.add("/x/src/core/B.cpp", "Draft", "", noop, lab::kDraft);
+  registry_.add("/x/src/core/C.cpp", "Both", "", noop,
+                lab::kDraft | lab::kInteractive);
+
+  EXPECT_EQ(registry_.find("core/Plain")->labels(), "");
+  EXPECT_TRUE(registry_.find("core/Draft")->isDraft());
+  EXPECT_EQ(registry_.find("core/Draft")->labels(), "  [draft]");
+  EXPECT_EQ(registry_.find("core/Both")->labels(), "  [draft]  [interactive]");
 }
 
 TEST_F(RegistryTest, FindPrefersExactMatches) {

From af7f04997cc21ef8093105ccbf65be93ec24e2a6 Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 09:18:59 +0700
Subject: [PATCH 19/20] Point the learning path and the README at the open
 drafts

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 README.md             |  2 +-
 docs/learning-path.md | 13 +++++++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4b57438..dc50167 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ src/
   lab/         framework implementation
   main.cpp     entry point: command line and menu
   core/        C++ language and standard library examples (incl. templates)
-  dp/          design patterns (behavioral, creational, structural)
+  dp/          design patterns (behavioral, creational, structural) and C++ idioms
   controller/  control algorithms (PID)
   socket/      POSIX TCP sockets
   ap/          architecture patterns (MVC, MVVM) as GTK4 apps
diff --git a/docs/learning-path.md b/docs/learning-path.md
index d37b788..f886394 100644
--- a/docs/learning-path.md
+++ b/docs/learning-path.md
@@ -104,6 +104,19 @@ the problem the pattern solves; several end with the modern C++ alternative (`st
 | `./build/bin/demo_dlopen` | loading a plugin at run time |
 | `src/embedded` | a firmware image booting in QEMU |
 
+## Stage 9 - what is not written yet
+
+Examples marked `[draft]` in the menu are scaffolds: the file lists what the topic should show and
+prints that outline, but the code is missing. Templates (`core/template/*`), move semantics,
+coroutines, `std::expected` and the rest of the open topics are listed per standard in
+[cpp-standards-coverage.md](cpp-standards-coverage.md).
+
+```bash
+./build/bin/cpp_lab_project --list | grep draft
+```
+
+Filling one in is the best exercise the lab has to offer.
+
 ---
 When something surprises you, change the example and rebuild - that is what the lab is for.
 Then write your own: see [adding-examples.md](adding-examples.md).

From 5dedfa884685c40c825b32bda44043e60080a40c Mon Sep 17 00:00:00 2001
From: Phong Nguyen <nphong2103@gmail.com>
Date: Sat, 12 Sep 2026 09:19:26 +0700
Subject: [PATCH 20/20] Drop an unused Doxygen PREDEFINED entry

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEsQ7AcLHafb1tAgosoJFz
---
 docs/Doxyfile.in | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index 6a31d74..b97d167 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -61,7 +61,6 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = NO
 SKIP_FUNCTION_MACROS   = YES
 INCLUDE_PATH           = "@PROJECT_SOURCE_DIR@/include"
-PREDEFINED             = CPPLAB_SOURCE_DIR=""
 
 # --- Source browser --------------------------------------------------------
 # The point of the lab is the code, so make every file browsable and linked.