Review exit codes / prep for release (#15)

* Remove-FileList and Remove-DirectoryList — added a FailedCount property on their result object.
Previously the catch block called Write-Warning and Write-Error but neither bubbled up to the outer try/catch (the inner catch consumed the exception), so failures were invisible to the exit code logic. Now failures increment FailedCount and the error message is surfaced via Write-Warning with the exception message included for diagnostics.
Issue #11

* Updated comments explaining exit codes

* Opportunistic fix:  -Whatif not displaying items that would be deleted

* Target working folder, not parent.  Reversing an idea that seemed good at the time...

* Comments updated - problem in letting Claude edit

* Streamline parameters: -ExcludeDirectoryPattern replace -ExcludeDirPattern + -ExcludeDirectories

* Streamline parameters: -ExcludeDirectoryPattern replace -ExcludeDirPattern + -ExcludeDirectories

* Streamline parameters: -ExcludeDirectoryPattern replace -ExcludeDirPattern + -ExcludeDirectories

* Document supported exit codes in Readme for #11

Author: darianmiller

README.md

@@ -37,7 +37,7 @@ pwsh -File .\delphi-clean.ps1 -Level deep -Json
 - Optional structured output via `-PassThru`
 - Supports the `-WhatIf` dry-run mode
 - Add extra file patterns with `-IncludeFilePattern`
-- Exclude directories by wildcard pattern with `-ExcludeDirPattern`
+- Exclude directories by wildcard pattern with `-ExcludeDirectoryPattern`
 - Send items to the recycle bin / trash instead of permanent deletion with `-RecycleBin`
 
 ---
@@ -129,16 +129,6 @@ Outputs a JSON summary including:
 
 ---
 
-### Exclude Directories
-
-```powershell
-pwsh -File .\delphi-clean.ps1 -ExcludeDirectories .git,.vs,.idea
-```
-
-Matches exact directory names. Default exclusions are `.git`, `.vs`, and `.claude`.
-
----
-
 ### Include Extra File Patterns
 
 ```powershell
@@ -154,13 +144,14 @@ project-specific artifacts not covered by the standard levels.
 ### Exclude Directory Patterns
 
 ```powershell
-pwsh -File .\delphi-clean.ps1 -ExcludeDirPattern 'vendor*'
-pwsh -File .\delphi-clean.ps1 -ExcludeDirPattern 'vendor*','assets'
+pwsh -File .\delphi-clean.ps1 -ExcludeDirectoryPattern 'vendor*'
+pwsh -File .\delphi-clean.ps1 -ExcludeDirectoryPattern 'vendor*','assets'
 ```
 
 Skips any directory whose name matches one of the given wildcard patterns.
-Unlike `-ExcludeDirectories`, patterns are matched with `-like` so wildcards
-(`*`, `?`) are supported.
+Patterns are matched with `-like` so wildcards (`*`, `?`) are supported.
+
+Specific directories are excluded by default: `.git`, `.vs`, and `.claude`.
 
 ---
 
@@ -223,6 +214,18 @@ Includes everything in `standard`, plus:
 
 ---
 
+## Exit Codes
+
+```text
+  0 = success: every matched item was removed (or WhatIf run, or nothing to clean)
+  1 = fatal:   unhandled exception before or during the scan phase - bad root path,
+               unsupported platform for -RecycleBin, scan error, etc.
+  2 = partial: the script reached the removal phase but at least one item could not
+               be deleted or recycled; successfully removed items are not rolled back
+```
+
+---
+
 ## Maturity
 
 This repository is currently `incubator` and is under active development.

docs/cleanup-levels.md

@@ -1,7 +1,6 @@
 # delphi-clean levels
 
-This document defines the cleanup levels and per-invocation extension
-parameters used by `delphi-clean.ps1`.
+This document defines the default cleanup levels used by `delphi-clean.ps1`.
 
 Each level is cumulative:
 
@@ -95,58 +94,3 @@ Includes everything in `standard`, plus the following additional items.
 ### Additional Directories
 
 - `__recovery`
-
----
-
-## Per-invocation extension parameters
-
-These parameters are independent of the chosen level and can be combined
-with any level.
-
-### `-IncludeFilePattern <string[]>`
-
-Adds one or more extra wildcard file patterns to the deletion set for this
-run.  Use this for project-specific files that are intentionally omitted
-from the built-in levels.
-
-Example -- delete compiled resource files in addition to the `basic` set:
-
-    delphi-clean.ps1 -Level basic -IncludeFilePattern '*.res'
-
-Example -- delete multiple extra patterns:
-
-    delphi-clean.ps1 -Level standard -IncludeFilePattern '*.res','*.mab'
-
-### `-ExcludeDirPattern <string[]>`
-
-Skips any directory whose name matches one of the supplied wildcard
-patterns.  This supplements the fixed `-ExcludeDirectories` list and is
-useful when a project folder (such as `assets` or a vendor subtree)
-contains files that would otherwise match the cleanup patterns.
-
-Example -- protect an assets folder from cleanup:
-
-    delphi-clean.ps1 -Level basic -ExcludeDirPattern 'assets'
-
-Example -- wildcard to protect all vendor-prefixed folders:
-
-    delphi-clean.ps1 -Level standard -ExcludeDirPattern 'vendor*'
-
-Both parameters may be combined:
-
-    delphi-clean.ps1 -Level basic -IncludeFilePattern '*.res' -ExcludeDirPattern 'assets','vendor*'
-
-### `-RecycleBin`
-
-Sends deleted items to the platform trash instead of permanently removing them.
-Supported on Windows (Recycle Bin), macOS (`~/.Trash/`), and Linux
-(`~/.local/share/Trash/` per the FreeDesktop spec).
-
-Example:
-
-    delphi-clean.ps1 -Level standard -RecycleBin
-
-Can be combined with `-WhatIf` to preview which items would be recycled without
-making any changes:
-
-    delphi-clean.ps1 -Level standard -RecycleBin -WhatIf