docs: separate usage from development (#404)

Author: reubeno

CONTRIBUTING.md

@@ -27,7 +27,7 @@ When you submit a pull request, if you have not already done so, you will be pro
 
   ```bash
   # Mage is not technically required, the build tools may also be invoked
-  # directly via 'go run magefile.go'
+  # directly via `go run magefile.go` or `./magefile.go`
   go install github.com/magefile/mage@latest
   ```
 
@@ -47,7 +47,45 @@ When you submit a pull request, if you have not already done so, you will be pro
    mage build
    ```
 
-## Build System Reference
+5. Install the built tools to your `$GOPATH/bin` directory:
+
+   ```bash
+   mage install
+   ```
+
+   After running `mage install`, the tools will be available in your `$GOPATH/bin` directory.
+   Not all systems will have this directory in their `$PATH` by default, so you may need to add it.
+
+#### Azure Linux 3.0 as a development host
+
+```bash
+# These instructions work for AzureLinux (https://github.com/microsoft/azurelinux)
+# While the tools should build and run on any system with golang installed, some of the runtime dependencies
+# may not be available on all systems (e.g., `mock`).
+tdnf install -y golang ca-certificates glibc-devel
+
+git clone <URL>
+cd <REPO>
+
+# You may want to permanently add $GOPATH/bin to your $PATH via
+#     echo 'export GOPATH=$(go env GOPATH)' >> $HOME/.bashrc
+#     echo 'export PATH=$PATH:${GOPATH}/bin' >> $HOME/.bashrc
+export GOPATH=$(go env GOPATH)
+export PATH=$PATH:${GOPATH}/bin
+go install github.com/magefile/mage@latest
+mage build
+mage install
+```
+
+## Build Reference
+
+All code in this repo is written in `golang`. The `golang` package is required to build and run the tools.
+
+The build system uses mage, which can be installed with `go install github.com/magefile/mage@latest`. Alternatively, a zero-install approach is available through `go run magefile.go` or `./magefile.go`, which automatically downloads the required dependencies without manual installation. All additional build tools are managed automatically by go, and no manual tool installation is required.
+
+All other tooling dependencies are handled by `go tool`, which will automatically get the required tools when using `mage`. See [the tools section](./tools/README.md) for more information.
+
+This repo contains configs for the `golangci-lint` linter. It is installed as part of the [VSCode go extension](https://marketplace.visualstudio.com/items?itemName=golang.go). It's also optionally available as a [binary release](https://golangci-lint.run/welcome/install/#local-installation).
 
 ### Mage Commands
 
@@ -56,6 +94,7 @@ When you submit a pull request, if you have not already done so, you will be pro
 | `mage -l` | List all available targets | To see all options |
 | `mage all` | Full build, test, and check pipeline | Before submitting PR |
 | `mage build` | Build Go binaries | After code changes |
+| `mage install` | Build Go binaries and install | Outer-loop testing |
 | `mage unit` | Run unit tests | After writing tests |
 | `mage scenario` | Run scenario tests (SLOW) | For major changes |
 | `mage scenarioUpdate` | Update test snapshots | When test expectations change |
@@ -183,6 +222,19 @@ mage -l
 
 ## Testing
 
+Testing can be run with `mage`, or directly using `go test`. The `mage` build system is preferred as it can also automatically run the scenario tests and update the test expectations.
+
+```bash
+# Run the unit tests
+mage unit
+
+# Run the coverage tests, producing an .html report
+mage coverage
+
+# Run scenario tests
+mage scenario
+```
+
 See the [testing documentation](docs/how-to/testing.md) for detailed guidelines on writing and running tests.
 
 ## Pull Request Process