port docs to doxygen

1 files changed, 22 insertions, 7 deletions

diff --git a/README.org b/README.org
index f8da320..0207c58 100644
--- a/README.org
+++ b/README.org
@@ -5,20 +5,21 @@
 
 * About
 
-This is a Relational NT-inspired database kernel. The goal of the project is to offer an approach similar to how the NT kernel offers for an OS, but for administrating database objects and state.
+Relational NT is an experimental database kernel inspired by the object-management model of the Windows NT kernel. The project explores what database internals look like when relations, tuples, transactions, namespaces, permissions, cursors, and handles are treated as explicit runtime-managed objects.
 
-Relational NT explores database internals through an object-manager style architecture. Instead of treating relations, tuples, transactions, namespaces, permissions, and handles as unrelated mechanisms, the runtime models them as managed objects with explicit lifecycle, uniform access paths and explicit security enforcement.
+The goal is to build a small, understandable runtime where database state is accessed through uniform paths, guarded by explicit security checks, and managed through visible lifecycle rules. The codebase is still early, so several classes define architectural boundaries before they define complete behavior.
 
 * Design Direction
 
-- Object management: database objects are registered, located, and referenced through a central object manager.
-- Permissions: access checks are separated from object lookup so security policy can evolve independently.
-- Identity and lifecycle: opening, closing, monitoring, and contention decisions are represented as runtime responsibilities.
-- Handles: authorized access to objects is modeled explicitly, making ownership and cleanup visible.
+- Object management: database objects are registered, located, and referenced through a central registry.
+- Permissions: access checks are kept separate from object lookup so security policy can evolve independently.
+- Identity and lifecycle: opening, closing, monitoring, pinning, cleanup, and contention are modeled as runtime responsibilities.
+- Handles: authorized access is explicit, which makes ownership, accounting, and cleanup visible.
+- Cursors and VM: retrieval is designed around pull-based cursors and a split between terminating first-order logic and higher-order logic execution.
 
 * Current Status
 
-The project is early-stage and focused on shaping the runtime structure. Many components are intentionally skeletal while the core abstractions settle.
+The project is currently focused on the runtime shape. Many components are intentionally skeletal while the core abstractions settle, but the headers document the intended responsibilities and constraints of each manager.
 
 * Building
 
@@ -33,3 +34,17 @@ For Unix-like environments with a C++17 compiler and Make installed:
 #+begin_src shell
 make unix
 #+end_src
+
+* Documentation
+
+API documentation is generated with Doxygen. The root =Doxyfile= reads the public headers, source files, and the documentation main page in =docs/mainpage.dox=.
+
+#+begin_src shell
+doxygen Doxyfile
+#+end_src
+
+Generated HTML is written to =docs/generated/html=.
+
+The comments in the public headers are part of the design record. Keep architectural notes close to the declarations they explain so Doxygen can publish them with the API reference.
+
+The repository also includes a GitHub Actions workflow that publishes the generated Doxygen HTML to GitHub Pages on pushes to =master=. In the repository settings, configure Pages to use =GitHub Actions= as its source.