feat: add staged TUI console wizard (#367)

Adds the staged text-console layer, ownership import wizard controls, release-root Start Menu launcher integration, exact menu command previews, safer no-suggestion header mapping, and updated operator docs.\n\nValidated with local PowerShell tests (131/131), dashboard tests (53/53), dashboard build, git diff --check, and GitHub CI.

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, asks the first-run questions, asks whether to run intensive share-permission diagnostics before the scan, checks the `inputs` folder for ownership files, offers to build missing `ownership-enrichment.csv` evidence from CSVs, saves `sharesurfer-startup.config.json`, and writes `operator-assistant.plan.json` plus `operator-assistant-rerun.ps1`. In the interactive path it then offers to show those 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**. From that 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 to build missing `ownership-enrichment.csv` evidence from CSVs, saves `sharesurfer-startup.config.json`, and writes `operator-assistant.plan.json` plus `operator-assistant-rerun.ps1`. In the interactive path it then offers to show those 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 or `Start-ShareSurferStartup` after importing the module. 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 `owner-mapping.csv` or `ownership-enrichment.csv` is missing, interactive startup can help build enrichment from candidate CSVs and can 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. If `owner-mapping.csv` or `ownership-enrichment.csv` is missing, interactive startup can help build enrichment from candidate CSVs and can queue a post-scan `owner-mapping-draft.csv` for the first rerun.
 
 ## Pause Before Owner Signoff
 
@@ -77,7 +77,7 @@ Stop or document the gap before business-owner approval when any of these are tr
 
 | Workflow | Commands and scripts |
 | --- | --- |
-| Guided first run | `Start-ShareSurfer.ps1`, `Start-ShareSurferStartup`, `Start-ShareSurferOperatorAssistant` |
+| Guided first run | `Start-ShareSurfer.ps1`, `Start-ShareSurfer`, `Start-ShareSurferStartup`, `Start-ShareSurferOperatorAssistant` |
 | Lab and fixture planning | `New-ShareSurferLabFixture`, `scripts\Invoke-ShareSurferLabValidation.ps1` |
 | Scan collection | `Invoke-ShareSurferScan` |
 | Optional readiness and diagnostics | `Invoke-ShareSurferOpenFileAssessment`, `Invoke-ShareSurferPortProtocolAssessment`, `Invoke-ShareSurferFileShareConnectivityAssessment`, `Invoke-ShareSurferSharePermissionDiagnostic` |

Start-ShareSurfer.ps1

@@ -4,8 +4,21 @@ param(
 
     [string] $SaveConfigPath = '',
 
+    [string] $InputRoot = '',
+
+    [string] $ExportPath = '',
+
+    [string] $StandaloneDashboardPath = '',
+
+    [string] $ObsAttribute = 'extensionAttribute10',
+
+    [ValidateSet('Auto', 'ActiveDirectory', 'Ldap', 'DirectoryOnly')]
+    [string] $AdLookupMode = 'Auto',
+
     [switch] $Interactive,
 
+    [switch] $StartupOnly,
+
     [switch] $Force
 )
 
@@ -92,8 +105,36 @@ if (-not (Test-Path -LiteralPath $modulePath -PathType Leaf)) {
 
 Import-Module $modulePath -Force
 
+if ([string]::IsNullOrWhiteSpace($InputRoot)) {
+    $InputRoot = Join-Path $releaseRoot 'inputs'
+}
+
+if ([string]::IsNullOrWhiteSpace($ExportPath)) {
+    $ExportPath = Join-Path (Join-Path $releaseRoot 'exports') 'startup-scan'
+}
+
+if ([string]::IsNullOrWhiteSpace($StandaloneDashboardPath)) {
+    $StandaloneDashboardPath = Join-Path $ExportPath 'standalone-dashboard'
+}
+
+if ([string]::IsNullOrWhiteSpace($ConfigPath) -and [string]::IsNullOrWhiteSpace($SaveConfigPath) -and -not $StartupOnly) {
+    Start-ShareSurfer `
+        -ReleaseRoot $releaseRoot `
+        -InputRoot $InputRoot `
+        -ExportPath $ExportPath `
+        -StandaloneDashboardPath $StandaloneDashboardPath `
+        -ObsAttribute $ObsAttribute `
+        -AdLookupMode $AdLookupMode
+    return
+}
+
 $startupParams = @{
     ReleaseRoot = $releaseRoot
+    InputRoot = $InputRoot
+    ExportPath = $ExportPath
+    StandaloneDashboardPath = $StandaloneDashboardPath
+    ObsAttribute = $ObsAttribute
+    AdLookupMode = $AdLookupMode
 }
 
 if (-not [string]::IsNullOrWhiteSpace($ConfigPath)) {

docs/admin-ownership-import.md

@@ -192,13 +192,13 @@ New-ShareSurferOwnershipMappingProfile `
   -Force
 ```
 
-During interactive mode, ShareSurfer keeps a controls line on screen:
+During interactive mode, ShareSurfer walks one guided screen per field. Each screen shows the step counter, the suggested header when there is one, the source CSV's headers as a numbered list, a short explanation of why the field matters, and this controls line:
 
 ```text
-Enter=accept/select | S=skip | B=back | ?=help | Q=quit
+Enter=accept | numbers=choose | type a header name | /text=filter | S=skip | B=back | ?=help | Q=quit
 ```
 
-Press Enter to accept a suggested header, type another header name when you know it, press `S` to deliberately leave that ShareSurfer field blank, or press `B` to go back and fix the previous field. If there is no confident suggestion and the source has fewer than 10 headers, pressing Enter opens a small selector so you can choose the right header with arrow keys where the console supports them, or by number in simpler hosts.
+Press Enter to accept the suggested header. When there is no suggestion, ShareSurfer keeps you on that field and asks you to choose a numbered header, type a header name, filter with `/text`, or press `S` to deliberately leave that ShareSurfer field blank. Press `B` to go back and fix the previous field, or press `Q` to cancel without writing any files. If you type a header name that is not in the CSV, ShareSurfer says so on screen and records it as a warning in the saved mapping profile so it can be reviewed later.
 
 ## Step 3: Import A Normalized Ownership CSV
 

docs/command-recipes.md

@@ -81,7 +81,7 @@ When run interactively, the startup script offers to show the generated JSON/pla
 
 If `ownership-enrichment.csv` is missing, interactive startup can offer to launch the same `Join-ShareSurferOwnershipSources -Interactive -BrowseForCsv -IncludeContextGraph` workflow shown in Recipe 2A. That creates the enrichment, context graph, manifest, definition JSON, and reusable ownership import rerun script before startup continues. If `owner-mapping.csv` is missing, startup can add a post-scan `New-ShareSurferOwnerMappingDraft` step to the generated rerun script so the first scan can produce `owner-mapping-draft.csv` for an admin to fill and save as `owner-mapping.csv`.
 
-The easiest release-root launcher is:
+The easiest release-root launcher opens the ShareSurfer Start Menu:
 
 ```powershell
 $releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
@@ -91,6 +91,8 @@ $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. 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:
 
 ```powershell
@@ -206,7 +208,7 @@ This recipe creates three reusable files:
 - `normalized-ownership.csv`: canonical ownership rows for review.
 - `ownership-import-rerun.ps1`: reusable commands to retest the source and regenerate the normalized CSV without repeating the header interview.
 
-If you need ShareSurfer to ask you about each header in the console, add `-Interactive` to `New-ShareSurferOwnershipMappingProfile`. The saved rerun file still uses the profile afterward. Interactive prompts show `Enter=accept/select | S=skip | B=back | ?=help | Q=quit`; use `B` to fix the previous field, `S` to intentionally leave a ShareSurfer field blank, and `?` for a reminder. When there is no suggestion and the source has fewer than 10 headers, Enter opens a small selector with arrow-key support where available and numbered fallback everywhere else.
+If you need ShareSurfer to ask you about each header in the console, add `-Interactive` to `New-ShareSurferOwnershipMappingProfile`. The saved rerun file still uses the profile afterward. Interactive prompts show `Enter=accept/select | S=skip | B=back | ?=help | Q=quit`; use `B` to fix the previous field, `S` to intentionally leave a ShareSurfer field blank, and `?` for a reminder. When there is no suggestion and the source has fewer than 10 headers, the prompt keeps the numbered header list on screen and asks you to choose a number, type a header name, or press `S` to skip deliberately.
 
 To gather AD data from an HR or OBS file before scanning, create an enrichment CSV. ShareSurfer uses employee ID or employee number values from the source CSV to look up matching AD accounts when `-AdLookupMode Auto` or `ActiveDirectory` can read the directory. It fills available account, mail, title, office, manager, and OBS fields, then writes a local CSV that travels with the scan evidence.
 

docs/first-run-guide.md

@@ -12,7 +12,7 @@ For a first useful scan:
 2. Use `C:\ShareSurfer-0.1.0-pre.34\` as `$releaseRoot`, or replace the version folder with the published prerelease you actually extracted.
 3. Run the recursive `Unblock-File` command in Step 1 before importing the module.
 4. Pick one known share and the correct `-ObsAttribute`.
-5. Recommended: run `Start-ShareSurfer.ps1` or `Start-ShareSurferStartup` to generate a reusable first-run JSON config, plan, and rerun script.
+5. Recommended: run `Start-ShareSurfer.ps1` to open the ShareSurfer Start Menu, then choose the guided scan setup when you are ready to generate a reusable first-run JSON config, plan, and rerun script. If you already know the startup command you want, you can still import the module and run `Start-ShareSurferStartup` directly.
 6. If HR, employee, OBS, project, or owner CSVs exist, let the startup prompts help build `ownership-enrichment.csv`, or normalize them before scanning with the ownership import commands.
 7. Run the collector, validate the export, and build `report.html`.
 8. Package the standalone dashboard from the validated export only when you need the richer local dashboard.

docs/ownership-csv-ingest-quick-reference.md

@@ -69,13 +69,13 @@ New-ShareSurferOwnershipMappingProfile `
   -Force
 ```
 
-During interactive mode, ShareSurfer asks which source CSV header should map to each ShareSurfer field and keeps this controls line visible:
+During interactive mode, ShareSurfer walks one guided screen per field, showing the step counter, the suggestion, the CSV's headers as a numbered list, and why the field matters, with this controls line visible:
 
 ```text
-Enter=accept/select | S=skip | B=back | ?=help | Q=quit
+Enter=accept | numbers=choose | type a header name | /text=filter | S=skip | B=back | ?=help | Q=quit
 ```
 
-Press Enter to accept a suggestion, type a different header when you already know it, press `S` to intentionally leave a field blank, or press `B` to go back and fix the previous field. If ShareSurfer does not have a suggestion and the CSV has fewer than 10 headers, pressing Enter opens a small selector. Arrow keys work in normal consoles; numbered selection is used as the fallback.
+Press Enter to accept a suggestion. When there is no suggestion, choose a numbered header, type a header name, type `/text` to filter a long header list, or press `S` to intentionally leave the field blank. Press `B` to go back and fix the previous field, or press `Q` to cancel without writing any files. A typed header that is not in the CSV is called out on screen and recorded as a warning in the saved mapping profile.
 
 ## 5. Normalize The CSV