From c649c0dbe794396343dd8e7eb78aec1a12718cf7 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Tue, 9 Jun 2026 04:16:28 -0700
Subject: [PATCH] docs: document Windows/PowerShell npx invocation (#93)

---
 README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/README.md b/README.md
index 6561214..055c98c 100644
--- a/README.md
+++ b/README.md
@@ -191,6 +191,19 @@ Or run directly (always resolves from the public npm registry):
 npx @google/design.md lint DESIGN.md
 ```
 
+On **Windows/PowerShell**, this direct form can produce no output (or open
+`DESIGN.md` in your Markdown editor) because the `.md` suffix in the `design.md`
+bin name collides with the Windows Markdown file association during command
+resolution. Run the dot-free `designmd` alias instead — point `npx` at the
+package with `-p`, then invoke `designmd`:
+
+```bash
+npx -p @google/design.md designmd lint DESIGN.md
+```
+
+The `designmd` shim resolves to the same entrypoint and works identically across
+all platforms.
+
 #### `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).