Address the first task from the plan

Author: alexander-yevsyukov

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

@@ -23,9 +23,21 @@ buildable documentation set, without expanding scope unnecessarily.
 ## Minimal task list (in order)
 
 1) Information architecture (IA): make Hugo navigation coherent
-- Ensure section landing pages and “What’s next” links provide an obvious reading path
-  under `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/`.
-- Fix obvious broken intra-doc links.
+- Status: DONE (2026-02-23).
+- Added/updated section landing pages:
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/_index.md`
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/developers-guide/_index.md`
+- Replaced broken `.../index.md` links with directory links where appropriate:
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/_index.md`
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/01-getting-started/_index.md`
+- Added “What’s next” navigation to keep a clear reading path:
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/target-audience.md`
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/philosophy.md`
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/developers-guide/architecture.md`
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/developers-guide/key-modules.md`
+  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/01-getting-started/first-model.md`
+- Fixed an obvious broken image reference:
+  `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/adding-custom-validation.md`
 
 2) Complete “Getting started” flow
 - Validate that “Adding to build” + “First model” cover:

docs/content/docs/validation/00-intro/_index.md

@@ -115,4 +115,4 @@ Spine stack.
 
 - [Target audience](target-audience.md)
 - [Philosophy](philosophy.md)
-- [Getting Started](../01-getting-started/index.md)
+- [Getting started](../01-getting-started/)

docs/content/docs/validation/00-intro/philosophy.md

@@ -136,3 +136,8 @@ Spine Validation is principled around:
 
 This makes it suitable for teams that need reliable, maintainable,
 and evolvable validation for complex systems built on top of Protobuf.
+
+## What’s next
+
+- Who this is for: [Target audience](target-audience.md).
+- Try it end-to-end: [Getting started](../01-getting-started/).

docs/content/docs/validation/00-intro/target-audience.md

@@ -96,3 +96,8 @@ If you:
 - and want to enforce clear, versionable, and strongly typed validation rules,
 
 then Spine Validation is designed for you.
+
+## What’s next
+
+- Learn the design principles: [Philosophy](philosophy.md).
+- Try it end-to-end: [Getting started](../01-getting-started/).

docs/content/docs/validation/01-getting-started/_index.md

@@ -4,7 +4,7 @@ This section helps you set up Spine Validation, define your first validated Prot
 and see validation in action in Java and Kotlin.
 
 If you are new to the library, read the short overview first:
-- Introduction → [Overview](../00-intro/index.md)
+- Introduction → [Overview](../00-intro/)
 - Who this is for → [Target audience](../00-intro/target-audience.md)
 - Design principles → [Philosophy](../00-intro/philosophy.md)
 

docs/content/docs/validation/_index.md

@@ -1,4 +1,14 @@
----
-build:
-  render: never
----
+# Spine Validation
+
+Spine Validation generates type-safe validation code from constraints declared in Protobuf
+options, and runs those checks automatically when you build messages.
+
+## Start here
+
+- New to the library: [Overview](00-intro/)
+- Ready to try it: [Getting started](01-getting-started/)
+
+## Deeper topics
+
+- How it works: [Architecture](developers-guide/architecture.md)
+- Extension points: [Adding custom validation](adding-custom-validation.md)

docs/content/docs/validation/adding-custom-validation.md

@@ -15,7 +15,11 @@ Follow these steps to create a custom option:
 
 Below is a workflow diagram for a typical option:
 
-![Typical custom option](.github/readme/typical_custom_option.png)
+![Typical custom option](.github/readme/typical_custom_option.jpg)
+
+## What’s next
+
+- Learn where this plugs in: [Architecture](developers-guide/architecture.md).
 
 Take a look at the `:java-tests:extensions` module that contains a full example of
 implementation of the custom `(currency)` option.

docs/content/docs/validation/developers-guide/_index.md

@@ -1,4 +1,9 @@
----
-build:
-  render: never
----
+# Developer’s guide
+
+This section explains how Spine Validation is structured internally and where to look when
+you need to extend it.
+
+## Topics
+
+- [Architecture](architecture.md)
+- [Key modules](key-modules.md)

docs/content/docs/validation/developers-guide/architecture.md

@@ -1,4 +1,4 @@
-## Architecture
+# Architecture
 
 The library is a set of plugins for [Spine Compiler](https://github.com/SpineEventEngine/compiler).
 
@@ -14,3 +14,8 @@ The workflow is the following:
 - (3) – Protobuf compiler generates Java classes.
 - (4), (5) – policies and views build the validation model.
 - (6), (7) – Java plugin generates and injects validation code.
+
+## What’s next
+
+- See the project layout: [Key modules](key-modules.md).
+- If you need organization-specific rules: [Adding custom validation](../adding-custom-validation.md).

docs/content/docs/validation/developers-guide/key-modules.md

@@ -1,8 +1,11 @@
-
-### Key modules
+# Key modules
 
 | Module    | Description                                                          |
 |-----------|----------------------------------------------------------------------|
 | :model    | The language-agnostic model for the built-in options.                |
 | :java     | Generates and injects Java validation code based on applied options. |
 | :java-api | Extension API for custom options in Java.                            |
+
+## What’s next
+
+- Build custom constraints: [Adding custom validation](../adding-custom-validation.md).