Re-apply PR #293 (Developer's guide)

[alexander-yevsyukov]

Re-applies the changes from #293 (`Developer's guide`), which was accidentally merged because of a misconfiguration of branch protection rules and is being reverted in #295.

The tree state of this branch is identical to the state of `master` before the revert, i.e. it preserves the exact contents that were on `master` after the original PR #293 merge.

Base branch

The base of this PR is set to `revert-pr-293` so that the diff cleanly shows the re-applied changes. Once #295 is merged, switch the base of this PR to `master`.

Original PR description

This PR adds the "Validation developer guide" to the documentation. The navigation of the preview site was changed so that "User guide" and "Developer guide" appear as top-level nodes on the left side panel. This, in turn, required having `user` and `developer` subdirectories under `docs/validation/`.

This PR also includes latest updates from `site-commons` that bring improved table styes and page level navigation on the right.

Other notable changes

• The `/writer` skill was updated to use typographic quotes when referencing sections and pages in the text body.
• `embed-code.yml` was updated with the `root` code path, `code-includes` parameter was also added to avoid copying files under `.git/` which failed the build. It will also make the embedding work a bit faster because we won't copy anything but embedded content candidates.

Test plan

• Confirm the diff equals the original PR Developer's guide #293 changes
• After Revert PR #293 (accidentally merged) #295 is merged, change the base of this PR to `master`
• CI passes on the re-apply branch

[chatgpt-codex-connector]

💡 Codex Review

validation/docs/content/docs/validation/user/05-custom-validation/_index.md

Line 25 in 1132eec



Restore custom option diagram asset

This page embeds typical_custom_option.jpg, but the commit deletes the image from the old location and does not add it under the new user/05-custom-validation/ directory, so the rendered page shows a broken image instead of the workflow diagram.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Update stale developer guide links

The docs restructure moved the guide under docs/content/docs/validation/developer/**, but this page still links to ../06-developers-guide/, which now resolves to a non-existent path (user/06-developers-guide) and produces a dead “Developer's guide” link for readers; the same broken target is repeated in user/04-validators/implement-a-validator.md and user/05-custom-validation/pass-to-compiler.md.

Useful? React with 👍 / 👎.

[armiol]

@alexander-yevsyukov this may be the case.

[armiol]

@alexander-yevsyukov LGTM.

[armiol]

@alexander-yevsyukov this may be the case.

[Copilot]

Pull request overview

This PR re-applies the documentation-focused changes from #293, restructuring the Validation docs into separate User and Developer guides, updating the docs toolchain configuration, and bumping related build/tooling versions.

Changes:

• Restructured Hugo docs navigation into top-level “Validation user guide” and “Validation developer guide”, adding many new/updated guide pages and removing the old 09-developers-guide section.
• Updated docs tooling/config (Go module metadata for docs, embed-code.yml paths/includes, site-commons module versions).
• Bumped project/snapshot versions and updated the Gradle wrapper distribution.

Reviewed changes

Copilot reviewed 43 out of 72 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
version.gradle.kts	Bumps Validation version and updates description comment.
tests/validator/build.gradle.kts	Updates comment wording for KSP output usage.
README.md	Simplifies README structure; adds reference-style links and redirects “custom validation” to docs.
pom.xml	Bumps project version and related dependency versions.
java-bundle/build.gradle.kts	Updates copyright year and Apache license URL.
gradlew.bat	Updates Windows wrapper script behavior (contains an exit-flow bug; see comments).
gradlew	Updates link to Gradle template source revision.
gradle/wrapper/gradle-wrapper.properties	Updates Gradle distribution URL and adds retry-related properties.
gradle-plugin/src/main/kotlin/io/spine/tools/validation/gradle/ValidationSdk.kt	Renames internal constant and updates artifact name interpolation.
docs/go.sum	Adds Go sums for docs module dependencies.
docs/go.mod	Adds indirect dependency on site-commons.
docs/data/docs/validation/2-0-0-snapshot/sidenav.yml	Splits sidenav into user/developer top-level sections with updated paths.
docs/content/docs/validation/user/05-custom-validation/summary.md	Updates links to point at the new developer docs locations.
docs/content/docs/validation/user/05-custom-validation/register-the-option.md	Adds new documentation page.
docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md	Updates content; “What’s next” link target currently wrong.
docs/content/docs/validation/user/05-custom-validation/implement-the-view.md	Adds new documentation page.
docs/content/docs/validation/user/05-custom-validation/implement-the-reaction.md	Adds new documentation page.
docs/content/docs/validation/user/05-custom-validation/implement-the-generator.md	Adds new documentation page.
docs/content/docs/validation/user/05-custom-validation/declare-the-option.md	Adds new documentation page.
docs/content/docs/validation/user/05-custom-validation/declare-event-and-view.md	Adds new documentation page.
docs/content/docs/validation/user/05-custom-validation/_index.md	Adds new section index (contains a duplicated nav entry; see comments).
docs/content/docs/validation/user/04-validators/validator-registry.md	Adds new documentation page.
docs/content/docs/validation/user/04-validators/implement-a-validator.md	Adds/updates content; “What’s next” link target currently wrong.
docs/content/docs/validation/user/04-validators/_index.md	Updates formatting and developer guide link.
docs/content/docs/validation/user/03-built-in-options/repeated-and-map-fields.md	Adds new documentation page.
docs/content/docs/validation/user/03-built-in-options/oneof-fields.md	Minor capitalization fix in link text.
docs/content/docs/validation/user/03-built-in-options/message-level-options.md	Adds new documentation page.
docs/content/docs/validation/user/03-built-in-options/field-level-options.md	Adds new documentation page.
docs/content/docs/validation/user/03-built-in-options/_index.md	Refactors “source of truth” section (includes a whitespace-only line; see comments).
docs/content/docs/validation/user/02-concepts/options-overview.md	Adds new documentation page.
docs/content/docs/validation/user/02-concepts/error-messages.md	Adds new documentation page.
docs/content/docs/validation/user/02-concepts/_index.md	Adds new documentation page.
docs/content/docs/validation/user/01-getting-started/generated-code.md	Adds new documentation page.
docs/content/docs/validation/user/01-getting-started/first-model.md	Adds new documentation page.
docs/content/docs/validation/user/01-getting-started/build-project.md	Adds new documentation page (frontmatter title inconsistency; see comments).
docs/content/docs/validation/user/01-getting-started/adding-to-build.md	Updates plugin version in docs snippet.
docs/content/docs/validation/user/01-getting-started/_index.md	Adds new documentation page.
docs/content/docs/validation/user/00-intro/target-audience.md	Adds new documentation page.
docs/content/docs/validation/user/00-intro/philosophy.md	Adds new documentation page.
docs/content/docs/validation/user/00-intro/_index.md	Updates terminology and expands introductory content.
docs/content/docs/validation/developer/validation-model.md	Adds developer guide page.
docs/content/docs/validation/developer/testing-strategy.md	Adds developer guide page.
docs/content/docs/validation/developer/runtime-library.md	Adds developer guide page.
docs/content/docs/validation/developer/overview-and-audience.md	Adds developer guide page.
docs/content/docs/validation/developer/key-modules.md	Adds developer guide page.
docs/content/docs/validation/developer/java-code-generation.md	Adds developer guide page.
docs/content/docs/validation/developer/extension-points.md	Adds developer guide page.
docs/content/docs/validation/developer/build-and-release.md	Adds developer guide page.
docs/content/docs/validation/developer/architecture.md	Adds developer guide page.
docs/content/docs/validation/developer/adding-a-built-in-option.md	Adds developer guide page.
docs/content/docs/validation/09-developers-guide/key-modules.md	Removes legacy developer guide page.
docs/content/docs/validation/09-developers-guide/architecture.md	Removes legacy developer guide page.
docs/content/docs/validation/09-developers-guide/_index.md	Removes legacy developer guide index.
docs/content/docs/validation/_index.md	Updates landing page links to new user/developer guide structure.
docs/_settings/embed-code.yml	Adds root/java/context code paths and include filters for embedding.
docs/_preview/go.sum	Updates preview module sums for updated Hugo/site-commons deps.
docs/_preview/go.mod	Updates preview module requires for updated Hugo/site-commons deps.
docs/_preview/content/_index.md	Fixes preview link to point at the new docs root.
dependencies.md	Regenerates dependency report for new snapshot version.
context/src/main/kotlin/io/spine/tools/validation/ValidationPlugin.kt	Adds trailing comment to closing paren.
context/src/main/kotlin/io/spine/tools/validation/ErrorPlaceholder.kt	Fixes grammar in KDoc about runtime duplication.
CLAUDE.md	Fixes path to .agents/_TOC.md.
buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt	Bumps local Validation dependency version.
buildSrc/src/main/kotlin/fat-jar.gradle.kts	Updates copyright year/URL and removes an exclusion block.
.gitignore	Ignores /.claude/worktrees/.
.agents/skills/writer/SKILL.md	Adds guideline about typographic quotes usage for doc references.

Comments suppressed due to low confidence (3)

docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md:76

• This link points to ../06-developers-guide/, but the developer docs were moved under validation/developer/ (see docs/content/docs/validation/developer/* and sidenav.yml entries). Update the link target to the new Developer’s Guide location (e.g. ../../developer/ or a concrete page like ../../developer/overview-and-audience.md).
  docs/content/docs/validation/user/04-validators/implement-a-validator.md:140
• This link points to ../06-developers-guide/, but the developer docs are now under validation/developer/ (see docs/content/docs/validation/developer/* and sidenav.yml). Update the link target to the new Developer’s Guide location (e.g. ../../developer/ or ../../developer/overview-and-audience.md).
  docs/content/docs/validation/user/03-built-in-options/_index.md:48
• There is a whitespace-only line here. Please remove it to avoid trailing-whitespace noise in diffs and potential markdown lint issues.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 44 out of 73 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md:76

• The "What's next" link points to ../06-developers-guide/, but the Developer guide content is now under docs/content/docs/validation/developer/ (e.g. ../../developer/ or ../../developer/overview-and-audience.md from this page). Update this link so it resolves to the new Developer guide location.
  docs/content/docs/validation/user/04-validators/implement-a-validator.md:141
• The "What's next" section links to ../06-developers-guide/, but the Developer guide was moved under docs/content/docs/validation/developer/. Please update this link to the new path (e.g. ../../developer/ or a specific page under it) so navigation doesn't 404.
  docs/content/docs/validation/user/03-built-in-options/_index.md:48
• Line contains a large run of trailing whitespace before the reference link definitions. This tends to create noisy diffs and can trip markdown linters; please remove the stray whitespace-only line.