From 59e2e05e8376cbacb8fe77900906b10c5158a6c1 Mon Sep 17 00:00:00 2001
From: nfebe <fenn25.fn@gmail.com>
Date: Wed, 9 Sep 2026 00:06:09 +0100
Subject: [PATCH] docs: Move versioning guidance out of the readme

---
 .github/workflows/validate-docs.yml | 17 +++++++++++++++++
 README.md                           | 10 ----------
 docs.json                           | 14 ++++++++++++++
 docs/versioning.md                  | 13 +++++++++++++
 4 files changed, 44 insertions(+), 10 deletions(-)
 create mode 100644 .github/workflows/validate-docs.yml
 create mode 100644 docs.json
 create mode 100644 docs/versioning.md

diff --git a/.github/workflows/validate-docs.yml b/.github/workflows/validate-docs.yml
new file mode 100644
index 0000000..c917178
--- /dev/null
+++ b/.github/workflows/validate-docs.yml
@@ -0,0 +1,17 @@
+name: Validate Docs
+
+on:
+  push:
+    paths: ['docs/**', 'docs.json', '.github/workflows/validate-docs.yml']
+  pull_request:
+    paths: ['docs/**', 'docs.json', '.github/workflows/validate-docs.yml']
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: whilesmart/docs-kit/.github/actions/validate-docs@main
diff --git a/README.md b/README.md
index 6ecfaf9..862f1fd 100644
--- a/README.md
+++ b/README.md
@@ -94,13 +94,3 @@ make build
 ## Licence
 
 MIT.
-
-## Versioning
-
-The CLI is versioned independently of the core, agent, and design package. A CLI release does not require matching releases of the components it installs. Use `--core-version` and `--agent-version` to select them separately, or `--image` and `--from` to choose the core directly.
-
-CLI `1.0.0-beta.3` requires agent `1.0.0-beta.3` for `sourceant stop`. The agent defines core compatibility. For a reproducible setup, select both explicitly:
-
-```bash
-sourceant setup --agent-version 1.0.0-beta.3 --core-version 1.0.0-beta.2
-```
diff --git a/docs.json b/docs.json
new file mode 100644
index 0000000..aa24bcd
--- /dev/null
+++ b/docs.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/whilesmart/docs-kit/main/schema/docs.schema.json",
+  "name": "SourceAnt CLI",
+  "description": "Install and control the local SourceAnt stack.",
+  "category": {
+    "language": "go"
+  },
+  "sidebar": [
+    {
+      "title": "Versions",
+      "path": "docs/versioning.md"
+    }
+  ]
+}
diff --git a/docs/versioning.md b/docs/versioning.md
new file mode 100644
index 0000000..3d691bb
--- /dev/null
+++ b/docs/versioning.md
@@ -0,0 +1,13 @@
+# Versions
+
+The CLI, agent, and core are versioned independently.
+
+Select the agent and core releases during setup:
+
+```bash
+sourceant setup --agent-version 1.0.0-beta.3 --core-version 1.0.0-beta.2
+```
+
+Use `--image` for a specific core container or `--from` for a Python installation source.
+
+CLI `1.0.0-beta.3` needs agent `1.0.0-beta.3` for `sourceant stop`. The agent defines core compatibility.