From 9c7ffd8f6038b718d05c64c9588e3ed713c2e82f Mon Sep 17 00:00:00 2001 From: vraspar Date: Fri, 20 Mar 2026 01:26:25 -0700 Subject: [PATCH 1/3] Add docs infrastructure: CI, feedback widget, Mintlify workflows - Add feedback thumbsRating and search prompt to docs.json - Remove empty redirects array - Add GitHub Actions CI: broken-links check + frontmatter validation on PRs - Add Mintlify Workflow to auto-update SDK docs on x402r-sdk push - Add Mintlify Workflow for weekly broken link scan Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/ci.yml | 33 ++++++++++++++++++++++++++++ .mintlify/workflows/broken-links.md | 8 +++++++ .mintlify/workflows/sdk-docs-sync.md | 13 +++++++++++ docs.json | 7 +++++- 4 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/ci.yml create mode 100644 .mintlify/workflows/broken-links.md create mode 100644 .mintlify/workflows/sdk-docs-sync.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..d51e6e0 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,33 @@ +name: Docs CI + +on: + pull_request: + branches: [main] + +jobs: + validate: + name: Validate docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Check broken links + run: npx mintlify@latest broken-links + + - name: Validate frontmatter + run: | + missing=() + for file in $(find . -name '*.mdx' -not -path './node_modules/*'); do + head -20 "$file" | grep -q '^title:' || missing+=("$file (missing title)") + head -20 "$file" | grep -q '^description:' || missing+=("$file (missing description)") + done + if [ ${#missing[@]} -gt 0 ]; then + echo "Files with missing frontmatter:" + printf ' %s\n' "${missing[@]}" + exit 1 + fi + echo "All MDX files have required frontmatter." diff --git a/.mintlify/workflows/broken-links.md b/.mintlify/workflows/broken-links.md new file mode 100644 index 0000000..695241f --- /dev/null +++ b/.mintlify/workflows/broken-links.md @@ -0,0 +1,8 @@ +--- +name: Check Broken Links +on: + cron: "0 9 * * 1" +--- + +Check all internal links in the documentation for broken references. +Fix any broken links by updating paths to match current file structure. diff --git a/.mintlify/workflows/sdk-docs-sync.md b/.mintlify/workflows/sdk-docs-sync.md new file mode 100644 index 0000000..c4861d1 --- /dev/null +++ b/.mintlify/workflows/sdk-docs-sync.md @@ -0,0 +1,13 @@ +--- +name: Update SDK Documentation +on: + push: + - repo: BackTrackCo/x402r-sdk + branch: main +--- + +Review the diff from the latest push to BackTrackCo/x402r-sdk. +Identify changed function signatures, new exports, or removed functions. +Update the relevant SDK documentation pages under sdk/. +Only modify SDK pages. Do not touch protocol or contract documentation. +Follow the writing style in CLAUDE.md. diff --git a/docs.json b/docs.json index d9989ee..3ae8129 100644 --- a/docs.json +++ b/docs.json @@ -160,6 +160,12 @@ "href": "https://github.com/BackTrackCo" } }, + "feedback": { + "thumbsRating": true + }, + "search": { + "prompt": "Search x402r docs..." + }, "contextual": { "options": [ "copy", @@ -172,7 +178,6 @@ "vscode" ] }, - "redirects": [], "footer": { "socials": { "x": "https://x.com/x402rorg", From 576f4c294e940affeeea6487daac298230921099 Mon Sep 17 00:00:00 2001 From: vraspar Date: Fri, 20 Mar 2026 01:42:12 -0700 Subject: [PATCH 2/3] Add Vale grammar linter to CI with custom anti-slop rules - Add Vale action to CI workflow (free alternative to Mintlify Pro grammar linter) - Custom x402r style rules: catch filler/marketing language, "allows you to" patterns, enthusiasm markers - Reports inline on PRs via github-pr-check Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/ci.yml | 7 +++++++ .vale.ini | 7 +++++++ styles/x402r/AllowsYouTo.yml | 10 ++++++++++ styles/x402r/Enthusiasm.yml | 10 ++++++++++ styles/x402r/Slop.yml | 20 ++++++++++++++++++++ 5 files changed, 54 insertions(+) create mode 100644 .vale.ini create mode 100644 styles/x402r/AllowsYouTo.yml create mode 100644 styles/x402r/Enthusiasm.yml create mode 100644 styles/x402r/Slop.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d51e6e0..7f3655f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,6 +18,13 @@ jobs: - name: Check broken links run: npx mintlify@latest broken-links + - name: Grammar lint (Vale) + uses: errata-ai/vale-action@v2 + with: + reporter: github-pr-check + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Validate frontmatter run: | missing=() diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..62b9674 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,7 @@ +[*] +BasedOnStyles = Vale, x402r + +MinAlertLevel = warning + +[*.mdx] +BasedOnStyles = Vale, x402r diff --git a/styles/x402r/AllowsYouTo.yml b/styles/x402r/AllowsYouTo.yml new file mode 100644 index 0000000..74d0c45 --- /dev/null +++ b/styles/x402r/AllowsYouTo.yml @@ -0,0 +1,10 @@ +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 diff --git a/styles/x402r/Enthusiasm.yml b/styles/x402r/Enthusiasm.yml new file mode 100644 index 0000000..658fa86 --- /dev/null +++ b/styles/x402r/Enthusiasm.yml @@ -0,0 +1,10 @@ +extends: existence +message: "Avoid enthusiasm markers: '%s'" +level: warning +ignorecase: true +tokens: + - Amazing + - Exciting + - Great news + - Incredibly + - Super easy diff --git a/styles/x402r/Slop.yml b/styles/x402r/Slop.yml new file mode 100644 index 0000000..a2c77e5 --- /dev/null +++ b/styles/x402r/Slop.yml @@ -0,0 +1,20 @@ +extends: existence +message: "Avoid filler/marketing language: '%s'" +level: warning +ignorecase: true +tokens: + - seamless + - robust + - comprehensive + - empower + - revolutionize + - unlock the + - leverage + - easy to use + - easy-to-use + - cutting-edge + - game-changer + - next-generation + - world-class + - best-in-class + - state-of-the-art From f9b4e27d0553dbf5ffc9b286f23147c61c6d22fd Mon Sep 17 00:00:00 2001 From: vraspar Date: Fri, 20 Mar 2026 01:51:36 -0700 Subject: [PATCH 3/3] Use industry-standard Vale packages + keep custom x402r rules - Add Microsoft, write-good, proselint packages (battle-tested, maintained) - Downgrade noisy Microsoft rules (contractions OFF, sentence length + passive to suggestion) - Keep custom x402r style for project-specific anti-slop rules - Scope Vale to .mdx files only Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/ci.yml | 1 + .vale.ini | 13 +++++++++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7f3655f..a76fd95 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,6 +22,7 @@ jobs: uses: errata-ai/vale-action@v2 with: reporter: github-pr-check + vale_flags: "--glob='*.mdx'" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.vale.ini b/.vale.ini index 62b9674..f0d3760 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,7 +1,12 @@ -[*] -BasedOnStyles = Vale, x402r - +StylesPath = styles MinAlertLevel = warning +Packages = Microsoft, write-good, proselint + [*.mdx] -BasedOnStyles = Vale, x402r +BasedOnStyles = Vale, Microsoft, write-good, proselint, x402r + +# Disable overly noisy Microsoft rules for docs +Microsoft.Contractions = NO +Microsoft.SentenceLength = suggestion +Microsoft.Passive = suggestion