From fd3e979c4fd24f08495b90abd1ce7922e26022ab Mon Sep 17 00:00:00 2001
From: Adam Driscoll <adamdriscoll@users.noreply.github.com>
Date: Tue, 21 Jul 2026 11:48:23 -0500
Subject: [PATCH] Clarify empty PSCommander config startup

Handle empty config.ps1 files by writing the starter toolbar configuration, matching the missing-file startup behavior. Update README guidance to explain that configuration commands belong in config.ps1 and are not automatically persisted from an interactive session.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 README.md                    | 11 +++++------
 pscommander/PSCommander.psm1 | 28 ++++++++++++++++++++++------
 2 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index a9cb62d..40e3f7d 100644
--- a/README.md
+++ b/README.md
@@ -28,16 +28,15 @@ Install-Commander
 
 ## Configuration
 
-PSCommander is configured using a single PS1 file. This file is stored within your documents folder. To create a new config file, you can use the following command.
+PSCommander is configured using a single PS1 file. This file is stored within your documents folder at `Documents\PSCommander\config.ps1`. To create the file with a starter configuration and open it in the editor, run:
 
 ```powershell
-$Documents = [Environment]::GetFolderPath('MyDocuments')
-$Commander = Join-Path $Documents 'PSCommander'
-New-Item $Commander -ItemType Directory 
-New-Item (Join-Path $Commander 'config.ps1')
+Start-Commander
 ```
 
-PSCommander will use this configuration file to load settings. Any changes to the file will result in PSCommander reconfiguring itself. If you don't have PSCommander running yet, you can use `Start-Commander`.
+PSCommander will use this configuration file to load settings. Add commands such as `New-CommanderSchedule`, `New-CommanderHotKey`, or `New-CommanderToolbarIcon` directly to `config.ps1`. Running those commands in a regular PowerShell session returns configuration objects for that session; it does not automatically save them to `config.ps1`.
+
+If you create an empty `config.ps1` manually, `Start-Commander` will add a starter toolbar icon configuration the first time it sees the empty file. Any changes to the file will result in PSCommander reconfiguring itself. If you don't have PSCommander running yet, you can use `Start-Commander`.
 
 ```powershell
 Start-Commander 
diff --git a/pscommander/PSCommander.psm1 b/pscommander/PSCommander.psm1
index 7da1be2..12f0bf6 100644
--- a/pscommander/PSCommander.psm1
+++ b/pscommander/PSCommander.psm1
@@ -421,14 +421,30 @@ function Start-Commander {
         $ConfigPath = [IO.Path]::Combine($Documents, 'PSCommander', 'config.ps1')
     }
 
+    $ConfigDirectory = Split-Path -Path $ConfigPath -Parent
+    $DefaultConfiguration = @"
+New-CommanderToolbarIcon -MenuItem @(
+    New-CommanderMenuItem -Text 'Documentation' -Action {
+        Start-Process 'https://docs.poshtools.com/powershell-pro-tools-documentation/pscommander'
+    }
+)
+"@
+
+    $OpenConfigEditor = $false
+
     if (-not (Test-Path $ConfigPath)) {
         Write-Warning "Configuration file for PSCommander not found. Creating config file..."
-        New-Item -Path (Join-Path $Documents 'PSCommander') -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-        "New-CommanderToolbarIcon -MenuItem @( 
-    New-CommanderMenuItem -Text 'Documentation' -Action { 
-        Start-Process 'https://docs.poshtools.com/powershell-pro-tools-documentation/pscommander' 
-    } 
-)" | Out-File $ConfigPath 
+        New-Item -Path $ConfigDirectory -ItemType Directory -Force | Out-Null
+        Set-Content -Path $ConfigPath -Value $DefaultConfiguration -Encoding UTF8
+        $OpenConfigEditor = $true
+    }
+    elseif ((Get-Item -Path $ConfigPath).Length -eq 0) {
+        Write-Warning "Configuration file for PSCommander is empty. Adding starter configuration..."
+        Set-Content -Path $ConfigPath -Value $DefaultConfiguration -Encoding UTF8
+        $OpenConfigEditor = $true
+    }
+
+    if ($OpenConfigEditor) {
         Start-Process -FilePath "$PSScriptRoot\psscriptpad.exe" -ArgumentList @("-c `"$ConfigPath`"")
     }