Improve readme

The idea is for an LLM to read this to understand the repo.

1 files changed, 89 insertions, 34 deletions

diff --git a/README.md b/README.md
index fb69112..142c07a 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,25 @@
-Omni.Dev is the namespace for development. Here we define the tools and
-infrastructure for internal dev work.
+This repo is for all subprojects.
 
-# Goals of the workflow
+# Goals of this project
+
+The Omni project is to leverage automation and asymmetries to create wealth. The
+target of the wealth is Bitcoin. The means: write everything down, first
+in English, then in code.
+
+Resources defined in the repo can be used to quickly create and release
+products. New technology shall be prototyped and developed as needed.
+
+Since Bitcoin always goes up, as long as we are acquiring more Bitcoin, then we
+are growing our wealth. There is a limit to the amount of wealth that one person
+needs, roughly defined as how much is required to live a modest life and provide
+for one's family. Once this is achieved, excess wealth shall be deployed to
+improve the world through activist entrepreneurship.
+
+# Developer Guide
+
+Here we define the tools and infrastructure for all dev work.
+
+## Goals of the workflow
 
 - have minimal ceremony
 - default to asynchrony, but allow for synchronous work when necessary
@@ -19,53 +37,90 @@ We should never need "out of office" email auto-replies, or urgent
 contact. No pager duty, no daily stand-ups. Yes, this policy will affect
 what code we write, not just how we write it; that is by design.
 
-# Getting started
-
-Jump into a development shell:
+## Source Layout
 
-    nix-shell
+The source tree maps to the module namespace, and roughly follows the Haskell
+namespace hierarchy. This is true of all languages: Python, Scheme, Rust, C,
+etc.
 
-Then run  `help` to see the dev commands.
+Namespaces are formatted either as file paths, like `Omni/Dev`, or
+dot-separated, like `Omni.Dev`. Parts of the namespace should always be
+capitalized.
 
-# Repository organization
+The namespace for all products that we own is `Biz`, this includes proprietary
+applications, products, and related infrastructure.
 
-The source tree maps to the module namespace, and roughly follows the Haskell
-namespace hierarchy (although nothing is enforced).
+The `Omni` namespace is used for internal development tooling and infrastructure
+that are shared between all other projects.
 
-The namespace for all products that we own is `Biz`; proprietary applications,
-products, and related infrastructure lives under there. The `Omni` namespace is
-used for internal development tooling and infrastructure that are not related to
-individual products. Stuff that can be open sourced or otherwise externalized
-should be outside of `Biz` or `Omni`.
+Stuff that can be open sourced or otherwise externalized should be outside of
+`Biz` or `Omni`.
 
-Development aspects should be localized to their sub-namespaces as much as
-possible. Only after sufficient iteration such that interfaces are solidified
-and functionality is well-established should some code be promoted up the
-namespace hierarchy.
+Related code should be kept close together. This means that you should start
+with small namespaces: use `Omni/Thing.hs` before `Omni/Thing/Service.hs`. Try
+to keep all related code in one spot for as long as possible.
 
-Start with small namespaces: use `Omni/Thing.hs` before `Omni/Thing/Service.hs`.
-Try to keep all related code in one spot for as long as possible.
+Re-use code from the `Omni/` namespace as much as possible. For example, use
+`Omni/Cli.hs` or `Omni/Test.py` instead of trying to roll your own code for cli
+parsing or running test suites. If the the namespace doesn't have the feature
+you need, then add the feature.
 
 Boundaries and interfaces between namespaces should be singular and
 well-defined. Likewise, the functionality and purpose of a particular
 namespace should be singular and well-defined. Follow the unix principle
 of "do one thing and do it well."
 
-Namespaces are always capitalized. I would prefer always lowercase, but `ghc`
-_really_ wants capitalized files, so we appeas `ghc`. In Scheme and Python this
-actually translates quite well and helps distinguish between types/classes and
-values.
+Namespaces are always capitalized. In Scheme and Python this actually translates
+quite well and helps distinguish between types/classes/modules and values.
+
+## Available tools
+
+We provide some tools for working with projects in the omnirepo:
+
+### bild
+
+`bild` is our universal build tool. It can build and test everything in the repo.
+
+#### Examples
+
+`bild --test Omni/Bild.hs` will build and test the `Omni/Bild.hs` namespace. Use
+this command to run tests for a namespace.
+
+`bild --time 0 Omni/Cloud.nix` will build the `Omni/Cloud.nix` namespace, which
+is our cloud VM instance. The `--time 0` argument disables the timeout (which
+defaults to 10 minutes), this is useful for longer builds.
+
+`bild --json Omni/Test.hs` this just does the analysis step, and prints a
+description of the build as JSON. It will not build anything.
+
+### lint
+
+The `lint` command is a universal lint and formatting tool. It will error if any
+lints fail, or if the code is not formatted properly. Use `lint --fix` to
+autofix any lints or autoformat where possible.
+
+#### Examples
+
+`lint Omni/Cli.hs` will lint the `Omni/Cli.hs` namespace and report any errors.
+
+`lint --fix **/*.py` will lint and fix all Python files in the repo.
+
+### repl.sh
+
+This is like `nix-shell` but specific to our repo. It will analyze the given
+namespace, pull in all necessary dependencies, and start a bash shell or
+language-specific repl.
+
+#### Examples
 
-File extensions denote _type_ and indicate to the build system how to
-handle the file. So for example:
+`repl.sh Omni/Bild.hs` this creates a nix shell for the `Omni/Bild.hs`
+namespace, and starts a Haskell repl using `ghci` with the namespace already
+loaded.
 
-- `.hs` is Haskell source code, the build system compiles it
-- `.scm` is Scheme source code, ditto
-- `.jnl` is a journal for accounting, the build system will check our
-  balances, make sure we're profitable
-- `.md` for notes and docs, mostly ignored by the build system
+`repl.sh --bash Omni/Log.py` this creates a nix shell for `Omni/Log.py`, but
+starts a bash shell for the namespace instead of a Python repl.
 
-# Setting up remote builds
+## Setting up remote builds
 
 The `Omni.Dev` machine acts as a remote build server and Nix cache. To use it from
 your local machine, your public key must be at `Omni/Keys/$USER.pub` and your