diff --git a/src/logger.js b/src/logger.js
index e0c6c91..0b7dec5 100644
--- a/src/logger.js
+++ b/src/logger.js
@@ -23,6 +23,21 @@
         verbose(msg, data) { this._log(4, 'VERBOSE', msg, data); }
         trace(msg, data)   { this._log(5, 'TRACE', msg, data); }
 
+        /**
+         * Logs command lifecycle events with visual icons for easy scanning.
+         *
+         * Currently unused in the refactored architecture, but reserved for future
+         * command state tracking. The dev branch used this extensively for monitoring
+         * command execution through different states.
+         *
+         * @param {string} action - The command action (e.g., 'get_file', 'update_file')
+         * @param {string} status - Command status: 'detected', 'parsing', 'validating', 'debouncing', 'executing', 'complete', 'error'
+         * @param {Object} [extra={}] - Additional data to log
+         *
+         * @example
+         * log.command('get_file', 'executing', { path: 'src/main.js' });
+         * // Logs: "⚙️ get_file [executing]" with extra data
+         */
         command(action, status, extra={}) {
             const icon = {
                 detected:'👁️', parsing:'📝', validating:'✓', debouncing:'⏳',