document the mash scripts that help with pkgx (#1083)

Author: mxcl

.github/markdownlint.yml

@@ -15,3 +15,7 @@ MD025: false
 MD033: false
 # Multiple consecutive blank lines
 MD012: false
+
+# Blank line inside blockquote
+# gives false positives on code blocks for literal consecutive blockquotes
+MD028: false

README.md

@@ -244,6 +244,7 @@ pprint([(k, v["title"]) for k, v in data.items()][:10])
 > ecosystem is available to your scripts Check it out [`mash`].
 
 > [!INFO]
+>
 > Notably, packages used during your script aren’t installed and don’t pollute
 > your system and anyone else’s systems either. Don’t be confused— they are
 > downloaded to `~/.pkgx` but the wider system is not touched.
@@ -312,8 +313,8 @@ exported.
 
 ## `pkgx install`
 
-We now provide [`pkgm`][pkgm] but if you miss the leanness of “stubs” we provide a
-[`mash`] script to create stubs in `/usr/local/bin`:
+We now provide [`pkgm`][pkgm] but if you miss the leanness of “stubs” we
+provide a [`mash`] script to create stubs in `/usr/local/bin`:
 
 ```sh
 $ pkgx mash pkgx/stub git

docs/pkgx.md

@@ -119,10 +119,68 @@ gum version 0.14.5
 For this mode we can also output JSON: `pkgx +gum --json`.
 
 
-## Silent Mode
+## Quietening Output
 
 ```sh
-pkgx --silent gum format 'no progress information is output'
+$ pkgx --quiet gum format 'download progress is still shown'
+# ^^ supresses resolving/syncing etc. messages but not download progress info
+
+```sh
+pkgx --silent gum format 'no output at all'
+# ^^ silences everything, even errors
+```
+
+Note that this only effects `pkgx` *not the tools you run with `pkgx`*.
+
+## Other Common Needs
+
+`pkgx` is not a package manager so the command itself doesn’t typically offer
+such operations you may expect, however the way `pkgx` works is simple and
+standardized so we offer some `mash` scripts to help.
+
+Longer term we will make a tool `pkgq` to help with these operations.
+
+### Updating Downloaded Packages
+
+```sh
+$ pkgx mash pkgx/cache upgrade
+updating: /Users/mxcl/.pkgx/python.org/v3.11.11
+# snip…
+```
+
+### Pruning Older Versions of Packages
+
+The `pkgx` download cache can get large over time. To prune older versions:
+
+```sh
+$ pkgx mash pkgx/cache prune
+pruning: ~/.pkgx/deno.land/v1.39.4
+pruning: ~/.pkgx/deno.land/v1.46.3
+# snip…
+```
+
+This may delete versions that you use—if so—this is fine. `pkgx` will just
+reinstall them next time you need them.
+
+### Listing Available Versions for a Package
+
+```sh
+$ pkgx mash pkgx/pantry-inventory git
+2.38.1
+2.39.0
+# snip…
+```
+
+### Listing What is Downloaded
+
+```sh
+$ mash pkgx/cache ls
+
+  Parent Directory                │Version
+  ────────────────────────────────┼──────────
+  perl.org                        │5.40.0
+  x.org/xcb                       │1.17.0
+  # snip…
 ```
 
 [SemVer]: https://devhints.io/semver