[wip] Initial README content, etc.

README.md

@@ -5,11 +5,18 @@
 
 ### Structured telemetry library for Clojure/Script
 
-This library is **still under development** and not available yet for public use.
+> This library is **still under development**!!
+
+**Telemere** is an [**upcoming**](https://www.taoensso.com/roadmap) next-generation observability toolkit for **capturing all kinds of un/structured information** in your running Clojure and ClojureScript programs.
+
+It offers a **simple, clean, unified API** that covers: **logging**, **events**, **performance measurement**, **tracing**, etc.
+
+Taking full advantage of Clojure's unique **macro and interop** capabilities, Telemere represents the **refinement and culmination** of ideas brewing for 10+ years in [Timbre](https://www.taoensso.com/timbre), [Tufte](https://www.taoensso.com/tufte), [Truss](https://www.taoensso.com/truss), etc.
 
 ## Latest release/s
 
-- Coming [~Apr 2024](https://www.taoensso.com/roadmap)
+- Stable release: coming [~Apr 2024](https://www.taoensso.com/roadmap)
+- `v1.0.0-SNAPSHOT` (dev): [release info](https://clojars.org/com.taoensso/telemere) (for early adopters)
 
 [![Main tests][Main tests SVG]][Main tests URL]
 [![Graal tests][Graal tests SVG]][Graal tests URL]
@@ -18,11 +25,57 @@ See [here][GitHub releases] for earlier releases.
 
 ## Why Telemere?
 
-- Coming later
+- Simple, lightweight API that's **easy to use**, **easy to configure**, and **deeply flexible**.
+- An **unmatched logging experience** designed to **scale comfortably** from the smallest disposable code, to the most massive production applications.
+- **Easy integration** with the **tooling of your choice**, including first-class **out-the-box interop** with [OpenTelemetry](https://opentelemetry.io/), [SLF4J v2](https://www.slf4j.org/), [clojure.tools.logging](https://github.com/clojure/tools.logging), and [Tufte](https://www.taoensso.com/tufte).
+- Hyper-optimized and **blazing fast**, see [performance](#performance).
+- Expressive **per-call** and **per-handler** filtering at both **runtime** and **compile-time**.
+- Easily filter by namespace and id pattern, level, **level by namespace pattern**, etc.
+- Support for auto **sampling**, **rate-limiting**, and **back-pressure monitoring**.
+- Support for **fully configurable a/sync dispatch** (blocking, dropping, sliding, etc.).
+- **Sensible defaults** to make getting started **fast and easy**.
+- Extensive **beginner-oriented** [documentation](#documentation), docstrings, examples, etc.
+
+## Video demo
+
+See for intro and usage: (**TODO**: coming later)
+
+<a href="https://www.youtube.com/watch?v=TODO" target="_blank">
+ <img src="https://img.youtube.com/vi/TODO/maxresdefault.jpg" alt="Telemere demo video" width="480" border="0" />
+</a>
+
+## Quick example
+
+```clojure
+;; TODO: coming later
+```
+
+## Observability tips
+
+See [here](/TODO) for general advice re: building and maintaining **highly observable** Clojure/Script systems.
+
+## Performance
+
+Telemere is **highly optimized** and offers terrific performance at any scale:
+
+| Compile-time filtering? | Runtime filtering? | Time? | Trace? | nsecs
+| :-:       | :-: | :-: | :-: | --:
+| ✓ (elide) | -   | -   | -   | 0
+| -         | ✓   | -   | -   | 220
+| -         | ✓   | ✓   | -   | 300
+| -         | ✓   | ✓   | ✓   | 730
+
+Measurements:
+
+- Are **~nanoseconds per signal call** (= milliseconds per 1e6 calls)
+- Taken on a 2020 Macbook Pro M1, running OpenJDK 21
+- Exclude handler runtime (which depends on handler/s, is usually async)
+
+**Tip**: Telemere offers extensive per-call and per-handler **filtering**, **sampling**, and **rate-limiting**. Use these to ensure that you're not capturing useless/low-value information in production. See [here](/TODO) for more tips!
 
 ## Documentation
 
-- [Wiki][GitHub wiki] (getting started, usage, etc.)
+- [Wiki][GitHub wiki] (getting started, usage, etc.) (**TODO:** coming later)
 - API reference: [Codox][Codox docs], [clj-doc][clj-doc docs]
 
 ## Funding

examples.clj

@@ -0,0 +1 @@
+;; TODO

examples.cljs

@@ -0,0 +1 @@
+;; TODO

src/taoensso/telemere.cljc

@@ -73,6 +73,7 @@
   enc/chance
   enc/rate-limiter
   enc/newline
+
   impl/msg-splice
   impl/msg-skip
   #?(:clj impl/with-signal)