diff --git a/packages/cli/README.md b/packages/cli/README.md
index c95e77ec2..24a2ff175 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -51,9 +51,13 @@ npx hyperframes render ./my-composition.html -o output.mp4
 Validate your Hyperframes HTML:
 
 ```bash
-npx hyperframes lint ./my-composition.html
+npx hyperframes lint ./my-composition
+npx hyperframes lint ./my-composition --json      # JSON output for CI/tooling
+npx hyperframes lint ./my-composition --verbose   # Include info-level findings
 ```
 
+By default only errors and warnings are shown. Use `--verbose` to also display informational findings (e.g., external script dependency notices). Use `--json` for machine-readable output with `errorCount`, `warningCount`, `infoCount`, and a `findings` array.
+
 ### `compositions`
 
 List compositions found in the current project:
diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md
index ada92b7a2..1c710c0c1 100644
--- a/packages/cli/src/templates/_shared/CLAUDE.md
+++ b/packages/cli/src/templates/_shared/CLAUDE.md
@@ -21,7 +21,9 @@
 ```bash
 npx hyperframes dev          # preview in browser (studio editor)
 npx hyperframes render       # render to MP4
-npx hyperframes lint         # validate compositions
+npx hyperframes lint         # validate compositions (errors + warnings)
+npx hyperframes lint --verbose  # include info-level findings
+npx hyperframes lint --json     # machine-readable output for CI
 npx hyperframes docs <topic> # reference docs in terminal
 ```