alexander-yevsyukov · Oct 20, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/docs/_bin/embed-code-linux b/docs/_bin/embed-code-linux
diff --git a/docs/_bin/embed-code-macos b/docs/_bin/embed-code-macos
diff --git a/docs/_bin/embed-code-macos-x86_64 b/docs/_bin/embed-code-macos-x86_64
diff --git a/docs/_bin/embed-code-windows.exe b/docs/_bin/embed-code-windows.exe
diff --git a/docs/_script/check-samples b/docs/_script/check-samples
@@ -17,13 +17,17 @@ fi
 # Navigate to the folder with embed-code binaries.
 cd _bin
 
-# Use the Linux binary for GitHub Actions and macOS binary in other cases.
+# Use the Linux binary for GitHub Actions, and the macOS binary
+# matching the host architecture in other cases.
 if [ "$GITHUB_ACTIONS" = "true" ]; then
   echo "Running in GitHub Action."
   TOOL="./embed-code-linux"
-else
-  echo "Running locally on macOS."
+elif [ "$(uname -m)" = "arm64" ]; then
+  echo "Running locally on macOS (Apple silicon)."
   TOOL="./embed-code-macos"
+else
+  echo "Running locally on macOS (Intel)."
+  TOOL="./embed-code-macos-x86_64"
 fi
 
 # Check code samples.

diff --git a/docs/_script/embed-code b/docs/_script/embed-code
@@ -18,5 +18,12 @@ git submodule update --remote --merge --recursive
 # Navigate to the folder with embed-code binaries.
 cd _bin
 
+# Use the macOS binary matching the host architecture.
+if [ "$(uname -m)" = "arm64" ]; then
+  TOOL="./embed-code-macos"
+else
+  TOOL="./embed-code-macos-x86_64"
+fi
+
 # Update code samples.
-./embed-code-macos -config-path="../_settings/embed-code.yml" -mode="embed"
+"$TOOL" -config-path="../_settings/embed-code.yml" -mode="embed"
diff --git a/docs/_settings/embed-code.yml b/docs/_settings/embed-code.yml
@@ -14,11 +14,3 @@ code-path:
   - name: "docs"
     path: ".."
 docs-path: "../content/docs/"
-code-includes:
-  - ".gitignore"
-  - "**/*.kts"
-  - "**/*.md"
-  - "**/*.proto"
-  - "**/*.java"
-  - "**/*.kt"
-  - "**/*.yml"
diff --git a/docs/content/docs/validation/developer/adding-a-built-in-option.md b/docs/content/docs/validation/developer/adding-a-built-in-option.md
@@ -164,6 +164,7 @@ projection:
 ```protobuf
 message RequiredField {
     option (entity).kind = PROJECTION;
+    option (is).java_type = "FieldView";
 
     compiler.FieldRef id = 1;
 

diff --git a/docs/content/docs/validation/developer/build-and-release.md b/docs/content/docs/validation/developer/build-and-release.md
@@ -47,7 +47,7 @@ through Gradle's `extra` properties:
   end="validationVersion">
 </embed-code>
 ```kotlin
-extra.set("validationVersion", "2.0.0-SNAPSHOT.466")
+extra.set("validationVersion", "2.0.0-SNAPSHOT.467")
 ```
 
 The root build script applies this file under `allprojects { … }` and assigns

diff --git a/docs/content/docs/validation/developer/documentation/build-tasks.md b/docs/content/docs/validation/developer/documentation/build-tasks.md
@@ -104,7 +104,9 @@ git submodule update --remote --merge --recursive
 ```
 
 so that `_examples/` and `_time/` track their default remote branches. It
-then invokes `embed-code-macos` with `-mode="embed"` and the configuration at
+then invokes the macOS binary matching the host architecture —
+`embed-code-macos` on Apple silicon, `embed-code-macos-x86_64` on Intel —
+with `-mode="embed"` and the configuration at
 `_settings/embed-code.yml`, which rewrites the fenced regions in the Markdown
 pages under `content/` from their source snippets. Run this task manually
 after editing an embedded snippet or after pointing a source root at a new
@@ -115,8 +117,9 @@ recipe.
 ### `checkSamples`
 
 Runs `_script/check-samples`. The script selects `embed-code-linux` when the
-`GITHUB_ACTIONS` environment variable is `true`, and `embed-code-macos`
-otherwise, then invokes it with `-mode="check"`. The tool exits non-zero if
+`GITHUB_ACTIONS` environment variable is `true`, and the macOS binary
+matching the host architecture otherwise, then invokes it with
+`-mode="check"`. The tool exits non-zero if
 any embedded snippet drifts from its source. This task is executed by the
 [Code Embedding][check-code-embedding] GitHub workflow on every pull
 request.

diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md
@@ -82,14 +82,6 @@ code-path:
   - name: "docs"
     path: ".."
 docs-path: "../content/docs/"
-code-includes:
-  - ".gitignore"
-  - "**/*.kts"
-  - "**/*.md"
-  - "**/*.proto"
-  - "**/*.java"
-  - "**/*.kt"
-  - "**/*.yml"
 ```
 
 ### Source roots (`code-path`)
@@ -117,12 +109,12 @@ to `docs/_time/`.
 should scan when running `embedCode` or `checkSamples`. Only files under
 this directory are considered for embedding.
 
-### Embeddable file types (`code-includes`)
+### Embeddable file types
 
-The globs under `code-includes` filter which source files the tool will
-read when resolving an `<embed-code>` block. Adding a new file extension
-(for example, `**/*.json` for embedded JSON snippets) means appending it
-to this list.
+The tool does not filter source files by type: an `<embed-code>` block can
+reference any file under a source root. Older releases of `embed-code-go`
+read a `code-includes` list of globs for this; current releases ignore it,
+so the configuration no longer declares one.
 
 ## Embedding syntax on the page side
 

diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md
@@ -118,7 +118,8 @@ commit.
 
 4. Re-embed snippets without running `:docs:embedCode`, because that task
    would move the submodule back to the default remote branch before
-   embedding:
+   embedding. On an Intel Mac, run `./embed-code-macos-x86_64` instead of
+   `./embed-code-macos`:
 
    ```bash
    ./gradlew :docs:updatePluginVersions
@@ -140,8 +141,7 @@ commit.
 
 1. If the source file lives outside the existing source roots in
    [`_settings/embed-code.yml`][embed-code-yml], add a new entry under
-   `code-path` (a `name` plus a path relative to `docs/_bin/`). If the
-   file extension is not yet listed, add a glob under `code-includes`.
+   `code-path` (a `name` plus a path relative to `docs/_bin/`).
 
 2. In the target Markdown page, write an `<embed-code>` element followed
    by an empty fenced code block. For example:
@@ -236,21 +236,32 @@ in this repository.
 ## Updating `embed-code-go`
 
 The tool is consumed as prebuilt binaries under `docs/_bin/`. The
-authoritative copies are published by the upstream project under
-[`embed-code-go/bin`][embed-code-bin]. We do *not* build the tool as
+authoritative copies are published by the upstream project as assets of
+its [GitHub releases][embed-code-releases]. We do *not* build the tool as
 part of the Validation documentation build — see the upstream repository
 for any build, test, or release questions.
 
-1. From [`embed-code-go/bin`][embed-code-bin], download the three
-   binaries on the branch or tag you want to ship:
-   `embed-code-linux`, `embed-code-macos`, `embed-code-windows.exe`.
+1. Download the assets of the release you want to ship, and verify them
+   against the SHA-256 digests shown on the release page:
 
-2. Replace the files of the same names under `docs/_bin/`.
+   ```bash
+   gh release download <tag> --repo SpineEventEngine/embed-code-go
+   ```
+
+2. Unzip the archives, and replace the files under `docs/_bin/` as follows:
+
+   | Release asset                | File under `docs/_bin/`     |
+   |------------------------------|-----------------------------|
+   | `embed-code-linux.zip`       | `embed-code-linux`          |
+   | `embed-code-macos-arm64.zip` | `embed-code-macos`          |
+   | `embed-code-macos-x64.zip`   | `embed-code-macos-x86_64`   |
+   | `embed-code-windows.exe`     | `embed-code-windows.exe`    |
 
 3. Make sure the macOS and Linux binaries are executable:
 
    ```bash
-   chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-linux
+   chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-macos-x86_64 \
+     docs/_bin/embed-code-linux
    ```
 
 4. Verify that the new binaries still produce the same embedded output
@@ -265,7 +276,7 @@ for any build, test, or release questions.
    before committing.
 
 5. Commit the updated binaries under `docs/_bin/` with a message that
-   names the upstream commit they were pulled from.
+   names the upstream release they were pulled from.
 
 ## Building the documentation locally
 
@@ -314,5 +325,5 @@ for any build, test, or release questions.
 [doc-guidelines]: https://github.com/SpineEventEngine/validation/blob/master/.agents/documentation-guidelines.md
 [theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates
 [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go
-[embed-code-bin]: https://github.com/SpineEventEngine/embed-code-go/tree/master/bin
+[embed-code-releases]: https://github.com/SpineEventEngine/embed-code-go/releases
 [versioning-policy]: https://github.com/SpineEventEngine/documentation/wiki/Versioning
diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md
@@ -84,18 +84,23 @@ The tool is consumed as **prebuilt binaries checked into the repository**,
 not as a Go module or downloaded artifact. The binaries live under
 `docs/_bin/`:
 
-| File                       | When it is used                                              |
-|----------------------------|--------------------------------------------------------------|
-| `embed-code-linux`         | `_script/check-samples` when `GITHUB_ACTIONS=true` (CI).     |
-| `embed-code-macos`         | `_script/check-samples` locally; `_script/embed-code` always. |
-| `embed-code-windows.exe`   | Currently not selected by either script.                     |
-
-There is no version string recorded in this repository, and the
+| File                       | When it is used                                          |
+|----------------------------|----------------------------------------------------------|
+| `embed-code-linux`         | `_script/check-samples` when `GITHUB_ACTIONS=true` (CI). |
+| `embed-code-macos`         | Both scripts on Apple silicon (arm64) Macs.              |
+| `embed-code-macos-x86_64`  | Both scripts on Intel Macs.                              |
+| `embed-code-windows.exe`   | Currently not selected by either script.                 |
+
+Outside CI, `_script/check-samples` and `_script/embed-code` pick the macOS
+binary by the host architecture reported by `uname -m`.
+
+There is no version string recorded in this repository; the tool prints
+its version when it starts (for example, `Running embed-code v1.2.5.`). The
 documentation build does *not* compile the tool. Updating to a new
-release means downloading the corresponding binaries from
-[`embed-code-go/bin`][embed-code-bin] in the upstream repository and
-replacing the files under `docs/_bin/`. The step-by-step recipe is
-"Updating `embed-code-go`" in "[Procedures](procedures.md)".
+release means downloading the corresponding assets from the upstream
+[releases][embed-code-releases] and replacing the files under `docs/_bin/`.
+The step-by-step recipe is "Updating `embed-code-go`" in
+"[Procedures](procedures.md)".
 
 ## Hugo and the Node toolchain
 
@@ -135,5 +140,5 @@ expects.
 [sidenav-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml
 [embed-code-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/_settings/embed-code.yml
 [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go
-[embed-code-bin]: https://github.com/SpineEventEngine/embed-code-go/tree/master/bin
+[embed-code-releases]: https://github.com/SpineEventEngine/embed-code-go/releases
 [hugo-install]: https://gohugo.io/installation/
diff --git a/docs/content/docs/validation/developer/testing-strategy.md b/docs/content/docs/validation/developer/testing-strategy.md
@@ -116,8 +116,7 @@ What sits where:
   test environments used across specs.
 - **`src/test/kotlin/io/spine/test/options/`** — the specs themselves, organised
   by option (`required/`, `goes/`, `setonce/`) or by cross-cutting concern
-  (`ChoiceITest.kt`, `ExternalConstraintITest.kt`,
-  `CustomOptionsLoadingITest.kt`).
+  (`ChoiceIgTest.kt`, `CustomOptionsLoadingIgTest.kt`).
 
 The framework stack is JUnit 5 plus Kotest assertions plus [Google Truth][truth]
 for the classes that already used it. Specs typically build a message, catch
@@ -229,8 +228,9 @@ peers in `:tests:validating`.
 
 A handful of conventions keep specs across the suites consistent:
 
-- **Kotest matchers**, JUnit 5 lifecycle. Specs use the `*Spec` or `*ITest`
-  naming convention; pick the suffix the surrounding directory already uses.
+- **Kotest matchers**, JUnit 5 lifecycle. A unit-test suite for `X` is named
+  `XSpec`; an integration suite is `XIgTest`, where `Ig` stands for
+  “integration”.
 - **Parameterised tests** with `@MethodSource` for per-field-type matrices. The
   built-in option specs in `:tests:validating` and `:tests:runtime` use this
   pattern liberally; copy it rather than handwriting per-type test methods.

diff --git a/docs/content/docs/validation/developer/validation-model.md b/docs/content/docs/validation/developer/validation-model.md
@@ -153,6 +153,7 @@ and is implemented in Kotlin as a `View`:
 ```protobuf
 message RequiredField {
     option (entity).kind = PROJECTION;
+    option (is).java_type = "FieldView";
 
     compiler.FieldRef id = 1;
 

diff --git a/docs/content/docs/validation/user/01-getting-started/adding-to-build.md b/docs/content/docs/validation/user/01-getting-started/adding-to-build.md
@@ -90,7 +90,7 @@ Add the Validation plugin to the build.
 ```kotlin
 plugins {
     module
-    id("io.spine.validation") version "2.0.0-SNAPSHOT.462"
+    id("io.spine.validation") version "2.0.0-SNAPSHOT.467"
 }
 ```
 
@@ -120,7 +120,7 @@ adding Validation directly. CoreJvm brings in the Validation Gradle plugin for y
 ```kotlin
 plugins {
     module
-    id("io.spine.core-jvm") version "2.0.0-SNAPSHOT.080"
+    id("io.spine.core-jvm") version "2.0.0-SNAPSHOT.097"
 }
 ```