docs: document libtortillas Tokio runtime boundary

[artrixdotdev]

Summary

• Document libtortillas as intentionally Tokio-only in crate and Engine docs.
• Add frontend/TUI guidance for owning one Tokio runtime and isolating blocking UI work.
• Clarify that runtime, HTTP client, clock, listener, and storage executor injection are not current API promises.

Testing

• cargo fmt --all -- --check
• cargo nextest run --workspace
• cargo clippy --workspace --all-targets -- -D warnings
• RUSTDOCFLAGS="-D warnings" cargo doc -p libtortillas --no-deps

Ignored network tests were not run because this is documentation-only and does not change network behavior.

Closes #237
Part of #221

Summary by CodeRabbit

• Documentation
  • Added guidance explaining that libtortillas operations must run within a Tokio runtime.
  • Documented recommended patterns for integrating blocking terminal or UI input with asynchronous engine tasks.
  • Clarified runtime requirements and limitations, including the lack of guarantees for custom runtime or infrastructure substitutions.
  • Updated usage examples to demonstrate running the engine within Tokio.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 85a8eb88-8cca-4fca-97fa-0eb91feae82e

📥 Commits

Reviewing files that changed from the base of the PR and between 431beae and 23fdfef.

📒 Files selected for processing (4)

• README.md
• crates/libtortillas/src/ARCHITECTURE.md
• crates/libtortillas/src/engine/mod.rs
• crates/libtortillas/src/lib.rs

---

Walkthrough

The documentation now establishes Tokio as the required runtime for libtortillas, explains frontend handling of blocking work, clarifies unsupported runtime substitutions, and updates Engine examples to run within Tokio.

Changes

Tokio Runtime Boundary

Layer / File(s)	Summary
Runtime contract documentation crates/libtortillas/src/lib.rs, crates/libtortillas/src/ARCHITECTURE.md, README.md	Documents Tokio runtime ownership, blocking UI isolation, and unsupported runtime or component substitution.
Engine runtime usage crates/libtortillas/src/engine/mod.rs	Clarifies the engine’s Tokio responsibilities and updates examples to use an explicit Tokio runtime.

Estimated code review effort: 1 (Trivial) | ~4 minutes

Possibly related issues

• #221 — The runtime documentation supports stabilizing the frontend-facing libtortillas API for a future TUI.

Suggested labels: med prio

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the PR’s main change: documenting libtortillas’ Tokio runtime boundary.
Linked Issues check	✅ Passed	The docs state the Tokio requirement, explain frontend/TUI integration, and avoid promising runtime independence.
Out of Scope Changes check	✅ Passed	All changes are documentation updates directly related to the runtime-boundary objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/document-libtortillas-runtime-boundary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}