From 4be2f48d8dcdd61e8cbfce5304779f8f8ab98aef Mon Sep 17 00:00:00 2001
From: Daniel Flanagan <daniel@lyte.dev>
Date: Thu, 20 Mar 2025 14:03:51 -0500
Subject: [PATCH] fix(#19): readme and docs

---
 lib/doc/readme.md | 31 +++++++++++++++++++++++++------
 readme.md         | 36 ++++++++++++++++++++++++++++--------
 2 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/lib/doc/readme.md b/lib/doc/readme.md
index 9490ce7..2bb68b7 100644
--- a/lib/doc/readme.md
+++ b/lib/doc/readme.md
@@ -1,6 +1,6 @@
-# Internal Usage
+# Documentation
 
-## Secrets?
+## Internal Setup
 
 If you're deploying anything secrets-related, you will need the proper keys:
 
@@ -9,7 +9,7 @@ $ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/sops/age
 $ pass age-key >> ${XDG_CONFIG_HOME:-~/.config}/sops/age/keys.txt
 ```
 
-## Update Server
+# Updates
 
 **NOTE**: I want to establish a solid way to do this without `root@`.
 
@@ -62,7 +62,7 @@ nix run nixpkgs#nixos-rebuild -- --flake ".#$host" \
 ssh "root@$host" nixos-rebuild --rollback switch
 ```
 
-## Provisioning New NixOS Hosts
+# Provisioning New NixOS Hosts
 
 ```shell
 nix run --extra-experimental-features 'nix-command flakes' \
@@ -103,7 +103,7 @@ nix-shell --packages git \
     --option trusted-public-keys 'cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= h.lyte.dev:HeVWtne31ZG8iMf+c15VY3/Mky/4ufXlfTpT8+4Xbs0='"
 ```
 
-Then:
+### Post-Installation Setup
 
 1. Tailscale connection and roles.
 
@@ -129,4 +129,23 @@ $ rsync -r ~/.local/share/password-store $host:~/.local/share/password-store
 
 # Temporary Firewall Changes
 
-Source: https://discourse.nixos.org/t/how-to-temporarily-open-a-tcp-port-in-nixos/12306/2
+```shell
+$ nixos-firewall-tool --help
+```
+
+Or if we're performing ad-hoc operations on the router's nftables rules as root:
+
+```shell
+# add a rule
+$ nft add rule ...
+
+# find a rule
+$ nft -a list table $table
+# examples:
+$ nft -a list table nat
+$ nft -a list table filter
+$ nft -a list table ip
+
+# delete a rule
+$ nft delete rule $table $chain handle $handle
+```
diff --git a/readme.md b/readme.md
index 072f20f..569e1ed 100644
--- a/readme.md
+++ b/readme.md
@@ -7,17 +7,37 @@ Nix for <code>lytedev</code>
 
 [![pre-merge status](https://git.lyte.dev/lytedev/nix/badges/workflows/pre-merge.yaml/badge.svg)](https://git.lyte.dev/lytedev/nix/actions?workflow=pre-merge.yaml)
 
+Desktop - Laptop - Servers - Routers - Packages - Templates
+
 </div>
 
-My Nix monorepo.
+# Details
 
-- Desktop configurations
-- Laptop configurations
-- Home server configurations
-- Remote server configurations
-- Home router configurations
-- My packages
-- New project templates
+I aim for declaring everything where possible, but I definitely break the rules
+if it's convenient enough and try to write it down when I do so. I also don't
+like repeating myself in configuration. I am mostly focused on being pragmatic
+and getting things done and doing so in a way that makes it easy to keep doing
+so (maintainability), but I also occasionally fall into experimenting with big
+refactors of the code for no real gain.
+
+## Layers
+
+- Common defaults (machines that I might not interact with at all or only
+  rarely, such as backup targets)
+- Machines that I interact with only remotely (`shell` class)
+- Machines that I interact with directly, such as a laptop or my desktop
+  workstation (`desktop` class)
+
+## Notable Links
+
+- [Set of NixOS modules](./lib/modules/nixos/default.nix)
+  - [Home router module](./lib/modules/nixos/router.nix)
+- [Set of Home Manager modules](./lib/modules/home/default.nix)
+- [NixOS hosts](./packages/hosts/default.nix)
+  - [Desktop workstation](./packages/hosts/dragon.nix)
+  - [Primary laptop](./packages/hosts/foxtrot.nix)
+  - [Server](./packages/hosts/beefcake.nix)
+  - [Router](./packages/hosts/router.nix)
 
 # Docs