feat: improve ownership interview controls (#363) (#364)

Co-authored-by: Jonathan Weinberg <2151251+jonathanweinberg@users.noreply.github.com>

Author: jonathanweinberg

README.md

@@ -31,12 +31,12 @@ For the fuller explanation, use the [visual field guide](docs/visual-field-guide
 
 For the first real run:
 
-1. Download `ShareSurfer-0.1.0-pre.33.zip` and its SHA256 file from the [current prerelease](https://github.com/jonathanweinberg/ShareSurfer/releases/tag/v0.1.0-pre.33). If that tag is not visible, use the latest published prerelease and substitute its version in the paths below.
-2. Extract to `C:\` so the release root is `C:\ShareSurfer-0.1.0-pre.33\`.
+1. Download `ShareSurfer-0.1.0-pre.34.zip` and its SHA256 file from the [current prerelease](https://github.com/jonathanweinberg/ShareSurfer/releases/tag/v0.1.0-pre.34). If that tag is not visible, use the latest published prerelease and substitute its version in the paths below.
+2. Extract to `C:\` so the release root is `C:\ShareSurfer-0.1.0-pre.34\`.
 3. Recursively unblock extracted PowerShell files:
 
    ```powershell
-   $releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+   $releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
    Get-ChildItem -LiteralPath $releaseRoot -Recurse -File |
      Where-Object { $_.Extension -in '.ps1', '.psm1', '.psd1' } |
      Unblock-File
@@ -149,7 +149,7 @@ See the [nonpermissive collector to dashboard host workflow](docs/nonpermissive-
 Use this compact pattern when the release folder has been copied to a locked-down Windows collector host:
 
 ```powershell
-$shareSurferRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$shareSurferRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $exportPath = 'C:\ShareSurfer\exports\scan-001'
 $handoffPath = 'C:\ShareSurfer\handoff\scan-001.zip'
 $inputRoot = 'C:\ShareSurfer\inputs'
@@ -232,7 +232,7 @@ Current screenshots are under [docs/visuals/dashboard-screenshots/2026-06-09-cur
 
 ## Pre-1.0 Release Packaging
 
-The first packages are unsigned but fully built. `v0.1.0-pre.33` includes the module, scripts, docs, SHA256 files, release manifest, dependency-age report, and prebuilt dashboard template assets. The manifest records `UnsignedPre1.0`.
+The first packages are unsigned but fully built. `v0.1.0-pre.34` includes the module, scripts, docs, SHA256 files, release manifest, dependency-age report, and prebuilt dashboard template assets. The manifest records `UnsignedPre1.0`.
 
 Release identity lives in [release-metadata.json](release-metadata.json). Update that file first when preparing a prerelease; packaging fails closed when the manual version or tag does not match.
 

docs/admin-ownership-import.md

@@ -133,10 +133,10 @@ Enriched rows can add these review fields:
 
 ## Step 1: Test The CSV
 
-If `v0.1.0-pre.33` is not visible yet on the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases), use the latest published prerelease and substitute that version in `$releaseRoot`.
+If `v0.1.0-pre.34` is not visible yet on the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases), use the latest published prerelease and substitute that version in `$releaseRoot`.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $sourcePath = 'C:\ShareSurfer\inputs\hr-obs.csv'
 
 Import-Module "$releaseRoot\src\ShareSurfer\ShareSurfer.psd1" -Force
@@ -192,7 +192,13 @@ New-ShareSurferOwnershipMappingProfile `
   -Force
 ```
 
-During interactive mode, press Enter to accept a suggested header, type another header, or type `S` to skip a field.
+During interactive mode, ShareSurfer keeps a controls line on screen:
+
+```text
+Enter=accept/select | 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.
 
 ## Step 3: Import A Normalized Ownership CSV
 
@@ -257,6 +263,17 @@ Join-ShareSurferOwnershipSources `
 
 In the picker, use the numbered folder and file choices to move around and toggle CSVs. The menu also lets you select all CSVs in the current folder, clear selected paths, show selected paths, go up to the parent folder, finish, or quit.
 
+After you choose source CSV files, interactive ownership enrichment asks what each file mostly describes and how much trust to place in it. The prompts use the same `Enter`, `S`, `B`, `?`, and `Q` controls where they apply. Source type choices are written in business terms:
+
+- `Identity`: people or accounts, usually HR or directory-aligned employee data.
+- `ObsContext`: OBS/OID, business-unit, or owner clues.
+- `ProjectContext`: projects, programs, apps, or WBS codes linked to OBS or owners.
+- `PathOwnership`: share, folder, UNC, or path-prefix ownership clues.
+- `GroupContext`: security groups linked to owners, OBS, projects, or business units.
+- `Mixed`: several kinds of clues or a file whose purpose is not cleanly separated.
+
+Authority choices tell reviewers how strongly to trust the file: `Authoritative` means a trusted source of record, `ReviewerHint` means useful but review-needed, `ContextOnly` means grouping context only, and `Unknown` means the trust level is unclear. `B` lets you return to an earlier source-classification prompt before the definition JSON is saved.
+
 If you already know the exact files, you can still pass them directly:
 
 ```powershell

docs/command-recipes.md

@@ -5,10 +5,10 @@ This page collects the most common first-run commands in one place. Use it when
 The examples assume the current quickstart release is unpacked here:
 
 ```text
-C:\ShareSurfer-0.1.0-pre.33\
+C:\ShareSurfer-0.1.0-pre.34\
 ```
 
-If `v0.1.0-pre.33` is not visible yet on the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases), use the latest published prerelease and substitute that version in every `ShareSurfer-0.1.0-pre.33` path and ZIP name below. The commands also assume Windows PowerShell 5.1 unless a command explicitly says otherwise.
+If `v0.1.0-pre.34` is not visible yet on the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases), use the latest published prerelease and substitute that version in every `ShareSurfer-0.1.0-pre.34` path and ZIP name below. The commands also assume Windows PowerShell 5.1 unless a command explicitly says otherwise.
 
 ## Start Here
 
@@ -49,11 +49,11 @@ If `v0.1.0-pre.33` is not visible yet on the [ShareSurfer Releases page](https:/
 
 ## Recipe 1: Unpack and Import the Release
 
-Use this on the Windows collector host after downloading `ShareSurfer-0.1.0-pre.33.zip` from the GitHub release on an approved connected workstation. If that checkpoint ZIP is not published yet, download the latest published prerelease ZIP and update `$releaseZip` and `$releaseRoot` to match it.
+Use this on the Windows collector host after downloading `ShareSurfer-0.1.0-pre.34.zip` from the GitHub release on an approved connected workstation. If that checkpoint ZIP is not published yet, download the latest published prerelease ZIP and update `$releaseZip` and `$releaseRoot` to match it.
 
 ```powershell
-$releaseZip = 'C:\Downloads\ShareSurfer-0.1.0-pre.33.zip'
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseZip = 'C:\Downloads\ShareSurfer-0.1.0-pre.34.zip'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 
 Expand-Archive -LiteralPath $releaseZip -DestinationPath 'C:\' -Force
 Get-ChildItem -LiteralPath $releaseRoot -Recurse -File |
@@ -71,7 +71,7 @@ The `Unblock-File` line clears the Windows downloaded-file block from ShareSurfe
 
 Run that manual unblock first for the no-prompt path. If you start `Start-ShareSurfer.ps1` before unblocking, Windows may still ask once for the launcher itself; after you choose **Run once**, the launcher attempts the same recursive unblock before importing ShareSurfer.
 
-Both `Test-Path` commands should return `True`. If either returns `False`, check for a doubled folder such as `C:\ShareSurfer-0.1.0-pre.33\ShareSurfer-0.1.0-pre.33`.
+Both `Test-Path` commands should return `True`. If either returns `False`, check for a doubled folder such as `C:\ShareSurfer-0.1.0-pre.34\ShareSurfer-0.1.0-pre.34`.
 
 ## Recipe 1A: Generate a Guided Startup Plan
 
@@ -84,7 +84,7 @@ If `ownership-enrichment.csv` is missing, interactive startup can offer to launc
 The easiest release-root launcher is:
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $inputRoot = 'C:\ShareSurfer\inputs'
 $exportPath = 'C:\ShareSurfer\exports\finance-001'
 
@@ -94,7 +94,7 @@ $exportPath = 'C:\ShareSurfer\exports\finance-001'
 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
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $inputRoot = 'C:\ShareSurfer\inputs'
 $exportPath = 'C:\ShareSurfer\exports\finance-001'
 
@@ -172,7 +172,7 @@ If you do not have either file yet, leave it absent. The scan recipes below only
 Use this when another team gives you a CSV with useful owner or OBS data but the headers do not match ShareSurfer's expected owner mapping format.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $sourcePath = 'C:\ShareSurfer\inputs\hr-obs.csv'
 $profilePath = 'C:\ShareSurfer\inputs\hr-obs.mapping.json'
 $normalizedPath = 'C:\ShareSurfer\inputs\normalized-ownership.csv'
@@ -206,12 +206,12 @@ 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.
+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.
 
 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.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $inputRoot = 'C:\ShareSurfer\inputs'
 $ownershipEnrichmentPath = Join-Path $inputRoot 'ownership-enrichment.csv'
 $ownershipDefinitionPath = Join-Path $inputRoot 'ownership-import.definition.json'
@@ -291,7 +291,7 @@ For more detail, see the [admin ownership import guide](admin-ownership-import.m
 Use this when you already know the share path and want a first reviewable export.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $exportPath = 'C:\ShareSurfer\exports\finance-001'
 $ownerMappingPath = 'C:\ShareSurfer\inputs\owner-mapping.csv'
 $ownershipEnrichmentPath = 'C:\ShareSurfer\inputs\ownership-enrichment.csv'
@@ -332,7 +332,7 @@ Use this recipe first if you are new to the tool. It can still record partial-da
 Use this when you know the Windows file server and share name and want ShareSurfer to collect share metadata.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $exportPath = 'C:\ShareSurfer\exports\finance-001'
 
 Import-Module "$releaseRoot\src\ShareSurfer\ShareSurfer.psd1" -Force
@@ -354,7 +354,7 @@ Use `-IncludeFiles` only when file-level rows matter for the review. Large share
 Use this when a Windows SMB target is reachable but default remote CIM or SMB cmdlets cannot prove share metadata cleanly.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $exportPath = 'C:\ShareSurfer\exports\finance-native-001'
 
 Import-Module "$releaseRoot\src\ShareSurfer\ShareSurfer.psd1" -Force
@@ -379,7 +379,7 @@ When `NetShareGetInfo` returns a path like `C:\Public\Share` for a remote target
 Use this when ShareSurfer can reach a share but `share_permissions.csv` is empty, `shares.csv` says `PartialData=True`, or `collection_errors.csv` shows share-permission or native security descriptor failures. This goes past "is the port open" and records each share-permission proof attempt.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $diagnosticPath = 'C:\ShareSurfer\diagnostics\finance-share-permissions'
 
 Import-Module "$releaseRoot\src\ShareSurfer\ShareSurfer.psd1" -Force
@@ -403,7 +403,7 @@ For a support-safe packet, review and share the redacted files under `$diagnosti
 Run this after the collector finishes.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $exportPath = 'C:\ShareSurfer\exports\finance-001'
 
 Test-ShareSurferExport -ExportPath $exportPath
@@ -430,7 +430,7 @@ Before owner signoff, open `evidence_confidence.csv` or the dashboard Scan Confi
 Use this after a scan has produced `owner_review_packets.csv` and `related_data_areas.csv`. The draft files are plain CSVs that can be edited in Excel, reviewed in a meeting, and imported back into the export folder before rebuilding the report or standalone dashboard.
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 $exportPath = 'C:\ShareSurfer\exports\finance-001'
 $decisionPath = 'C:\ShareSurfer\reviews\finance-001'
 $decisionRerunPath = Join-Path $decisionPath 'review-decisions-rerun.ps1'

docs/first-run-guide.md

@@ -8,8 +8,8 @@ If report or command terms are unfamiliar, keep the [glossary](glossary.md) open
 
 For a first useful scan:
 
-1. Extract the current `v0.1.0-pre.33` release ZIP to `C:\`. If that checkpoint tag is not visible on the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases) yet, use the latest published prerelease and substitute that version in the paths below.
-2. Use `C:\ShareSurfer-0.1.0-pre.33\` as `$releaseRoot`, or replace the version folder with the published prerelease you actually extracted.
+1. Extract the current `v0.1.0-pre.34` release ZIP to `C:\`. If that checkpoint tag is not visible on the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases) yet, use the latest published prerelease and substitute that version in the paths below.
+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.
@@ -92,17 +92,17 @@ $PSVersionTable.PSVersion
 
 The major version should be `5`.
 
-If you are using the `v0.1.0-pre.33` release ZIP, extract it to `C:\`. If that checkpoint tag is not visible yet, use the latest published prerelease and substitute that version in the paths below. The extracted release root should be:
+If you are using the `v0.1.0-pre.34` release ZIP, extract it to `C:\`. If that checkpoint tag is not visible yet, use the latest published prerelease and substitute that version in the paths below. The extracted release root should be:
 
 ```text
-C:\ShareSurfer-0.1.0-pre.33\
+C:\ShareSurfer-0.1.0-pre.34\
 ```
 
-If Windows Explorer suggests extracting to `C:\ShareSurfer-0.1.0-pre.33`, change the destination to `C:\` so you do not end up with a doubled nested folder. From PowerShell:
+If Windows Explorer suggests extracting to `C:\ShareSurfer-0.1.0-pre.34`, change the destination to `C:\` so you do not end up with a doubled nested folder. From PowerShell:
 
 ```powershell
-$releaseZip = 'C:\Downloads\ShareSurfer-0.1.0-pre.33.zip'
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseZip = 'C:\Downloads\ShareSurfer-0.1.0-pre.34.zip'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 
 Expand-Archive -LiteralPath $releaseZip -DestinationPath 'C:\' -Force
 Get-ChildItem -LiteralPath $releaseRoot -Recurse -File |
@@ -716,12 +716,12 @@ For the longer version, see the [nonpermissive collector to dashboard host workf
 
 ## Optional: Generate the Standalone Dashboard
 
-The legacy `report.html` remains the safest default report because it is generated directly by the PowerShell module. The v0.1.0-pre.33 release package from the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases), or the latest published prerelease while waiting for that checkpoint tag to appear, also includes prebuilt standalone dashboard template assets for richer novice-admin and business-owner review.
+The legacy `report.html` remains the safest default report because it is generated directly by the PowerShell module. The v0.1.0-pre.34 release package from the [ShareSurfer Releases page](https://github.com/jonathanweinberg/ShareSurfer/releases), or the latest published prerelease while waiting for that checkpoint tag to appear, also includes prebuilt standalone dashboard template assets for richer novice-admin and business-owner review.
 
 If you are using the release ZIP, you do not need Node, npm, Vite, a development server, or internet access to package the dashboard. Run the packager from Windows PowerShell 5.1 and point it at the extracted release root:
 
 ```powershell
-$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.33'
+$releaseRoot = 'C:\ShareSurfer-0.1.0-pre.34'
 
 powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$releaseRoot\scripts\New-ShareSurferStandaloneDashboard.ps1" `
   -ExportPath $exportPath `