Clarify documentation

 - Better description of what a spec is in the README.md
 - Clarification about thread-safe and aio containers

Author: alganet

README.md

@@ -40,6 +40,9 @@ wired = Wiring(spec)
 service = wired.service()  # Lazy instantiation + caching
 ```
 
+`spec` is a plain dictionary. It can be written in Python, or come from a
+[config file](docs/user-guide/configuration-files.md), apywire doesn't care.
+
 ## Documentation
 
 📚 **[Full Documentation](docs/index.md)** • [Getting Started](docs/getting-started.md) • [API Reference](docs/api-reference.md) • [Examples](docs/examples.md)
@@ -53,7 +56,7 @@ make docs-serve  # http://127.0.0.1:8000
 
 ```bash
 make .venv && source .venv/bin/activate  # Setup
-make all                                  # Format, lint, test, build
+make all                                 # Format, lint, test, build
 ```
 
 See [docs/development.md](docs/development.md) for guidelines.

docs/user-guide/async-support.md

@@ -38,6 +38,8 @@ async def main():
 asyncio.run(main())
 ```
 
+This is especially useful for [factory methods](docs/user-guide/advanced.md#factory-methods) that perform I/O operations.
+
 ## How It Works
 
 When you use `.aio`, apywire wraps the object instantiation in an executor:

docs/user-guide/thread-safety.md

@@ -34,6 +34,9 @@ wired = Wiring(spec, thread_safe=True)
 - Single-threaded applications
 - Each thread has its own `Wiring` container instance
 
+Rule of thumb: If you're not sure if you need thread-safe containers, you probably
+don't need them.
+
 ## How It Works
 
 apywire uses a two-level locking strategy: