docs(readme): verifiable npm downloads section + daily refresh (#385)

* docs(readme): add verifiable npm downloads section with daily refresh action

* test(contract): cover the verifiable npm downloads README section

Required by the OSS Harness authority-docs contract for README.md changes.

Author: ceilf6

.github/workflows/update-npm-downloads.yml

@@ -0,0 +1,29 @@
+name: Update npm downloads counter
+
+on:
+  schedule:
+    - cron: "17 1 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch cumulative downloads and patch README
+        run: |
+          END=$(date -u -d yesterday +%F)
+          N=$(curl -sf "https://api.npmjs.org/downloads/point/2026-01-14:${END}/frontagent" | jq -r '.downloads')
+          if [ -z "$N" ] || [ "$N" = "null" ]; then
+            echo "npm API unavailable, skip"; exit 0
+          fi
+          perl -0pi -e "s/<!-- npm-downloads:start -->.*?<!-- npm-downloads:end -->/<!-- npm-downloads:start -->\n**Cumulative npm downloads since 2026-01-14: ${N}** (updated ${END}, via GitHub Action)\n<!-- npm-downloads:end -->/s" README.md
+      - name: Commit if changed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git diff --cached --quiet || (git commit -m "chore(readme): refresh npm downloads counter" && git push)

README.md

@@ -5,6 +5,7 @@
 </div>
 
 [![npm version](https://badge.fury.io/js/frontagent.svg)](https://www.npmjs.com/package/frontagent)
+[![npm total downloads](https://img.shields.io/npm/dt/frontagent)](https://www.npmjs.com/package/frontagent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 
@@ -1297,6 +1298,19 @@ pnpm clean
 - [RedBox](https://github.com/Jamailar/RedBox) - Local AI creation workspace for Xiaohongshu creators.
 - [1flowbase](https://github.com/taichuy/1flowbase) - Virtual model gateway for publishing multi-model workflows as OpenAI/Claude-compatible endpoints, with trace, token, latency, and cost visibility.
 
+## Download Stats (verifiable)
+
+<!-- npm-downloads:start -->
+**Cumulative npm downloads since 2026-01-14: 2447** (updated 2026-07-10, via GitHub Action)
+<!-- npm-downloads:end -->
+
+Verify it yourself against the public npm registry API:
+
+```bash
+# macOS:  date -u -v-1d +%F   |  Linux:  date -u -d yesterday +%F
+curl -s "https://api.npmjs.org/downloads/point/2026-01-14:$(date -u -v-1d +%F 2>/dev/null || date -u -d yesterday +%F)/frontagent" | jq
+```
+
 ## Contributing
 
 Welcome to contribute! Submit issues, bugs, or suggestions:

scripts/tests/workflow-rules.test.mjs

@@ -548,3 +548,14 @@ test('agent prompts describe the OSS Harness review loop', () => {
     assert.match(prompt, /maintainers decide merge readiness/u);
   }
 });
+
+test('README exposes the verifiable npm downloads counter with its marker block', () => {
+  const readme = readFileSync('README.md', 'utf8');
+
+  assert.match(readme, /## Download Stats \(verifiable\)/u);
+  // Marker comments are the GitHub Action's substitution anchors — do not rename.
+  assert.match(readme, /<!-- npm-downloads:start -->/u);
+  assert.match(readme, /<!-- npm-downloads:end -->/u);
+  // The reader can verify the number against the public registry API.
+  assert.match(readme, /api\.npmjs\.org\/downloads\/point/u);
+});