docs: document libtortillas Tokio runtime boundary

README.md

@@ -78,6 +78,19 @@ Libtortillas is the library that powers the frontend TUI application. It is a li
 ```bash
 cargo add --git https://github.com/artrixdotdev/tortillas libtortillas
 ```
+
+#### Runtime Contract
+
+`libtortillas` is a Tokio-first library. Applications that use it must run
+engine and torrent operations inside a Tokio runtime.
+
+For the Tortillas TUI, the binary should own a single application runtime,
+typically through `#[tokio::main]`, and create `libtortillas::engine::Engine`
+inside that runtime. UI rendering or terminal input that blocks should run on a
+dedicated thread or through Tokio blocking tasks, then send commands into async
+engine tasks. The library does not currently support swapping in a different
+async runtime, HTTP client, clock, listener, or storage executor.
+
 ## 🤝 Contributing
 
 We welcome contributions! If you'd like to help improve `tortillas`, please check out our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and tips.

crates/libtortillas/src/ARCHITECTURE.md

@@ -10,6 +10,25 @@ The library is organized around a small actor hierarchy:
 Module facades should export stable public types while keeping actor internals private to the crate.
 Domain types such as torrent state, storage strategy, exported snapshots, tracker model types, and tracker stats live outside actor files so actors can focus on orchestration.
 
+## Runtime Boundary
+
+`libtortillas` is intentionally tied to Tokio. The crate uses Tokio for actor
+task execution, TCP and UDP sockets, timers, cancellation, channels, and
+filesystem work. HTTP fetching is also part of the library runtime path through
+`reqwest`.
+
+Frontend applications should treat Tokio as the runtime boundary. A frontend,
+including the planned Tortillas TUI, should create one Tokio runtime at process
+startup and run `Engine` plus all torrent handle operations on that runtime. If
+the UI layer has blocking terminal rendering or input loops, those should be
+isolated from async torrent work with channels, a dedicated UI thread, or
+`tokio::task::spawn_blocking`.
+
+Runtime independence is not a current API promise. The public facade should not
+claim support for custom async runtimes, injected HTTP clients, injected clocks,
+custom network listeners, or non-Tokio storage executors unless those extension
+points are added explicitly.
+
 ## Choking
 
 `TorrentActor` owns the BEP 3 choking scheduler for its swarm. Active torrents run a rechoke round every 10 seconds, collect peer-local transfer stats from `PeerActor`, and keep at most four interested peers unchoked.

crates/libtortillas/src/engine/mod.rs

@@ -14,6 +14,13 @@
 //! - Each torrent is represented by a [`Torrent`] handle, which can be used to
 //!   interact with the torrent session.
 //!
+//! ## Runtime
+//!
+//! The engine is Tokio-only. Construct and use [`Engine`] from tasks running on
+//! a Tokio runtime, such as a TUI binary with `#[tokio::main]`. `Engine` starts
+//! actor tasks, binds Tokio TCP and uTP sockets, uses Tokio timers, and
+//! performs async filesystem and HTTP work through the same runtime.
+//!
 //! ## Example
 //!
 //! ```no_run
@@ -62,6 +69,10 @@ use crate::{
 /// - Adding new [torrents](Torrent) from different sources
 /// - Managing peer connections and tracker communication
 ///
+/// `Engine` must be created and used from a Tokio runtime. Applications should
+/// create one runtime at the frontend boundary and run all engine and torrent
+/// operations on that runtime.
+///
 /// Typically, you create a single `Engine` instance per application and attach
 /// multiple [`Torrent`] instances to it.
 ///

crates/libtortillas/src/lib.rs

@@ -1,3 +1,20 @@
+//! Async BitTorrent engine for building Tortillas frontends.
+//!
+//! # Runtime boundary
+//!
+//! `libtortillas` is intentionally a Tokio-based library. Public handles such
+//! as [`engine::Engine`] and [`torrent::Torrent`] expose async methods that
+//! must be driven inside a Tokio runtime, and the crate uses Tokio tasks,
+//! sockets, timers, channels, and filesystem APIs internally.
+//!
+//! Frontends should create one application-level Tokio runtime and keep the
+//! engine plus all torrent handles on work scheduled by that runtime. The crate
+//! does not promise runtime independence, HTTP client injection, clock
+//! injection, listener injection, or storage runtime abstraction.
+//!
+//! A TUI can use `#[tokio::main]` on its binary entry point, or create an
+//! explicit Tokio runtime before initializing `Engine`.
+
 pub mod engine;
 pub mod errors;
 pub mod hashes;