Edit-time docs style enforcement via Vale + PostToolUse hook

.gitignore

@@ -0,0 +1,4 @@
+# Vale-synced style packs — fetch with `vale sync`
+styles/Microsoft/
+styles/proselint/
+styles/write-good/

.vale.ini

@@ -1,12 +1,66 @@
 StylesPath = styles
 MinAlertLevel = warning
+Vocab = x402r
 
 Packages = Microsoft, write-good, proselint
 
+# Parse .mdx as Markdown so Vale doesn't need the separate mdx2vast binary
+# (used by the PostToolUse hook for local edit-time linting). The CI action
+# (errata-ai/vale-action) installs its own MDX parser server-side.
+#
+# Tradeoff per Vale's MDX docs (https://vale.sh/docs/formats/mdx): mdx = md is
+# an extension-level substitution, not real MDX support. JSX components
+# (<CodeGroup>, <Note>, <Steps>), JSX expressions, and ESM imports/exports
+# aren't parsed out and can leak into prose linting. Hook view (md mode) is
+# strictly less accurate than CI view (mdx2vast). Acceptable here because the
+# hook trades local accuracy for zero-dep installation, and CI is the actual
+# merge gate.
+[formats]
+mdx = md
+
 [*.mdx]
 BasedOnStyles = Vale, Microsoft, write-good, proselint, x402r
 
-# Disable overly noisy Microsoft rules for docs
+# Disabled Microsoft rules. = NO is explicit-off; the runtime effect varies
+# per rule because each ships with a different default `level:` in its YAML.
+#
+# Contractions:   rule default = error. Without `= NO` it fires ~37x
+#                 across docs (irrelevant for technical writing, encourages
+#                 informal voice). This is the only real suppression here.
+# SentenceLength: rule default = suggestion. Already filtered by our
+#                 MinAlertLevel = warning floor regardless of this line.
+#                 `= NO` makes intent explicit; behavior unchanged.
+#                 Low-ROI rule with no actionable threshold.
+# Passive:        rule default = suggestion. Same story as SentenceLength.
+#                 Also duplicative — write-good.Passive (enabled below)
+#                 fires on identical spans, so enabling both would
+#                 double-warn every passive sentence.
+#
+# Footgun to watch for: a rule that ships with `level: error` and gets
+# = suggestion in this file IS a real downgrade — and with our warning
+# floor it becomes silent. That's how the earlier Vale.Spelling regression
+# happened. Always check the rule file's default before assuming
+# `= suggestion` is a downgrade rather than a redundant restatement.
 Microsoft.Contractions = NO
-Microsoft.SentenceLength = suggestion
-Microsoft.Passive = suggestion
+Microsoft.SentenceLength = NO
+Microsoft.Passive = NO
+
+# Vale.Terms reads the same accept.txt as Vale.Spelling but treats each entry
+# as the canonical case form. That fires false positives whenever a vocab
+# entry collides with a code identifier (e.g. PaymentInfo type vs paymentInfo
+# variable, Hono package vs hono import path, Base chain vs base code
+# identifier) or when the entry uses Vale's regex syntax (SDKs? becomes a
+# literal canonical-form suggestion). Vocab here is for spelling acceptance
+# only, not terminology enforcement — disabled.
+Vale.Terms = NO
+
+# Vale.Spelling stays at its default (error) severity here. CI gates real
+# typos before merge — the right place for strict spell-check.
+#
+# The PostToolUse hook in workspace .claude/settings.json filters Vale.Spelling
+# out of its output via `vale --filter='.Name != "Vale.Spelling"'` so Claude's
+# self-correction context isn't drowned by chain-name and identifier false
+# positives. CI (errata-ai/vale-action) does not apply that filter, so PR
+# review still sees the full spell-check.
+#
+# Strict-in-CI / lenient-in-hook pattern, per GitLab and Vaadin Vale configs.

CLAUDE.md

@@ -2,19 +2,29 @@
 
 Mintlify docs at docs.x402r.org. Config in `docs.json`.
 
+## Workflow
+
+For any non-trivial doc work, invoke the **`writing-docs` skill** — it loads the style guide, per-page creative briefs, quality gates, and source-file map, and walks the full workflow.
+
 ## Commands
 
 ```bash
 npx mint dev  # Preview at localhost:3000
 ```
 
-## Standards
+## Hard constraints
 
 - YAML frontmatter required on all MDX files (`title`, `description`)
-- Second person ("You can..."), active voice, short paragraphs (2-4 sentences)
-- **Never use em dashes (`—`).** Use a comma, period, or rewrite the sentence instead.
+- Real addresses from `x402r-sdk/packages/core/src/config/index.ts` — never placeholders like `0xYourAddress` or `<CHAIN_ID>`
+- Verify every export, function name, and file path exists before referencing
+- Test all code examples before including
+- Never use em dashes (`—`) — use a comma, period, or rewrite
 - Use Mermaid for diagrams, never ASCII art
 - Relative paths for internal links, alt text on images
-- Test all code examples before including, use realistic values
-- All install commands must be copy-pasteable. Use `CodeGroup` with npm/pnpm/bun tabs for every install command.
 - Components: `Note`, `Tip`, `Warning`, `Info`, `Steps`, `CardGroup`, `Tabs`, `Accordion`, `CodeGroup`
+
+## Style
+
+Style rules (anti-slop, voice, structure) live in:
+- `.vale.ini` + `styles/x402r/` — deterministic enforcement (runs in CI and via PostToolUse hook on `.mdx` edits)
+- The `writing-docs` skill (installed at the monorepo workspace level) — full prose style guide, per-page briefs, quality gates, source-files map

styles/config/vocabularies/x402r/accept.txt

@@ -0,0 +1,67 @@
+[Ss]epolia
+[Mm]iddleware
+[Mm]isconfigured
+RPCs?
+CAIP
+Hono
+Permit2
+ERC3009
+ERC-3009
+Codehash
+[Bb]asescan
+[Bb]igint
+viem
+[Mm]ulticall3
+EIP-155
+EIP-712
+EIP-3009
+[Pp]aginated
+[Pp]agination
+[Cc]onfig
+[Cc]onfigs
+[Ll]ookups?
+PaymentInfo
+PaymentInfoHash
+PaymentOperator
+PaymentIndexRecorderHook
+HookCombinator
+AuthCaptureEscrow
+RefundRequest
+RefundRequestStatus
+ReceiverRefundCollector
+USDC
+EURC
+PYUSD
+DAI
+EOA
+CREATE2
+walletClient
+publicClient
+operatorAddress
+paymentInfo
+fromBlock
+eventFromBlock
+paymentIndexRecorderHook
+[Ee]nums?
+codehash
+multicall3
+async
+SDK
+SDKs?
+[Mm]ainnet
+[Pp]roxying
+[Pp]roxy
+
+# --- Chain names ---
+# Source of truth: `x402rChains` in
+# `x402r-sdk/packages/core/src/config/index.ts`. Only chains with deployed
+# contracts. When chains are added/removed in core, regenerate via:
+#
+#   awk '/export const x402rChains/,/^} as const/' \
+#     ../x402r-sdk/packages/core/src/config/index.ts \
+#     | grep -oE "'[A-Z][a-zA-Z ]+'" | sort -u
+#
+# Chain names referenced in marketing/roadmap docs but NOT in x402rChains
+# (e.g. Ethereum, Polygon, Arbitrum, Optimism) will fire as Vale warnings.
+# That is intentional signal — those mentions document unshipped support.
+Base