1 files changed, 53 insertions, 46 deletions
diff --git a/docs/mainpage.dox b/docs/mainpage.dox
index 76f4eca..3c6daa3 100644
--- a/docs/mainpage.dox
+++ b/docs/mainpage.dox
@@ -4,67 +4,74 @@
  * @image html logo.png
  *
  * Relational NT is an experimental database kernel inspired by the
- * object-management model of the Windows NT kernel. The project applies the
- * same style of explicit object management to database state: relations,
- * tuples, transactions, namespaces, permissions, cursors, and handles are
- * treated as runtime-managed objects rather than isolated subsystems.
- *
- * The current codebase is intentionally early-stage. Most classes define the
- * boundaries of the runtime and document the design constraints that should
- * guide future implementation.
- *
- * @section architecture Architecture Direction
- *
- * - ObjectManager registers, locates, and references database objects.
- * - PermissionsManager keeps security checks separate from object lookup.
- * - IdentityManager decides whether an object supports lifecycle operations
- *   such as open and close.
+ * object-management model of the Windows NT kernel. The project applies
+ * explicit object management to database state: relations, tuples,
+ * transactions, namespaces, permissions, cursors, and handles are
+ * runtime-managed objects rather than isolated subsystems.
+ *
+ * @section motivation Motivation
+ *
+ * The NT kernel is a good model for a dedicated database kernel for three
+ * reasons.
+ *
+ * **The object manager.** NT's OB gives every kernel resource a named path,
+ * a security descriptor, and a uniform open/close lifecycle enforced through
+ * handles. A database kernel has the same requirements. Rather than building
+ * those mechanisms independently for each database concept, this project
+ * borrows the NT object manager's shape directly.
+ *
+ * **Physical backends as drivers.** NT device drivers expose a narrow
+ * dispatch table. The kernel routes I/O through it without knowing whether
+ * the device is a local disk or a network adapter. Storage backends here
+ * follow the same pattern. A remote backend like etcd is just another
+ * driver, but brings its own concerns: network latency, connection
+ * management, and the possibility of partial failure. The driver boundary
+ * keeps those concerns inside the backend module.
+ *
+ * **Clients as environment subsystems.** NT supports Win32, POSIX, and OS/2
+ * as environment subsystems layered above a common native API. A database
+ * client works the same way: a PostgreSQL wire adapter, a MySQL wire
+ * adapter, or an HTTP/JSON interface each translates its protocol into
+ * kernel-level operations. The kernel never sees SQL syntax or protocol
+ * framing.
+ *
+ * @section architecture Architecture
+ *
+ * - ObjectManager registers, locates, and references database objects by
+ *   logical path.
+ * - PermissionsManager keeps capability checks separate from object lookup.
+ * - IdentityManager decides whether an object supports a requested lifecycle
+ *   operation.
  * - LifecycleManager models monitoring, pinning, cleanup, and contention.
- * - HandlerManager represents authorized access through explicit handles.
- * - CursorManager bridges durable snapshots and pull-based query execution.
- * - VM separates terminating relational retrieval from higher-order logic
- *   execution.
- *
- * @section design Design Notes
- *
- * The following documents record architectural decisions and comparisons with
- * the ReactOS NT kernel, which this project draws from:
- *
- * - **docs/reactos-ob-comparison.md** — Object manager comparison: dual
- *   reference counting, type callbacks, hash directory, per-handle access
- *   masks, capability security, branch HEAD contention, and the namespace
- *   reparse layer.
- *
- * - **docs/nt-architecture-mapping.md** — Holistic mapping of the full NT
- *   kernel to a database kernel: wire protocols as environment subsystems,
- *   the I/O driver stack as the query operator pipeline, drivers as storage
- *   backends, MM as the buffer pool, CC as the WAL flusher, PS as the
- *   session manager, SE as the authorization engine, and LPC as the wire
- *   protocol connection layer.
+ * - HandlerManager orchestrates the full open/close workflow and owns handle
+ *   allocation.
+ * - CursorManager provides a pull-based iterator over storage, abstracting
+ *   pagination, snapshot pinning, and scan boundaries.
+ * - VM separates terminating first-order relational retrieval (Tarski) from
+ *   higher-order logic execution (Karuta).
+ * - NamespaceReferenceManager handles logical path mapping and namespace
+ *   isolation, including private branch shadowing and atomic multi-reference
+ *   updates.
  *
  * @section building Building
  *
- * From a Visual Studio/NMake environment:
+ * Requires MSVC, CMake 3.10 or later, and vcpkg. Dependencies are fetched
+ * automatically during configure.
  *
  * @code{.sh}
- * nmake /f Makefile windows
+ * cmake --preset x64-debug
+ * cmake --build out/build/x64-debug
  * @endcode
  *
- * From a Unix-like environment with Make and a C++17 compiler:
- *
- * @code{.sh}
- * make unix
- * @endcode
+ * A release build uses @c --preset @c x64-release.
  *
  * @section docs Generating Documentation
  *
- * Install Doxygen and run:
- *
  * @code{.sh}
  * doxygen Doxyfile
  * @endcode
  *
- * The generated HTML documentation is written to docs/generated/html.
+ * Generated HTML is written to @c docs/generated/html.
  */
 
 /**