M README → README

@@ -2,9 +2,9 @@ ?????????????????
                 ?  what is zoa  ?
                 ?????????????????
 
-  zoa is the best config management tool. it's the
-  best because it's the simplest. it's written in shell, has
-  a few nice little VERY USEFUL helpers, and doesn't go out
+  zoa is a simple config management tool. it's the
+  best. it's written in shell, has a few nice
+  cute little helper functions, and doesn't go out
   of its way to make you hate yourself.
 
   zoa requires access to a git repo, though it may be used
@@ -21,12 +21,13 @@ and hate maintaining them when things break for no reason.
 
 
 
-              why did you write this?
+              why did you write this? (are you insane)
 
-       i manage systems with config management tools for a living.
-     i know how impossible they all are firsthand, i have 6+ years
-  of painful, painful experience. i wrote zoa to use on my personal
-systems, because i hate the primary config management tools a lot. 
+  first, yes, duh, but also:
+       i manage systems with config management tools for a living. (6+ years)
+     i know how impossible they all are to operate & keep up with
+  years of painful, painful experience. i wrote zoa to use on my personal
+systems, because i hate the main config management tools a lot. 
 
                also, i <3 shell :D
 
@@ -76,6 +77,48 @@ try to do everything.
 
       zoa breaks rarely because it does almost nothing.
 
+    other tools are slow because they have HUGE runtimes and scopes
+
+      zoa is comparatively fast, because it's just running god dang
+      shell scripts :3
+      zoa doesn't require:
+      - ssh
+      - python
+      - ruby
+      - a chef server or salt master
+
+    other tools abstract too much
+
+      zoa abstracts a few definitely useful functions, but
+      otherwise gets out of the way and gives you a light
+      framework to speak shell to your systems.
+
+      in zoa, you write plain POSIX shell. Why?
+      - posix shell is productive!
+      - posix shell is portable!
+      - posix shell is the language of system configuration!
+      - posix shell is easy to remember!
+      - posix shell rarely changes!
+
+
+
+          zoa's design touchstones
+          ------------------------
+          * no config on the nodes
+            node-side config is cumbersome. everything
+            should be adjustable via git and git alone.
+          * expose 1 way to do common things
+            zoa exposes only 1 hostname var, only 1 copy function,
+            has 0 flags, and 1 way to run via git, and 1 way to 
+            format your repository. less overhead for you.
+          * adopt functionality slowly
+            zoa is starting with a minimal set of built-in functions
+            because i only want to maintain functions in order to address
+            severe pain-points. most things should just be handled via shell.
+          * as standards-compliant as reasonable
+            but not ball-breakingly so tbh, see $HOSTNAME for an example
+            of zoa not being "fully" standards compliant.
+
 
 
                !!!!!!!!!!!!!!!!!!
@@ -92,31 +135,29 @@ 3: the layout
 
          --- 1: the utility ---
 
-  simply run zoa on all of your systems. it's a simple binary that can be installed
-  trivially.
-  it expects to run as root, and it should probably run on a cron/timer/whatever
-  schedule at whatever interval you want.
+  zoa is a single binary.
 
-  install:
-    wget -O  https://j3s.sh/zoa/zoa # TODO
+  it expects to run as root (it is managing your system, after all),
+  and it should probably run on a cron/timer/whatever schedule at
+  whatever interval you want.
+
+  installation process:
+    wget https://j3s.sh/zoa/zoa # TODO
     mv zoa /usr/local/sbin
     chmod +x /usr/local/sbin/zoa
 
-  design guideline: all configuration data comes from a git repository.
-                             the nodes themselves keep no state at all.
-
   to run zoa:
     zoa https://git.j3s.sh/j3s/config main
     ^              ^                   ^
   zoa, duh.       git repo             optional git branch
 
   zoa will clone the repo+branch specified to /var/lib/zoa/repo, and then
-  it will execute
+  it will execute the "main" script in that repo - more on that later.
 
-  you can also run zoa in local-mode by specifying a dir:
+  to run zoa in local-only mode:
     zoa /path/to/zoa/dir
   
-  in which case, zoa will just execute whatever is in the dir you specify
+  in which case, zoa will just execute main from that dir you specify
 
   that's it, you've run zoa! now set up a cronjob/systemd timer to
   run zoa on a schedule, if that's your thing. or just login and run zoa
@@ -130,11 +171,6 @@ 
 
          --- 2: environment variables and helper functions ---
 
-  in zoa, you write plain POSIX shell. Why?
-  - posix shell is productive (fun)!
-  - posix shell is portable (everywhere)!
-  - posix shell is hard to make too complicated (fights complexity bc it's spaghetti)!
-
                         ENVIRONMENT VARIABLES
 
   before zoa runs, it sets a few standard environment variables for your usage.
@@ -181,7 +217,7 @@ HELPER FUNCTIONS
 
      zoa has some little helper functions for common operations.
 
-      zoa-file
+    * zoa-file
         usage:
           zoa-file example.conf /etc/example.conf optional-command
                     ^                ^                  ^
@@ -202,7 +238,7 @@ 
         todo:
           add a template processing step of some kind?
 
-      zoa-script
+    * zoa-script
         usage:
           zoa-script scriptname
                          ^
@@ -225,16 +261,16 @@ 
   here's the canonical repo layout:
 
          main     <-- file, entrypoint
-         files/   <-- dir, contains arbitrary text files you'd like to place
-         scripts/ <-- dir, contains arbitrary shell scripts to config your systems
+         files/   <-- dir, contains arbitrary text files
+         scripts/ <-- dir, contains arbitrary shell scripts
 
-  you need at least main! everything else is optional.
+  you need at least main. everything else is optional.
 
-  main is your entrypoint. if your whole vibe is just doing basic configuration
-  of nodes, you _could_ put literally everything in main and just be done with it.
+  main is your entrypoint. you could just stick everything in main and
+  be done with it, if you want.
 
-  however, if you want main to be a little more complex,
-  here's a good starting point:
+  however, if you want main to be a little more capable,
+  here's one starting point:
 
       case $HOSTNAME in
           git.j3s.sh)

M env/env.go → env/env.go

@@ -104,7 +104,6 @@ }
 
 // I want to keep this list as small as possible, since
 // this struct is unreliable.
-// design principle: only 1 way to do common things
 type OSRelease struct {
 	ID        string // distro name - "arch"
 	VersionID string // for debian distros, this is set to "22.04"