docs-files-api: program scripts' @file is their manual

The exception: a script run directly (shebang or import.meta.main) puts
its purpose, usage synopsis, arguments, and outputs in @file. Readers
open a script to learn how to run it; its main has no call sites for
JSDoc to show at.

Generated-by: Claude Opus 5.5

docs-files-api/SKILL.md

@@ -19,6 +19,12 @@ JSDoc placement rules (from the
   its declaration — IDEs show it at call sites and on hover; a `//` line
   above the declaration shows nowhere. `//` is for implementation notes
   inside a body: the *why* of a non-obvious line, next to that line.
+- **Exception: program scripts** (run directly: a shebang, or
+  `import.meta.main`). The `@file` comment is the script's manual: a
+  one-line purpose, a usage synopsis, the arguments, and what it writes
+  or prints. People open a script to learn how to run it, and its `main`
+  has no call sites for JSDoc to show at. Helpers inside still get their
+  own JSDoc.
 - **External design constraints:** If a module is constrained by external
   contracts, standards, or off-repo design docs, add a short JSDoc note with a
   `@see` link to the authoritative source at the relevant entry point(s).