update doc to match new template format and logic

doc/concepts/extern.md

@@ -1,45 +1,42 @@
 # External Art
 When you need to use a module, overlay, or pass a value from one of your inputs
-to the rest of your NixOS configuration, [extern][extern] is where you do it.
+to the rest of your NixOS configuration, you can make use of a couple arguments.
+It is encouraged to add external art directly in your `flake.nix` so the file
+represents a complete dependency overview of your flake.
 
-Modules and overlays are self explanatory, and the `specialArgs` attribute is
-used to extend the arguments passed to all NixOS modules, allowing for
-arbitrary values to be passed from flake inputs to the rest of your
-configuration.
+## Overlays
+External overlays can directly be added to a channel's `overlays` list.
 
-## Home Manager
-There is also an `hmModules` attribute set for pulling home-manager modules in
-from the outside world:
-
-### Declare:
 flake.nix:
 ```nix
 {
-  inputs.doom-emacs.url = "github:vlaci/nix-doom-emacs";
+  channels.nixos.overlays = [ inputs.agenix.overlay ];
 }
 ```
+These overlays will be automatically filtered by inspecting the `inputs` argument.
 
-extern/default.nix:
+## Modules
+There is a dedicated `nixos.hostDefaults.externalModules` argument for external
+modules.
+
+flake.nix:
 ```nix
-with inputs;
 {
-  hmModules = {
-    doom-emacs = doom-emacs.hmModule;
-  };
+  nixos.hostDefaults.externalModules = [ inputs.agenix.nixosModules.age ];
 }
 ```
 
-### Use:
-users/nixos/default.nix:
+## Home Manager
+Since there isn't a `hosts` concept for home-manager, externalModules is just a
+top-level argument in the `home` namespace.
+
+flake.nix:
 ```nix
-{ hmModules, ... }:
 {
-  home-manager.users.nixos = {
-    imports = [ hmModules.doom-emacs ] ;
-
-    programs.doom-emacs.enable = true;
-  };
+  home.externalModules = [ doom-emacs = doom-emacs.hmModule ];
 }
 ```
 
-[extern]: https://github.com/divnix/devos/tree/core/extern/default.nix
+> ##### Note:
+> The optimal solution would be to automatically export modules that were created in
+> your flake. But this is not possible due to NixOS/nix#4740.

doc/concepts/hosts.md

@@ -1,19 +1,18 @@
 # Hosts
 
 Nix flakes contain an output called `nixosConfigurations` declaring an
-attribute set of valid NixOS systems. To simplify the management and creation
-of these hosts, devos automatically imports every _.nix_ file inside this
-directory to the mentioned attribute set, applying the projects defaults to
-each. The only hard requirement is that the file contain a valid NixOS module.
+attribute set of valid NixOS systems. To create hosts, you can use the 
+`nixos.hosts` argument and pass `modules` to each host. Host-specific modules
+typically go in the `hosts` folder of the template.
 
-As an example, a file `hosts/system.nix` will be available via the flake
-output `nixosConfigurations.system`. You can have as many hosts as you want
-and all of them will be automatically imported based on their name.
+Each host should follow a certain channel to define the `pkgs` of that host.
+You can use the `nixos.hostDefaults` to set defaults and global modules for all
+hosts.
 
 For each host, the configuration automatically sets the `networking.hostName`
-attribute to the name of the file minus the _.nix_ extension. This is for
-convenience, since `nixos-rebuild` automatically searches for a configuration
-matching the current systems hostname if one is not specified explicitly.
+attribute to the name of the host. This is for convenience, since `nixos-rebuild`
+automatically searches for a configuration matching the current systems hostname
+if one is not specified explicitly.
 
 It is recommended that the host modules only contain configuration information
 specific to a particular piece of hardware. Anything reusable across machines
@@ -22,12 +21,8 @@ is best saved for [profile modules](./profiles.md).
 This is a good place to import sets of profiles, called [suites](./suites.md),
 that you intend to use on your machine.
 
-Additionally, this is the perfect place to import anything you might need from
-the [nixos-hardware][nixos-hardware] repository.
-
-> ##### _Note:_
-> Set `nixpkgs.system` to the architecture of this host, default is "x86_64-linux".
-> Keep in mind that not all packages are available for all architectures.
+Additionally, you can pass modules from [nixos-hardware][nixos-hardware] in the
+`modules` argument for relevant hosts.
 
 ## Example
 
@@ -44,4 +39,15 @@ hosts/librem.nix:
 }
 ```
 
+flake.nix
+```nix
+{
+  nixos.hosts.librem = {
+    system = "aarch64-linux";
+    modules = ./hosts/librem.nix;
+  };
+}
+```
+
+
 [nixos-hardware]: https://github.com/NixOS/nixos-hardware

doc/concepts/overrides.md

@@ -1,47 +1,39 @@
 # Overrides
-By default, the NixOS systems are based on unstable. While it is trivial to
-change this to a stable release, or any other branch of nixpkgs by
-changing the flake url, sometimes all we want is a single package from another
-branch.
+Each NixOS host follows one channel. But many times it is useful to get packages
+or modules from different channels.
 
-This is what the overrides are for. By default, they are pulled directly from
-nixpkgs/master, but you can change the `override` flake input url to
-nixos-unstable, or even a specific sha revision.
-
-They are defined in the `extern/overrides.nix` file.
+This is what the overrides are for. You can make use of the `overrides.nix` to
+override specific packages to be pulled from other channels. Any overlay may get
+`channels` as their first argument.
 
 ## Example
 
 ### Packages
 The override packages are defined as a regular overlay with an extra arguement
-`pkgs`. This refers to the packages built from the `override` flake.
+`channels`. This refers to all channels defined in `flake.nix`.
 
-Pulling the manix package from the override flake:
+Pulling the manix package from the latest flake:
 ```nix
-{
-  packages = pkgs: final: prev: {
-    inherit (pkgs) manix;
-  };
+channels: final: prev: {
+  inherit (pkgs.latest) manix;
 }
 ```
 
 ### Modules
 
-You can also pull modules from override. Simply specify their path relative to
-the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added
-to `disabledModules` and the new version imported into the configuration.
+You can also pull modules from other channels. All modules have access to the 
+`modulesPath` for each channel as `<channelName>ModulesPath`. And you can use
+`disabledModules` to remove modules from the current channel.
 
-Pulling the zsh module from the override flake:
+Pulling the zsh module from the latest flake:
 ```nix
-{
-  modules = [ "programs/zsh/zsh.nix" ];
+{ latestModulesPath }: {
+  modules = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
+  disabledModules = [ "programs/zsh/zsh.nix" ];
 }
 ```
 
 > ##### _Note:_
-> Sometimes a modules name will change from one branch to another. This is what
-> the `disabledModules` list is for. If the module name changes, the old
-> version will not automatically be disabled, so simply put it's old name in
-> this list to disable it.
+> Sometimes a modules name will change from one branch to another.
 
 [nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

doc/concepts/suites.md

@@ -6,7 +6,13 @@ profiles. For good examples, check out the suites defined in the community
 In the future, we will use suites as a mechanism for deploying various machine
 types which don't depend on hardware, such as vm's and containers.
 
-They are defined in `profiles/suites.nix`.
+They are defined with the `suites` argument in either `home` or `nixos` namespace.
+Suites should be passed as a function that take profiles as an argument.
+
+The profiles are passed based on the folder names and list passed to the relevant
+`profiles` argument. In the template's flake.nix `profiles` is set as
+`[ ./profiles ./users ]` and that corresponds to the `{ profiles, users }` argument
+pattern.
 
 ## Definition
 ```nix

doc/outputs/overlays.md

@@ -4,7 +4,7 @@ we want to keep the process as simple and straightforward as possible.
 
 Any _.nix_ files declared in this directory will be assumed to be a valid
 overlay, and will be automatically imported into all [hosts](../concepts/hosts.md), and
-exported via `overlays.<file-basename>` _as well as_
+exported via `overlays.<channel>/<pkgName>` _as well as_
 `packages.<system>.<pkgName>` (for valid systems), so all you have to do is
 write it.
 

doc/start/from-nixos.md

@@ -10,10 +10,18 @@ flk up
 This will make a new file `hosts/up-$(hostname).nix`, which you can edit to
 your liking.
 
+You must then add a host to `nixos.hosts` in flake.nix:
+```nix
+{
+  nixos.hosts = {
+    modules = hosts/NixOS.nix;
+  };
+}
+```
+
 Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for
 your region. Keep in mind that `networking.hostName` with be automatically
-set to the filename of your hosts file, so `hosts/my-host.nix` will have the
-hostname `my-host`.
+set to the name of your host;
 
 Now might be a good time to read the docs on [suites](../concepts/suites.md) and
 [profiles](../concepts/profiles.md) and add or create any that you need.

doc/tests.md

@@ -7,7 +7,7 @@ configuration, and, optionally, run them in
 
 ## Lib Tests
 You can easily write tests for your own library functions in the
-___tests/lib.nix___ file and they will be run on every `nix flake check` or
+lib/___tests/lib.nix___ file and they will be run on every `nix flake check` or
 during a CI run.
 
 ## Unit Tests