Align style guide with AI-assisted authoring workflow

[brunopgalvao]

Summary

This is a draft that rewrites the PaperMoon style guide so it's loadable, enforceable, and unambiguous for AI-assisted authoring workflows — and reduces the manual review friction the team has been seeing on AI-generated PRs.

The intent is to keep the existing substance, make ambiguous rules concrete, fold in the patterns reviewers actually flag, and ship an agent-loadable companion plus a mechanical lint layer.

Keep / drop / add

Keep + improve — every existing section survives. High-friction sections were rewritten with explicit Do: / Don't: example pairs:

• List Formatting — collapses the punctuation rule to one decision ("full sentences → period, fragments → no period; all items in a list must match"), with a worked example showing both correct forms and a wrong-mixed form.
• Bold — adds explicit Don't examples for emphasis-bolding in prose; clarifies bold is only for UI elements and description-list terms.
• Terminology — promoted to a table; TestNet / MainNet (previously only in the checklist) moved into the style guide proper.
• Links — splits the {target=\_blank} rule into external vs. same-page-internal, with examples.
• Punctuation — adds an Em Dash / En Dash subsection (currently silent in the guide; common reviewer correction).
• Symbols — explicitly bans ✅ / ❌ / 🟢 / 🔴 / ⚠️ markers; standardizes on text Do: / Don't: labels.

Drop

• The 🟢 / 🔴 emoji markers in the existing variable-conventions examples — replaced with text labels, since the guide itself forbids emojis.

Add (data-driven from your last two months of PR reviews on polkadot-developers/polkadot-docs):

• AGENTS.md — agent-loadable, rule-first companion. Coding agents auto-load AGENTS.md from a repo root, so downstream docs repos that reference it get the rules applied on every authoring session. Vendor-neutral; not coupled to any specific tool.
• Banned Phrases table — explicit list of filler and LLM clichés (delve, leverage, seamless, robust, it's important to note, simply, currently, etc., and the rest).
• Code Identifiers in Prose — every function, method, type, pallet, module, variable, parameter, and file path reference must be in backticks, on every mention. (Recurring inline-review correction: 0xlukem on #1586: "StakingOperator, it should be in backticks here?")
• Identifier Consistency Within a Document — pick one form for an identifier / role and use it everywhere. (sigurpol on #1586: "at line 90 you are using stakingRcClient.purge_keys, here purgeKeys. Worth using purgeKeys everywhere.")
• Image File Naming — <topic>-<number>.webp rule made explicit. (eshaben CHANGES_REQUESTED on #1575: "the images aren't using the correct format. They should be <filename>-<number>.webp. This helps us when we do reorgs.")
• No redundant subheadings above lead-in lists — agents often insert a ### directly above a list that's already introduced by a sentence ending in :. Reviewers strip them. (nhussein11 on #1575.)
• Description-list bullets must not mix with free-form bullets — agents often start a list in **Term**: Description. form and drift back to plain bullets. (eshaben on #1575: "Pls update rest of list items to use this same format.")
• Contractions guidance — currently silent.
• .vale.ini + styles/PaperMoon/ — starter Vale config covering banned phrases (hard ban + discouraged), terminology substitutions (ERC-20, JSON-RPC, dApp, TestNet, MainNet), emoji ban, first-person plural, link text, placeholder format, and an accept-list vocabulary. Lets the high-friction rules be enforced mechanically in CI rather than caught in prose review.

What this is meant to fix

Across the last 21 PRs on polkadot-docs from this author, the recurring inline-review categories were:

• List punctuation inconsistency (eshaben PR-level on #1575: "Lists for the most part aren't being properly formatted and some unnecessary bold usage.")
• Unnecessary bold in prose, and missing bold on description-list terms (both directions)
• Backticks missing on second/third mention of code identifiers
• Identifier/term drift within a single page
• Image naming convention misses
• Subheadings inserted directly above lead-in-sentence lists
• Mixed description-list and free-form bullet formats in the same list

Every one of those now has either an explicit rule (with Do/Don't example) in the style guide, a corresponding agent-loadable rule in AGENTS.md, or a mechanical Vale check — and most have all three.

Test plan

• Style guide renders correctly on GitHub (TOC links, tables, code fences). Verified: all 40 TOC anchors resolve to headings, code fences balanced, tables render, GitHub HTML render confirmed.
• vale . from repo root succeeds against the style guide itself (i.e., the guide doesn't violate its own rules). Verified: exit 0, 0 errors / 0 warnings / 0 suggestions across all linted files (rule-source files excluded as they intentionally contain examples of banned content).
• At least one downstream docs repo (polkadot-docs) tries adopting AGENTS.md and the Vale config on a single PR as a pilot — see docs: adopt PaperMoon styleguide via AGENTS.md + Vale lint polkadot-developers/polkadot-docs#1678 (draft): adds AGENTS.md pointing here, .vale.ini + styles/PaperMoon/, and a changed-files-scoped Vale CI workflow.
• Authoring-agent dry run: open a small docs change with an AI coding agent in the downstream repo and confirm fewer of the recurring reviewer corrections appear. Pilot is infrastructure-only; this is a forward-looking measurement to confirm on the next authoring PR against the historical baseline.

Note: absorbs 5 rules from the orchestrator (single-source consolidation)

The latest commit adds five PaperMoon house conventions that previously lived only in a downstream agent's inline style mirror: supermajority spelling, define-acronyms-on-first-use, hyphenated-identifier / runtime-network-profile casing (e.g. paseo-next), the "step label ending in a colon counts as punctuated" list nuance, and extending the rocket-emoji (🚀) prohibition to banners/UI for blockchain projects. Centralizing them here lets that downstream mirror be deleted entirely, so these rules have exactly one home. Added to both AGENTS.md and style-guide.md; vale . still passes clean.

Marking draft so the team can iterate on rule wording, lint severities, and the AGENTS.md convention before merging.

[brunopgalvao]

Addressed the inline review in c0b23d1. Per your note on style-guide.md:1 to apply your comments throughout, the same fixes are mirrored across AGENTS.md, style-guide.md, checklist.md, and README.md.

• List item punctuation (AGENTS.md:30): Rewrote rule 1 to follow Google's list rules verbatim — single-word, verbless, code-font, and link-text items take no end punctuation; mixed lists must be rewritten for parallel construction.
• Description-list capitalization (AGENTS.md:30): Added — both the term and the first letter of the description are now explicitly required to be capitalized.
• Bold for emphasis (AGENTS.md:68): Now allows italics for emphasis (and admonitions for stronger callouts) instead of "rewrite the sentence". Matches style-guide.md Italics.
• Conceptual headings (AGENTS.md:102): Left in per your "it's fine" comment.
• External / internal link target_blank (AGENTS.md:158-159, 164): Scrapped both bullets; replaced with a single note that the MkDocs plugin handles it. Removed {target=\_blank} from every example in this repo.
• Don't usage contradicting contractions (AGENTS.md:170): Switched every Don't: label to Do not: so the guide practices what it preaches.
• paseo-next / westend-next (AGENTS.md:198): Split into two rules — backticked canonical-case identifier when used as an identifier, and prose title case ("Paseo Next") when referring to the network in prose.
• <topic> → <filename> (AGENTS.md:251, 312; checklist.md:53; style-guide.md): Renamed everywhere.
• target_blank in pre-output checklist (AGENTS.md:304): Replaced with descriptive-link-text guidance and a plugin note.
• Alt text decorative exception (AGENTS.md:312): Added per Google's guidance — empty alt="" is allowed for purely decorative images; non-empty required for informative ones.
• checklist.md:5 bold-for-emphasis: Switched to italics.
• checklist.md:46 italics + admonitions: Updated to recommend italics for emphasis or an admonition for stronger callouts.
• README.md list formatting: Reformatted as proper description-list bullets (**Term**: Description.).

vale . exits 0 clean against the new content.

[eshaben]

Cool, looks good on my end. Let me know when it gets kicked out of draft mode

[brunopgalvao]

Cool, looks good on my end. Let me know when it gets kicked out of draft mode

Thank you @eshaben - it is out of draft now.

[eshaben]

Not sure the vale configs belong in this repo as they're quite polkadot specific. But you can make adjustments later if needed.

[brunopgalvao]

Good catch on the Polkadot-flavored content — neutralized in 08a1a5a:

• Vale vocab: dropped Polkadot/Kusama/Moonbeam/Moonriver/Moonbase/Substrate/parachain/relay chain. The accept list is now cross-cutting only (dApp, TestNet, MainNet, JSON-RPC, Web3, EVM, WASM, etc.). Each customer's own repo can extend the vocab with its ecosystem terms.
• Examples throughout AGENTS.md / style-guide.md / checklist.md: Moonbase Alpha faucet → generic project faucet at example.com; session.purgeKeys / StakingOperator / staker-validator-stash → auth.getUserId / RoleManager / author-editor-writer; paseo-next / westend-next → generic hyphenated identifier wording (rule itself unchanged); Oxford-comma example "red, white, and blue"; image filenames dashboard-overview-01.webp / user-permissions-01.webp.

No rule changes — only example substitutions. vale . still clean.