Production readiness: complete docs rewrite, cross-OS fix, UX consolidation

Framework fixes:
- CRLF→LF fix for .sh stubs (was breaking bash on Linux/macOS with "ambiguous redirect")
- .gitattributes: enforce LF for .sh files
- Pipeline detection: commands with pipes/semicolons now B64-wrap even if first word is native LR verb
- Rate-Limiter: ActiveRequest retry message shows correct limit (12, not 5)
- Auth-Internal: session expiry message simplified to "Type 'connect' to re-authenticate"
- Invoke-LRCommand: default timeout 1800s (server decides, not client)
- Manage-Library: warns when .sh uploaded via Official API (doesn't sync to Linux/macOS)
- Removed lara_loader.sh (executor_b64.sh works on all platforms once properly uploaded)

UX consolidation:
- Unified auth menu (7 methods in one screen, mode derived from choice)
- connect command re-authenticates when session expired
- mode command informational only (no manual switching)
- session/session list for awareness
- Dynamic error handling with server response parsing
- Typo detection for shell commands
- 403 DisallowedOperation: specific device group guidance

Cross-OS findings:
- Linux/macOS PROVEN WORKING via both APIs (Internal: 6.2s avg, Official: 26-33s avg)
- .sh stubs MUST have Unix line endings (LF)
- Official API library upload doesn't sync .sh to Linux/macOS — upload via Internal API/portal first
- Once stubs are properly uploaded, Official API RunScript works fine on all 3 platforms

Documentation: complete rewrite of all 7 doc files from scratch:
- README.md, ARCHITECTURE.md, USER_GUIDE.md, COMMAND_REFERENCE.md
- ERROR_REFERENCE.md, PERFORMANCE_COMPARISON.md, tests/README.md

Test results (2026-04-03):
- Offline: 736/736 PASS (100%)
- Internal Pester: 251/251 PASS (100%)
- Stress Internal (blackhat): 23/26 PASS (88%)
- Stress Official (larabond): 25/26 PASS (96%)
- Stress CrossOS Internal (Win+Lin+Mac): 36/36 PASS (100%)
- Stress CrossOS Official (Win+Lin+Mac): 30/36 PASS (83%)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: akefallonitis

.gitattributes

@@ -1,2 +1,3 @@
 *.yml text eol=lf
 *.yaml text eol=lf
+*.sh text eol=lf

ARCHITECTURE.md

@@ -1,7 +1,6 @@
 # LaraC2 Shell -- Command Reference
 
-Complete reference for all commands, native LR operations, aliases, and command
-routing logic in the MDE Live Response Interactive Shell.
+Complete reference for all commands, native LR operations, aliases, and command routing logic.
 
 ---
 
@@ -15,14 +14,12 @@ These commands are handled by the REPL dispatcher and do not execute on the remo
 | `help commands` | List all 25 native LR commands with descriptions. | `help commands` |
 | `help aliases` | Show all command aliases. | `help aliases` |
 | `mode` | Display the current API mode (official or internal). | `mode` |
-| `mode official` | Switch to Official API mode and re-authenticate. | `mode official` |
-| `mode internal` | Switch to Internal API mode and re-authenticate. | `mode internal` |
 | `status` | Show connection status: API mode, auth method/state, token expiry, session info, selected machine, OS, working directory. | `status` |
-| `config` | Show Live Response configuration (unsigned scripts allowed, LR enabled). Works in both modes. | `config` |
-| `disconnect` | Disconnect the current LR session (internal mode) and clear machine selection. | `disconnect` |
+| `config` | Show Live Response configuration (unsigned scripts allowed, LR enabled). | `config` |
+| `disconnect` | Disconnect the current LR session and clear machine selection. | `disconnect` |
 | `machines` | List enrolled machines (cached 5 min) and prompt for selection. | `machines` |
 | `machines refresh` | Force-reload the machine list from the API, then prompt for selection. | `machines refresh` |
-| `connect [name\|id]` | Switch the active target machine. By name substring, ID prefix, or interactive picker if omitted. Auto-disconnects old session in internal mode. | `connect`, `connect blackhat`, `connect abc123` |
+| `connect [name\|id]` | Re-authenticate if expired, then select a machine. By name substring, ID prefix, or interactive picker if omitted. Auto-disconnects old session in internal mode. | `connect`, `connect blackhat`, `connect abc123` |
 | `library` | List all files in the MDE Library. | `library` |
 | `library refresh` | Force-refresh the library file list from API. | `library refresh` |
 | `library upload <path>` | Upload a local file to the MDE Library. | `library upload ./myscript.ps1` |
@@ -31,49 +28,46 @@ These commands are handled by the REPL dispatcher and do not execute on the remo
 | `actions` | List InProgress/Pending actions for the current machine. | `actions` |
 | `actions all` | List all recent actions across all statuses. | `actions all` |
 | `actions cancel <id>` | Cancel an action by full or partial GUID (prefix match). | `actions cancel abc123` |
-| `multi <command>` | Run a command on multiple machines simultaneously. Supports `-top N` and `-filter <pattern>` options. | `multi whoami`, `multi -top 3 hostname` |
+| `multi <command>` | Run a command on multiple machines. Supports `-top N` and `-filter <pattern>`. | `multi whoami`, `multi -top 3 hostname` |
+| `session` | Show current session info (machine, age, CWD). | `session` |
+| `session list` | Show all cached sessions with age and idle time. | `session list` |
 | `exit` / `quit` / `q` | Exit the shell. Disconnects the internal session first. | `exit` |
 
 ---
 
 ## Native LR Commands (25)
 
-These commands are recognized by the shell as native Live Response operations. In official
-mode, `getfile`, `putfile`, and `run` are sent as their native API types (`GetFile`,
-`PutFile`, `RunScript`). All other native commands are executed via the B64 executor stub
-in official mode. In internal mode, all native commands are sent using the session's cached
-command definitions with proper `param_id`/`value` pairs.
+These commands are recognized as native Live Response operations. In internal mode, all native commands are sent using the session's cached command definitions with proper `param_id`/`value` pairs. In official mode, `getfile`, `putfile`, and `run` use their native API types (`GetFile`, `PutFile`, `RunScript`); all other native commands go through the B64 executor.
 
-| Command | Description | OS | API Mode | Example |
-|---------|-------------|-----|----------|---------|
+| Command | Description | OS | Mode | Example |
+|---------|-------------|-----|------|---------|
 | `processes` | List running processes (PID, name, memory, CPU). | All | Both | `processes` |
-| `connections` | List active network connections (local/remote address, port, protocol). | All | Both | `connections` |
+| `connections` | List active network connections. | All | Both | `connections` |
 | `getfile <path>` | Download a file from the remote machine. | All | Both | `getfile C:\Windows\System32\drivers\etc\hosts` |
-| `putfile <name> [dest]` | Upload a file from the library to the remote working directory. Optional destination path. | All | Both | `putfile myscript.ps1` |
+| `putfile <name>` | Upload a file from the library to the remote working directory. | All | Both | `putfile myscript.ps1` |
 | `run <script> [args]` | Run a script from the MDE Library on the machine. | All | Both | `run myscript.ps1 -Param1 value1` |
 | `cd <path>` | Change the working directory on the target. Internal mode updates the session directory. | All | Both | `cd C:\Windows\Temp` |
 | `dir [path]` | List directory contents. | All | Both | `dir`, `dir C:\Windows\Temp` |
-| `findfile <name>` | Search for a file by name across all drives/volumes. Timeout: 1800s (30 min). | All | Both | `findfile suspicious.exe` |
-| `trace` | Capture a diagnostic ETW trace. Timeout: 600s (10 min). | All | Both | `trace -etl` |
-| `analyze <path>` | Submit a file for deep analysis by MDE. Timeout: 600s (10 min). | All | Both | `analyze C:\Users\Public\suspicious.exe` |
+| `findfile <name>` | Search for a file by name across all drives/volumes. Timeout: 1800s. | All | Both | `findfile suspicious.exe` |
+| `trace` | Capture a diagnostic ETW trace. Timeout: 600s. | All | Both | `trace -etl` |
+| `analyze <path>` | Submit a file for deep analysis by MDE. Timeout: 600s. | All | Both | `analyze C:\Users\Public\suspicious.exe` |
 | `remediate <path>` | Quarantine/remediate a file on the remote machine. | All | Both | `remediate file C:\malware\suspicious.exe` |
 | `undo <actionId>` | Undo a previous remediation action. | All | Both | `undo file C:\restored\file.exe` |
 | `registry <key>` | Query registry keys and values (read-only). | Windows | Both | `registry HKLM\Software\Microsoft` |
-| `scheduledtasks` | List scheduled tasks (Windows: task names/status; Linux: cron/systemd). | Windows | Both | `scheduledtasks` |
-| `persistence` | Check common persistence mechanisms (autoruns, services, startup, cron). | All | Both | `persistence` |
+| `scheduledtasks` | List scheduled tasks. | Windows | Both | `scheduledtasks` |
+| `persistence` | Check common persistence mechanisms. | All | Both | `persistence` |
 | `drivers` | List loaded drivers. | Windows | Both | `drivers` |
-| `services` | List services (Windows: name, display name, status; Linux: running daemons). | All | Both | `services` |
+| `services` | List services. | All | Both | `services` |
 | `startupfolders` | List startup folder contents. | Windows | Both | `startupfolders` |
-| `fileinfo <path>` | Get detailed file information (size, timestamps, attributes, hash, signature). 30 GB limit. | All | Both | `fileinfo C:\Windows\System32\cmd.exe` |
+| `fileinfo <path>` | Get detailed file information (size, timestamps, hash, signature). 30 GB limit. | All | Both | `fileinfo C:\Windows\System32\cmd.exe` |
 | `prefetch` | List prefetch data (recently executed programs). | Windows | Both | `prefetch` |
-| `log` | View diagnostic logs on the target machine. | All | Both | `log` |
+| `log` | View diagnostic logs. | All | Both | `log` |
 | `jobs` | List background jobs in the current LR session. | All | Internal | `jobs` |
 | `fg <jobId>` | Bring a background job to the foreground. | All | Internal | `fg 1` |
 
 ### Windows-Only Commands
 
-The following commands are designed for Windows targets and will produce a warning
-if sent to a Linux or macOS target:
+The following commands produce a warning if sent to a Linux or macOS target:
 
 - `registry`
 - `scheduledtasks`
@@ -83,16 +77,14 @@ if sent to a Linux or macOS target:
 
 ### Per-Command Timeouts
 
-Some commands have extended timeouts to account for their expected execution time:
-
 | Command | Timeout | Reason |
 |---------|---------|--------|
-| `analyze` | 600s (10 min) | Deep analysis can be slow. |
-| `findfile` | 1800s (30 min) | Full-disk search. MS API limit. |
-| `trace` | 600s (10 min) | ETW trace collection. |
-| `getfile` | 1800s (30 min) | Large file downloads. MS API limit. |
+| `analyze` | 600s (10 min) | Deep analysis can be slow |
+| `findfile` | 1800s (30 min) | Full-disk search (MS API limit) |
+| `trace` | 600s (10 min) | ETW trace collection |
+| `getfile` | 1800s (30 min) | Large file downloads (MS API limit) |
 
-All other commands default to 300s (5 min), configurable via `commandTimeoutSeconds` in config.
+All other commands use the default timeout: 1800s (server decides). The client-side `commandTimeoutSeconds` config value provides an additional ceiling.
 
 ---
 
@@ -106,25 +98,25 @@ All other commands default to 300s (5 min), configurable via `commandTimeoutSeco
 | `process` | `processes` | List running processes |
 | `netstat` | `connections` | List network connections |
 
-Aliases are resolved before command execution. Both the alias and the full command
-name work identically.
+Aliases are resolved before command execution. Both the alias and the full command name work identically.
 
 ---
 
 ## Arbitrary Commands
 
-Any input that is not a shell command, native LR command, or alias is treated as an
-arbitrary command and executed on the remote machine via the B64 executor stub.
+Any input that is not a shell command, native LR command, or alias is treated as an arbitrary command and executed on the remote machine via the B64 executor stub.
 
 **How it works:**
 
 1. The command string is Base64-encoded:
    - **Windows targets**: UTF-16-LE encoding, then Base64
    - **Linux/macOS targets**: UTF-8 encoding, then Base64
-2. The encoded payload is passed as the `-B64` argument to the executor stub
+2. The encoded payload is sent as the argument to the executor stub
 3. The executor decodes and executes the command:
-   - **Windows**: `executor_b64.ps1` decodes and runs via PowerShell `Invoke-Expression`
-   - **Linux/macOS**: `executor_b64.sh` decodes and runs via `bash`
+   - **Windows**: `executor_b64.ps1` decodes and runs via PowerShell `[ScriptBlock]::Create()`
+   - **Linux/macOS**: `executor_b64.sh` decodes and pipes through `bash`
+
+**Pipeline detection**: Commands containing pipes (`|`), semicolons (`;`), redirects (`>>`), or subexpressions (`$(`) are always B64-wrapped, even if the first word is a native LR verb. For example, `dir C:\ | Select-Object` goes through B64, not native `dir`.
 
 **Examples:**
 
@@ -136,9 +128,7 @@ cat /etc/passwd
 uname -a
 ```
 
-**Size limits:** Commands are reliable up to ~30KB after encoding. Payloads over 35KB
-may timeout, and 40KB+ are typically rejected by the API. For large scripts, use
-`library upload` + `run <script>` instead.
+**Size limits:** Commands are reliable up to ~30KB after encoding. Payloads over 35KB may timeout, and 40KB+ are typically rejected. For large scripts, use `library upload` + `run <script>` instead.
 
 ---
 
@@ -151,7 +141,7 @@ User Input
     |
     v
 1. Shell command? (help, machines, library, actions, multi, mode, status, config,
-   connect, disconnect, exit/quit/q)
+   connect, disconnect, session, exit/quit/q)
    --> YES: Handled by the REPL dispatcher. No remote execution.
    --> NO: Continue...
     |
@@ -163,11 +153,13 @@ User Input
     v
 3. Native LR command or alias?
    --> YES (alias): Resolve alias to canonical name, then...
-   --> YES (native): Route based on API mode:
-       - Official: getfile/putfile/run use native API types (GetFile/PutFile/RunScript).
-         All other native commands go through B64 executor.
-       - Internal: All native commands sent using session command definitions
-         with proper param_id/value pairs.
+   --> Has pipes/semicolons/redirects/subexpressions?
+       --> YES: Skip native routing, go to step 5 (B64 wrap)
+       --> NO: Route as native command:
+           - Official: getfile/putfile/run use native API types.
+             All others go through B64 executor.
+           - Internal: All native commands sent using session command
+             definitions with proper param_id/value pairs.
    --> NO: Continue...
     |
     v
@@ -187,8 +179,7 @@ User Input
 
 ## Multi-Command Batching (Official Mode)
 
-Official mode supports sending up to 5 `RunScript` commands in a single API call.
-This is handled internally by `Invoke-LRCommandOfficial`:
+Official mode supports sending up to 5 `RunScript` commands in a single API call. This is handled internally by `Invoke-LRCommandOfficial`:
 
 - Commands are batched in groups of 5
 - Each batch is sent as one `POST /machines/{id}/runliveresponse` with a `Commands` array
@@ -208,9 +199,7 @@ Run a single command across multiple machines simultaneously.
 | `multi -top N <command>` | Run on first N active | `multi -top 3 hostname` |
 | `multi -filter <pattern> <command>` | Run on matching machines | `multi -filter ws* processes` |
 
-The `multi` command filters enrolled machines by `healthStatus -eq 'Active'`, then pipes
-them to `Invoke-LRCommandMultiMachine`. Results are displayed as a table with MachineName,
-Status, TimeMs, and a truncated Output preview.
+The `multi` command filters enrolled machines by `healthStatus -eq 'Active'`, then runs the command on each. Results are displayed as a table with MachineName, Status, TimeMs, and a truncated Output preview.
 
 **Internal API**: Uses persistent sessions per machine (2-5s per machine).
 **Official API**: Creates separate runliveresponse actions (15-30s per machine).
@@ -236,7 +225,6 @@ The shell registers PSReadLine tab completion for:
   - `library`: `upload`, `delete`, `download`, `refresh`
   - `actions`: `all`, `cancel`, `list`
   - `machines`: `refresh`
-  - `mode`: `official`, `internal`
   - `multi`: `-top`, `-filter`
   - `help`: All commands plus `commands` and `aliases`
 - **`connect` subcommand**: Machine names from the cached machine list