Prerequisites
馃挕 Summary
ScubaGear now exports a growing set of user-facing commands (Invoke-SCuBA, Invoke-SCuBACached, Invoke-SCuBADiff, New-SCuBAConfig, Start-SCuBAConfigApp, Start-SCuBAConfigAnalyzer, Show-SCuBABaselinePolicyViewer, plus setup/dependency commands). New and returning users struggle to know which command to use, when, and why without reading several long docs. This issue adds two low-cost, high-value discoverability aids:
- A tool-selection matrix page in
docs/: a one-screen cheat sheet mapping each command to a BLUF, "use it when," and "why it matters."
- A
-Help summary surfaced from the module itself so users get the same at-a-glance guidance directly in the terminal, without leaving PowerShell.
Motivation and context
- The command surface keeps expanding; existing docs are thorough but require a lot of reading to answer "which one do I run?"
- Users often discover commands by accident or word-of-mouth, then reach for the wrong tool (e.g., re-scanning when
Invoke-SCuBACached or Invoke-SCuBADiff would do).
- A concise decision aid - in docs and in-terminal - shortens time-to-first-success and reduces support questions.
Implementation notes
Docs (partially drafted)
docs/misc/tool-selection-matrix.md with two matrices:
- Configuration & analysis tools (
New-SCuBAConfig, Start-SCuBAConfigApp, Start-SCuBAConfigAnalyzer, Show-SCuBABaselinePolicyViewer, Invoke-SCuBADiff).
- Core assessment commands (
Invoke-SCuBA, Invoke-SCuBACached, Disconnect-SCuBATenant, Install-ScubaDependencies, Install-OPAforSCuBA, Get-ScubaGearDependencyStatus, Update-ScubaGear).
- Include a Mermaid flow showing how the tools chain together.
- Link the page from
README.md (Configuration & Usage + Additional Resources).
In-terminal help
- Add a lightweight help summary command, e.g.
Get-ScubaHelp (verb-approved) that prints the same matrix content as a formatted table grouped by category, with a one-line BLUF per command and a pointer to the docs page.
- Consider a
-Help switch on Invoke-SCuBA that routes to the same summary, since Invoke-SCuBA is the most common entry point and where users land first.
- Source the summary from a single data structure (hashtable/JSON) so the docs matrix and the in-terminal output can be generated/validated from one source of truth and won't drift.
- Keep it dependency-free and offline; no Graph/tenant calls.
- Export the new command in
ScubaGear.psd1 (FunctionsToExport) and add a comment-based help block.
Acceptance criteria
Prerequisites
馃挕 Summary
ScubaGear now exports a growing set of user-facing commands (
Invoke-SCuBA,Invoke-SCuBACached,Invoke-SCuBADiff,New-SCuBAConfig,Start-SCuBAConfigApp,Start-SCuBAConfigAnalyzer,Show-SCuBABaselinePolicyViewer, plus setup/dependency commands). New and returning users struggle to know which command to use, when, and why without reading several long docs. This issue adds two low-cost, high-value discoverability aids:docs/: a one-screen cheat sheet mapping each command to a BLUF, "use it when," and "why it matters."-Helpsummary surfaced from the module itself so users get the same at-a-glance guidance directly in the terminal, without leaving PowerShell.Motivation and context
Invoke-SCuBACachedorInvoke-SCuBADiffwould do).Implementation notes
Docs (partially drafted)
docs/misc/tool-selection-matrix.mdwith two matrices:New-SCuBAConfig,Start-SCuBAConfigApp,Start-SCuBAConfigAnalyzer,Show-SCuBABaselinePolicyViewer,Invoke-SCuBADiff).Invoke-SCuBA,Invoke-SCuBACached,Disconnect-SCuBATenant,Install-ScubaDependencies,Install-OPAforSCuBA,Get-ScubaGearDependencyStatus,Update-ScubaGear).README.md(Configuration & Usage + Additional Resources).In-terminal help
Get-ScubaHelp(verb-approved) that prints the same matrix content as a formatted table grouped by category, with a one-line BLUF per command and a pointer to the docs page.-Helpswitch onInvoke-SCuBAthat routes to the same summary, sinceInvoke-SCuBAis the most common entry point and where users land first.ScubaGear.psd1(FunctionsToExport) and add a comment-based help block.Acceptance criteria
docs/misc/tool-selection-matrix.mdexists with both matrices (BLUF / when / why) and a Mermaid diagram.README.mdlinks to the new matrix page in at least one discoverable location.Get-ScubaHelpand/orInvoke-SCuBA -Help) that lists each user-facing command with a one-line BLUF, grouped by category, and points to the docs page.ScubaGear.psd1and has comment-based help.CONTENTSTYLEGUIDE.mdand pass PSScriptAnalyzer.