cli11, bsd manual

doc/runtime-completions.md

@@ -31,7 +31,7 @@ def inshellah-complete [spans: list<string>] {
         }
 
         try {
-            let result = (run-external "inshellah" "help" ...($candidate) | complete)
+            let result = (run-external "inshellah" "help" "--iterative" ...($candidate) | complete)
             if $result.exit_code == 0 and ($result.stdout | str length) > 10 {
                 $result.stdout | save -f $cache_file
                 $cmd_spans = $candidate
@@ -64,17 +64,24 @@ When you type `docker compose up --<TAB>`:
 
 1. Nushell calls the completer with `spans = ["docker", "compose", "up", "--"]`
 2. The completer tries progressively deeper prefixes as cache keys
-3. On cache miss, runs `inshellah help docker compose up`
+3. On cache miss, runs `inshellah help --iterative docker compose up`
 4. Caches the result; all subsequent completions are instant
 
-First tab-press latency is ~100-200ms. Depth is capped at 5 levels.
+The `--iterative` flag tells inshellah to resolve only the immediate level
+without recursing into subcommands. This keeps each cache miss fast
+(~100-200ms) and lets the completer progressively resolve deeper levels
+on demand. Without `--iterative`, `inshellah help` recursively resolves
+all subcommands, which is better for upfront generation but too slow for
+interactive tab-completion.
+
+Depth is capped at 5 levels.
 
 ## Cache management
 
 ```sh
 rm -rf ~/.cache/inshellah/          # Clear all
 ls ~/.cache/inshellah/              # List cached
-inshellah help docker run > ~/.cache/inshellah/docker-run.nu  # Regenerate one
+inshellah help --iterative docker run > ~/.cache/inshellah/docker-run.nu  # Regenerate one
 ```
 
 ## When to use this vs build-time generation
@@ -85,3 +92,10 @@ at build time. Runtime caching is useful for:
 - Commands installed outside the system profile (cargo, pip, npm, go)
 - Subcommand completions at arbitrary depth
 - Systems without the NixOS module
+
+For one-off upfront generation (not runtime caching), use `inshellah help`
+without `--iterative` to recursively resolve all subcommands at once:
+
+```sh
+inshellah help docker > docker.nu  # Resolves all subcommands recursively
+```