Add overview and basic usage to README

README.md

@@ -5,10 +5,126 @@
 [![codecov.io][codecov-badge]][codecov-report]
 [![license][apache-badge]][apache-license]
 
-Spine Compiler is a collection of tools for generating quality
-domain models from Protobuf definitions.
+Spine Compiler is a collection of tools for generating quality domain models from Protobuf
+definitions. It plugs into your Gradle build and extends the code that `protoc` produces,
+turning plain `.proto` messages into rich domain types — with validation, factory methods,
+and other conveniences contributed by pluggable code generators.
 
-The project is under development right now. Proceed with caution.
+The Compiler is part of the [Spine SDK][spine-site] and powers code generation across
+Spine-based projects. It is not limited to them, though: any Protobuf-based JVM project can
+apply the Compiler and drive it with its own code-generation plugins.
+
+## How it works
+
+The Compiler treats your Protobuf definitions as a model and processes it reactively:
+
+1. `protoc` parses the `.proto` files. A `protoc` plugin bundled with the Compiler captures
+   the result as a code-generation request.
+2. The Compiler reads that request and represents the Protobuf files, types, fields, and
+   options as a model, delivered as a stream of events.
+3. The plugins you attach observe the model through *views* and react to it through
+   *policies*, then emit source code through *renderers*.
+4. The renderers create new source files or edit the ones `protoc` generated, producing the
+   final domain model.
+
+A *plugin* bundles these parts together, so attaching one plugin is enough to contribute a
+whole feature to the generated code.
+
+## Getting started
+
+### Requirements
+
+- JDK 17 or newer.
+- The [Protobuf Gradle Plugin][protobuf-gradle] (`com.google.protobuf`), which the Compiler
+  builds upon.
+
+### Apply the Gradle plugin
+
+The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal under the
+`io.spine.compiler` ID. It requires the Protobuf Gradle Plugin, so apply both:
+
+```kotlin
+plugins {
+    java
+    id("com.google.protobuf") version "<Protobuf plugin version>"
+    id("io.spine.compiler") version "<Compiler version>"
+}
+```
+
+The example applies the `java` plugin; use `kotlin("jvm")` instead for a Kotlin project — the
+Compiler generates code for both. Once applied, the Compiler hooks into the `generateProto`
+tasks, so the generated model is refreshed on every build.
+
+### Configure code-generation plugins
+
+Out of the box the Compiler runs the pipeline without changing the generated code. To make it
+do something, attach one or more Compiler plugins: list their classes in the `compiler { }`
+block — nested inside the `spine { }` extension — and put them on the Compiler classpath with
+the `spineCompiler` configuration.
+
+```kotlin
+spine {
+    compiler {
+        plugins(
+            "com.acme.codegen.MyPlugin",
+        )
+    }
+}
+
+dependencies {
+    spineCompiler("com.acme:my-codegen:1.0.0")
+}
+```
+
+Then build the project as usual:
+
+```bash
+./gradlew build
+```
+
+## Writing a plugin
+
+A Compiler plugin is a class with a parameterless constructor that bundles the components doing
+the work. The most common component is a *renderer*, which creates or edits source files:
+
+```kotlin
+import io.spine.tools.code.Java
+import io.spine.tools.compiler.plugin.Plugin
+import io.spine.tools.compiler.render.Renderer
+import io.spine.tools.compiler.render.SourceFileSet
+
+/** Modifies the Java sources produced for the Protobuf model. */
+public class MyRenderer : Renderer<Java>(Java) {
+
+    override fun render(sources: SourceFileSet) {
+        // Inspect the Protobuf model and create or edit source files here.
+    }
+}
+
+/** Exposes the renderer — and any views or policies — to the Compiler. */
+public class MyPlugin : Plugin(renderers = listOf(MyRenderer()))
+```
+
+Compile the plugin against the public API artifact:
+
+```kotlin
+dependencies {
+    implementation("io.spine.tools:compiler-api:<Compiler version>")
+}
+```
+
+Renderers can inspect the Protobuf model through views and react to it through policies. See the
+`api` module and its API documentation for the full set of building blocks.
+
+## Further reading
+
+- [Spine SDK website][spine-site]
+- [Contributing guidelines](CONTRIBUTING.md)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+Spine Compiler is released under the [Apache License, Version 2.0](LICENSE.md).
 
 [ubuntu-badge]: https://github.com/SpineEventEngine/compiler/actions/workflows/build-on-ubuntu.yml/badge.svg
 [ubuntu-build]: https://github.com/SpineEventEngine/compiler/actions/workflows/build-on-ubuntu.yml
@@ -19,5 +135,8 @@ The project is under development right now. Proceed with caution.
 [codecov-badge]: https://codecov.io/github/SpineEventEngine/compiler/coverage.svg?branch=master
 [codecov-report]: https://codecov.io/github/SpineEventEngine/compiler?branch=master
 
-[apache-badge]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat 
+[apache-badge]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat
 [apache-license]: https://www.apache.org/licenses/LICENSE-2.0
+
+[spine-site]: https://spine.io/
+[protobuf-gradle]: https://github.com/google/protobuf-gradle-plugin

buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvm.kt

@@ -39,7 +39,7 @@ typealias CoreJava = CoreJvm
 @Suppress("ConstPropertyName", "unused")
 object CoreJvm {
     const val group = Spine.group
-    const val version = "2.0.0-SNAPSHOT.380"
+    const val version = "2.0.0-SNAPSHOT.381"
 
     const val coreArtifact = "spine-core"
     const val clientArtifact = "spine-client"

docs/dependencies/dependencies.md

@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine.tools:compiler-api:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-api:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -1067,14 +1067,14 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-api-tests:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-api-tests:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 ## Compile, tests, and tooling
@@ -1444,14 +1444,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:23 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-backend:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-backend:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -2522,14 +2522,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-cli:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-cli:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -3759,14 +3759,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-gradle-api:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-gradle-api:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -4783,14 +4783,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-gradle-plugin:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-gradle-plugin:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -5851,14 +5851,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-jvm:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-jvm:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -6946,14 +6946,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-params:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-params:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -8012,14 +8012,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-protoc-plugin:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-protoc-plugin:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -8852,14 +8852,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-test-env:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-test-env:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -9926,14 +9926,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:compiler-testlib:2.0.0-SNAPSHOT.056`
+# Dependencies of `io.spine.tools:compiler-testlib:2.0.0-SNAPSHOT.057`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0.
@@ -11107,6 +11107,6 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using 
+This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

docs/dependencies/pom.xml

@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine.tools</groupId>
 <artifactId>compiler</artifactId>
-<version>2.0.0-SNAPSHOT.056</version>
+<version>2.0.0-SNAPSHOT.057</version>
 
 <inceptionYear>2015</inceptionYear>
 
@@ -137,7 +137,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-server</artifactId>
-    <version>2.0.0-SNAPSHOT.380</version>
+    <version>2.0.0-SNAPSHOT.381</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
@@ -209,7 +209,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>server-testlib</artifactId>
-    <version>2.0.0-SNAPSHOT.380</version>
+    <version>2.0.0-SNAPSHOT.381</version>
     <scope>compile</scope>
   </dependency>
   <dependency>

docs/project.md

@@ -24,10 +24,12 @@ with these modules:
   published separately from the rest of the modules.
 - `test-env`, `testlib` — shared test fixtures and utilities.
 
-Module artifacts are published under `io.spine.tools` (see
-[`dependencies.md`](dependencies/dependencies.md) for the published coordinates). Public
-API boundaries live in `api` and `gradle-api`; downstream Spine repos depend
-on these.
+Module artifacts are published under the `io.spine.tools` group with the
+`compiler-` prefix — for example, `io.spine.tools:compiler-api` (see
+[`dependencies.md`](dependencies/dependencies.md) for the full coordinates) —
+and the Gradle plugin to the Gradle Plugin Portal as `io.spine.compiler`.
+Public API boundaries live in `api` and `gradle-api`; downstream Spine repos
+depend on these.
 
 Read [`.agents/guidelines/jvm-project.md`](../.agents/guidelines/jvm-project.md) for build stack,
 coding style, tests, and versioning.