diff --git a/xo-interpreter/CMakeLists.txt b/xo-interpreter/CMakeLists.txt
new file mode 100644
index 00000000..132e7b86
--- /dev/null
+++ b/xo-interpreter/CMakeLists.txt
@@ -0,0 +1,42 @@
+# xo-interpreter/CMakeLists.txt
+
+cmake_minimum_required(VERSION 3.10)
+
+project (xo_interpreter VERSION 0.1)
+
+include(GNUInstallDirs)
+include(cmake/xo-bootstrap-macros.cmake)
+
+xo_cxx_toplevel_options3()
+
+# ----------------------------------------------------------------
+# c++ settings
+
+set(PROJECT_CXX_FLAGS "")
+#set(PROJECT_CXX_FLAGS "-fconcepts-diagnostics-depth=2")  # gcc-only!
+add_definitions(${PROJECT_CXX_FLAGS})
+
+# ----------------------------------------------------------------
+
+# note on ordering: must read .cmake defn of lib before configuring any examples
+add_subdirectory(src/interpreter)
+
+xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
+
+# ----------------------------------------------------------------
+
+#add_subdirectory(example)
+#add_subdirectory(utest)
+
+# ----------------------------------------------------------------
+
+#if (XO_ENABLE_EXAMPLES)
+#    install(TARGETS xo_interpreter_ex1 DESTINATION bin/xo/example)
+#endif()
+
+# ----------------------------------------------------------------
+# docs targets depend on all other library/utest targets
+#
+#add_subdirectory(docs)
+
+# end CMakeLists.txt
diff --git a/xo-interpreter/docs/README b/xo-interpreter/docs/README
new file mode 100644
index 00000000..6aff5d41
--- /dev/null
+++ b/xo-interpreter/docs/README
@@ -0,0 +1,41 @@
+standalone build
+
+        +-----------------------------------------------+
+        | cmake                                         |
+        |   CMakeLists.txt                              |
+        |   $PREFIX/share/cmake/xo_macros/xo_cxx.cmake  |
+        +-----------------------------------------------+
+           |
+           |                                                  +----------------------+
+           +------------------------------------------------->| .build/docs/Doxyfile |
+           |                                                  +----------------------+
+           |                                                     ^
+           |                                 (cmake)             |
+           |                                        /------------/
+           |                                        |
+           |     +---------------------------------------+          +-----------------+
+           +---->| doxygen                               |--------->| .build/docs/dox |
+           |     |   $PREFIX/share/xo-macros/Doxyfile.in | (doxygen)|   +- html/      |
+           |     +---------------------------------------+          |   +- xml/       |
+           |                                                        +-----------------+
+           |                                                             |
+           |                                                             |(sphinx)
+           |                                                             |
+           |                                                             v
+           |     +---------------------------------------+        +--------------------+
+           \---->| sphinx                                |------->| .build/docs/sphinx |
+                 |   +- conf.py                          |        |   +- html/         |
+                 |   +- _static/                         |        +--------------------+
+                 |   +- *.rst                            |
+                 +---------------------------------------+
+
+umbrella build relies on top-level cmake macros
+
+files
+
+   README            this file
+   CMakeLists.txt    build entry point
+   conf.py           sphinx config
+   _static           static files for sphinx
+
+   index.rst         toplevel sphinx document; entry point
diff --git a/xo-interpreter/docs/_static/README b/xo-interpreter/docs/_static/README
new file mode 100644
index 00000000..8230095c
--- /dev/null
+++ b/xo-interpreter/docs/_static/README
@@ -0,0 +1 @@
+add any static {.html, .js, ..} files for sphinx to pickup here
\ No newline at end of file
diff --git a/xo-interpreter/docs/_static/img/favicon.ico b/xo-interpreter/docs/_static/img/favicon.ico
new file mode 100644
index 00000000..4163dd69
Binary files /dev/null and b/xo-interpreter/docs/_static/img/favicon.ico differ
diff --git a/xo-interpreter/docs/index.rst b/xo-interpreter/docs/index.rst
new file mode 100644
index 00000000..e5b5a1c2
--- /dev/null
+++ b/xo-interpreter/docs/index.rst
@@ -0,0 +1,12 @@
+.. xo-interpreter documentation master file.
+
+xo-interpreter documentation
+============================
+
+xo-interpreter provides an interpreter for the Schematika language
+
+.. toctree::
+   :maxdepth: 2
+   :caption: xo-interpreter contents
+
+   install
diff --git a/xo-interpreter/docs/install.rst b/xo-interpreter/docs/install.rst
new file mode 100644
index 00000000..827bb1b0
--- /dev/null
+++ b/xo-interpreter/docs/install.rst
@@ -0,0 +1,202 @@
+.. _install:
+
+.. toctree:
+   :maxdepth: 2
+
+Source
+======
+
+Source code lives on github `here`_
+
+.. _here: https://github.com/rconybea/xo-interpreter
+
+To clone from git:
+
+.. code-block:: bash
+
+    git clone https://github.com/rconybea/xo-interpreter
+
+Tested with gcc 14.2
+
+Install
+=======
+
+One-step Install
+----------------
+
+Install xo-interpreter along with the rest of *XO* from `xo-umbrella2 source`_:
+see install instructions for xo-umbrella2.
+
+.. _xo-umbrella2 source: https://github.com/rconybea/xo-umbrella2
+
+Essential Xo Dependencies
+-------------------------
+
+``xo-interpreter`` uses several supporting libraries from elsewhere in the *XO* project:
+
+- `xo-reader source`_ (Schematika expression parser)
+- `xo-expression source`_ (Schematika AST representation)
+- `xo-tokenizer source`_ (Schematika lexer)
+- `xo-object source`_ (gc-eligible runtime polymorphism)
+- `xo-randomgen source`_ (fast pseudo-random number generators)
+- `xo-alloc source`_ (arena allocators, garbage collector)
+- `xo-unit source`_ (dimension checking library)
+- `xo-ratio source`_ (exact ratio library)
+- `xo-flatstring source`_ (no-allocation string library)
+- `xo-callback source`_ (callback library)
+- `xo-reflectutil source`_ (reflection utils for participating libs)
+- `xo-reflect source`_ (reflection library)
+- `xo-refcnt source`_ (reference-counting library)
+- `xo-subsys source`_ (utility library)
+- `xo-indentlog source`_ (structured logging, pretty-printing)
+- `xo-cmake source`_ (shared cmake macros)
+
+.. _xo-reader source: https://github.com/rconybea/xo-reader
+.. _xo-expression source: https://github.com/rconybea/xo-expression
+.. _xo-tokenizer source: https://github.com/rconybea/xo-tokenizer
+.. _xo-object source: https://github.com/rconybea/xo-object
+.. _xo-randomgen source: https://github.com/rconybea/xo-randomgen
+.. _xo-alloc source: https://github.com/rconybea/xo-alloc
+.. _xo-unit source: https://github.com/rconybea/xo-unit
+.. _xo-ratio source: https://github.com/rconybea/xo-ratio
+.. _xo-flatstring source: https://github.comr/rconybea/xo-flatstring
+.. _xo-callback source: https://github.com/rconybea/xo-callback
+.. _xo-reflect source: https://github.com/rconybea/xo-reflect
+.. _xo-refcnt source: https://github.com/rconybea/refcnt
+.. _xo-subsys source: https://github.com/rconybea/subsys
+.. _xo-indentlog source: https://github.com/rconybea/indentlog
+.. _xo-cmake source: https://github.com/rconybea/xo-cmake
+
+Building from source
+--------------------
+
+Instructions for building xo-interpreter from source, along with only its essential dependencies.
+
+Install scripts for XO libraries depend on helper scripts installed from `xo-cmake`.
+
+Preamble:
+
+.. code-block:: bash
+
+    mkdir -p ~/proj/xo
+    cd ~/proj/xo
+
+    git clone https://github.com/rconybea/xo-cmake
+
+    PREFIX=$HOME/local  # or desired installation path
+
+    # will want PREFIX/bin in PATH to use xo-cmake helpers
+    PATH=$PREFIX/bin:$PATH
+
+Isntall `xo-cmake`:
+
+.. code-block:: bash
+
+    cmake -B xo-cmake/.build -S xo-cmake
+    cmake --install xo-cmake/.build
+
+Now that we have xo-build in PATH, can build+install XO components in topological order:
+
+.. code-block:: bash
+
+    xo-build --clone --configure --build --install xo-indentlog
+    xo-build --clone --configure --build --install xo-subsys
+    xo-build --clone --configure --build --install xo-refcnt
+    xo-build --clone --configure --build --install xo-reflect
+    xo-build --clone --configure --build --install xo-reflectutil
+    xo-build --clone --configure --build --install xo-callback
+    xo-build --clone --configure --build --install xo-flatstring
+    xo-build --clone --configure --build --install xo-ratio
+    xo-build --clone --configure --build --install xo-unit
+    xo-build --clone --configure --build --install xo-alloc
+    xo-build --clone --configure --build --install xo-randomgen
+    xo-build --clone --configure --build --install xo-object
+    xo-build --clone --configure --build --install xo-tokenizer
+    xo-build --clone --configure --build --install xo-expression
+    xo-build --clone --configure --build --install xo-reader
+
+Directories under ``PREFIX`` will then contain something like:
+
+.. code-block::
+
+    PREFIX
+    += bin
+    |  +- xo-build
+    │  +- xo-cmake-config
+    │  \- xo-cmake-lcov-harness
+    +─ include
+    |  \- xo
+    │     +- alloc/
+    |     +- callback/
+    |     +- cxxutil/
+    |     +- expression/
+    |     |  +- typeinf/
+    |     |  ..
+    |     +- flatstring/
+    |     +- indentlog/
+    |     |  +- machdep/
+    |     |  +- print/
+    |     |  +- timeutil/
+    |     |  ..
+    |     +- object/
+    |     +- randomgen/
+    |     +- ratio/
+    |     +- reader/
+    |     +- refcnt/
+    |     +- reflect/
+    |     |  +- atomic/
+    |     |  +- function/
+    |     |  +- pointer/
+    |     |  +- struct/
+    |     |  +- vector/
+    |     |  ..
+    |     +- reflectutil/
+    |     +- subsys/
+    |     +- tokenizer/
+    |     \- unit/
+    +- lib
+    |  +- cmake
+    |  |  +- callback/
+    |  |  +- indentlog/
+    |  |  +- randomgen/
+    |  |  +- refcnt/
+    |  |  +- reflect/
+    |  |  +- subsys/
+    |  |  +- xo_alloc/
+    |  |  +- xo_expression/
+    |  |  +- xo_flatstring/
+    |  |  +- xo_object/
+    |  |  +- xo_ratio/
+    |  |  +- xo_reader/
+    |  |  +- xo_reflectutil/
+    |  |  +- xo_tokenizer/
+    |  |  \- xo_unit/
+    |  +- librefcnt.so
+    |  ..
+    \- share
+       +- cmake
+       |  \- xo-macros
+       |     +- code-coverage.cmake
+       |     +- xo_cxx.cmake
+       |     \- xo-project-macros.cmake
+       +- etc
+       |  \- xo
+       |     \- subsystem_list
+       +- xo-macros
+          +- Doxyfile.in
+          +- gen-ccov.in
+          \- xo-bootstrap-macros.cmake
+
+CMake Support
+-------------
+
+To use built-in cmake support, when using ``xo-interpreter`` from another project:
+
+Make sure ``PREFIX/lib/cmake`` is searched by cmake (for example include it in ``CMAKE_PREFIX_PATH``)
+
+Add to your ``CMakeLists.txt``:
+
+.. code-block:: cmake
+
+    FindPackage(xo_interpreter CONFIG REQUIRED)
+    target_link_libraries(mytarget PUBLIC xo_interpreter)
diff --git a/xo-interpreter/include/xo/interpreter/StackFrame.hpp b/xo-interpreter/include/xo/interpreter/StackFrame.hpp
new file mode 100644
index 00000000..c18f6bae
--- /dev/null
+++ b/xo-interpreter/include/xo/interpreter/StackFrame.hpp
@@ -0,0 +1,24 @@
+/** @file StackFrame.hpp **/
+
+#include "xo/alloc/Object.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class StackFrame
+         *  @brief Represent a single runtime stack frame for a Schematika function
+         *
+         *  StackFrame intended to be used for interpreted functions.
+         *  Compiled functions will stil likely have stack frames, but need not use the
+         *  @ref StackFrame class
+         **/
+        class StackFrame : public Object {
+        public:
+            StackFrame(std::size_t n_slot)
+
+        private:
+
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end StackFrame.hpp */
diff --git a/xo-interpreter/include/xo/interpreter/VirtualSchematikaMachine.hpp b/xo-interpreter/include/xo/interpreter/VirtualSchematikaMachine.hpp
index eca9368c..edcd9706 100644
--- a/xo-interpreter/include/xo/interpreter/VirtualSchematikaMachine.hpp
+++ b/xo-interpreter/include/xo/interpreter/VirtualSchematikaMachine.hpp
@@ -2,17 +2,26 @@
 
 #pragma once
 
-#include "VmInstr.hpp"
+#include "VsmInstr.hpp"
 
 namespace xo {
     namespace scm {
         /** @class VirtualSchematikaMachine
          *  @brief Virtual machine implementing a Schematika interpreter
+         *
          **/
         class VirtualSchematikaMachine {
         public:
+            VirtualSchematikaMachine();
+
+
         private:
+            /** program counter **/
+            const VsmInstr * pc_ = nullptr;
+
+
         };
+
     } /*namespace scm*/
 } /*namespace xo*/
 
diff --git a/xo-interpreter/include/xo/interpreter/VmInstr.hpp b/xo-interpreter/include/xo/interpreter/VsmInstr.hpp
similarity index 79%
rename from xo-interpreter/include/xo/interpreter/VmInstr.hpp
rename to xo-interpreter/include/xo/interpreter/VsmInstr.hpp
index 7502a3ac..8f4e1e97 100644
--- a/xo-interpreter/include/xo/interpreter/VmInstr.hpp
+++ b/xo-interpreter/include/xo/interpreter/VsmInstr.hpp
@@ -1,8 +1,8 @@
-/** @file VmInstr.hpp **/
+/** @file VsmInstr.hpp **/
 
 #pragma once
 
-#include <string>
+#include <string_view>
 
 namespace xo {
     namespace scm {
@@ -13,16 +13,16 @@ namespace xo {
          *
          *  A vsm instruction acts on a virtual schematika machine instance.
          **/
-        class VmInstr
+        class VsmInstr
         {
         public:
             using ActionFn = void (*)(VirtualSchematikaMachine * vm);
 
         private:
-            std::string name_;
+            std::string_view name_;
             ActionFn action_;
         };
     }
 }
 
-/* end VmInstr.hpp */
+/* end VsmInstr.hpp */
diff --git a/xo-interpreter/src/interpreter/VirtualSchematikaMachine.cpp b/xo-interpreter/src/interpreter/VirtualSchematikaMachine.cpp
new file mode 100644
index 00000000..d46b6433
--- /dev/null
+++ b/xo-interpreter/src/interpreter/VirtualSchematikaMachine.cpp
@@ -0,0 +1,12 @@
+/** @file VirtualSchematikaMachine.cpp **/
+
+#include "VirtualSchematikaMachine.hpp"
+
+#include "VsmInstr.hpp"
+
+namespace xo {
+    namespace scm {
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end VirtualSchematikaMachine.hpp */