fix: clean up startup menu compatibility (#427 #428)

Author: jonathanweinberg

README.md

@@ -50,15 +50,15 @@ For the first real run:
    powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$releaseRoot\Start-ShareSurfer.ps1" -Force
    ```
 
-   It recursively unblocks ShareSurfer PowerShell files, imports the module, and opens the **ShareSurfer Start Menu**. In a normal PowerShell ConsoleHost it uses arrow-key selection; redirected or locked-down consoles automatically fall back to numbered prompts, and you can force that behavior with `-ConsoleMode Plain`. From the menu you can review readiness, build ownership inputs, start the guided scan setup, validate exports, package the standalone dashboard, and review stop gates. The scan setup asks the first-run questions, asks whether to run intensive share-permission diagnostics before the scan, checks the `inputs` folder for ownership files, offers one ownership-input decision screen, saves `sharesurfer-startup.config.json`, and writes `operator-assistant.plan.json` plus `operator-assistant-rerun.ps1`. In the interactive path it then shows a final review screen, offers to show the generated files, and asks whether to run the generated diagnostic/scan/validate/dashboard script now. The run prompt defaults to No.
+   It recursively unblocks ShareSurfer PowerShell files, imports the module, and opens the **ShareSurfer Start Menu**. The default menu uses reliable numbered prompts for Windows PowerShell 5.1; operators who want arrow-key selection can opt in with `-ConsoleMode Enhanced`, and redirected or locked-down consoles can still use `-ConsoleMode Plain`. From the menu you can review readiness, build ownership inputs, start the guided scan setup, validate exports, package the standalone dashboard, and review stop gates. The scan setup asks the first-run questions, asks whether to run intensive share-permission diagnostics before the scan, checks the `inputs` folder for ownership files, offers one ownership-input decision screen, saves `sharesurfer-startup.config.json`, and writes `operator-assistant.plan.json` plus `operator-assistant-rerun.ps1`. In the interactive path it then shows a final review screen, offers to show the generated files, and asks whether to run the generated diagnostic/scan/validate/dashboard script now. The run prompt defaults to No.
 
 5. Choose the scan route: UNC path, `-ComputerName` and `-ShareName`, or `-SmbCollectionProvider NativeSmbRpc` when WinRM/CIM is blocked. The startup diagnostic path automatically checks whether a server-returned local path such as `C:\Public\Share` really exists on the collector; when it does not, ShareSurfer attempts the target UNC path instead and records that decision in `share-permission-diagnostics\share_permission_diagnostics.md` and `.csv`.
 6. Pick `-ObsAttribute`. The default is `extensionAttribute10`; some labs or smaller AD schemas may need another attribute such as `info`.
 7. Run the generated rerun script or `Invoke-ShareSurferScan`, then always run `Test-ShareSurferExport`.
 8. Open `report.html`, or package a real export with `scripts\New-ShareSurferStandaloneDashboard.ps1`.
 9. Review the stop gates before owner signoff or migration planning.
 
-New operators should start with the [first-run guide](docs/first-run-guide.md) and keep the [command recipes](docs/command-recipes.md) nearby. For a guided console starting point, run `Start-ShareSurfer.ps1` from the release root; it opens the ShareSurfer Start Menu unless you supply `-ConfigPath` for startup replay. After importing the module, advanced operators can run `Start-ShareSurfer` for the same menu or `Start-ShareSurferStartup` to jump directly into startup config generation. The startup flow writes a reusable JSON config and delegates to `Start-ShareSurferOperatorAssistant`; it does not collect data or change permissions until you review and run the generated rerun script. If the arrow-key menu feels rough in an older host, rerun with `-ConsoleMode Plain`. If `owner-mapping.csv` or `ownership-enrichment.csv` is missing, interactive startup first offers to use discovered files and skip missing ones, offers to build missing `ownership-enrichment.csv` from candidate CSVs, or lets you enter advanced custom paths. It can also queue a post-scan `owner-mapping-draft.csv` for the first rerun.
+New operators should start with the [first-run guide](docs/first-run-guide.md) and keep the [command recipes](docs/command-recipes.md) nearby. For a guided console starting point, run `Start-ShareSurfer.ps1` from the release root; it opens the ShareSurfer Start Menu unless you supply `-ConfigPath` for startup replay. After importing the module, advanced operators can run `Start-ShareSurfer` for the same menu or `Start-ShareSurferStartup` to jump directly into startup config generation. The startup flow writes a reusable JSON config and delegates to `Start-ShareSurferOperatorAssistant`; it does not collect data or change permissions until you review and run the generated rerun script. The default menu uses numbered prompts; use `-ConsoleMode Enhanced` only when you specifically want arrow-key selection in a console that handles it well. If `owner-mapping.csv` or `ownership-enrichment.csv` is missing, interactive startup first offers to use discovered files and skip missing ones, offers to build missing `ownership-enrichment.csv` from candidate CSVs, or lets you enter advanced custom paths. It can also queue a post-scan `owner-mapping-draft.csv` for the first rerun.
 
 ## Pause Before Owner Signoff
 

Start-ShareSurfer.ps1

@@ -22,7 +22,7 @@ param(
     [string] $AclExportMode = 'Compact',
 
     [ValidateSet('Auto', 'Enhanced', 'Plain')]
-    [string] $ConsoleMode = 'Auto',
+    [string] $ConsoleMode = 'Plain',
 
     [switch] $Interactive,
 

docs/command-recipes.md

@@ -93,7 +93,7 @@ $exportPath = 'C:\ShareSurfer\exports\finance-001'
 & "$releaseRoot\Start-ShareSurfer.ps1" -Force
 ```
 
-The menu shows readiness for ownership inputs, saved startup config, export validation, standalone dashboard packaging, and stop gates. Each menu entry previews the command it will run before asking for confirmation. A normal ConsoleHost uses arrow-key selection; add `-ConsoleMode Plain` when you want simple numbered prompts. If you want to replay an existing startup config without the menu, pass `-ConfigPath` to the same launcher.
+The menu shows readiness for ownership inputs, saved startup config, export validation, standalone dashboard packaging, and stop gates. Each menu entry previews the command it will run before asking for confirmation. The default menu uses simple numbered prompts for Windows PowerShell 5.1; add `-ConsoleMode Enhanced` only when you specifically want arrow-key selection in a console that handles it well. If you want to replay an existing startup config without the menu, pass `-ConfigPath` to the same launcher.
 
 If you already know the answers and want to generate the same files without prompts, import the module and call the startup command directly:
 

docs/first-run-guide.md

@@ -136,7 +136,7 @@ Confirm the commands are available:
 Get-Command -Module ShareSurfer
 ```
 
-Recommended: generate a guided startup plan before scanning. This does not collect data or change permissions. It recursively unblocks local ShareSurfer PowerShell files, asks the first-run questions when run interactively, asks whether to run intensive share-permission diagnostics before the scan, checks for optional ownership files in the input folder, writes a reusable startup JSON config, then writes a JSON plan and a rerun script so you can review the requested diagnostic, scan, validation, and standalone dashboard packaging steps first. Optional CSV paths are only used by the rerun script when those files exist. The menu uses arrow-key prompts in a normal ConsoleHost and falls back to numbered prompts when the console does not support raw keys; use `-ConsoleMode Plain` if an older PowerShell 5.1 host feels clunky.
+Recommended: generate a guided startup plan before scanning. This does not collect data or change permissions. It recursively unblocks local ShareSurfer PowerShell files, asks the first-run questions when run interactively, asks whether to run intensive share-permission diagnostics before the scan, checks for optional ownership files in the input folder, writes a reusable startup JSON config, then writes a JSON plan and a rerun script so you can review the requested diagnostic, scan, validation, and standalone dashboard packaging steps first. Optional CSV paths are only used by the rerun script when those files exist. The menu defaults to reliable numbered prompts for Windows PowerShell 5.1; use `-ConsoleMode Enhanced` only when you specifically want arrow-key selection in a console that handles it well.
 
 When startup reaches ownership inputs, choose **Use discovered files and skip missing files** for the safest first run. If `ownership-enrichment.csv` is missing, choose **Build ownership enrichment now** to open the multi-CSV ownership import picker when you have HR, employee, OBS, project, application, or owner CSVs that should enrich identities before the scan. Choose **Enter advanced custom paths** only when your CSVs are outside the `inputs` folder. The ownership import writes `ownership-enrichment.csv`, `ownership_context.csv`, `ownership_relationships.csv`, `ownership_import_manifest.csv`, `ownership-import.definition.json`, and `ownership-import-rerun.ps1`, then returns to the normal startup flow.
 

release-metadata.json

@@ -5,7 +5,7 @@
   "zipAssetName": "ShareSurfer-0.1.0-pre.43.zip",
   "releaseUrl": "https://github.com/jonathanweinberg/ShareSurfer/releases/tag/v0.1.0-pre.43",
   "minimumDependencyAgeDays": 7,
-  "releaseNotesSummary": "Unsigned pre-1.0 startup ACL export mode fix release. v0.1.0-pre.43 includes the v0.1.0-pre.42 export-classification performance work plus a startup/menu fix so guided runs preserve AclExportMode instead of silently falling back to FullEffective. The release-root launcher, Start Menu preview, startup JSON config, operator assistant plan, and generated rerun script now carry Compact or FullEffective consistently into Invoke-ShareSurferScan. Guided startup defaults to Compact for large operator reviews; direct Invoke-ShareSurferScan still uses its own parameter behavior and can be run with -AclExportMode Compact when desired. The package includes the built PowerShell module files, startup launcher, diagnostic scripts, documentation, hashes, release manifest, dependency-age report, and prebuilt standalone dashboard template assets.",
+  "releaseNotesSummary": "Unsigned pre-1.0 startup ACL export mode fix release. v0.1.0-pre.43 includes the v0.1.0-pre.42 export-classification performance work plus a startup/menu fix so guided runs preserve AclExportMode instead of silently falling back to FullEffective. The release-root launcher, Start Menu preview, startup JSON config, operator assistant plan, and generated rerun script now carry Compact or FullEffective consistently into Invoke-ShareSurferScan. Guided startup defaults to Compact for large operator reviews; direct Invoke-ShareSurferScan still uses its own parameter behavior and can be run with -AclExportMode Compact when desired. This release also accepts AclExportMode as a compatibility no-op for older ownership-import rerun scripts and defaults the Start Menu to reliable numbered prompts while keeping enhanced arrow-key prompts available with -ConsoleMode Enhanced. The package includes the built PowerShell module files, startup launcher, diagnostic scripts, documentation, hashes, release manifest, dependency-age report, and prebuilt standalone dashboard template assets.",
   "docsReferencePaths": [
     "README.md",
     "docs/first-run-guide.md",

src/ShareSurfer/Private/ShareSurfer.Console.ps1

@@ -4,14 +4,42 @@
 # shares one controls contract, renders through one sink, and can be tested
 # headlessly by driving the state machines with scripted commands.
 #
-# Controls contract (docs/superpowers/specs/2026-07-06-staged-sharesurfer-tui-design.md):
-#   Enter=accept | arrows/numbers=choose | S=skip | B=back | ?=help | Q=quit
+# Controls contract: prompts only advertise the actions enabled by that caller.
 #
 # Cancellation contract: prompts and wizards return results whose Action is
 # 'Cancelled'; they never throw. Flow entry points decide what cancel means.
 
 function Get-ShareSurferConsoleControlsLine {
-    'Controls: Enter=accept | arrows/numbers=choose | S=skip | B=back | ?=help | Q=quit'
+    param(
+        [switch] $AllowSkip,
+
+        [switch] $AllowBack,
+
+        [switch] $AllowQuit,
+
+        [switch] $AllowCustom,
+
+        [switch] $UseArrowKeys
+    )
+
+    $parts = New-Object System.Collections.Generic.List[string]
+    $parts.Add('Enter=select')
+    $parts.Add($(if ($UseArrowKeys) { 'arrows/numbers=choose' } else { 'numbers=choose' }))
+    if ($AllowCustom) {
+        $parts.Add('type=value')
+    }
+    if ($AllowSkip) {
+        $parts.Add('S=skip')
+    }
+    if ($AllowBack) {
+        $parts.Add('B=back')
+    }
+    $parts.Add('?=help')
+    if ($AllowQuit) {
+        $parts.Add('Q=quit')
+    }
+
+    'Controls: {0}' -f ($parts -join ' | ')
 }
 
 function Test-ShareSurferConsoleRawKeyAvailable {
@@ -242,7 +270,14 @@ function Invoke-ShareSurferConsoleChoiceCommand {
 
     if ($upper -eq '?' -or $upper -eq 'HELP') {
         $State.Action = 'Help'
-        $State.Message = 'Use Up/Down or a number to choose. Enter selects. S skips when available. B goes back when available. Q cancels when available.'
+        $helpParts = New-Object System.Collections.Generic.List[string]
+        $helpParts.Add('Use a number to choose. In enhanced console mode, Up/Down also navigates.')
+        $helpParts.Add('Enter selects.')
+        if ($AllowCustom) { $helpParts.Add('Type a custom value when the listed choices do not fit.') }
+        if ($AllowSkip) { $helpParts.Add('S skips this prompt.') }
+        if ($AllowBack) { $helpParts.Add('B returns to the previous prompt.') }
+        if ($AllowQuit) { $helpParts.Add('Q cancels this flow.') }
+        $State.Message = ($helpParts -join ' ')
         return $State
     }
 
@@ -251,18 +286,30 @@ function Invoke-ShareSurferConsoleChoiceCommand {
         $State.Action = 'Skip'
         return $State
     }
+    elseif ($upper -in @('S', 'SKIP')) {
+        $State.Message = 'Skip is not available on this prompt. Type ? for the available controls.'
+        return $State
+    }
 
     if ($upper -in @('B', 'BACK', 'BACKSPACE') -and $AllowBack) {
         $State.Done = $true
         $State.Action = 'Back'
         return $State
     }
+    elseif ($upper -in @('B', 'BACK', 'BACKSPACE')) {
+        $State.Message = 'Back is not available on this prompt. Use the review/edit choices when this flow offers them.'
+        return $State
+    }
 
     if ($upper -in @('Q', 'QUIT', 'ESC', 'ESCAPE') -and $AllowQuit) {
         $State.Done = $true
         $State.Action = 'Cancelled'
         return $State
     }
+    elseif ($upper -in @('Q', 'QUIT', 'ESC', 'ESCAPE')) {
+        $State.Message = 'Quit is not available on this prompt. Type ? for the available controls.'
+        return $State
+    }
 
     if ($text -match '^\d+$') {
         $index = [int]$text
@@ -350,7 +397,17 @@ function Get-ShareSurferConsoleChoiceScreen {
         [Parameter(Mandatory = $true)]
         [string] $Title,
 
-        [string] $HelpText = ''
+        [string] $HelpText = '',
+
+        [switch] $AllowSkip,
+
+        [switch] $AllowBack,
+
+        [switch] $AllowQuit,
+
+        [switch] $AllowCustom,
+
+        [switch] $UseArrowKeys
     )
 
     $lines = New-Object System.Collections.Generic.List[string]
@@ -359,7 +416,7 @@ function Get-ShareSurferConsoleChoiceScreen {
     if (-not [string]::IsNullOrWhiteSpace($HelpText)) {
         $lines.Add($HelpText)
     }
-    $lines.Add((Get-ShareSurferConsoleControlsLine))
+    $lines.Add((Get-ShareSurferConsoleControlsLine -AllowSkip:$AllowSkip -AllowBack:$AllowBack -AllowQuit:$AllowQuit -AllowCustom:$AllowCustom -UseArrowKeys:$UseArrowKeys))
     $lines.Add('')
     for ($index = 0; $index -lt @($State.Options).Count; $index++) {
         $option = @($State.Options)[$index]
@@ -385,6 +442,16 @@ function Show-ShareSurferConsoleChoice {
 
         [string] $HelpText = '',
 
+        [switch] $AllowSkip,
+
+        [switch] $AllowBack,
+
+        [switch] $AllowQuit,
+
+        [switch] $AllowCustom,
+
+        [switch] $UseArrowKeys,
+
         [switch] $ClearBeforeRender
     )
 
@@ -396,7 +463,7 @@ function Show-ShareSurferConsoleChoice {
         }
     }
 
-    Write-ShareSurferConsoleLines -Lines (Get-ShareSurferConsoleChoiceScreen -State $State -Title $Title -HelpText $HelpText)
+    Write-ShareSurferConsoleLines -Lines (Get-ShareSurferConsoleChoiceScreen -State $State -Title $Title -HelpText $HelpText -AllowSkip:$AllowSkip -AllowBack:$AllowBack -AllowQuit:$AllowQuit -AllowCustom:$AllowCustom -UseArrowKeys:$UseArrowKeys)
 }
 
 function Read-ShareSurferConsoleChoice {
@@ -420,7 +487,7 @@ function Read-ShareSurferConsoleChoice {
         [switch] $AllowCustom,
 
         [ValidateSet('Auto', 'Enhanced', 'Plain')]
-        [string] $ConsoleMode = 'Auto',
+        [string] $ConsoleMode = 'Plain',
 
         $Capabilities = $null
     )
@@ -436,7 +503,7 @@ function Read-ShareSurferConsoleChoice {
     $renderedOnce = $false
     while (-not $state.Done) {
         if ($needsRender) {
-            Show-ShareSurferConsoleChoice -State $state -Title $Title -HelpText $HelpText -ClearBeforeRender:([bool]$renderBehavior.ClearBeforeRender -and $renderedOnce)
+            Show-ShareSurferConsoleChoice -State $state -Title $Title -HelpText $HelpText -AllowSkip:$AllowSkip -AllowBack:$AllowBack -AllowQuit:$AllowQuit -AllowCustom:$AllowCustom -UseArrowKeys:$useRawKeys -ClearBeforeRender:([bool]$renderBehavior.ClearBeforeRender -and $renderedOnce)
             $renderedOnce = $true
             $needsRender = $false
         }
@@ -524,7 +591,12 @@ function Invoke-ShareSurferConsoleTextCommand {
             [string]$State.HelpText
         }
         else {
-            'Type a value and press Enter, or press Enter alone to accept the default. S skips when available. B goes back when available. Q cancels when available.'
+            $textHelpParts = New-Object System.Collections.Generic.List[string]
+            $textHelpParts.Add('Type a value and press Enter, or press Enter alone to accept the default.')
+            if ($AllowSkip) { $textHelpParts.Add('S skips this prompt.') }
+            if ($AllowBack) { $textHelpParts.Add('B returns to the previous prompt.') }
+            if ($AllowQuit) { $textHelpParts.Add('Q cancels this flow.') }
+            ($textHelpParts -join ' ')
         }
         return $State
     }
@@ -607,7 +679,7 @@ function Read-ShareSurferConsoleBoolean {
         [switch] $AllowQuit,
 
         [ValidateSet('Auto', 'Enhanced', 'Plain')]
-        [string] $ConsoleMode = 'Auto'
+        [string] $ConsoleMode = 'Plain'
     )
 
     $options = @(
@@ -899,7 +971,7 @@ function Show-ShareSurferPromptChoice {
         [switch] $AllowQuit
     )
 
-    Show-ShareSurferConsoleChoice -State $State -Title $Title -HelpText $HelpText
+    Show-ShareSurferConsoleChoice -State $State -Title $Title -HelpText $HelpText -AllowSkip:$AllowSkip -AllowBack:$AllowBack -AllowQuit:$AllowQuit
 }
 
 function Read-ShareSurferPromptChoice {

src/ShareSurfer/Public/Join-ShareSurferOwnershipSources.ps1

@@ -35,6 +35,10 @@ function Join-ShareSurferOwnershipSources {
         [ValidateSet('Auto', 'ActiveDirectory', 'Ldap', 'DirectoryOnly')]
         [string] $AdLookupMode = 'Auto',
 
+        # Compatibility shim for older ownership-import rerun scripts that
+        # accidentally included this scan-only setting. Ownership import ignores it.
+        [string] $AclExportMode = '',
+
         [string[]] $ForbiddenOu = @(),
 
         [switch] $Interactive,