Clean up end-user documentation

README.md

@@ -1,104 +1,151 @@
 # CsoKit
 
-CsoKit is a Windows x64 toolkit for PSP ISO and CSO files. Use the desktop app for normal work, or the CLI when you want scripting and exact control.
+CsoKit is a Windows x64 command-line tool for PSP ISO and compressed disc images.
 
-## Download
+It supports detection, inspection, verification, compression, decompression, and conservative rebuilding of readable containers.
 
-Grab the latest Windows x64 package from the [Releases page](https://github.com/HAKAMIQ/CsoKit/releases/latest):
+## Installation
 
-    csokit-*-win-x64.zip
+1. Download the latest Windows x64 ZIP from:
+   https://github.com/HAKAMIQ/CsoKit/releases/latest
+2. Extract the complete ZIP into one folder.
+3. Keep `csokit.exe` and `CsoKit.Native.dll` together.
+4. No installer is required.
 
-Extract it anywhere. Keep `CsoKit.Native.dll` next to the executables.
+## First check
 
-## Quick start
+    .\csokit.exe --version
+    .\csokit.exe native-info
+    .\csokit.exe --help
 
-Desktop app:
+`native-info` should report that the native backend and codecs are available.
 
-    .\CsoKit.App.exe
+## Detect the input format
 
-CLI help:
+    .\csokit.exe detect ".\game.iso"
+    .\csokit.exe detect ".\game.cso"
 
-    .\csokit.exe --help
+## Inspect a compressed image
 
-Version:
+    .\csokit.exe info ".\game.cso"
 
-    .\csokit.exe --version
+## Analyze a PSP ISO
 
-## Common commands
+    .\csokit.exe analyze ".\game.iso" --psp
 
-Show CSO information:
+This checks the PSP ISO structure without changing the file.
 
-    .\csokit.exe info ".\game.cso"
+## Verify a compressed image
 
-Verify a CSO file:
+Basic verification:
 
     .\csokit.exe verify ".\game.cso"
 
-Deep-verify and calculate SHA256:
+Deep verification with SHA-256:
 
     .\csokit.exe verify ".\game.cso" --deep --sha256
 
-Detect an input format:
+Verification supports CSO, ZSO, and DAX where indicated by the command help.
 
-    .\csokit.exe detect ".\game.iso"
+## Compress ISO to CSO
 
-Analyze a PSP ISO:
+Recommended:
 
-    .\csokit.exe analyze ".\game.iso" --psp
+    .\csokit.exe compress ".\game.iso" --profile game-safe
 
-Compress ISO to CSO:
+Choose the output file:
 
-    .\csokit.exe compress ".\game.iso"
+    .\csokit.exe compress ".\game.iso" -o ".\game.cso" --profile game-safe
 
-Use the fast profile:
+Faster compression:
 
     .\csokit.exe compress ".\game.iso" --profile fast
 
-Decompress CSO to ISO:
+Estimate size without creating a file:
+
+    .\csokit.exe compress ".\game.iso" --measure
+
+## Decompress CSO to ISO
 
-    .\csokit.exe decompress ".\game.cso"
+    .\csokit.exe decompress ".\game.cso" -o ".\game.iso"
 
-Repair or normalize readable input into CSO1:
+## Repair or normalize
 
     .\csokit.exe repair ".\game.cso" -o ".\fixed.cso" --profile game-safe --deep-verify
 
-Profiles: `game-safe` default, `compat`, `fast`, `smallest`, `archive-smallest`.
+Repair rebuilds readable data into CSO1. It cannot recreate missing or unreadable source data.
+
+## Compression profiles
+
+| Profile | Purpose |
+| --- | --- |
+| `game-safe` | Recommended default |
+| `compat` | Compatibility-focused |
+| `fast` | Faster compression |
+| `smallest` | More compression trials |
+| `archive-smallest` | Size-focused experimental profile |
+
+Use `game-safe` unless you have a specific reason to choose another profile.
+
+## Output names
+
+The output base name must contain 2 to 10 Unicode characters. The extension is not counted.
+
+Valid:
+
+    game.cso
+    game-2.cso
+    back.iso
+
+Invalid:
+
+    x.cso
+    verylongname.cso
+
+## Existing files
+
+CsoKit does not overwrite an output file unless `--force` is supplied.
+
+    .\csokit.exe decompress ".\game.cso" -o ".\game.iso" --force
 
-Output base names must be 2 to 10 characters; `.cso` and `.iso` extensions are not counted. Automatically suggested names follow this limit.
+## JSON output
 
-Full CLI reference: [docs/CLI.md](docs/CLI.md).
+    .\csokit.exe verify ".\game.cso" --deep --json
 
 ## Exit codes
 
 | Code | Meaning |
 | ---: | --- |
 | 0 | Success |
 | 1 | General failure |
-| 2 | Invalid command or missing argument |
+| 2 | Invalid command or argument |
 | 10 | Input file not found |
-| 11 | Invalid CSO file header |
-| 12 | Unsupported CSO file |
-| 13 | Corrupt CSO index table |
-| 14 | Output file already exists |
-| 15 | Cannot write output file |
-| 16 | Not enough disk space |
+| 11 | Invalid container header |
+| 12 | Unsupported container |
+| 13 | Corrupt index |
+| 14 | Output already exists |
+| 15 | Output cannot be written |
+| 16 | Insufficient disk space |
 | 20 | Decompression failed |
 | 21 | Compression failed |
-| 130 | Operation canceled by user |
+| 130 | Operation canceled |
 
-## Limitations
+## Safety
 
-CsoKit focuses on PSP ISO/CSO workflows.
-ZSO, DAX, and CSO2 are readable input containers; CSO1 is the default output format.
-Verification checks file structure, not emulator or device compatibility.
+- Keep the original image until the output is verified.
+- Use `--deep` before archiving or transferring an output.
+- Repair does not invent missing sectors or corrupted blocks.
+- Structural verification does not guarantee emulator or device compatibility.
+- Do not separate `CsoKit.Native.dll` from `csokit.exe`.
 
-## More documentation
+## Release ZIP contents
 
-- [CLI reference](docs/CLI.md)
-- [Contributor scripts and release gates](CONTRIBUTING.md)
-## Architecture and safety
+    csokit.exe
+    CsoKit.Native.dll
+    README.md
+    RELEASE_NOTES.md
+    LICENSE.txt
+    THIRD_PARTY_NOTICES.md
+    SHA256SUMS.txt
 
-The repository is split into `CsoKit.Core`, `CsoKit.Application`, CLI, and WPF adapters.
-Production native loading is limited to the application directory and requires ABI 2.
-Compression workers are bounded, and cancellation is propagated through verification,
-repair, and final output promotion. See `docs/SECURITY_HARDENING.md`.
+Use `SHA256SUMS.txt` to verify that release files were not modified.