diff --git a/README.md b/README.md
index 76c40be..c93eddc 100644
--- a/README.md
+++ b/README.md
@@ -10,3 +10,84 @@ $ nix build .#darwinConfigurations.matbook.system
 $ ./result/sw/bin/darwin-rebuild switch --flake .
 ```
 
+## organization
+
+### flake.nix
+
+main entry point and glue for submodules
+
+### default.nix
+
+compatibility for legacy nix tooling, eg `nix-build`
+
+### nixpkgs.nix
+
+used to hack compatibility for `<nixpkgs>` in nix expressions
+
+### configs
+
+non-nix configurations
+
+### darwin
+
+[nix-darwin](https://github.com/LnL7/nix-darwin) specific configuration
+
+#### bootstrap.nix
+
+minimal configuration for a base macOS system
+
+#### default.nix
+
+full featured macOS system
+
+#### homebrew.nix
+
+homebrew + mac app store apps
+
+#### macos-defaults.nix
+
+macOS system settings
+
+### home
+
+[home-manager](https://github.com/nix-community/home-manager) configuration
+
+#### configs
+
+simple configurations
+
+#### copyApplications.nix
+
+hack to work around https://github.com/nix-community/home-manager/issues/1341
+
+#### default.nix
+
+main user environment configuration
+
+#### kitty.nix
+
+kitty terminal configuration and integrations
+
+#### shells.nix
+
+fish shell configuration and integrations
+
+### modules
+
+#### darwin
+
+various extensions for nix-darwin
+
+#### home
+
+customization for kitty terminal and neovim
+
+### overlays
+
+#### colors
+
+cross-application color configurations
+
+### pkgs
+
+custom-built nix packages
diff --git a/home/copyApplications.nix b/home/copyApplications.nix
index 189738c..3f503da 100644
--- a/home/copyApplications.nix
+++ b/home/copyApplications.nix
@@ -1,5 +1,8 @@
 # adapted from
 # https://github.com/reckenrode/nixos-configs/blob/2acd7b0699fd57628deb7b8855b4d5f0ea8f8cb1/common/darwin/home-manager/copyApplications.nix
+# workaround for
+# https://github.com/nix-community/home-manager/issues/1341
+
 
 { config, pkgs, lib, ... }: