Improve proto field references, update README.md

.agents/skills/writer/SKILL.md

@@ -3,7 +3,7 @@ name: writer
 description: >
   Write, edit, and restructure user-facing and developer-facing documentation.
   Use when asked to create/update docs such as `README.md`, `docs/**`, and
-  other Markdown documentation; 
+  other Markdown documentation, including keeping docs navigation data in sync;
   when drafting tutorials, guides, troubleshooting pages, or migration notes; and
   when improving inline API documentation (KDoc) and examples.
 ---
@@ -24,10 +24,36 @@ description: >
   - `docs/`: longer-form docs (follow existing conventions in that tree).
   - Source KDoc: API usage, examples, and semantics that belong with the code.
 
+## Keep docs navigation in sync
+
+- When adding, removing, moving, or renaming a page under
+  `docs/content/docs/<section>/`, keep the current version's matching
+  `sidenav.yml` in sync.
+- Use `docs/data/versions.yml` to identify the current documentation version for
+  that section. The current version is the entry with `is_main: true`; its
+  `version_id` maps to `docs/data/docs/<section>/<version_id>/sidenav.yml`.
+- Do not update historical version entries or their navigation files unless the
+  user explicitly asks to edit that historical version.
+- Map page files to `file_path` values relative to the current version's
+  `content_path`, without `.md`; `_index.md` maps to its directory path, such as
+  `01-getting-started/_index.md` -> `01-getting-started`.
+- Keep each `page` label aligned with the page frontmatter `title` unless the
+  existing navigation intentionally uses a shorter reader-facing label.
+- Preserve the existing ordering, nesting, keys, comments, and YAML quoting
+  style. Remove nav entries for deleted pages and update `file_path` values for
+  moved pages.
+- If a docs content change should not appear in navigation, say so explicitly in
+  the final response.
+
 ## Follow local documentation conventions
 
 - Follow `.agents/documentation-guidelines.md` and `.agents/documentation-tasks.md`.
 - Use fenced code blocks for commands and examples; format file/dir names as code.
+- In Markdown files, prefer footnote-style reference links for external `https://`
+  targets instead of inline links. Write readable body text like
+  `[label][short-id]`, then place the URL definition near the end of the file,
+  such as `[short-id]: https://example.com/long/path`. Keep reference IDs short
+  and descriptive. Inline links are still fine for local relative paths.
 - Avoid widows, runts, orphans, and rivers by reflowing paragraphs when needed.
 
 ## Make docs actionable
@@ -48,4 +74,3 @@ description: >
 
 - For code changes, follow `.agents/running-builds.md`.
 - For documentation-only changes in Kotlin/Java sources, prefer `./gradlew dokka`.
-

README.md

@@ -8,47 +8,138 @@
 [ubuntu-build-badge]: https://github.com/SpineEventEngine/time/actions/workflows/build-on-ubuntu.yml/badge.svg
 
 
-In addition to `Timestamp` and `Duration` natively available from Protobuf, the Spine Time library 
-provides a set of data types for describing date and time in a business model. 
+In addition to `Timestamp` and `Duration` natively available from Protobuf, the Spine Time library
+provides a set of data types for describing date and time in a business model.
 
 The types provided by this library follow the conventions offered by [Java Time][java-time].
 
 ## Supported programming languages
 
-The library currently supports Java, Kotlin (Protobuf DSL), and JavaScript. 
+The library currently supports Java and Kotlin (Protobuf DSL and
+compatibility with [`kotlinx-datetime`][kotlinx-datetime]).
 
-For JavaScript code, please see the [`time-js`](./time-js) module.
+The versions `1.*` are built using Java 8.
 
-The versions `1.x` and early `2.x` snapshots are built using Java 8. 
+The versions `2.*` are built with Java 17.
+Therefore, consumer projects should aim for Java 17+ to use them.
 
-Starting `2.0.0-SNAPSHOT.76`, all modules are built with Java 11. Therefore, consumer projects
-should aim for Java 11+ to use them.
-
-## Using Spine Time in a Gradle project
+## Integration with Spine CoreJvm
 
-To add a dependency to a Gradle project, please use the following:
+Projects based on the [Spine CoreJvm][core-jvm] library do not need to configure Time manually.
+The [CoreJvm Compiler][core-jvm-compiler] automatically adds and configures Spine Time, including
+the `(when)` option validation support.
+
+The sections below apply only when using Spine Time as a **standalone** library, without CoreJvm.
+
+## Using the Time Gradle plugin
+
+The recommended way to add Spine Time to a standalone project is via the `io.spine.time` Gradle
+plugin. Apply it after a JVM language plugin (`java`, `java-library`, or `kotlin("jvm")`):
+
+```kotlin
+plugins {
+    id("io.spine.time")
+}
+```
+
+The plugin automatically adds `io.spine:spine-time` as an `implementation` dependency.
+
+### Optional modules
+
+Use the `time` extension block to opt in to additional modules:
+
+```kotlin
+spine {
+    time {
+        useJavaExtensions.set(true)    // adds `spine-time-java` (Java Time converters)
+        useKotlinExtensions.set(true)  // adds `spine-time-kotlin` (`kotlinx-datetime` converters)
+        useTestLib.set(true)           // adds `time-testlib` as `testImplementation`
+    }
+}
+```
+
+All three flags default to `false`.
+
+### Manual dependency
+
+If you prefer to manage the dependency directly rather than through the plugin:
 
 ```kotlin
 dependencies {
-    implementation("io.spine:spine-time:$spineVersion") 
+    implementation("io.spine:spine-time:$version")
 }
 ```
 
-In addition to the generated types and basic factory and calculation routines, the library 
-provides converters between its types and Java Time. It is expected that an application code would 
-perform the date/time calculations using Java Time.
-
-## Integration with `kotlinx-datetime` 
+## Validating time fields with `(when)`
+
+The `(when)` Protobuf field option constrains a time-valued field so that it must hold
+a value either in the past or in the future.
+
+It applies to:
+
+- `google.protobuf.Timestamp`
+- Any type from the `spine.time` package (e.g. `LocalDateTime`, `ZonedDateTime`)
+- Repeated and map fields of the above types
 
-Compatibility with [`kotlinx-datetime`][kotlinx-datetime] [planned][issue-113] for v2.0.
+### Enabling validation
+
+The `(when)` option requires the [Spine Validation][validation] Gradle plugin. The `io.spine.time`
+plugin automatically registers the `time-validation` module on the compiler classpath when
+`io.spine.validation` is also applied:
+
+```kotlin
+plugins {
+    id("io.spine.validation")
+    id("io.spine.time")
+}
+```
+
+### Usage
+
+```protobuf
+import "spine/time_options.proto";
+
+message ScheduleMeeting {
+    spine.time.ZonedDateTime start = 1 [(when).in = FUTURE];
+    spine.time.ZonedDateTime end   = 2 [(when).in = FUTURE];
+}
+
+message AuditRecord {
+    google.protobuf.Timestamp occurred_at = 1 [(when).in = PAST];
+}
+```
+
+The `Time` enum accepts two values:
+
+| Value    | Meaning                        |
+|----------|--------------------------------|
+| `PAST`   | The field value must be in the past   |
+| `FUTURE` | The field value must be in the future |
+
+### Custom error messages
+
+Supply a custom message via `error_msg`. The following placeholders are available:
+
+- `${field.path}` — the field path
+- `${field.value}` — the field value
+- `${field.type}` — the fully qualified name of the field type
+- `${parent.type}` — the fully qualified name of the validated message
+- `${when.in}` — the restriction, either `"past"` or `"future"`
+
+```protobuf
+google.protobuf.Timestamp scheduled_at = 1 [(when) = {
+    in: FUTURE,
+    error_msg: "The meeting must be scheduled in the future, but got `${field.value}`."
+}];
+```
 
-[travis]: https://travis-ci.com/SpineEventEngine/time
-[travis-badge]: https://travis-ci.com/SpineEventEngine/time.svg?branch=master
 [codecov]: https://codecov.io/gh/SpineEventEngine/time
 [codecov-badge]: https://codecov.io/gh/SpineEventEngine/time/branch/master/graph/badge.svg
 [license-badge]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat
 [license]: http://www.apache.org/licenses/LICENSE-2.0
 
-[java-time]: http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html                                                        
+[core-jvm]: https://github.com/SpineEventEngine/core-jvm/
+[core-jvm-compiler]: https://github.com/SpineEventEngine/core-jvm-compiler/
+[java-time]: http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html
 [kotlinx-datetime]: https://github.com/Kotlin/kotlinx-datetime
-[issue-113]: https://github.com/SpineEventEngine/time/issues/113
+[validation]: https://github.com/SpineEventEngine/validation

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

@@ -40,7 +40,7 @@ import io.spine.dependency.Dependency
 )
 object Time : Dependency() {
     override val group = Spine.group
-    override val version = "2.0.0-SNAPSHOT.236"
+    override val version = "2.0.0-SNAPSHOT.237"
     private const val infix = "spine-time"
 
     fun lib(version: String): String = "$group:$infix:$version"

dependencies.md

@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine.tools:time-gradle-plugin:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine.tools:time-gradle-plugin:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
@@ -1059,14 +1059,14 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:46 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:time-testlib:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine.tools:time-testlib:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -1869,14 +1869,14 @@ This report was generated on **Fri May 01 17:48:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:46 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:spine-time:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine:spine-time:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -2833,14 +2833,14 @@ This report was generated on **Fri May 01 17:48:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:46 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:spine-time-java:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine:spine-time-java:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -3643,14 +3643,14 @@ This report was generated on **Fri May 01 17:48:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:46 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:spine-time-kotlin:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine:spine-time-kotlin:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -4461,14 +4461,14 @@ This report was generated on **Fri May 01 17:48:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:46 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:time-validation:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine.tools:time-validation:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
@@ -5590,14 +5590,14 @@ This report was generated on **Fri May 01 17:48:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:47 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:spine-validation-tests:2.0.0-SNAPSHOT.237`
+# Dependencies of `io.spine:spine-validation-tests:2.0.0-SNAPSHOT.238`
 
 ## Runtime
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0.
@@ -6683,6 +6683,6 @@ This report was generated on **Fri May 01 17:48:31 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri May 01 17:48:31 WEST 2026** using 
+This report was generated on **Mon May 04 17:42:47 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).
+[Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

pom.xml

@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine</groupId>
 <artifactId>spine-time</artifactId>
-<version>2.0.0-SNAPSHOT.237</version>
+<version>2.0.0-SNAPSHOT.238</version>
 
 <inceptionYear>2015</inceptionYear>
 
@@ -56,7 +56,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-time</artifactId>
-    <version>2.0.0-SNAPSHOT.236</version>
+    <version>2.0.0-SNAPSHOT.237</version>
     <scope>compile</scope>
   </dependency>
   <dependency>