shop audit

docs/cli.md

@@ -70,10 +70,11 @@ pit ls <package>    # list files in specified package
 
 ### pit build
 
-Build the current package.
+Build the current package. Compiles C files into per-file dynamic libraries and installs them to `~/.pit/lib/<pkg>/<stem>.dylib`.
 
 ```bash
-pit build
+pit build              # build current package
+pit build <package>    # build specific package
 ```
 
 ### pit test
@@ -159,9 +160,11 @@ pit install /Users/john/work/mylib
 
 ```
 ~/.pit/
-├── packages/       # installed packages
-├── lib/            # compiled dynamic libraries
-├── build/          # build cache
+├── packages/       # installed package sources
+├── lib/            # installed per-file dylibs (persistent)
+│   ├── core/       # core package dylibs
+│   └── <pkg>/      # per-package subdirectories
+├── build/          # ephemeral build cache (safe to delete)
 ├── cache/          # downloaded archives
 ├── lock.toml       # installed package versions
 └── link.toml       # local development links