packages/cli JSDoc field contracts

Prefer JSDoc to inline comments. In packages/cli, add JSDoc to exported functions, classes, and types, plus important internal symbols. Document every type or interface property’s representation, units, permitted values, null meaning, and defaults; TypeScript syntax alone does not explain runtime units, sentinel values, or default behavior.