From 828a9394700a5c8591e5f9c8b469d7a116f5b2de Mon Sep 17 00:00:00 2001
From: Timothy DeHerrera <tim.deh@pm.me>
Date: Mon, 28 Dec 2020 22:15:10 -0700
Subject: [PATCH] README.md: Add some useful information

---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 72 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 86e351ff..0387f861 100644
--- a/README.md
+++ b/README.md
@@ -34,18 +34,60 @@ Flakes are still new, so not everything works yet. However, it has been to
 merged in [nixpkgs][nixpkgs] via [`pkgs.nixFlakes`][nixFlakes]. Thus, this
 project should be considered _experimental_, until flakes become the default.
 
-Also, flakes are meant to deprecate nix-channels. It's recommend not to install
-any. If your really want them, they should work if you hook them into
+Also, flakes are meant to deprecate nix-channels. It's recommended not to
+install any. If your really want them, they should work if you hook them into
 `NIX_PATH`.
 
+# Sharing
+One of the great benefits of flakes is the ability to easily share your user
+defined packages, modules and other nix expressions without having to merge
+anything upstream. In that spirit, everything defined in this flake is usable
+from other flakes. So even if you don't want to use this project as a template,
+you can still pull in any useful modules, packages or profiles defined here.
+
+From the command line:
+```sh
+# to see what this flake exports
+nix flake show "github:nrdxp/nixflk"
+
+# run an app
+nix run "github:nrdxp/nixflk#someApp"
+
+# start a dev shell for a given derivation
+nix develop "github:nrdxp/nixflk#somePackage"
+
+# a nix shell with the package in scope
+nix shell "github:nrdxp/nixflk#somePackage"
+```
+
+From within a flake:
+```nix
+{
+  inputs.nixflk.url = "github:nrdxp/nixflk";
+
+  outputs = { self, nixpkgs, nixflk, ... }:
+  {
+    nixosConfigurations.example = nixpkgs.lib.nixosSystem {
+      # ...
+        modules = [
+        nixflk.nixosModules.someModule
+        ({
+          nixpkgs.overlays = [ nixflk.overlay nixflk.overlays.someOverlay ];
+        })
+        # ...
+      ];
+    };
+  };
+}
+```
+
 # Setup
-There are many way to get up and running. You can fork this repo or use it as
+There are a few ways to get up and running. You can fork this repo or use it as
 a template. There is a [bare branch][bare] if you want to start with a
-completely empty template and make your own profiles from scratch.
-
-You'll need to have NixOS already installed since the `nixos-install` script
-doesn't yet support flakes.
+completely empty template and make your own profiles from scratch. The only
+hard requirement is nix itself. The `shell.nix` will pull in everything else.
 
+## Flake Templates
 If you already have [nix-command][nix-command] setup you can:
 ```sh
 # for standard template
@@ -55,36 +97,42 @@ nix flake new -t "github:nrdxp/nixflk" flk
 nix flake new -t "github:nrdxp/nixflk/bare" flk
 ```
 
-However you decide to acquire the repo, once you have it, you'll want to __move
-or symlink__ it to `/etc/nixos` for ease of use. Once inside:
-
+## Nix Only
+Once you have this repo, you'll want to __move or symlink__ it to `/etc/nixos`
+for ease of use. Once inside:
 ```sh
+# This will setup nix-command and pull in the needed tools
 nix-shell # or `direnv allow` if you prefer
-```
 
-From here it's up to you. You can deploy the barebones [NixOS](./hosts/NixOS.nix)
-host and build from there, or you can copy your existing `configuration.nix`.
-You'll probably at least need to setup your `fileSystems` and make sure the
-[locale](./local/locale.nix) is correct.
+# quick way to setup your fileSystems (assuming they are partioned):
+sudo mount /dev/<install-drive> /mnt
+nixos-generate-config --root /mnt --show-hardware-config > hosts/yourConfig.nix
 
-Once you're ready to deploy you can use `nixos-rebuild` if your NixOS version
-is recent enough to support flakes, _or_ the [shell.nix](./shell.nix) defines
-its own `flk` command in case you need it.
+# Edit your config to add a bootloader
+$EDITOR hosts/yourConfig.nix
 
-```sh
-# Usage: flk host {switch|boot|test|iso}
-flk <host-filename> test
+# The following should work fine for EFI systems.
+# boot.loader.systemd-boot.enable = true;
+# boot.loader.efi.canTouchEfiVariables = true;
+
+# Set your locale
+$EDITOR local/locale.nix
+
+# install NixOS to bare metal
+flk install yourConfig # deploys hosts/yourConfig.nix
+
+# if you already have NixOS and just want to deploy your new setup
+flk yourConfig switch
 ```
 
 ## Build an ISO
 
+You can make an ISO and customize it by modifying the [niximg](./hosts/niximg.nix)
+file:
 ```sh
 flk iso
 ```
 
-You can make an ISO and customize it by modifying the [niximg](./hosts/niximg.nix)
-file:
-
 ## Use a Package from NUR
 
 NUR is wired in from the start. For safety, nothing is added from it by default,