Docs cleanup: remove orphaned summaries, fix changelog org links, and align API spec docs

.github/workflows/protect-changelog.yml

@@ -25,3 +25,21 @@ jobs:
           echo "It is auto-generated by git-cliff on release."
           echo "Remove the CHANGELOG.md change from this PR."
           exit 1
+
+      # Guard against changelog links drifting to a defunct GitHub org after a
+      # repo transfer. The canonical remote is solutions-plug/predictIQ; any
+      # other org (e.g. the legacy popsman01) must never appear in generated
+      # compare/commit/issue links. See cliff.toml for the git-cliff remote
+      # configuration that produces these links.
+      - name: Fail if CHANGELOG.md links point to a non-canonical org
+        if: |
+          !(github.actor == 'github-actions[bot]' &&
+            startsWith(github.head_ref, 'changelog-update/'))
+        run: |
+          if grep -nE 'github\.com/(popsman01)/predictIQ' CHANGELOG.md; then
+            echo "❌ CHANGELOG.md contains links to a defunct GitHub org."
+            echo "Expected org: solutions-plug (see cliff.toml remote config)."
+            echo "Regenerate the changelog with git-cliff so links use the canonical remote."
+            exit 1
+          fi
+          echo "✅ CHANGELOG.md links use the canonical org."

API_SPEC.md

@@ -23,6 +23,9 @@ Clients should monitor these headers and migrate before the sunset date.
 Deprecated versions are supported for a minimum of **12 months** after the deprecation
 announcement before being removed.
 
+For the authoritative versioning and deprecation policy — including current sunset
+dates and the version roadmap — see [`docs/api-versioning.md`](docs/api-versioning.md).
+
 ## Table of Contents
 
 - [Overview](#overview)
@@ -40,25 +43,6 @@ announcement before being removed.
 http://0.0.0.0:8080
 ```
 
-### API Versioning
-
-The API uses URL path versioning (`/api/v1/`). The current stable version is **v1**.
-
-Clients may also send an `API-Version` header (e.g. `API-Version: v1`) to explicitly
-declare the version they target. If omitted, the server defaults to the current version.
-
-### Deprecation Policy
-
-When a version is deprecated:
-- Responses will include a `Deprecation` header set to `true`.
-- A `Sunset` header will indicate the date after which the version will be removed.
-- A `Link` header will point to migration documentation.
-
-Clients should monitor these headers and migrate before the sunset date.
-
-Deprecated versions are supported for a minimum of **12 months** after the deprecation
-announcement before being removed.
-
 ## Authentication
 
 The API uses Bearer token authentication. Include your API key in the `Authorization` header:

cliff.toml

@@ -1,3 +1,14 @@
+# Changelog configuration for git-cliff.
+#
+# IMPORTANT: The canonical repository is https://github.com/solutions-plug/predictIQ
+# The `remote` below MUST point at the `solutions-plug` org. If the repo is ever
+# transferred again, update this value (and regenerate CHANGELOG.md) so that
+# compare/commit/issue links do not silently drift to a defunct org.
+
+[remote.github]
+owner = "solutions-plug"
+repo = "predictIQ"
+
 [changelog]
 header = """
 # Changelog

docs/api-versioning.md

@@ -94,3 +94,7 @@ Unsupported versions are ignored and the server falls back to the default versio
 
 - `services/api/src/versioning.rs` — sunset header injection middleware
 - `API_SPEC.md` — full endpoint reference
+
+---
+
+> **Single source of truth:** This document is the canonical reference for API versioning, sunset dates, and the v2 roadmap. `API_SPEC.md` links here rather than restating version status or sunset dates, so update versioning details only in this file.