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

[brunopgalvao]

Summary

Pilot adoption of the agent-loadable PaperMoon documentation styleguide, so coding agents (Claude Code, Cursor, Codex, etc.) authoring documentation in this repo apply the PaperMoon rules during generation instead of waiting for reviewers to flag them.

Styleguide source (public): papermoonio/documentation-style-guide#6.

Why

Across recent AI-assisted documentation PRs in this repo, the same reviewer corrections kept recurring:

• List item punctuation inconsistency (e.g., Add Bulletin Chain data storage reference and tutorial #1575 PR-level review: "Lists for the most part aren't being properly formatted and some unnecessary bold usage").
• Bold used for emphasis in prose.
• Backticks dropped on the 2nd/3rd mention of a code identifier (e.g., Fix Staking Operator Proxy setup flow #1586: "StakingOperator, it should be in backticks here?").
• Identifier and term casing drift within a single page (e.g., Fix Staking Operator Proxy setup flow #1586: "at line 90 you are using stakingRcClient.purge_keys, here purgeKeys. Worth using purgeKeys everywhere").
• Image filenames missing the <filename>-<number>.webp convention (e.g., Add Bulletin Chain data storage reference and tutorial #1575 CHANGES_REQUESTED).
• Subheadings inserted above lists that already have a lead-in sentence (e.g., Add Bulletin Chain data storage reference and tutorial #1575: "I'd remove this sub-title since above you are saying 'the following extrinsics:'").
• Description-list format applied to one bullet but not the rest (e.g., Add Bulletin Chain data storage reference and tutorial #1575: "Pls update rest of list items to use this same format").

These all map to rules in the PaperMoon styleguide — they recur because the styleguide has no in-repo presence agents can load.

Architecture — single source of truth

PaperMoon's Vale rules and vocab are not copied into this repo. They are pulled from papermoonio/documentation-style-guide on every CI run, and on demand for local linting.

Layer	Lives in	How it gets here
PaperMoon house-style rules (styles/PaperMoon/*.yml) and the PaperMoon vocab (styles/config/vocabularies/PaperMoon/)	The canonical styleguide repo (single source of truth)	scripts/sync-styleguide-vale.sh clones the repo and copies the files into local styles/. The synced directories are gitignored — never committed back.
Project-specific Polkadot vocab (styles/config/vocabularies/Polkadot/)	This repo	Committed normally. Contains ecosystem terms the canonical vocab intentionally does not carry (Polkadot, Kusama, Paseo, parachain, collator, XCM, etc.).
Project-specific config / overrides (.vale.ini, project notes in AGENTS.md)	This repo	Committed normally.
CI runner (.github/workflows/vale.yml)	This repo	Runs the sync step first, then Vale on changed markdown files via reviewdog.

How it changes the authoring workflow

Before: agents author docs with no PaperMoon context. Reviewers manually catch the recurring patterns. Same corrections appear on every PR.

After:

• Agents read AGENTS.md at session start, load the canonical rules from the styleguide repo, apply them at generation time.
• Vale CI catches anything the agent missed before review. The lint rules always reflect the latest canonical styleguide — no manual sync.
• Reviewers focus on technical accuracy instead of formatting friction.

Local dev

./scripts/sync-styleguide-vale.sh   # pull canonical rules + vocab
vale .                              # lint

Re-run the sync script any time the canonical styleguide updates.

Spelling is intentionally disabled

Vale.Spelling (Hunspell) is turned off in .vale.ini (Vale.Spelling = NO). This PR enforces house style — list punctuation, bold usage, backticks, casing, image filenames — not spelling. The spell-checker arrived for free with the base Vale style and, on a deeply technical docs repo, flags an endless tail of valid tool and package names (npm, dev, toolchain, Turbopack, etc.) with no typo-catching benefit worth the ongoing vocab-curation toil.

The curated PaperMoon house-style rules plus Vale.Repetition and Vale.Terms remain enabled. Tradeoff: genuine typos in prose are no longer caught by Vale and rely on review.

[eshaben]

This looks fine to me, but the part I am concerned about is that it runs automatically on every PR, and whenever subsequent commits are made to an open PR.

For a trip down memory lane, this was back when we used Vale before: #38 - 25 comments first round, 11 2nd round, 6 3rd round, 1 4th round... a comment about false positives.

Maybe it's more practical to use it now since the scope is a bit more limited, but fair warning that it generates a lot of noise, and previously the benefit wasn't worth it 🤷‍♀️

I'll approve it, but I think @nhussein11 if you're not fully aware of this, please check it out. I'll leave it up to you guys to decide if you want to go down this road again or maybe even consider taking a different approach on when and how frequently it runs... whatever you guys think.

[brunopgalvao]

@eshaben thanks for the history — that #38 thread (25 → 11 → 6 → 1 comments + false-positive fatigue) is exactly the failure mode to avoid. I've tuned this run specifically so it doesn't repeat it:

Why this shouldn't be a #38 redux:

• filter_mode: added — Vale only annotates lines added in the diff, never pre-existing prose. The "25 comments on old text" problem can't occur.
• It lints only changed *.md files, not the whole repo.
• Vale.Spelling is now disabled — that was the single biggest false-positive source (it was flagging valid terms like npm, toolchain, Turbopack). What's left is a small curated house-style rule set (lists, bold, backticks, casing, link text, etc.).

Changes I just pushed to address the "when/how often it runs" concern:

• Non-blocking: fail_on_error: false — Vale never blocks merge.
• Checks tab, not inline: reporter: github-pr-check — findings show as a check run, not inline review comments. No comment spam.
• Kept per-commit runs on purpose: if it only ran on open/ready, a contributor who pushes a fix (or adds content after marking ready) would get no updated signal. Since it's now advisory + in the Checks tab, re-running per commit is cheap and keeps the status accurate without adding noise.

So it's now an advisory signal authors can glance at, not a gate. Happy to dial it further (warning-only level, manual trigger, etc.) — leaving the final call to you and @nhussein11 as you suggested.