docs: update messenger-docs README with monorepo and client usage

Author: cryptodev-2s

packages/messenger-docs/README.md

@@ -2,6 +2,8 @@
 
 Generate and serve Messenger API documentation for MetaMask controller packages.
 
+Scans TypeScript source files and declaration files for messenger action/event types, then generates a searchable Docusaurus site with per-namespace documentation.
+
 ## Installation
 
 `yarn add @metamask/messenger-docs`
@@ -12,27 +14,67 @@ or
 
 ## Usage
 
+### Core monorepo
+
+The package includes workspace scripts for development:
+
 ```bash
-# Default: scans cwd for node_modules/@metamask controller/service packages
-npx @metamask/messenger-docs
+# Generate docs from all packages
+yarn workspace @metamask/messenger-docs docs:generate
 
-# Scan a specific project
-npx @metamask/messenger-docs /path/to/project
+# Generate + start dev server with hot reload
+yarn workspace @metamask/messenger-docs docs:dev
 
 # Generate + build static site
-npx @metamask/messenger-docs --build
+yarn workspace @metamask/messenger-docs docs:build
+
+# Generate + build + serve
+yarn workspace @metamask/messenger-docs docs:serve
+```
+
+### Client projects (Extension, Mobile)
+
+Add `@metamask/messenger-docs` as a dev dependency, then add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:messenger": "messenger-docs --serve"
+  }
+}
+```
 
-# Generate + serve (build + http server)
-npx @metamask/messenger-docs --serve
+By default, the tool scans `src/` for `.ts` files and `node_modules/@metamask/` for `.d.cts` declaration files. If your project has source files in other directories, configure `scanDirs` in `package.json`:
 
-# Generate + dev server (hot reload)
-npx @metamask/messenger-docs --dev
+```json
+{
+  "messenger-docs": {
+    "scanDirs": ["app", "src"]
+  }
+}
+```
+
+Or pass `--scan-dir` flags:
+
+```bash
+messenger-docs --scan-dir app --scan-dir shared --serve
+```
+
+### CLI options
+
+```
+messenger-docs [project-path] [options]
 
-# Scan source .ts files instead of .d.cts (for monorepo development)
-npx @metamask/messenger-docs --source
+Arguments:
+  project-path      Path to the project to scan (default: current directory)
 
-# Custom output directory (default: .messenger-docs)
-npx @metamask/messenger-docs --output ./my-docs
+Options:
+  --build           Generate docs and build static site
+  --serve           Generate docs, build, and serve static site
+  --dev             Generate docs and start dev server with hot reload
+  --scan-dir <dir>  Extra source directory to scan (repeatable)
+  --output <dir>    Output directory (default: <project-path>/.messenger-docs)
+  --help            Show this help message
 ```
 
 ## Contributing