Improve docs

Expand on Work In Progress status; remove manual line wrapping; clarify
roadmap and add chunking feature

README.md

@@ -26,15 +26,16 @@
 
 ## WARNING - Work In Progress
 
+API stability (including as a code library and as a network endpoint) is NOT guaranteed before `v1` API definitions and a 1.0 release. The following recommendations are made regarding usage patterns of hauler:
+- `alpha` (`v1alpha1`, `v1alpha2`, ...) API versions: use **_only_** through `haulerctl`
+- `beta` (`v1beta1`, `v1beta2`, ...) API versions: use as an **_experimental_** library and/or API endpoint
+- `stable` (`v1`, `v2`, ...) API versions: use as stable CLI tool, library, and/or API endpoint
 
 ## Purpose: collect, transfer, and self-host cloud-native artifacts
 
-Kubernetes-focused software usually relies on CLI binaries, container images, helm charts, and more
-for installation. Standing up tools for serving these artifacts, collecting the dependencies, and
-mirroring them into the self-hosting solutions is usually a manual process with minimal automation. 
+Kubernetes-focused software usually relies on executables, archives, container images, helm charts, and more for installation. Collecting the dependencies, standing up tools for serving these artifacts, and mirroring them into the self-hosting solutions is usually a manual process with minimal automation. 
 
-Hauler aims to fill this gap by standardizing low-level components of this stack and automating the
-collection and transfer of all artifacts.
+Hauler aims to fill this gap by standardizing low-level components of this stack and automating the collection and transfer of artifacts.
 
 ## Additional Details
 
@@ -43,26 +44,22 @@ collection and transfer of all artifacts.
 
 ## Go CLI
 
-The initial MVP for a hauler CLI used to streamline the packaging and deploying processes is in the
-`cmd/` and `pkg/` folders, along with `go.mod` and `go.sum`. Currently only a `package` subcommand
-is supported, which generates a `.tar.gz` archive used in the future `deploy` subcommand.
+The initial MVP for a hauler CLI used to streamline the packaging and deploying processes is in the `cmd/` and `pkg/` folders, along with `go.mod` and `go.sum`. Currently only a `package` subcommand is supported, which generates a `.tar.gz` archive used in the future `deploy` subcommand.
 
 ### Build
 
-To build hauler, the Go CLI v1.14 or higher is required. See <https://golang.org/dl/> for downloads
-and see <https://golang.org/doc/install> for installation instructions.
+To build hauler, the Go CLI v1.14 or higher is required. See <https://golang.org/dl/> for downloads and see <https://golang.org/doc/install> for installation instructions.
 
 To build hauler for your local machine (usually for the `package` step), run the following:
 
-```bash
+```shell
 mkdir bin
 go build -o bin ./cmd/...
 ```
 
-To build hauler for linux amd64 (required for the `deploy` step in an air-gapped environment), run
-the following:
+To build hauler for linux amd64 (required for the `deploy` step in an air-gapped environment), run the following:
 
-```bash
+```shell
 mkdir bin-linux-amd64
 GOOS=linux GOARCH=amd64 go build -o bin-linux-amd64 ./cmd/...
 ```

ROADMAP.md

@@ -2,28 +2,35 @@
 
 ## v0.1.0
 
-- install single-node k3s cluster
-- define image list
-   - collect images
-   - deploy to docker registry
-- git repos
-   - collect repos
-   - deploy caddy git server
-- define file list
-   - collect files
-   - deploy caddy file server
-   - NOTE: "generic" option, as most other use cases can be satisfied by a specially crafted file
-   server directory
+- Install single-node k3s cluster
+- Serve container images
+  - Collect images from image list file
+  - Collect images from image archives
+  - Deploy docker registry
+  - Populate registry with all images
+- Serve git repositories 
+  - Collect repos
+  - Deploy git server (Caddy? NGINX?)
+  - Populate git server with repos
+- Serve files
+  - Collect files from directory, including subdirectories
+  - Deploy caddy file server
+  - Populate file server with directory contents
+  - NOTE: "generic" option - most other use cases can be satisfied by a specially crafted file
+    server directory
 
 
 ## Potential future features
 
 - Helm charts
-   - Pull charts, migrate chart artifacts
-   - Analyze images needed, add to dependency list
+  - Pull charts, migrate chart artifacts
+  - Analyze required container images, add to dependency list
 - Yum repo
-   - Target package list, collect all dependencies
-   - Deploy fully configured yum repo into file server
+  - Provide package list, collect all dependencies
+  - Deploy fully configured yum repo into file server
 - Deploy Minio for S3 API
   - MVP: backed by HA storage solution (e.g. AWS S3, Azure Blob Storage)
   - Stable: backed by local storage, including backups
+- Split archives into chunks of chosen size
+  - Enables easier transfer via physical media
+  - Allows smaller network transfers, losing less progress on failed upload (or working around timeouts)

VAGRANT.md

@@ -1,31 +1,27 @@
 ## Hauler Vagrant machine
 
-A Vagrantfile is provided to allow easy provisioning of a local air-gapped CentOS environment. Some
-artifacts need to be collected from the internet; below are the steps required for successfully
-provisioning this machine, downloading all dependencies, and installing k3s (without hauler) into
-this machine.
+A Vagrantfile is provided to allow easy provisioning of a local air-gapped CentOS environment. Some artifacts need to be collected from the internet; below are the steps required for successfully provisioning this machine, downloading all dependencies, and installing k3s (without hauler) into this machine.
 
 ### First-time setup
 
 1. Install vagrant, if needed: <https://www.vagrantup.com/downloads>
-2. Install `vagrant-vbguest` plugin, as noted in the Vagrantfile:  
-  ```bash
-  vagrant plugin install vagrant-vbguest
-  ```
+2. Install `vagrant-vbguest` plugin, as noted in the Vagrantfile:
+   ```shell
+   vagrant plugin install vagrant-vbguest
+   ```
 3. Deploy Vagrant machine, disabling SELinux:
-  ```bash
-  SELINUX=Disabled vagrant up
-  ```
+   ```shell
+   SELINUX=Disabled vagrant up
+   ```
 4. Access the Vagrant machine via SSH:
-  ```bash
-  vagrant ssh
-  ```
+   ```shell
+   vagrant ssh
+   ```
 5. Run all prep scripts inside of the Vagrant machine:
-  ```bash
-  sudo /opt/k3ama/vagrant-scripts/prep-all.sh
-  ```
-  > This script temporarily enables internet access from within the VM to allow downloading all
-  > dependencies. Even so, the air-gapped network configuration IS restored before completion.
+    > This script temporarily enables internet access from within the VM to allow downloading all dependencies. Even so, the air-gapped network configuration IS restored before completion.
+   ```shell
+   sudo /opt/hauler/vagrant-scripts/prep-all.sh
+   ```
 
 All dependencies for all `vagrant-scripts/*-install.sh` scripts are now downloaded to the local
 repository under `local-artifacts`.
@@ -37,17 +33,17 @@ repository under `local-artifacts`.
   vagrant ssh
   ```
 2. Run the k3s install script inside of the Vagrant machine:
-  ```bash
-  sudo /opt/k3ama/vagrant-scripts/k3s-install.sh
+  ```shell
+  sudo /opt/hauler/vagrant-scripts/k3s-install.sh
   ```
 
 ### Installing RKE2 manually
 
 1. Access the Vagrant machine via SSH:
-  ```bash
+  ```shell
   vagrant ssh
   ```
 2. Run the RKE2 install script inside of the Vagrant machine:
-  ```bash
-  sudo /opt/k3ama/vagrant-scripts/rke2-install.sh
+  ```shell
+  sudo /opt/hauler/vagrant-scripts/rke2-install.sh
   ```