doc updates [no ci]

README.md

@@ -81,5 +81,5 @@ If you're not sure how these instructions fit into your app, check the example a
 - 🚦 Read our [compiling guide](docs/compiling.md)
 
 ## Testimonials 
-I have now got my external facing application using velopack. I am very impressed. Seems to work fabulously well and be much faster both in the initial build and in the upgrading of the software on the end user's  machine than Squirrel was. I hope to go live with this late next week. It's amazing and the best installer I've ever used in over 30 years of development. Thanks so much!  You are doing some great work!
+I have now got my external facing application using velopack. I am very impressed. Seems to work fabulously well and be much faster both in the initial build and in the upgrading of the software on the end user's  machine than Squirrel was. It's amazing and the best installer I've ever used in over 30 years of development. Thanks so much!  You are doing some great work!
 [- Stefan (Discord)](https://discord.com/channels/767856501477343282/767856501477343286/1195642674078830613)

docs/bootstrapping.md

@@ -11,7 +11,10 @@ It is possibly to specify more than one requirement, using a comma delimited lis
 vpk pack ... --framework net6.0-x64-desktop,vcredist142-x64
 ```
 
-These dependencies will be downloaded and installed before your application can be installed.
+These dependencies will be downloaded and installed before your application will be installed.
+
+## ❗ Important for dotnet ❗
+If you are building your application with `--self-contained`, you should **NOT** provide a `--framework` argument specifying that your app requires dotnet installed, because your application already has the runtime bundled in. If you are publishing your application with `--no-self-contained`, then you should provide the `--framework` argument.
 
 ## Adding dependencies during updates
 

docs/channels.md

@@ -0,0 +1,39 @@
+| [docs](.) / channels.md |
+|:---|
+
+# Release Channels
+*Applies to: Windows, MacOS, Linux*
+
+Channels is a fundemental part of how Velopack understands and builds releases. Every release must belong to a channel. If you do not specify a channel when building a release (via the `--channel`) argument, the default channel will be the name of the target Operating System (eg. `win`, `osx`, or `linux`). 
+
+When building releases, Velopack will create a `releases.{channel}.json` file, that should be uploaded with your other assets (eg. `.nupkg`). This is how `UpdateManager` knows what releases are available.
+
+In general, you should not provide a channel to the `UpdateManager` constructor (leave it null). In this case, it will only search for update packages in the same channel that the current release was built for. For example, if you provided the `--channel stable` argument to `vpk`, and installed your app, then `UpdateManager` will automatically be searching for the file `releases.stable.json` when checking for updates.
+
+❗For legacy purposes, Velopack will also generate a `RELEASES` file (for the `win` channel), or a `RELEASES-{channel}` file (for any other channel). By deploying these files as well as the `releases.{channel}.json` will allow legacy apps to upgrade to Velopack. If you do not have any users on legacy versions of your software, you can ignore these files.
+
+## Switching channels in installed apps
+It is often desirable to allow users to switch channels easily. For example, if your users downloaded an installer for a "stable" version of your app, they will only receive updates for the "stable" channel. Later on, they decide they wish to switch to the "beta" channel to try some experimental features in your app. 
+
+This can be done by supplying a non-null channel argument to the UpdateManager constructor. So you would instantiate as `new UpdateManager("https://the.place/you-store/updates", "beta")` and then perform an update process as usual.
+
+## Deploying cross-platform apps
+
+It's important when deploying cross platform (or cross-architecture) apps that every unique os/rid has it's own channel. It wouldn't be good if your Windows app tried to install an OSX package etc!
+
+The default channels are, `win`, `osx`, or `linux`, so if you are only distributing one release per platform, you do not need to specify a channel argument, everything should work automatically. If you are distributing feature channels (eg. 'stable', 'beta') or need to distribute multiple versions of your app per os (eg. `win-x64`, `win-arm64`) then you will need to define a channel strategy that does not collide. 
+
+For example, if I was distributing an app on windows and osx which needed to support x64, and arm64, and also needed to support "stable" and "beta", then I would need the following 8 channels:
+- win-x64-stable
+- win-x64-beta
+- win-arm64-stable
+- win-arm64-beta
+- osx-x64-stable
+- osx-x64-beta
+- osx-arm64-stable
+- osx-arm64-beta
+
+## Renaming a channel
+You can't rename a channel per-say, but you can supercede it (ie. force all your users to switch to the new channel). Imagine you have been publishing an app that only supports x64 windows to the channel `stable` until now, but you now would like to release an arm64 version of your app. So you want to migrate all the users on `stable` to `win-x64`, while also creating a new channel named `win-arm64`. 
+
+You should publish your next update (say v2.0.0) using `--channel win-x64`, which will create a new `releases.win-x64.json` file. You can now copy this file and rename it to `releases.stable.json` and deploy both files along with your v2.0.0 `.nupkg` to your update server. Any users on the "stable" channel will find the `releases.stable.json` file and update to your v2.0.0 win-x64 release, and once done will search for future updates at `releases.win-x64.json`. You only need to do this once, you will not need to update the `releases.stable.json` file again, however you may not want to delete it so users who have not opened your app in some time can still find the new updates.

docs/cli.md

@@ -2,6 +2,7 @@
 |:---|
 
 # Velopack Command Line Reference
+*Applies to: Windows, MacOS, Linux*
 
 ## vpk
 ```txt

docs/compiling.md

@@ -2,6 +2,7 @@
 |:---|
 
 # Compiling Velopack
+*Applies to: Windows, MacOS, Linux*
 
 Velopack is made up of some Rust binaries which are re-distributed with installed apps, a .NET NuGet package, and a .NET command line tool. In order to test the project, you need to build the Rust binaries before compiling dotnet.   
 

docs/debugging.md

@@ -2,6 +2,7 @@
 |:---|
 
 # Debugging Velopack
+*Applies to: Windows, MacOS, Linux*
 
 ## Logging
 All parts of Velopack have logging built in to help troubleshoot issues, and you should provide these logs when opening a GitHub issue about a potential bug.

docs/readme.md

@@ -7,7 +7,7 @@
 ## FAQ
  - **My application was detected as a virus?** <br/>
    Velopack can't help with this, but you can [code-sign](signing.md) your app and check [other suggestions here](https://github.com/clowd/Clowd.Squirrel/issues/28#issuecomment-1016241760).
- - **What happened to SquirrelAwareApp?** <br/>
+ - **What happened to SquirrelAwareApp? / Shortcuts** <br/>
    This concept no longer exists in Velopack. You can create hooks on install/update in a similar way using the `VelopackApp` builder. Although note that creating shortcuts or registry entries yourself during hooks is no longer required.
  - **Can Velopack bootstrap new runtimes during updates?** <br/>
    Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates.

docs/shortcuts.md

@@ -4,13 +4,11 @@
 # Windows Shortcuts
 *Applies to: Windows*
 
-By default, during installation Velopack will create a shortcut on the Desktop and in the StartMenuRoot. 
+By default, during installation Velopack will create a shortcut on the Desktop and in the StartMenuRoot. It will automatically delete any shortcuts it finds when uninstalling the application.
 
-It will automatically delete any shortcuts it finds when uninstalling the application.
+The name of the shortcuts will be determined by the `--packTitle` vpk argument. For example, if you pass `--packTitle "My Fancy App"`, then the shortcuts created will be created as `"My Fancy App.lnk"`.
 
-If you need to create shortcuts in any extra locations, the `Velopack.Windows.Shortcuts` and `Velopack.Windows.ShellLink` classes are provided. 
-
-These classes are provided for legacy reasons, and in general the stability of such functions is not guarenteed.
+If you need to create shortcuts in any extra locations, the `Velopack.Windows.Shortcuts` and `Velopack.Windows.ShellLink` classes are provided. These classes are provided for legacy reasons, and in general the stability of such functions is not guarenteed.
 
 For example, if you wished to create a shortcut during the install of your app, you might do the following:
 

docs/signing.md

@@ -16,7 +16,7 @@ First, you need to acquire a code-signing certificate from a reputable brand. To
 **Disclaimer: This is by no means a recommendation or advice for any particular code-signing certificate issuer, but instead is general guidance for the process one might follow to purchase a certificate.**
 
 ### Signing via `signtool.exe`
-usually signing is accomplished via `signtool.exe`. If you already use this tool to sign your application, you can just lift your sign parameters straight to Velopack.
+Usually signing is accomplished via `signtool.exe`. If you already use this tool to sign your application, you can just pass your sign parameters straight to Velopack (minus the 'sign' command).
 
 For example, if your signing command before was:
 ```cmd
@@ -30,7 +30,7 @@ vpk pack ... --signParams "/td sha256 /fd sha256 /f yourCert.pfx /tr http://time
 
 If you are new to using `signtool.exe`, you can check the [command line reference here](https://learn.microsoft.com/en-us/dotnet/framework/tools/signtool-exe). I recommend getting signing working on a single binary first, using `signtool.exe`, before trying to get things working with the Velopack CLI.
 
-Take care when providing parameters that if you have any quoted (`"`) arguments you will need to escape those quotes with a backslash. 
+❗**Take care when providing parameters: If any have a space in a signing argument, you must wrap it with quotes and escape with a backslash.**
 
 By default, Velopack will sign 10 files per call to `signtool.exe`, to speed up signing and reduce the number of times you need to interact with the console if you are using some kind of interactive signing method. This can be disabled with the `--signParallel 1` argument.