From 814730e23c626786959c043d34d73289a727e150 Mon Sep 17 00:00:00 2001 From: A1igator Date: Tue, 19 May 2026 15:07:18 -0700 Subject: [PATCH] docs: let domain terms and protocol acronyms through Vale After applying the writing-docs skill across the 14-PR consolidation, the remaining ~300 Vale violations were all in three categories of domain false positives, not real style issues: - Spelling on legitimate domain vocabulary (IHook, ICondition, captureAuthorizer, authCapture, escrowed, pluggable, multisig, timelock, ...). - Microsoft.HeadingAcronyms on every reference page that headlines a protocol acronym (ERC-3009, EIP-712, EIP-6492, BUSL-1.1, JSON-RPC, CDP, DAO). - Microsoft.Terms swapping "agent" -> "personal digital assistant", which is wrong for ERC-8004 on-chain agents. - proselint.Typography suggesting the multiplication sign in place of every `0x` hex literal. Vocab additions (60+ entries), grouped by intent: - Contract interfaces (IHook, ICondition, IRecorder, IPaymentOperator) - Protocol concepts (authCapture, captureAuthorizer, capturable, combinators, escrowed, permissionless, pluggable, composability, micropayments, gasless, terminalize, reentrancy, refundability, timelock, multisig, mempool, calldata) - SDK identifiers (operatorConfig, maxAmount, responseBody, paymentPayload, newCount, existingCount, escrowPeriod, txHashes, codehashes) - Tooling and runtime (npm, npx, pnpm, bunx, dlx, tsx, dotenv, stdout, stderr, mkdir, Boolean, namespace, testnet, devnet, Mintlify, subgraph, gwei, txns, const) - Standards and acronyms (APIs, ABIs, UIs, EVMs, dApps, CIDs) - Ecosystem (Uniswap, Coinbase, Fireblocks, Flashbots, Solana, Solady, Spearbit, Ownable, Aave) Rule disables in .vale.ini, each with rationale in-place: - Microsoft.HeadingAcronyms = NO (no allowlist mechanism, every reference heading triggers it) - Microsoft.Terms = NO (ERC-8004 agent terminology) - proselint.Typography = NO (no code/identifier context awareness) Pairs with the writing-docs cleanup landing in PR #35. Co-Authored-By: Claude Opus 4.7 (1M context) --- .vale.ini | 23 ++++++ styles/config/vocabularies/x402r/accept.txt | 80 +++++++++++++++++++++ 2 files changed, 103 insertions(+) diff --git a/.vale.ini b/.vale.ini index 028b7e7..c7c106b 100644 --- a/.vale.ini +++ b/.vale.ini @@ -45,6 +45,29 @@ Microsoft.Contractions = NO Microsoft.SentenceLength = NO Microsoft.Passive = NO +# Microsoft.HeadingAcronyms (default: warning) flags any heading containing +# an acronym longer than 3 letters, on the theory that headings should be +# spelled out for accessibility. In x402r docs almost every reference page +# headlines a protocol acronym (ERC-3009, EIP-712, EIP-6492, BUSL-1.1, +# JSON-RPC, CDP, DAO). Spelling them out (e.g. "Electronic Resource Cluster +# 3009") is wrong — these names are the canonical identifiers for the +# standards. The rule has no allowlist mechanism, so disable wholesale. +Microsoft.HeadingAcronyms = NO + +# Microsoft.Terms (default: warning) enforces Microsoft Writing Style Guide +# terminology swaps, e.g. "agent" → "personal digital assistant", +# "blacklist" → "block list". The "agent" mapping is wrong for x402r: +# ERC-8004 defines on-chain "agents" as autonomous protocol actors, and +# the same word is used across the crypto/AI-agents ecosystem. No useful +# swaps remain that aren't covered by other style rules. Disabled. +Microsoft.Terms = NO + +# proselint.Typography (default: warning) suggests replacing `x` with the +# `×` (Unicode multiplication sign) symbol. Every hex address literal in +# the docs (`0x0000...`, `0x833589f...`) triggers this — the rule has no +# concept of code/identifier context. Adversarial in a Web3 codebase. +proselint.Typography = 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 diff --git a/styles/config/vocabularies/x402r/accept.txt b/styles/config/vocabularies/x402r/accept.txt index e4d069b..a6f9cef 100644 --- a/styles/config/vocabularies/x402r/accept.txt +++ b/styles/config/vocabularies/x402r/accept.txt @@ -52,6 +52,86 @@ SDKs? [Pp]roxying [Pp]roxy +# --- Contract interfaces --- +# Solidity interface names referenced across the contracts docs. +IHook +ICondition +IRecorder +IPaymentOperator + +# --- Protocol concepts --- +# Domain vocabulary that appears in prose, not just code. +authCapture +captureAuthorizer +[Cc]apturable +[Cc]ombinators? +[Ee]scrowed +[Pp]ermissionless +[Pp]luggable +[Cc]omposability +[Mm]icropayments? +[Gg]asless +[Tt]erminalize +[Rr]eentrancy +[Rr]efundability +[Tt]imelock +[Mm]ultisig +[Mm]empool +[Cc]alldata + +# --- SDK identifiers --- +# CamelCase identifiers that appear inline without code formatting. +operatorConfig +maxAmount +responseBody +paymentPayload +newCount +existingCount +escrowPeriod +txHashes +codehashes? + +# --- Tooling and runtime --- +npm +npx +pnpm +bunx +dlx +mkdir +tsx +dotenv +stdout +stderr +[Bb]oolean +[Nn]amespace +[Tt]estnet +[Dd]evnet +[Mm]intlify +[Ss]ubgraph +gwei +txns? +const + +# --- Standards and acronyms --- +APIs? +ABIs? +UIs? +EVMs? +dApps? +CIDs? + +# --- Ecosystem --- +# Third-party projects/orgs referenced in the docs. +Uniswap +[Cc]oinbase +[Ff]ireblocks +[Ff]lashbots +[Ss]olana +Solady +Spearbit +Ownable +Aave + # --- Chain names --- # Source of truth: `x402rChains` in # `x402r-sdk/packages/core/src/config/index.ts`. Only chains with deployed