From 7f1cb38364c8fe2e47c9a1073cf400e692d17d43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Camilo=20Vel=C3=A1squez=20Amarillo?=
 <camilojheans@gmail.com>
Date: Mon, 27 Apr 2026 17:09:12 -0500
Subject: [PATCH] docs(ci): clarify npm install on Windows and add registry
 smoke test

- Document quoting for scoped package in shells that treat @ specially
- Explain ENOVERSIONS and registry/.npmrc checks (addresses #55)
- Add Windows CI job that installs @google/design.md from npmjs.org

Made-with: Cursor
---
 .github/workflows/test.yml | 19 +++++++++++++++++++
 README.md                  | 20 +++++++++++++++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index fca41f0e..18aecf13 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -52,3 +52,22 @@ jobs:
         npx design.md lint DESIGN.md
         node -e "import('@google/design.md/linter').then(m => console.log('OK:', Object.keys(m).length, 'exports'))"
 
+  npm-registry-smoke-windows:
+    runs-on: windows-latest
+    steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+        registry-url: https://registry.npmjs.org
+
+    - name: Install @google/design.md from the public npm registry
+      shell: bash
+      run: |
+        set -euo pipefail
+        mkdir -p "$RUNNER_TEMP/npm-registry-smoke"
+        cd "$RUNNER_TEMP/npm-registry-smoke"
+        npm init -y
+        npm install "@google/design.md@latest"
+        node node_modules/@google/design.md/dist/index.js spec --rules-only --format json > /dev/null
+        node -e "import('@google/design.md/linter').then(m => console.log('OK:', Object.keys(m).length, 'exports'))"
+
diff --git a/README.md b/README.md
index c7d9f0b5..37543cf0 100644
--- a/README.md
+++ b/README.md
@@ -179,12 +179,30 @@ Variants (hover, active, pressed) are expressed as separate component entries wi
 npm install @google/design.md
 ```
 
-Or run directly:
+On **Windows**, quote the package name if your shell treats `@` specially (PowerShell, some terminals):
+
+```bash
+npm install "@google/design.md"
+```
+
+Or run directly (always resolves from the public npm registry):
 
 ```bash
 npx @google/design.md lint DESIGN.md
 ```
 
+#### `npm error ENOVERSIONS` (“No versions available for @google/design.md”)
+
+The CLI is published as [`@google/design.md` on npm](https://www.npmjs.com/package/@google/design.md). `ENOVERSIONS` almost always means npm is not querying the public registry (custom `registry=` in `.npmrc`, a corporate mirror that has not synced this package, or a misconfigured `@google:registry` for the `@google` scope).
+
+Check your effective registry:
+
+```bash
+npm config get registry
+```
+
+For a normal install from the internet it should be `https://registry.npmjs.org/`. After fixing config, retry with `npm cache clean --force` if a stale 404 was cached.
+
 All commands accept a file path or `-` for stdin. Output defaults to JSON.
 
 ### `lint`