Add content to the "Concepts" section of the documentation

.agents/skills/writer/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: writer
+description: Write, edit, and restructure user-facing and developer-facing documentation for the Spine `validation` repository. Use when asked to create/update docs such as `README.md`, `docs/**`, `CONTRIBUTING.md`, and other Markdown documentation; when drafting tutorials, guides, troubleshooting pages, or migration notes; and when improving inline API documentation (KDoc) and examples.
+---
+
+# Write documentation (repo-specific)
+
+## Decide the target and audience
+
+- Identify the target reader: end user, contributor, maintainer, or tooling/automation.
+- Identify the task type: new doc, update, restructure, or documentation audit.
+- Identify the acceptance criteria: “what is correct when the reader is done?”
+
+## Choose where the content should live
+
+- Prefer updating an existing doc over creating a new one.
+- Place content in the most discoverable location:
+  - `README.md`: project entry point and “what is this?”.
+  - `docs/`: longer-form docs (follow existing conventions in that tree).
+  - `CONTRIBUTING.md`: contributor workflows.
+  - Source KDoc: API usage, examples, and semantics that belong with the code.
+
+## 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.
+- Avoid widows, runts, orphans, and rivers by reflowing paragraphs when needed.
+
+## Make docs actionable
+
+- Prefer steps the reader can execute (commands + expected outcome).
+- Prefer concrete examples over abstract descriptions.
+- Include prerequisites (versions, OS, environment) when they are easy to miss.
+- Use consistent terminology (match code identifiers and existing docs).
+
+## KDoc-specific guidance
+
+- For public/internal APIs, include at least one example snippet demonstrating common usage.
+- When converting from Javadoc/inline comments to KDoc:
+  - Remove HTML like `<p>` and preserve meaning.
+  - Prefer short paragraphs and blank lines over HTML formatting.
+
+## Validate changes
+
+- For code changes, follow `.agents/running-builds.md`.
+- For documentation-only changes in Kotlin/Java sources, prefer `./gradlew dokka`.
+

.agents/skills/writer/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Writer"
+  short_description: "Write and update user/developer docs"
+  default_prompt: "Write or revise documentation in this repository (for example: README.md, docs/**, CONTRIBUTING.md, and API documentation/KDoc). Follow local documentation guidelines in .agents/*.md, keep changes concise and actionable, and include concrete examples and commands where appropriate."
+

.agents/skills/writer/assets/templates/doc-page.md

@@ -0,0 +1,23 @@
+# Title
+
+## Goal
+
+State what the reader will accomplish.
+
+## Prerequisites
+
+- List versions/tools the reader needs.
+
+## Steps
+
+1. Do the first thing.
+2. Do the next thing.
+
+## Verify
+
+Show how the reader can confirm success.
+
+## Troubleshooting
+
+- Common failure: likely cause → fix.
+

.agents/skills/writer/assets/templates/kdoc-example.md

@@ -0,0 +1,11 @@
+````kotlin
+/**
+ * Explain what this API does in one sentence.
+ *
+ * ## Example
+ * ```kotlin
+ * // Show the typical usage pattern.
+ * val result = doThing()
+ * ```
+ */
+````

.agents/skills/writer/assets/templates/kotlin-java-example.md

@@ -0,0 +1,13 @@
+{{< code-tabs langs="Kotlin, Java">}}
+
+{{< code-tab lang="Kotlin" >}}
+```kotlin
+```
+{{< /code-tab >}}
+
+{{< code-tab lang="Java" >}}
+```java
+```
+{{< /code-tab >}}
+
+{{< /code-tabs >}}

.agents/tasks/archive/concepts-plan.md

@@ -0,0 +1,57 @@
+**Goal**: explain how Validation works (one layer deeper than “getting started”)
+- Add a Concepts landing page and an “options overview” page that explains:
+  where options come from, how they’re applied, and what code gets generated.
+- Keep this conceptual (no option-by-option details yet).
+- Target outcome: a reader can explain that Validation is enforced by generated code
+  (not by parsing descriptor/options at runtime) and that the Gradle plugin wires the
+  Validation Compiler into the build to augment `protoc` output.
+- Terminology: use “Validation Compiler” consistently (it is a plugin to the Spine Compiler).
+- Pages to create/update:
+    - Concepts landing: `docs/content/docs/validation/02-concepts/_index.md`
+    - Options overview: `docs/content/docs/validation/02-concepts/options-overview.md`
+- Concepts landing page: planned content (conceptual, 1 screen deeper than “Getting started”)
+    - Open with a 2–3 sentence “mental model”:
+        - Constraints are declared in `.proto` files using built-in options imported from `spine/options.proto`.
+        - The Validation Compiler updates Java sources generated by `protoc` so runtime checks happen in code.
+    - Explain the “build-time vs runtime” boundary:
+        - Build-time: options are read from descriptors and used to generate/inject checks into message code.
+        - Runtime: there is no descriptor parsing; validation runs as regular code in `build()` / `validate()`.
+    - Add a small pipeline diagram (Mermaid) showing:
+      `.proto` + `spine/options.proto` import → `protoc` (Java) → Validation Compiler (via Gradle plugin)
+      → generated Java API (`build()`, `validate()`).
+    - Define (briefly) what Protobuf custom options are with a one-sentence refresher,
+      then link to Protobuf docs for details.
+    - Clarify “what you write” vs “what you get”:
+        - You write: option annotations on fields/messages.
+        - You get: runtime enforcement through `build()` throwing `ValidationException` and
+          `validate()` returning an error object (as introduced in “Getting started”).
+    - Mention extensibility without diving in:
+        - Note that custom validation options + codegen are possible; link forward to
+          `docs/content/docs/validation/08-custom-validation/_index.md`.
+    - Close with “What’s next” links:
+        - Options overview page.
+        - Custom validation (for organization-specific rules).
+        - Developers guide (architecture/key modules) for internals.
+- Options overview page: planned content (concrete examples, but not an option catalog)
+    - Purpose statement: explain where built-in options come from and how they influence generated code.
+    - Where options come from (built-ins only):
+        - Options are defined in `spine/options.proto` (and related Spine option protos).
+        - Users import the option proto(s) and annotate their own message/field definitions.
+    - One-sentence refresher on Protobuf options + a link to Protobuf docs about custom options.
+    - How options are applied at build time:
+        - The Gradle plugin integrates Validation into the build.
+        - Validation Compiler uses the compiled descriptors (including option values) to augment `protoc` output.
+    - What code gets generated (high-level, user-facing):
+        - `build()` performs validation and throws `ValidationException` on violations.
+        - `validate()` can be used to obtain a structured validation error without throwing.
+        - (Avoid helper-class details; keep terminology aligned with “Using the generated code”.)
+    - What does *not* happen:
+        - Validation does not parse descriptor option data at runtime to decide what to validate.
+    - 1–3 tiny illustrative `.proto` snippets (no deep semantics):
+        - Example: `(required)` on a field.
+        - Example: `(pattern)` on a string field.
+        - Example: `(min)/(max)` on a numeric field.
+          Each snippet should be used only to anchor the “options → generated code” explanation.
+    - Add “What’s next” links:
+        - Built-in options reference (future section 4).
+        - Custom validation (for defining your own options/rules).

.agents/tasks/archive/error-messages-plan.md

@@ -0,0 +1,34 @@
+# Task: Write documentation on working with validation error messages
+- Placement of the page: Under the Concepts section after the “Options overview” page.
+- Purpose: explain how validation error messages work, how to customize them, and how to use them in code.
+- Target outcome: a reader can explain the relationship between validation options and error messages,
+- how to define custom messages, and how to format them for end users or diagnostics.
+- Terminology: `TemplateString`, `ValidationError`, `ConstraintViolation`, `format()`, `formatUnsafe()`
+- Describe that validation options have default error messages and user-defined error messages
+  (via the `error_msg` field of a validation option, such as `(pattern).error_msg`).
+- Give an example of a custom validation error message with placeholders
+  defined in a proto field option. Use `spine/options.proto` as a reference for
+  the option definition and the `error_msg` field.
+- Explain the notion of placeholders in error messages and how they correspond to
+  values provided at runtime when a violation occurs.
+- Describe how `TemplateString` works (placeholders + values) and how to convert it to a
+  human-readable message (formatting).
+- Clarify the recommended ways to work with Validation errors in:
+    - Kotlin: `TemplateString.format()` / `TemplateString.formatUnsafe()`.
+    - Java: `io.spine.validation.TemplateStrings.format(TemplateString)`
+    - Java: `io.spine.validation.TemplateStrings.formatUnsafe(TemplateString)`.
+- Explain the structure of `ValidationError` / `ConstraintViolation`, and what fields developers
+  should use when:
+    - displaying messages to end users;
+    - logging diagnostics (e.g. include `type_name`, `field_path`, and the unformatted template).
+- Add troubleshooting notes for common runtime formatting problems (e.g. missing placeholder
+  values; choosing `formatUnsafe()` when partial substitution is acceptable).
+- Source references to anchor the docs:
+    - `jvm-runtime/src/main/proto/spine/validation/error_message.proto`
+    - `jvm-runtime/src/main/proto/spine/validation/validation_error.proto`
+    - `jvm-runtime/src/main/kotlin/io/spine/validation/TemplateStringExts.kt`
+    - `jvm-runtime/src/main/kotlin/io/spine/validation/RuntimeErrorPlaceholder.kt`
+
+## Output
+
+Implemented as `docs/content/docs/validation/02-concepts/error-messages.md`.

.agents/tasks/built-in-options-plan.md

@@ -0,0 +1,7 @@
+# Task: Publish a minimal reference set on built-in validation options
+- Placement: a separate section coming after the "Concepts" section.
+- From `docs/_options/options.proto`,
+  enumerate the built-in options and group them (fields, strings, numbers, collections, message-level).
+- For each documented option: purpose, supported field types, common pitfalls, and a short `.proto` example.
+- Start with the options already used in docs/examples: `(required)`, `(pattern)`, `(min)/(max)`,
+  `(distinct)`, `(validate)`.

.agents/tasks/custom-validation-plan.md

@@ -0,0 +1,47 @@
+# Task: Expand “Custom validation” docs (custom options + codegen)
+
+## Goal
+
+Turn the existing “Custom validation” landing page into a complete, end-to-end guide for
+implementing organization-specific rules via custom Protobuf options and code generation.
+
+Target outcome: a reader can define a custom option, register it, implement reaction/view/generator,
+and verify it works in a consumer project.
+
+## Placement
+
+- Placement of the pages: `docs/content/docs/validation/08-custom-validation/`.
+- Keep the current landing page as an overview and add a single practical walkthrough page.
+
+## Planned content
+
+- Clarify the extension surface:
+  - Custom Protobuf option definition (`extend google.protobuf.*Options`).
+  - Option discovery + validation (reaction).
+  - Accumulating a model (views, plus policies if needed).
+  - Generating/injecting Java validation code (generator).
+- Make the steps actionable:
+  - Show file/Gradle locations where each piece belongs in a consumer project.
+  - Explain registration points:
+    - `io.spine.option.OptionsProvider`
+    - `io.spine.tools.validation.java.ValidationOption` (SPI for custom option implementations)
+- Provide a minimal “walkthrough” with the existing `(currency)` sample:
+  - Point to the option declaration, the reaction/view/generator, and the registration.
+  - Explain the intended contract: what rule is enforced, where the error message comes from.
+- Add a short troubleshooting section:
+  - Option not discovered (missing `OptionsProvider`).
+  - Generator not invoked (missing `ValidationOption` SPI entry).
+  - Illegal option application should fail compilation (where to look for error messages).
+
+## Source references to anchor the docs
+
+- Existing overview page:
+  - `docs/content/docs/validation/08-custom-validation/_index.md`
+- Full working example:
+  - `:tests:extensions` module (custom `(currency)` option implementation)
+
+## Output
+
+- Update: `docs/content/docs/validation/08-custom-validation/_index.md`.
+- Add: `docs/content/docs/validation/08-custom-validation/currency-example.md`.
+

.agents/tasks/developers-guide-plan.md

@@ -0,0 +1,51 @@
+# Task: Complete Developer’s guide (architecture and key modules)
+
+## Goal
+
+Make the “Developer’s guide” pages sufficient for maintainers and contributors:
+the reader should understand the compilation pipeline, where each responsibility lives,
+and where to start when debugging a doc/codegen/runtime issue.
+
+## Placement
+
+- Placement of the pages: `docs/content/docs/validation/09-developers-guide/`.
+- Expand the existing pages without adding many new sections (keep it minimal).
+
+## Planned content
+
+- Architecture page (`architecture.md`)
+  - Add a legend / step-by-step explanation for the existing diagram:
+    - where options are discovered;
+    - where the validation model is built (policies/views);
+    - where Java code is generated/injected;
+    - what artifacts flow between stages (descriptors, generated sources, resources).
+  - Call out the main extension points and where they plug in:
+    - custom options (reaction/view/generator + SPI);
+    - external message validators (`MessageValidator` + `@Validator` + KSP discovery).
+  - Add “Where to look” links:
+    - built-in options reference;
+    - custom validation section;
+    - key modules page.
+
+- Key modules page (`key-modules.md`)
+  - Keep the tables, but add a 1–2 paragraph “debugging map”:
+    - build-time problems (compiler/plugin) vs runtime problems (generated code / runtime library).
+  - Add a short list of “common entry points” by scenario:
+    - option semantics or compilation errors → `:context`, `:java`, `:gradle-plugin`;
+    - validator discovery problems → `:ksp`, `:java`;
+    - error message formatting → `:jvm-runtime`.
+
+## Source references to anchor the docs
+
+- Existing pages:
+  - `docs/content/docs/validation/09-developers-guide/architecture.md`
+  - `docs/content/docs/validation/09-developers-guide/key-modules.md`
+- External message validator mechanism (for cross-linking):
+  - `jvm-runtime/src/main/kotlin/io/spine/validation/MessageValidator.kt`
+  - `jvm-runtime/src/main/kotlin/io/spine/validation/Validator.kt`
+
+## Output
+
+- Update: `docs/content/docs/validation/09-developers-guide/architecture.md`.
+- Update: `docs/content/docs/validation/09-developers-guide/key-modules.md`.
+

.agents/tasks/third-party-messages-plan.md

@@ -0,0 +1,60 @@
+# Task: Document validating third-party (external) messages
+
+## Goal
+
+Explain how to enforce validation rules for Protobuf message classes that are **already generated**
+by third parties and therefore cannot be updated via `.proto` option annotations + codegen.
+
+Target outcome: a reader can pick the right strategy depending on whether they control the `.proto`
+source, and can implement an external message validator that is automatically applied when
+validating local messages.
+
+## Placement
+
+- Placement of the page: after “Built-in options”, before “Custom validation”.
+- Hugo section (minimal change): add the page under `docs/content/docs/validation/02-concepts/`.
+  If the site navigation later gains an “Advanced topics” section, the page can move there.
+
+## Planned content
+
+- Define “local” vs “external” messages:
+  - Local: `.proto` sources compiled in the current build; Validation injects checks into generated code.
+  - External: message classes already compiled (e.g., come from dependencies); codegen cannot be applied.
+- What does and does not work:
+  - You cannot attach Validation options to fields of external messages unless you rebuild their `.proto`.
+  - External validators are applied **only when an external message is a field inside a local message**.
+  - External validators are not applied transitively inside other external messages.
+- Recommended strategy decision tree:
+  - If you control `.proto`: prefer built-in options or custom validation options (codegen).
+  - If you don’t control `.proto`: use `MessageValidator` + `@Validator`.
+- How external validation works (high-level):
+  - Implement `io.spine.validation.MessageValidator<M>`.
+  - Annotate the implementation with `@io.spine.validation.Validator(M::class)`.
+  - Ensure a `public` no-args constructor (required by discovery/instantiation).
+  - Validation invokes the validator for:
+    - singular fields of type `M`;
+    - repeated fields of type `M`;
+    - map values of type `M`.
+- Error reporting shape:
+  - Return `List<DetectedViolation>`.
+  - Use `FieldViolation` (and other available violation types) to point at a field path and value.
+  - Mention that the runtime converts `DetectedViolation` into `ConstraintViolation`/`ValidationError`.
+- Constraints and guardrails:
+  - Exactly one validator per external message type (duplicate is an error).
+  - Validators for local messages are prohibited (use options/codegen instead).
+- Example walkthrough (short, copy-pastable):
+  - Implement `EarphonesValidator` (from `:tests:validator`) and show how it affects a local message
+    that contains an `Earphones` field.
+
+## Source references to anchor the docs
+
+- External validation API and requirements:
+  - `jvm-runtime/src/main/kotlin/io/spine/validation/MessageValidator.kt`
+  - `jvm-runtime/src/main/kotlin/io/spine/validation/Validator.kt`
+- Example implementation:
+  - `tests/validator/src/main/kotlin/io/spine/tools/validation/test/EarphonesValidator.kt`
+
+## Output
+
+Implemented as `docs/content/docs/validation/02-concepts/third-party-messages.md`.
+