From c99d5193053a9377acfb62677bf241e540f9f6ee Mon Sep 17 00:00:00 2001
From: Jeff Carr <jcarr@wit.com>
Date: Mon, 20 Oct 2025 05:52:05 -0500
Subject: maybe Gemini AI formatted this better

---
 README.md | 67 +++++++++++++++++++++++++++++++++------------------------------
 1 file changed, 35 insertions(+), 32 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 8529fb0..df37678 100644
--- a/README.md
+++ b/README.md
@@ -1,51 +1,54 @@
-* Theory of config
+# Configuration Library
 
-    * Make the defaults the same everywhere
+## Theory of Operation
 
-    * There are two types of config files:
+The core philosophy of this library is to standardize configuration handling with sensible, consistent defaults.
 
-        1) A super simple ENV key:value file (config.proto defined in this package)
-        2) A application defined <appname>.proto (.proto wherever you want to put it)
+There are two types of configuration files:
 
+1.  A simple environment-style `KEY=VALUE` file (defined by `config.proto` in this package).
+2.  An application-specific Protobuf file (e.g., `<appname>.proto`).
 
-* 1) Basic application config.proto information
+---
 
-    the application config.proto is loaded from, in order:
+### 1. Basic Application Configuration
 
-    /usr/share/doc/appname/config.text
-    /etc/default/appname
-    ~/.config/appname/config.text
+This configuration uses a simple, environment-style file for basic settings. The file is loaded from the following locations, in order of precedence (later files override earlier ones):
 
-    These files ONLY HAVE ENV LIKE KEY/VALUE Pairs
+1.  `/usr/share/doc/<appname>/config.text`
+2.  `/etc/default/<appname>`
+3.  `~/.config/<appname>/config.text`
 
-* 2) application specific protobuf files
+**Note:** These files **must** only contain `KEY=VALUE` pairs.
 
-    Application config files are always located in the same place
-    with the same name by default.
+---
 
-    For the application "forge" using forge.proto
+### 2. Application-Specific Protobuf Configuration
 
-    ~/.config/forge/forge.text
+This is for the application's main data structure, defined in its own `.proto` file. By default, these files are always located in a standard location.
 
-    To override these defaults, set the values in the 1) protobuf
+For an application named `forge` using a `forge.proto` definition, the default file path is:
 
-* notes from the code
+-   `~/.config/forge/forge.text`
 
-```
-// Because you followed autogenpb's advice (you did follow it right?) you now
-// win the automation lottery.
-//
-// for this .proto file, GetProtobufName(pb) returns "repos"
-// Then, ConfigLoad(), ConfigSave(), CacheLoad() and CacheSave()
-// all do exactly what is expected:
-//
-// Automatically work with the files:
-//  ~/.config/<appname>/repos.pb
-// or
-//  ~/.cache/<appname/repos.pb
-//
+The default paths and filenames can be overridden by setting the appropriate values in the basic application config file (see #1 above).
+
+---
+
+## Code Example & Notes
+
+The `autogenpb` tool provides powerful automation. If you follow its conventions, the configuration and cache management functions work seamlessly.
+
+For a `.proto` file containing the message `Repos`, the function `GetProtobufName(pb)` will return `"repos"`.
+
+Consequently, the standard functions `ConfigLoad()`, `ConfigSave()`, `CacheLoad()`, and `CacheSave()` will automatically handle the correct files without any extra code:
+
+-   **Config:** `~/.config/<appname>/repos.pb`
+-   **Cache:** `~/.cache/<appname>/repos.pb`
+
+```protobuf
 // message Repos {
 //         string                      uuid                     = 1;
 //         string                      version                  = 2;
 //         repeated Repo               repos                    = 3;
-```
+```
\ No newline at end of file
-- 
cgit v1.2.3