Docs corrections

DEFINITIONS.md

@@ -9,9 +9,15 @@ All definitions can contain metadata as TOML key-value pairs with a special pref
 
 Metadata can be placed anywhere in the file. When Box evaluates a definition, each line of metadata is extracted and concatenated into a single TOML document; any intervening lines are ignored.
 
-Currently, only two keys are recognized:
+Currently, only one key is recognized:
 - `depends_on` (`[string]`) - a list of definition names that this definition depends on. Defaults to empty.
 
+## Build Laziness
+
+By default, Box only builds new and changed definitions to maximize efficiency, especially for those on slow or data-limited connections. This logic takes into account dependency trees; if `alpha` depends on `beta` and only `beta` is changed, both `alpha` and `beta` will be rebuilt.
+
+To override this behavior, pass the `-f`/`--force` flag to `bx build`.
+
 ## Commands
 
 Box provides (approximate) implementations of all OCI Containerfile operations as shell functions, as well as several additional tools.
@@ -111,14 +117,14 @@ CFG <FUNCTION> [ARGS...]
 | `cap-add` | Add a Linux capability to the container. | See `man capabilities`. |
 | `cap-drop` | Remove a Linux capability from the container. | See `man capabilities`. |
 | `cpus` | Number of CPUs the container can utilize. | Self-explanatory. |
-| `memory` | Container memory limit. | Supports `b`, `kb`, `mb`, and `gb` as suffixes. |
+| `memory` | Container memory limit. | Supports `b`, `k`, `m`, and `g` as suffixes. |
 | `ulimit` | Set the `ulimit` parameters for the container. | See `man ulimit`. |
 | `device` | Add a host device to the container. Uses `--volume` syntax. | Self-explanatory. |
-| `userns` | Set the user namespace mode for the container. | [Podman docs](https://docs.podman.io/en/v4.4/markdown/options/userns.container.html) |
-| `security-opt` | Set a security option for the container. | [Podman docs](https://docs.podman.io/en/v4.6.1/markdown/options/security-opt.html) |
-| `mount` | Add a mount (`bind` or otherwise) to the container. Uses `--mount` syntax. | [Podman docs](https://docs.podman.io/en/v5.1.0/markdown/podman-create.1.html#mount-type-type-type-specific-option) |
-| `restart` | Set the container restart policy. | [Podman docs](https://docs.podman.io/en/v5.1.0/markdown/podman-create.1.html#restart-policy)
-| `secret` | Give the container access to a secret. | [Podman docs](https://docs.podman.io/en/v5.1.0/markdown/podman-create.1.html#secret-secret-opt-opt) |
+| `userns` | Set the user namespace mode for the container. | [Podman docs](https://docs.podman.io/en/stable/markdown/podman-create.1.html#userns-mode) |
+| `security-opt` | Set a security option for the container. | [Podman docs](https://docs.podman.io/en/stable/markdown/podman-create.1.html#security-opt-option) |
+| `mount` | Add a mount (`bind` or otherwise) to the container. Uses `--mount` syntax. | [Podman docs](https://docs.podman.io/en/stable/markdown/podman-create.1.html#mount-type-type-type-specific-option) |
+| `restart` | Set the container restart policy. | [Podman docs](https://docs.podman.io/en/stable/markdown/podman-create.1.html#restart-policy)
+| `secret` | Give the container access to a secret. | [Podman docs](https://docs.podman.io/en/stable/markdown/podman-create.1.html#secret-secret-opt-opt) |
 
 ### `PRESET`
 
@@ -172,4 +178,8 @@ trap cp
 
 This is not included in the POSIX harness, which automatically applies `set -eu` to abort on non-zero exit codes or uses of unset variables.
 
+## Additional Pointers
+
+
+
 [^1]: If you're wondering "how the hell does it do that" - it saves them as OCI annotations that are read back at creation time. <br> [Did you know you can just use the ASCII separator characters to separate things?](https://github.com/Colonial-Dev/box/blob/0c45cfe2c51a4ff1c3f62b3f753bcfeab882a56b/src/podman.rs#L341-L352) They're right there. Nobody can stop you.

README.md

@@ -209,17 +209,36 @@ As a Silverblue user, this tight coupling with my "pure" host always left a bad
 
 Box also requires that every container be associated with a "definition," rather than defaulting to a standard "toolbox" image for each container. These use Box's custom shell-based format to declare runtime arguments (like mounts) during build time.
 
-> I find this particularly advantageous for ensuring a consistent environment between my desktop and my laptop. It also makes for a good "lazy man's NixOS" on my Pi-hole server.
+> I find this particularly advantageous for ensuring a consistent environment between my desktop and my laptop. It also makes for a good "lazy man's NixOS[^2]" on my Pi-hole server.
 
 So:
 - If you don't mind the above caveats and want containerized environments that Just Work with the host, use Toolbx or Distrobox.
 - If you *do* mind the above caveats and/or want some declarative-ness in your containers, give Box a try.
 
+> This is also where the name 'Box' came from; it makes boxes without any promises about the contents. You get to decide.
+
+### "Why use shell scripts for definitions?"
+
+Not only is shell a familiar environment that's easily extensible by external programs like Box, it also enables you to sprinkle logic into your definitions if needed.
+
+Consider this snippet that mounts all non-hidden `$HOME` directories into the container:
+
+```sh
+for dir in (ls -p $HOME | grep /)
+  CFG mount type=bind,src=(realpath $dir),dst=/home/$USER/$dir
+end
+```
+
+As far as I'm aware, doing something like this in the available declarative formats (`compose` et. al.) would be a tedious manual affair duplicated across every container that needs this behavior.
+
 ### "Why not just use Kubernetes YAML or `compose`?"
 A few reasons:
 
 1.  For Box's target use case of "bespoke interactive containers," separating the information on how to *build* the image from information on how to *run* it is [suboptimal](https://htmx.org/essays/locality-of-behaviour/).
 2. Kubernetes YAML is massively overcomplicated for what I wanted to do, and the `podman` version of `compose` was somewhat buggy when I tried it.
+    - I was made aware as I was finishing up Box that `docker-compose` now works "out of the box" with `podman`, so if that sounds like what you want - by all means, use that instead!
 3. YAML is... [yeah](https://github.com/Colonial-Dev/satpaper/blob/b2016c63ffeafc70538fd2b02fa60d1c077fd694/.github/workflows/release.yml#L1-L3).
 
 [^1]: Single Rust binary compiled from ~2000 lines of boring plumbing code. Red Hat and the OCI have already done all the heavy lifting here!
+
+[^2]: My apologies to any Nix fans in the audience, but my brain is too smooth to handle it.