diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6bb209d --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +# Vale-synced style packs — fetch with `vale sync` +styles/Microsoft/ +styles/proselint/ +styles/write-good/ diff --git a/.vale.ini b/.vale.ini index f0d3760..028b7e7 100644 --- a/.vale.ini +++ b/.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 +# (, , ), 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. diff --git a/CLAUDE.md b/CLAUDE.md index d587c8a..16c5cf2 100644 --- a/CLAUDE.md +++ b/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 `` +- 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 diff --git a/styles/config/vocabularies/x402r/accept.txt b/styles/config/vocabularies/x402r/accept.txt new file mode 100644 index 0000000..e4d069b --- /dev/null +++ b/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 diff --git a/styles/x402r/AllowsYouTo.yml b/styles/x402r/AllowsYouTo.yml deleted file mode 100644 index 74d0c45..0000000 --- a/styles/x402r/AllowsYouTo.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: existence -message: "Rewrite without 'allows you to' — state what it does directly." -level: warning -ignorecase: true -tokens: - - allows you to - - enabling you to - - enables you to - - makes it easy to - - gives you the ability to