Add docs-sync workflow and transform tools

.github/workflows/docs-sync.yml

@@ -0,0 +1,142 @@
+name: Docs Sync → cosmos/docs
+
+# Runs when docs/ files change on main.
+# Transforms .md → .mdx and opens a PR on the docs site repo.
+# If a sync PR is already open, updates it instead of opening a new one.
+# Skip if the commit was itself produced by the sync (loop guard).
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+
+jobs:
+  sync:
+    name: Sync docs to cosmos/docs
+    runs-on: ubuntu-latest
+    # Loop guard: skip commits that the docs-sync bot created
+    if: "!contains(github.event.head_commit.message, '[docs-sync]')"
+
+    steps:
+      - name: Checkout example repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Checkout cosmos/docs
+        uses: actions/checkout@v4
+        with:
+          repository: cosmos/docs
+          # Fine-grained PAT with contents:write and pull-requests:write on cosmos/docs
+          token: ${{ secrets.DOCS_REPO_TOKEN }}
+          path: cosmos-docs
+
+      - name: Transform docs → Mintlify format
+        run: |
+          python3 scripts/docs-sync/transform.py \
+            --direction to-mintlify \
+            --input docs/ \
+            --output-dir cosmos-docs/sdk/next/tutorials/example/
+
+      - name: Check for changes
+        id: diff
+        run: |
+          cd cosmos-docs
+          git diff --quiet && echo "changed=false" >> "$GITHUB_OUTPUT" || echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Open or update PR on cosmos/docs
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }}
+        run: |
+          cd cosmos-docs
+
+          git config user.name  "docs-sync[bot]"
+          git config user.email "docs-sync[bot]@users.noreply.github.com"
+
+          # Check for an existing open sync PR
+          EXISTING=$(gh pr list \
+            --repo cosmos/docs \
+            --label "docs-sync" \
+            --state open \
+            --json number,headRefName \
+            --jq '.[0]')
+
+          if [ -n "$EXISTING" ]; then
+            PR_NUMBER=$(echo "$EXISTING" | jq -r '.number')
+            BRANCH=$(echo "$EXISTING" | jq -r '.headRefName')
+
+            # Update the existing branch
+            git fetch origin "$BRANCH"
+            git checkout "$BRANCH"
+            git add sdk/next/tutorials/example/
+            git commit -m "docs: sync example tutorials from cosmos/example [docs-sync]
+
+Auto-synced from cosmos/example@${{ github.sha }}
+Source commit: ${{ github.event.head_commit.message }}"
+            git push origin "$BRANCH"
+
+            gh pr comment "$PR_NUMBER" \
+              --repo cosmos/docs \
+              --body "$(cat <<'EOF'
+## Sync updated
+
+A new commit was pushed to **cosmos/example** before this PR was merged. This PR's branch has been updated with the latest changes.
+
+**New commit:** ${{ github.sha }}
+**Triggered by:** ${{ github.event.head_commit.message }}
+
+Please re-review the diff before merging.
+
+🤖 docs-sync bot
+EOF
+)"
+            echo "Updated existing PR #$PR_NUMBER"
+
+          else
+            # No existing PR — create a new branch and open one
+            BRANCH="docs-sync/example-$(date +%Y%m%d-%H%M%S)"
+            git checkout -b "$BRANCH"
+            git add sdk/next/tutorials/example/
+            git commit -m "docs: sync example tutorials from cosmos/example [docs-sync]
+
+Auto-synced from cosmos/example@${{ github.sha }}
+Source commit: ${{ github.event.head_commit.message }}"
+            git push origin "$BRANCH"
+
+            gh pr create \
+              --repo cosmos/docs \
+              --head "$BRANCH" \
+              --base main \
+              --title "docs: sync example tutorials from cosmos/example" \
+              --label "docs-sync" \
+              --body "$(cat <<'EOF'
+## Automated docs sync
+
+This PR was auto-generated by the [docs-sync workflow](https://github.com/cosmos/example/blob/main/.github/workflows/docs-sync.yml) in **cosmos/example**.
+
+**Source commit:** ${{ github.sha }}
+**Triggered by:** ${{ github.event.head_commit.message }}
+
+### What changed
+Transformed \`docs/*.md\` → \`sdk/next/tutorials/example/*.mdx\`:
+- Stripped \`# H1\` headings → YAML frontmatter
+- Rewrote \`https://docs.cosmos.network/...\` links → relative paths
+- Renamed \`.md\` extensions → \`.mdx\`
+
+### Review checklist
+- [ ] Mintlify frontmatter looks correct
+- [ ] Links render correctly in preview
+- [ ] Navigation in \`docs.json\` is up to date
+
+> **Do not edit these files directly** — edit the source in cosmos/example and let the sync bot update them. Changes made here will be synced back automatically.
+
+🤖 Generated by docs-sync bot
+EOF
+)"
+          fi

CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this repository are tracked here for agent context.
+
+## [Unreleased]
+
+### Docs Changes
+
+- Renamed tutorial docs to `NN-name.md` format (`01-prerequisites.md` through `05-run-and-test.md`), added `00-overview.md` intro page
+- `02-quickstart.md`: rewrote opening paragraph, added Mintlify Note callout linking to prerequisites
+- `03-build-a-module.md`: replaced blockquote prerequisite notice with Mintlify Note callout; added links to SDK concept docs throughout (modules, transactions, encoding, keeper, app.go, etc.)
+- `04-counter-walkthrough.md`: added anchor links in feature comparison table; added Gas section covering `minimum-gas-prices` in `app.toml`; linked repo in branch switch instruction; removed stale to-do comment
+- `05-run-and-test.md`: added Node Configuration section covering `app.toml` and `config.toml` with key settings tables
+- `01-prerequisites.md`: updated Go version output to show both Linux and macOS variants; updated Make install instructions to cover both platforms
+- Verified `make install` builds successfully on Linux via Docker `golang:1.25` container
+
+### CLAUDE.md Changes
+
+- Added Changelog Policy section requiring changelog updates after every change
+
+---
+
+## [2026-03-18] — Docs sync system + file renames
+
+Branch: `feat/docs-sync` (in `cosmos/example`), `feat/example-tutorial-sync` (in `cosmos/docs`)
+
+### example repo changes
+- Renamed all 5 tutorial docs to drop the `tutorial-NN-` prefix:
+  - `tutorial-00-prerequisites.md` → `prerequisites.md`
+  - `tutorial-01-quickstart.md` → `quickstart.md`
+  - `tutorial-02-build-a-module.md` → `build-a-module.md`
+  - `tutorial-03-counter-walkthrough.md` → `counter-walkthrough.md`
+  - `tutorial-04-run-and-test.md` → `run-and-test.md`
+- Updated all internal cross-links between tutorial files to use new names
+- Added `scripts/docs-sync/transform.py` — bidirectional transform between `.md` and Mintlify `.mdx` format (H1 ↔ frontmatter, absolute ↔ relative links, `.md` ↔ `.mdx` extensions)
+- Added `scripts/docs-sync/test_transform.py` — 25 unit + round-trip tests (all passing)
+- Added `.github/workflows/docs-sync.yml` — GitHub Action that auto-opens PRs on `cosmos/docs` when `docs/**` changes on `main`
+
+### cosmos/docs repo changes
+- Fixed typo: `prerequisits.mdx` → `prerequisites.mdx`
+- Added 5 new `.mdx` files in `sdk/next/tutorials/example/` (transformed from `docs/*.md`)
+- Added `Build a Chain` group to `docs.json` navigation under `sdk/next` How-to Guides
+- Added `.github/workflows/docs-sync-to-example.yml` — reverse sync action that opens PRs on `cosmos/example` when tutorial `.mdx` files change
+
+### Setup required (one-time)
+- Add secret `DOCS_REPO_TOKEN` to `cosmos/example` (PAT: `contents:write` + `pull-requests:write` on `cosmos/docs`)
+- Add secret `EXAMPLE_REPO_TOKEN` to `cosmos/docs` (PAT: `contents:write` + `pull-requests:write` on `cosmos/example`)
+
+---
+
+## [2026-03-18] — Initial setup
+
+- Added `CLAUDE.md` to document repo purpose, branch strategy, docs policy, and module architecture for future agents.
+- Added `CHANGELOG.md` (this file) to track changes over time.
+
+---
+
+## Format
+
+Each entry should follow:
+
+```
+## [YYYY-MM-DD] — Short description
+
+- What changed and why
+- Docs site impact (if any)
+- Branch(es) affected
+```