ff

SYS/pipeline.py

@@ -584,8 +584,20 @@ def set_last_result_table(
     items: Optional[List[Any]] = None,
     subject: Optional[Any] = None
 ) -> None:
-    """
-    Store the last result table and items for @ selection syntax.
+    """Store the last result table and items for @ selection syntax.
+    
+    Persists result table and items across command invocations, enabling
+    subsequent commands to reference and operate on previous results using @N syntax.
+    
+    Example:
+        search-file hash:<...>  # Returns table with 3 results
+        @1 | get-metadata      # Gets metadata for result #1
+        @2 | add-tag foo       # Adds tag to result #2
+    
+    Args:
+        result_table: Table object with results (can be None to clear)
+        items: List of item objects corresponding to table rows
+        subject: Optional context object (first item or full list)
     """
     state = _get_pipeline_state()
 
@@ -662,6 +674,16 @@ def set_last_result_table_overlay(
 
     Used by action cmdlets (get-metadata, get-tag, get-url) to display detail
     panels or filtered results without disrupting the primary search-result history.
+    
+    Difference from set_last_result_table():
+    - Overlay tables are transient (in-process memory only)
+    - Don't persist across command invocations
+    - Used for "live" displays that shouldn't be part of @N selection
+    
+    Args:
+        result_table: Table object with transient results
+        items: List of item objects (not persisted)
+        subject: Optional context object
     """
     state = _get_pipeline_state()
     state.display_table = result_table
@@ -833,8 +855,17 @@ def get_last_result_table() -> Optional[Any]:
 
 
 def get_last_result_items() -> List[Any]:
-    """
-    Get the items available for @N selection.
+    """Get the items available for @N selection in current pipeline context.
+    
+    Returns items in priority order:
+    1. Display items (from get-tag, get-metadata, etc.) if display table is selectable
+    2. Last result items (from search-file, etc.) if last result table is selectable
+    3. Empty list if no selectable tables available
+    
+    Used to resolve @1, @2, etc. in commands.
+    
+    Returns:
+        List of items that can be selected via @N syntax
     """
     state = _get_pipeline_state()
     # Prioritize items from display commands (get-tag, delete-tag, etc.)