docs: adopt PaperMoon styleguide via AGENTS.md + Vale lint

.github/scripts/sync-styleguide-vale.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Sync canonical Vale rules and the PaperMoon vocab from the
+# papermoonio/documentation-style-guide repository into this repo's
+# styles/ directory. The synced files are gitignored — the canonical
+# repo is the single source of truth.
+#
+# Usage:
+#   ./.github/scripts/sync-styleguide-vale.sh           # sync from main
+#   ./.github/scripts/sync-styleguide-vale.sh <ref>     # sync from a branch, tag, or sha
+#
+# Project-specific vocab (styles/config/vocabularies/Polkadot/) is
+# managed in this repo and is NOT overwritten.
+
+set -euo pipefail
+
+REPO=papermoonio/documentation-style-guide
+REF=${1:-main}
+
+repo_root=$(git rev-parse --show-toplevel)
+cd "$repo_root"
+
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+
+echo "Cloning $REPO@$REF..."
+git clone --depth=1 --branch="$REF" --quiet "https://github.com/$REPO" "$tmpdir/styleguide"
+
+mkdir -p styles/PaperMoon styles/config/vocabularies/PaperMoon
+
+cp "$tmpdir/styleguide"/styles/PaperMoon/*.yml styles/PaperMoon/
+cp "$tmpdir/styleguide"/styles/config/vocabularies/PaperMoon/accept.txt \
+   styles/config/vocabularies/PaperMoon/accept.txt
+
+echo "Synced Vale rules and PaperMoon vocab from $REPO@$REF."
+echo "Run 'vale .' to lint."

.github/workflows/vale.yml

@@ -0,0 +1,48 @@
+name: Vale style check
+
+on:
+  pull_request:
+    paths:
+      - "**.md"
+      - ".vale.ini"
+      - "styles/config/vocabularies/Polkadot/**"
+      - ".github/scripts/sync-styleguide-vale.sh"
+      - ".github/workflows/vale.yml"
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: read
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Sync canonical Vale rules from the PaperMoon styleguide
+        run: ./.github/scripts/sync-styleguide-vale.sh
+
+      - name: List changed markdown files
+        id: changed
+        run: |
+          base="${{ github.event.pull_request.base.sha }}"
+          head="${{ github.event.pull_request.head.sha }}"
+          files=$(git diff --name-only --diff-filter=AM "$base...$head" -- '*.md' | tr '\n' ' ')
+          echo "files=$files" >> "$GITHUB_OUTPUT"
+          echo "Changed markdown files: $files"
+
+      - name: Run Vale on changed files
+        if: steps.changed.outputs.files != ''
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: ${{ steps.changed.outputs.files }}
+          # Advisory only: surface findings in the Checks tab without blocking
+          # merge or spamming inline review comments. Reruns on every push, so
+          # the check status always reflects the latest commit.
+          fail_on_error: false
+          reporter: github-pr-check
+          filter_mode: added
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -9,3 +9,9 @@ scripts/__pycache__/*
 
 .github/instructions/kluster-code-verify.instructions.md
 .kluster
+
+# Vale rules and vocab synced from papermoonio/documentation-style-guide
+# by .github/scripts/sync-styleguide-vale.sh (CI runs the script before linting).
+# The canonical repo is the single source of truth — never commit copies.
+styles/PaperMoon/
+styles/config/vocabularies/PaperMoon/

.vale.ini

@@ -0,0 +1,31 @@
+StylesPath = styles
+MinAlertLevel = suggestion
+Vocab = PaperMoon, Polkadot
+
+# Vale rules and the PaperMoon vocab in styles/PaperMoon/ and
+# styles/config/vocabularies/PaperMoon/ are synced from the canonical
+# papermoonio/documentation-style-guide repo and are gitignored.
+# Run `./.github/scripts/sync-styleguide-vale.sh` before linting locally;
+# CI runs the script automatically (see .github/workflows/vale.yml).
+#
+# To also lint against Google's style, run `vale sync` after adding:
+#   Packages = Google
+# then add `Google` to the BasedOnStyles list below.
+
+[*.md]
+BasedOnStyles = Vale, PaperMoon
+
+# Vale.Spelling (Hunspell) is disabled: this repo enforces house style,
+# not spelling. On a deeply technical docs repo the spell-checker flags an
+# endless tail of valid tool/package names (npm, toolchain, Turbopack, ...)
+# with no typo-catching benefit worth the vocab-curation toil. The curated
+# PaperMoon house-style rules and Vale.Repetition/Vale.Terms stay enabled.
+Vale.Spelling = NO
+
+TokenIgnores = (?:dApp|TestNet|MainNet|ERC-\d+|JSON-RPC)
+BlockIgnores = (?s) *(```.*?```)
+
+# AGENTS.md describes the rules and references banned content by name;
+# it is not subject to its own rules.
+[AGENTS.md]
+BasedOnStyles =

AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md — polkadot-docs
+
+This file is loaded automatically by coding agents (Claude Code, Cursor, Codex, and any tool that respects the `AGENTS.md` convention) when they open this repository. Read it before generating or editing any documentation.
+
+## Style and authoring rules
+
+Documentation in this repository follows the **PaperMoon Documentation Style Guide**. The agent-loadable rule set lives in a separate repository so it can be shared across customers and updated independently:
+
+- **Canonical source**: [`papermoonio/documentation-style-guide/AGENTS.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/AGENTS.md)
+- **Prose reference**: [`papermoonio/documentation-style-guide/style-guide.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md)
+- **Reviewer checklist**: [`papermoonio/documentation-style-guide/checklist.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/checklist.md)
+
+**Read the canonical `AGENTS.md` before authoring.** It front-loads the rules that AI-generated documentation most often violates — list punctuation, bold misuse, em dashes, banned phrases, terminology, code-identifier backticks, identifier consistency, image filenames, and the "no redundant subheadings above lead-in lists" rule. The pre-output checklist at the bottom of that file is the last thing to run before returning a draft.
+
+## Linting
+
+Vale rules and the PaperMoon vocab are not copied into this repo — they are pulled from the canonical [`papermoonio/documentation-style-guide`](https://github.com/papermoonio/documentation-style-guide) repo on every CI run, and on demand for local linting. The single source of truth is the styleguide repo.
+
+```bash
+./.github/scripts/sync-styleguide-vale.sh   # pull canonical Vale rules + PaperMoon vocab
+vale .                              # lint
+```
+
+The `styles/PaperMoon/` and `styles/config/vocabularies/PaperMoon/` directories are gitignored. Project-specific vocab lives in `styles/config/vocabularies/Polkadot/` and is committed.
+
+CI runs the sync script and then Vale against changed markdown files on every pull request (see `.github/workflows/vale.yml`).
+
+## Project-specific rules
+
+These supplement (and where they conflict, override) the canonical styleguide:
+
+- **Customer override on heading case**: This site uses Chicago title case per the styleguide default.
+- **External links open in a new tab**: this is handled by the MkDocs plugin configured for this site. Do not add `{target=\_blank}` manually — the canonical styleguide also drops the manual rule.
+- **Snippet includes**: Reusable code lives in `.snippets/code/` and is included via `--8<-- 'code/path/to/file.ext'`. Do not inline code that already exists as a snippet.
+- **Variables**: `variables.yml` at the repo root holds shared version pins and identifiers. Reference via `{{ variable_name }}`.
+
+## Precedence
+
+When rules conflict:
+
+1. **This file** (`polkadot-docs/AGENTS.md`) — project-specific overrides win.
+2. **PaperMoon canonical styleguide** — default.
+3. **Google developer documentation style guide** — fallback for anything the PaperMoon guide does not cover.
+
+## How to use this in an agent session
+
+A typical session opens by reading this file, then fetching the canonical styleguide rules (the file at the GitHub URL above, or a local clone if present). Apply the rules during generation, not just at review time. Run the pre-output checklist from the canonical `AGENTS.md` before returning a draft.

styles/config/vocabularies/Polkadot/accept.txt

@@ -0,0 +1,39 @@
+Polkadot
+Kusama
+Paseo
+Westend
+Moonbeam
+Moonriver
+Moonbase
+parachain
+parachains
+parathread
+parathreads
+relay chain
+relaychain
+Substrate
+collator
+collators
+nominator
+nominators
+validator
+validators
+extrinsic
+extrinsics
+pallet
+pallets
+runtime
+runtimes
+XCM
+SDK
+SS58
+Subxt
+Dedot
+Chopsticks
+PAPI
+Polkadot.js
+omninode
+Zombienet
+Bulletin
+ink
+ScaleCodec