diff --git a/dsl/README.md b/dsl/README.md
index ce24bc1..0ef496d 100644
--- a/dsl/README.md
+++ b/dsl/README.md
@@ -1,14 +1,25 @@
-# `ket`
+[***dizzle***](https://codeberg.org/unspeaker/tengri/src/branch/main/dsl)
+is a means of adding a tiny interpreted domain-specific language to your programs.
 
-**ket** is the configuration language of **tek**.
-it's based on [edn](https://en.wikipedia.org/wiki/Clojure#Extensible_Data_Notation)
-but without all the features.
+dizzle currently provides an s-expression based syntax.
 
-## usage
+dizzle parses source code by means of the `Dsl`, `DslExpr` and `DslWord` traits.
+those are implemented for basic stringy types and their `Option` and `Result` wrapped analogs.
+to customize parsing, define and use your own traits on top of the provided ones.
 
-### with `tengri_output`
+dizzle evaluates the parsed source code by means of the `DslNs` trait. the methods of
+this trait match literals, words, and expressions, against pre-defined lists. the
+`dsl_words` and `dsl_exprs` macros let you define those lists slightly less verbosely.
 
-this is a `tengri_output` view layout defined using ket:
+## goals
+
+* [x] const parse
+* [ ] live reload
+* [ ] serialize modified code back to original indentation
+
+## examples
+
+### in [`tengri_output`](../output)
 
 ```edn
 (bsp/s (fixed/y 2 :toolbar)
@@ -16,9 +27,7 @@ this is a `tengri_output` view layout defined using ket:
     (bsp/s :outputs (bsp/s :inputs (bsp/s :tracks :scenes)))))))
 ```
 
-### with `tengri_input`
-
-this is a `tengri_input` keymap defined using ket:
+### in [`tengri_input`](../input)
 
 ```edn
 (@u       undo 1)
@@ -29,70 +38,6 @@ this is a `tengri_input` keymap defined using ket:
 (@tab     pool toggle)
 ```
 
-## tokens
-
-ket has 4 "types", represented by variants of the `Value` enum:
-
-* `Num` - numeric literal
-* `Sym` - textual symbol
-* `Key` - textual key
-* `Exp` - parenthesized group of tokens
-
-### numeric literal
-
-numbers are passed through as is. only non-negative integers are supported.
-
-```edn
-0
-123456
-```
-
-### keys
-
-keys are the names of available operations. they look like this:
-
-```edn
-simple-key
-multi-part/key
-```
-
-keys are implemented by the underlying subsystem:
-
-* in `tengri_output`, keys are names of layout primitives
-* in `tengri_input`, keys are names of commands
-
-### symbols
-
-symbols that start with `:` represent the names of variables
-provided by the `Context` trait - such as command parameters,
-or entire layout components:
-
-```edn
-:symbol-name
-```
-
-symbols that start with `@` represent keybindings.
-they are parsed in `tengri_tui` and look like this:
-
-```edn
-@ctrl-alt-shift-space
-```
-
-### parenthesized groups
-
-parenthesized groups represent things like expressions
-or configuration statements, and look like this:
-
-```edn
-(some-key :symbol (some/other-key @another-symbol 123) 456)
-```
-
-## goals
-
-* [ ] const parse
-* [ ] live reload
-* [ ] serialize modified code back to original indentation
-
 ## implementation notes
 
 ### `DslExpr` trait behavior
@@ -114,9 +59,7 @@ this is the trait which differentiates "a thing" from
 * e2: Unexpected 'b'
 * e3: Unexpected 'd'
 
-## todo
-
-### operators
+### possible design for operator-based syntax
 
 * replace: `(:= :name :value1 :valueN)`
 * append:  `(:+ :name :value2 :valueN)`
diff --git a/tengri/README.md b/tengri/README.md
index 9c5e04d..962f196 100644
--- a/tengri/README.md
+++ b/tengri/README.md
@@ -4,7 +4,14 @@ tengri is developed as part of [***tek***](https://codeberg.org/unspeaker/tek),
 a music program for terminals.
 
 tengri contains:
-* [***dizzle***](./dsl), a framework for defining domain-specific languages.
-* [***output***](./output), an abstract UI layout framework.
-* [***input***](./input), an abstract UI event framework.
+* [***dizzle***](./dsl), a framework for defining domain-specific languages
+* [***output***](./output), an abstract UI layout framework
+* [***input***](./input), an abstract UI event framework
 * [***tui***](./tui), an implementation of tengri over [***ratatui***](https://ratatui.rs/).
+
+as well as:
+* [***core***](./core), the shared definitions ("utils") module
+* [***proc***](./proc), the space for procedural macros
+* [***tengri***](./tengri), the top-level reexport crate
+
+tengri is published under [**AGPL3**](./LICENSE).
diff --git a/tui/README.md b/tui/README.md
index d8c2f29..8e227d8 100644
--- a/tui/README.md
+++ b/tui/README.md
@@ -1,15 +1,4 @@
-# `tengri_tui`
+***tengri_tui*** is an implementation of [tengri_output](../output) and [tengri_input](../input)
+on top of [ratatui](https://ratatui.rs/) and [crossterm](https://github.com/crossterm-rs/crossterm).
 
-the `Tui` struct (the *engine*) implements the
-`tengri_input::Input` and `tengri_output::Output` traits.
-
-at launch, the `Tui` engine spawns two threads,
-a **render thread** and an **input thread**. (the
-application may spawn further threads, such as a
-**jack thread**.)
-
-all threads communicate using shared ownership,
-`Arc<RwLock>` and `Arc<Atomic>`. the engine and
-application instances are expected to be wrapped
-in `Arc<RwLock>`; internally, those synchronization
-mechanisms may be used liberally.
+tengri is published under [**AGPL3**](../LICENSE).
diff --git a/tui/src/tui_engine.rs b/tui/src/tui_engine.rs
index 4700555..ff93db3 100644
--- a/tui/src/tui_engine.rs
+++ b/tui/src/tui_engine.rs
@@ -7,6 +7,12 @@ mod tui_event;  pub use self::tui_event::*;
 mod tui_output; pub use self::tui_output::*;
 mod tui_perf;   pub use self::tui_perf::*;
 
+// The `Tui` struct (the *engine*) implements the
+// `tengri_input::Input` and `tengri_output::Output` traits.
+
+// At launch, the `Tui` engine spawns two threads, the render thread and the input thread.
+// the application may further spawn other threads. All threads communicate using shared ownership:
+// `Arc<RwLock<T>>` and `Arc<AtomicT>`. Thus, at launch the engine and application instances are expected to be wrapped in `Arc<RwLock>`.
 pub struct Tui {
     pub exited:  Arc<AtomicBool>,
     pub backend: CrosstermBackend<Stdout>,