7mind · neko-kai · Dec 18, 2025 · Dec 18, 2025 · Dec 18, 2025 · Dec 18, 2025
@@ -31,17 +31,17 @@ What is it?
 
 Izumi (jp. 泉水) is an ecosystem of independent libraries and frameworks allowing you to significantly increase productivity of your Scala development.
 
-including the following components:
-
-1. [distage](https://izumi.7mind.io/distage/) – Compile-time safe, transparent and debuggable multi-modal Dependency Injection framework for pure FP Scala,
-2. [distage-testkit](https://izumi.7mind.io/distage/distage-testkit) – Hyper-pragmatic pure FP Test framework. Shares heavy resources globally across all test suites; lets you easily swap implementations of component; uses your effect type for parallelism.
-3. [distage-framework-docker](https://izumi.7mind.io/distage/distage-framework-docker) – A distage extension for using docker containers in tests or for local application runs, comes with example Postgres, Cassandra, Kafka & DynamoDB containers.
-4. [LogStage](https://izumi.7mind.io/logstage/) – Automatic structural logs from Scala string interpolations,
-5. [BIO](https://izumi.7mind.io/bio/) - A typeclass hierarchy for tagless final style with Bifunctor effect types. Focused on ergonomics and ease of use with zero boilerplate.
-6. [izumi-reflect](https://github.com/zio/izumi-reflect) (moved to [zio/izumi-reflect](https://github.com/zio/izumi-reflect)) - Portable, lightweight and kind-polymorphic alternative to `scala-reflect`'s Typetag for Scala, Scala.js, Scala Native and Scala 3
-7. [IdeaLingua](https://izumi.7mind.io/idealingua/) (moved to [7mind/idealingua-v1](https://github.com/7mind/idealingua-v1)) – API Definition, Data Modeling and RPC language, optimized for fast prototyping – like gRPC or Swagger, but with a human face. Generates RPC servers and clients for Go, TypeScript, C# and Scala,
-8. [Opinionated SBT plugins](https://izumi.7mind.io/sbt/) (moved to [7mind/sbtgen](https://github.com/7mind/sbtgen)) – Reduces verbosity of SBT builds and introduces new features – inter-project shared test scopes and BOM plugins (from Maven)
-9. [Percept-Plan-Execute-Repeat (PPER)](https://izumi.7mind.io/pper/) – A pattern that enables modeling very complex domains and orchestrate deadly complex processes a lot easier than you're used to.
+It includes:
+
+1. [distage](https://izumi.7mind.io/distage/) – Compile-time safe, transparent and debuggable dependency injection library for Scala and Scala.js.
+2. [distage-testkit](https://izumi.7mind.io/distage/distage-testkit) – Hyper-pragmatic testing framework. Shares heavy resources across test suites; lets you inject or swap components; uses your effect type for parallelism.
+3. [distage-framework-docker](https://izumi.7mind.io/distage/distage-framework-docker) – A distage extension for using docker containers in tests or for local application runs. Comes with example containers.
+4. [LogStage](https://izumi.7mind.io/logstage/) – Structural logger that derives structure from Scala string interpolations.
+5. [BIO](https://izumi.7mind.io/bio/) – A typeclass hierarchy for tagless final style with Bifunctor effect types. Focused on ergonomics and ease of use with zero boilerplate.
+6. [izumi-reflect](https://github.com/zio/izumi-reflect) (moved to [zio/izumi-reflect](https://github.com/zio/izumi-reflect)) – Portable, lightweight and kind-polymorphic alternative to `scala-reflect`'s Typetag for Scala, Scala.js, Scala Native and Scala 3.
+7. [IdeaLingua](https://izumi.7mind.io/idealingua/) (moved to [7mind/idealingua-v1](https://github.com/7mind/idealingua-v1)) – API Definition, Data Modeling and RPC language, optimized for fast prototyping – like gRPC or Swagger, but with a human face. Generates RPC servers and clients for Go, TypeScript, C# and Scala.
+8. [Opinionated SBT plugins](https://izumi.7mind.io/sbt/) (moved to [7mind/sbtgen](https://github.com/7mind/sbtgen)) – Reduces verbosity of SBT builds and introduces new features – inter-project shared test scopes and BOM plugins (from Maven).
+9. [Percept-Plan-Execute-Repeat (PPER)](https://izumi.7mind.io/pper/) – A pattern that enables modeling very complex domains and orchestrating deadly complex processes.
 
 Docs
 ----

@@ -48,7 +48,7 @@ object ClassConstructor {
 }
 
 /**
-  * An implicitly summonable constructor for a traits or abstract class `T`
+  * An implicitly summonable constructor for a trait or abstract class `T`
   *
   * @see [[https://izumi.7mind.io/distage/basics.html#auto-traits Auto-Traits feature]]
   * @see [[izumi.distage.model.definition.impl]] recommended documenting annotation for use with [[TraitConstructor]]

@@ -79,7 +79,7 @@ trait ReflectionProviderDefaultImpl extends ReflectionProvider {
              |  * When trying to create a constructor for the result of `$factoryMethod` - `$tpe`
              |  * Type `${factoryMethod.owner}` has been considered a factory because it's an abstract type and contains unimplemented abstract methods with parameters
              |  * Type `$tpe` has been considered a factory because it's an abstract type and contains unimplemented abstract methods with parameters
-             |  * Did you forget a `distage.With` annotation on the factory method to specify a non-abstract implementation type?
+             |  * Did you forget a `distage.With` annotation on the factory method to specify a concrete implementation type?
              |  * This may happen in case you unintentionally bind an abstract type (trait, etc) as implementation type.
              |
              |  * $mms

@@ -46,7 +46,7 @@ object ClassConstructor {
 }
 
 /**
-  * An implicitly summonable constructor for a traits or abstract class `T`
+  * An implicitly summonable constructor for a trait or abstract class `T`
   *
   * @see [[https://izumi.7mind.io/distage/basics.html#auto-traits Auto-Traits feature]]
   * @see [[izumi.distage.model.definition.impl]] recommended documenting annotation for use with [[TraitConstructor]]

@@ -60,7 +60,7 @@ import izumi.distage.reflection.macros.FunctoidMacroMethods
   *
   * @see [[izumi.distage.reflection.macros.FunctoidMacro]]]
   * @see Functoid is based on the Magnet Pattern: [[http://spray.io/blog/2012-12-13-the-magnet-pattern/]]
-  * @see Essentially Functoid is a function-like entity with additional properties, so it's funny name is reasonable enough: [[https://en.wiktionary.org/wiki/-oid#English]]
+  * @see Essentially Functoid is a function-like entity with additional properties, so its funny name is reasonable enough: [[https://en.wiktionary.org/wiki/-oid#English]]
   */
 final case class Functoid[+A](get: Provider) extends AbstractFunctoid[A, Functoid] {
   override protected def create[B](provider: Provider): Functoid[B] = Functoid.create[B](provider)

@@ -3,11 +3,12 @@ package izumi.distage.plugins
 import izumi.distage.model.definition.{Binding, ModuleBase, ModuleMake}
 
 /**
-  * Non-abstract class or object inheritors of [[PluginBase]] will be found on the classpath by `distage-extension-plugins`
-  * scanning machinery. ([[izumi.distage.plugins.load.PluginLoader]])
+  * Concrete classes or objects that inherit from [[PluginBase]] will be found on the classpath
+  * by `distage-extension-plugins` scanning machinery. ([[izumi.distage.plugins.load.PluginLoader PluginLoader]])
   *
   * @see [[https://izumi.7mind.io/distage/distage-framework#plugins Plugins]]
-  * @see [[izumi.distage.plugins.PluginDef]]
+  * @see [[izumi.distage.plugins.PluginDef PluginDef]]
+  * @see [[izumi.distage.plugins.load.PluginLoader PluginLoader]]
   */
 trait PluginBase extends ModuleBase
 

@@ -2,19 +2,19 @@
 out: index.html
 ---
 
-# DIStage
+# distage
 
 ```scala mdoc:reset:invisible:to-string
 System.setProperty(izumi.fundamentals.platform.PlatformProperties.`izumi.app.disable-terminal-colors`.name, "true")
 ```
 
-`distage` is a pragmatic module system for Scala and Scala.js. It combines the simplicity and expressiveness of pure FP with the flexibility and extreme late-binding, traditionally associated with Java dependency injection frameworks, such as Guice.
+`distage` is a pragmatic dependency injection library for Scala and Scala.js. It combines the simplicity and expressiveness of pure FP with the flexibility and extreme late-binding, traditionally associated with Java dependency injection frameworks, such as Guice.
 
 `distage` supports any Scala style, whether it's @ref[Tagless Final Style](basics.md#tagless-final-style), @ref[ZIO Layer](basics.md#zio-environment-bindings), ordinary FP, actor-based or imperative Scala.
 
 ## Getting started
 
-The best way get started is to clone [`distage-example`](https://github.com/7mind/distage-example) sample project and play around with it.
+The best way to get started is to clone [`distage-example`](https://github.com/7mind/distage-example) project and play around with it.
 
 It shows how to write an idiomatic `distage` application from scratch and how to:
 
@@ -27,48 +27,56 @@ It shows how to write an idiomatic `distage` application from scratch and how to
 /**
 add to distage-example
 
-- how to setup graalvm native image with distage
+- [done] how to setup graalvm native image with distage
 - how to debug dump graphs and render to graphviz [Actually, we have a GUI component now, can we show em there???]
 */
 ```
 
 ## Why distage?
 
-1. **Faster applications and tests**:
-    `distage` guarantees that no unnecessary instantiations will happen during your tests or application startup. `distage` itself is very fast, in part due to not using Java reflection.
+1. **Fast startup and tests**:
 
-2. **Faster integration tests**:
-    @ref[distage-testkit](distage-testkit.md) allows you to reuse expensive resources (such as database connections and docker containers)
-    across multiple test suites, gaining performance without sacrificing correctness.
+    `distage` guarantees that no unnecessary instantiations will happen during your tests or application startup. `distage` itself is very fast, in part due to not using any runtime reflection.
 
-3. **Managed test environments**:
-    @ref[distage-testkit](distage-testkit.md) eliminates all the hard work of setting up test environments, especially configurable ones. Easily describe tests environments, share heavy resources across all the test suites in the environment, use the power of DI to override components and run your tests under different scenarios.
+2. **Cross-platform**:
+
+    `distage` is available for JVM, Scala.js and GraalVM Native Image.
+
+3. **Compile-time error detection**:
 
-4. **Compile-time error detection**:
     `distage` can detect wiring errors @ref[at compile-time](distage-framework.md#compile-time-checks) for fast feedback during development.
-    Despite that, `distage` extensions are simple to write and do not require type-level programming.
 
-5. **Early failure detection**:
-    `distage` performs all the integration checks for your application and tests even before any instantiations happen.
+4. **Effect-type support**:
+
+    `distage` is polymorphic in effect type. Whether you use cats-effect `IO`, `ZIO`, a custom `F[_]` type or direct style with no effect type, all of distage's lifecycle management and test utilities work seamlessly. No effect type is privileged; distage adapts to your stack, not the other way around.
+
+5. **Lifecycle management**:
+
+    `distage` supports component lifecycle via native `Lifecycle`, cats-effect `Resource`, or ZIO `Scope`/`ZLayer`/`ZManaged`. Startup and cleanup follow dependency order, with cleanup guaranteed even on failure.
+
+6. **Fast integration tests**:
+
+    @ref[distage-testkit](distage-testkit.md) allows you to reuse expensive resources (such as database connections and docker containers) across multiple test suites, gaining performance without sacrificing correctness. Easily describe test environments, share heavy resources across all the test suites in the environment, use the power of DI to override components and run your tests under different scenarios.
+
+7. **Fail-fast integration checks**:
+
+    The @ref[Integration checks](distage-testkit.md#using-integrationcheck) feature dynamically skips tests when external dependencies are unavailable (e.g. no Docker daemon), and in production ensures applications fail fast with clear diagnostics.
+
+8. **Portable Docker test environments**:
+
+    @ref[distage-framework-docker](distage-framework-docker.md) turns Docker containers into managed resources with automatic health checks, port discovery, and cross-test reuse. Define containers once, inject them anywhere, and get reproducible integration tests on any machine with Docker. Or use them without DI, via monadic `Lifecycle` type.
 
-6. **Simplify development workflow**:
-    @ref[distage-framework](distage-framework.md) allows you to develop Role-based applications, letting you run all your services in one process for development purposes (and even switch to mock implementations with a single commandline argument).
+9. **Simplify development workflow**:
 
-7. **Easy deployment**:
-    Role-based applications allow you to deploy and orchestrate fewer containers and achieve a higher computation density.
+    @ref[distage-framework](distage-framework.md) allows you to develop Role-based applications, letting you run all your services in one process for development or test purposes (and even switch to mock implementations with a single commandline argument). In production, Role-based applications allow you to deploy and orchestrate fewer containers and achieve a higher computation density.
 
-8. **Simple debugging**:
-    `distage` provides you insights about your application structure and allows you to introspect and modify it on the fly, before any instantiations happen.
+10. **Simple debugging**:
 
-9. **Lifecycle management**:
-    `distage` supports resources and lifecycle natively and guarantees proper cleanups even when something went wrong.
+    Your wiring is just data. `Plan` is an immutable value you can inspect, print, render @ref[to GraphViz](debugging.md#graphviz-rendering), or rewrite it entirely - all before any instantiations happen.
 
-10. **Non-invasive**:
-    `distage` is designed to not impact the way your Scala code is written, it just removes all the initialization boilerplate.
-      You don't need to learn magic tricks to write components in a distage application.
+11. **Non-invasive**:
 
-11. **Cross-platform**:
-    `distage` is available for JVM, Graal Native Image and Scala.js.
+    `distage` is designed to not impact the way your Scala code is written, it just removes all the initialization boilerplate. You don't need to learn magic tricks to write components in a distage application.
 
 > Given its native support for type classes and higher-kinded types -- both features indispensable to functional programming -- distage is one of the leading dependency injection libraries out there. Bonus points for being built by a wicked-smart team that contributes to ZIO!
 >