feat: add changelog verification script and CI workflow

.changelog/unreleased/537-dx-025-verify-release-tags.md

@@ -0,0 +1,7 @@
+---
+type: added
+area: ci
+pr: 537
+breaking: false
+---
+Added CI release workflow that verifies changelog state and publishes GitHub Releases on release tags.

.changelog/unreleased/538-docs-workspace.md

@@ -1,7 +1,7 @@
 ---
-title: Scaffold docs workspace
-category: docs
+type: added
+area: docs
+pr: 538
+breaking: false
 ---
-
-Adds the initial `apps/docs` workspace, content validation command, keyboard
-shortcut shell, and accessibility coverage for representative docs states.
+Added the initial docs workspace, content validation command, keyboard shortcut shell, and accessibility coverage for representative docs states.

.changelog/unreleased/544-dx-032-toc-scroll-spy.md

@@ -0,0 +1,7 @@
+---
+type: added
+area: docs
+pr: 544
+breaking: false
+---
+Added on-page table of contents with scroll-spy and heading focus navigation to the documentation site.

.changelog/unreleased/557-dx-045-edit-page-and-freshness.md

@@ -0,0 +1,7 @@
+---
+type: added
+area: docs
+pr: 557
+breaking: false
+---
+Added GitHub edit links, relative updated dates, and commit-date freshness validation to documentation pages.

.changelog/unreleased/558-dx-046-sitemap-and-robots.md

@@ -0,0 +1,7 @@
+---
+type: added
+area: docs
+pr: 558
+breaking: false
+---
+Generated sitemap.xml and robots.txt with canonical link tags during the documentation build.

.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    name: Verify & Publish Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      # Quality Gate from AGENTS.md §1
+      - name: Lint
+        run: bun lint
+
+      - name: Typecheck
+        run: bun typecheck
+
+      - name: Design token check
+        run: bun run check:tokens
+
+      - name: Documentation content and prose checks
+        run: bun run check:content && bun run --cwd apps/docs lint:prose
+
+      - name: Documentation link and FAQ drift checks
+        run: bun run check:links && bun run --cwd apps/docs check:faq
+
+      - name: Documentation generated-reference drift checks
+        run: bun run --cwd apps/docs check:tokens:generated && bun run --cwd apps/docs check:errors:generated
+
+      - name: Test
+        run: bun run test
+
+      - name: Coverage
+        run: bun run test:coverage
+
+      - name: Build
+        run: bun run build
+
+      # Release verification assertions & note extraction
+      - name: Verify release tag and changelog
+        run: bun run scripts/changelog/verify-tag.ts --tag "${{ github.ref_name }}" --output-notes /tmp/release-notes.md
+
+      # Publish GitHub Release (never pushes a commit back)
+      - name: Publish GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --notes-file /tmp/release-notes.md

CONTRIBUTING.md

@@ -16,6 +16,8 @@ quality bar every change must clear, and how to get a pull request merged.
 - [The quality gate](#the-quality-gate)
 - [Development workflow](#development-workflow)
 - [Fixing issues properly](#fixing-issues-properly)
+- [Changelog entries](#changelog-entries)
+- [Release procedure](#release-procedure)
 - [Commit conventions](#commit-conventions)
 - [Pull requests](#pull-requests)
 - [Project-specific gotchas](#project-specific-gotchas)
@@ -252,6 +254,46 @@ Run `bun run changelog:validate` before committing to catch formatting errors.
 
 ---
 
+## Release procedure
+
+SO4 Market uses tag-driven release automation with CI verification (DX-025).
+
+CI **verifies** release readiness; it **never writes** back to `main`. The release process is kept entirely in reviewed PRs:
+
+1. **Cut the release in a PR**:
+   Run the release command with the target SemVer version:
+   ```bash
+   bun run changelog:release 0.2.0
+   ```
+   This command:
+   - Validates all pending entry files in `.changelog/unreleased/`.
+   - Aggregates them into a new `## [0.2.0] - YYYY-MM-DD` section in `CHANGELOG.md`.
+   - Clears consumed entry files from `.changelog/unreleased/`.
+   - Updates compare links at the bottom of `CHANGELOG.md`.
+
+2. **Open, review, and merge the PR**:
+   Submit the release PR targeting `main`. Run the full quality gate. Once approved and CI is green, merge to `main`.
+
+3. **Tag the release on `main`**:
+   After merging, pull the latest `main` and push an annotated git tag matching the release version:
+   ```bash
+   git checkout main
+   git pull upstream main
+   git tag -a v0.2.0 -m "Release v0.2.0"
+   git push upstream v0.2.0
+   ```
+
+4. **CI Release Workflow (`.github/workflows/release.yml`)**:
+   On push of any `v*` tag, CI:
+   - Runs the full quality gate (`AGENTS.md` §1).
+   - Asserts `.changelog/unreleased/` is empty.
+   - Asserts `CHANGELOG.md` contains a release section matching the version in the tag.
+   - Asserts the release date in `CHANGELOG.md` is within 1 day of the tag date.
+   - Extracts the release section notes and creates a GitHub Release for the tag.
+   - Never pushes commits to any branch.
+
+---
+
 ## Commit conventions
 
 We follow [Conventional Commits](https://www.conventionalcommits.org/):

apps/docs/content/concepts/liquidation.mdx

@@ -1,7 +1,7 @@
 ---
 title: Liquidation
 description: How maintenance margin and changing position value determine whether a leveraged position may be liquidated.
-updated: 2026-08-24
+updated: 2026-08-25
 status: stable
 ---
 

apps/docs/content/guides/troubleshooting.mdx

@@ -76,7 +76,7 @@ Likely causes, in order:
 3. **The transaction that would have created it failed.** Check `TxStatus` for a failure state and the message against [/reference/errors](/reference/errors) — a position that never opened has nothing to display.
 
 **Checks:**
-- Confirm the transaction hash on Stellar Expert actually invoked `exchange-router` successfully.
+- Confirm the transaction hash on Stellar Expert actually invoked `ExchangeRouter` successfully.
 - Check the orders list for a pending order with the same parameters.
 - Confirm you're on the same network and market you traded on.
 

apps/docs/content/reference/glossary.mdx

@@ -1,7 +1,7 @@
 ---
 title: Glossary
 description: Alphabetical definitions linking perpetual-markets and Stellar or Soroban terms to their detailed documentation.
-updated: 2026-08-24
+updated: 2026-08-25
 status: stable
 ---
 

apps/docs/content/resources/changelog.mdx

@@ -1,7 +1,7 @@
 ---
 title: Changelog
 description: How documentation updates relate to the product release history published on the SO4 interface.
-updated: 2026-08-24
+updated: 2026-08-25
 status: stable
 ---
 

apps/docs/content/resources/faq.mdx

@@ -1,7 +1,7 @@
 ---
 title: Frequently asked questions
 description: Short answers to common SO4 trading, custody, fees, liquidation, wallet, and availability questions.
-updated: 2026-08-24
+updated: 2026-08-25
 status: stable
 landing: [what-is-so4, self-custody, liquidation, fees, availability]
 ---

apps/docs/content/resources/roadmap.mdx

@@ -1,7 +1,7 @@
 ---
 title: Roadmap
 description: The current status of shipped and planned SO4 interface, protocol, and documentation work.
-updated: 2026-08-24
+updated: 2026-08-25
 status: stable
 ---
 

apps/docs/package.json

@@ -10,8 +10,8 @@
     "lint:prose": "bun run scripts/lint-prose.ts",
     "format": "prettier --write \"content/**/*.mdx\" \"scripts/**/*.ts\" \"src/**/*.{ts,tsx}\"",
     "typecheck": "tsc --noEmit",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage",
+    "test": "vitest run && bun test scripts/content-loader.test.ts scripts/content.test.ts scripts/frontmatter.test.ts scripts/generate-graphql.test.ts scripts/image-pipeline.test.ts scripts/lint-prose.test.ts scripts/nav-builder.test.ts scripts/seo.test.ts scripts/shiki.test.ts scripts/sitemap.test.ts",
+    "test:coverage": "vitest run --coverage",
     "check:content": "bun run scripts/check-content.ts",
     "check:links": "bun run scripts/check-links.ts",
     "generate:faq": "bun run scripts/generate-faq.ts",
@@ -38,14 +38,21 @@
     "@repo/vitest-config": "workspace:*",
     "@shikijs/rehype": "^4.4.3",
     "@shikijs/transformers": "^4.4.3",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/bun": "^1.3.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "@vitest/expect": "^3.2.7",
+    "vitest": "3",
+    "vitest-axe": "^0.1.0",
     "@types/mdx": "^2.0.14",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "h3": "^2.0.1-rc.29",
     "happy-dom": "^20.11.6",
     "jsdom": "^30.0.1",
+    "msw": "^2.12.12",
     "nitro": "^3.0.260610-beta",
     "pagefind": "^1.5.2",
     "prettier": "^3.8.1",
@@ -55,6 +62,7 @@
     "shiki": "^4.4.3",
     "tailwindcss": "^4.1.18",
     "typescript": "^5.9.3",
-    "vite": "^7.3.2"
+    "vite": "^7.3.2",
+    "vite-tsconfig-paths": "^5.1.4"
   }
 }

apps/docs/public/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+Sitemap: https://docs.so4.market/sitemap.xml

apps/docs/public/sitemap.xml

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://docs.so4.market/</loc>
+    <lastmod>2026-08-28</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/concepts/funding-and-fees</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/concepts/liquidation</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/concepts/risk</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/architecture</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/contract-clients</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/design-system</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/indexer</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/json-feed</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/local-setup</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/reading-data</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/developers/writing-transactions</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/get-started/introduction</loc>
+    <lastmod>2026-08-30</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/get-started/quickstart</loc>
+    <lastmod>2026-08-30</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/guides/troubleshooting</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/contracts.generated</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/data-store</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/errors</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/exchange-router</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/glossary</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/order-vault</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/synthetics-reader</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/reference/tokens.generated</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/resources/changelog</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/resources/faq</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/resources/roadmap</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+  <url>
+    <loc>https://docs.so4.market/resources/security</loc>
+    <lastmod>2026-08-25</lastmod>
+  </url>
+</urlset>