docs: soft update (fix the most obvious drift)

.github/workflows/mdbook_docs.yml

@@ -3,7 +3,7 @@ name: Deploy Docs to GitHub Pages
 on:
   push:
     branches:
-      - core
+      - main
 
 jobs:
   deploy:

doc/CONTRIBUTING.md

@@ -1,25 +1,18 @@
 # Pull Requests
-All development is done in the `develop` branch. Only minor bug-fixes and release
-PRs should target `master`.
 
-If making a change to the template, or adding a feature, please be sure to update the
+## TL;DR;
-relevant docs. Each directory contains its own README.md, which will
+- **Target Branch**: `main`
-automatically be pulled into the [mdbook](https://devos.divnix.com). The book is
+- **Merge Policy**: [`bors`][bors] is alwyas right (→ `bors try`)
-rendered on every change, so the docs should always be up to date.
+- **Docs**: every changeset is expected to contain doc updates
+- **Commit Msg**: be a poet! Comprehensive and explanatory commit messages 
+  should cover the motivation and use case in an easily understandable manner
+  even when read after a few months.
+- **Test Driven Development**: please default to test driven development where possible.
 
-We also use [BORS](https://bors.tech) to ensure that all pull requests pass the
+### Within the Devshell (`nix develop`)
-test suite once at least one review is completed.
+- **Hooks**: please `git commit` within the devshell
+- **Fail Early**: please run from within the devshell on your local machine:
+  - `nix flake check`
 
-# Style
+[bors]: https://bors.tech
-If you wish to contribute please follow these guidelines:
 
-* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
-  includes a pre-commit hook that does this for you.
-
-* The commit message follows the same semantics as [nixpkgs][nixpkgs].
-  * You can use a `#` symbol to specify ambiguities. For example,
-  `develop#zsh: <rest of commit message>` would tell me that you're updating the
-  `zsh` subprofile living under the `develop` profile.
-
-[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
-[nixpkgs]: https://github.com/NixOS/nixpkgs

doc/SUMMARY.md

@@ -6,7 +6,6 @@
   - [Bootstrapping](./start/bootstrapping.md)
   - [From NixOS](./start/from-nixos.md)
 - [Key Concepts](./concepts/index.md)
-  - [Extern](./concepts/extern.md)
   - [Hosts](./concepts/hosts.md)
   - [Overrides](./concepts/overrides.md)
   - [Profiles](./concepts/profiles.md)
@@ -17,17 +16,10 @@
   - [Overlays](./outputs/overlays.md)
   - [Packages](./outputs/pkgs.md)
 - [Concerns]()
-  - [Lib](./lib.md)
   - [Secrets](./secrets.md)
   - [Tests](./tests.md)
-- [Helper Script – `flk`](./flk/index.md)
+- [Helper Script – `bud`](./bud/index.md)
-  - [up](./flk/up.md)
+  - [get](./bud/get.md)
-  - [update](./flk/update.md)
-  - [get](./flk/get.md)
-  - [doi](./flk/doi.md)
-  - [iso](./flk/iso.md)
-  - [install](./flk/install.md)
-  - [home](./flk/home.md)
 - [Integrations](./integrations/index.md)
   - [Cachix](./integrations/cachix.md)
   - [Deploy RS](./integrations/deploy.md)

doc/bud/get.md

@@ -4,7 +4,7 @@ git history.
 
 ## Usage
 ```sh
-flk get DEST-DIR
+bud get DEST-DIR
 ```
 
 If DEST-DIR is ommitted, it defaults to _./devos_.

doc/bud/index.md

@@ -0,0 +1,24 @@
+# [`bud`][bud] command
+The template incudes a convenient script for managing your system called [`bud`][bud].
+
+It is a portable and highly composable system control tool that work anywhere on your host
+or in the flake's devshell. 
+
+Although it comes with some predefined standard helpers,
+it is very extensible and you are encouraged to write your own script snippets
+to ease your workflows. An example is the bud module for a `get` command that
+comes included with `devos`.
+
+While writing scripts you can convenientely access smart environment variables
+that can tell the current architecture, user or host name, among others, regardless
+wether you invoke `bud` within the devshell or as the system-wide installed `bud`.
+
+For details, please review the [bud repo][bud].
+
+## Usage
+```sh
+bud help
+```
+
+
+[bud]: https://github.com/divnix/bud

doc/concepts/extern.md

@@ -1,42 +0,0 @@
-# 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, 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.
-
-## Overlays
-External overlays can directly be added to a channel's `overlays` list.
-
-flake.nix:
-```nix
-{
-  channels.nixos.overlays = [ inputs.agenix.overlay ];
-}
-```
-Upon exporting overlays, these overlays will be automatically filtered out by inspecting the `inputs` argument.
-
-## Modules
-There is a dedicated `nixos.hostDefaults.externalModules` argument for external
-modules.
-
-flake.nix:
-```nix
-{
-  nixos.hostDefaults.externalModules = [ inputs.agenix.nixosModules.age ];
-}
-```
-
-## 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
-{
-  home.externalModules = [ doom-emacs = doom-emacs.hmModule ];
-}
-```
-
-> ##### Note:
-> To avoid declaring "external" modules separately, which is obvious since they come from `inputs`, 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/index.md

@@ -1,4 +1,10 @@
 # Key Concepts
 
-There are few idioms unique to DevOS. This section is dedicated to helping you
+Key concepts are derived from [digga][digga]. Please refer to its
-understand them.
+[docs][digga-docs] for more details.
+
+This section is dedicated to helping you develop a more hands on
+understanding of them them.
+
+[digga-docs]: https://digga.divnix.com
+[digga]: https://github.com/divnix/digga

doc/concepts/users.md

@@ -1,3 +1,8 @@
+> ##### _Note:_
+> This  section and its semantics need a conceptiual rework.
+> Since recently [portable home configurations][portableuser]
+> that are not bound to any specific host are a thing.
+
 # Users
 
 Users are a special case of [profiles](profiles.md) that define system
@@ -69,3 +74,4 @@ nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPac
 
 [home-manager]: https://nix-community.github.io/home-manager
 [modules-list]: https://github.com/divnix/devos/tree/core/users/modules/module-list.nix
+[portableuser]: https://digga.divnix.com/api-reference-home.html#homeusers

doc/flk/doi.md

@@ -1,10 +0,0 @@
-# DigitalOcean
-
-Now you can [create a droplet](https://cloud.digitalocean.com/droplets/new) using your custom image.
-
-Making a DigitalOcean compatible image for `hosts/NixOS.nix` is as simple as:
-```sh
-flk doi NixOS
-```
-
-This works for any file matching `hosts/*.nix` excluding `default.nix`.

doc/flk/home.md

@@ -1,8 +0,0 @@
-# home
-The `home` subcommand is for using your home-manager configurations outside of
-NixOS, providing an awesome mechanism for keeping your environments
-synchronized, even when using other systems.
-
-## Usage
-The [users](../concepts/users.md#external-usage) page contains a good usage
-example.

doc/flk/index.md

@@ -1,20 +0,0 @@
-# flk command
-The devshell for the project incudes a convenient script for managing your
-system called `flk`. Each of the following chapters is a reference for one of
-its subcommands.
-
-## Rebuild
-Without any of the subcommands, `flk` acts as a convenient shortcut for
-`nixos-rebuild`:
-```sh
-flk NixOS build
-```
-
-Will build _hosts/NixOS.nix_. You can change out `build` for `switch`, `test`,
-etc. Any additional arguments are passed through to the call to
-`nixos-rebuild`.
-
-## Usage
-```sh
-flk help
-```

doc/flk/install.md

@@ -1,12 +0,0 @@
-# install
-The `install` subcommand is a simple convenience for `nixos-install`, similar
-to the shortcut for `nixos-rebuild`, all additional arguments are passed
-through.
-
-## Example
-```sh
-flk install NixOS
-```
-
-This will install _hosts/NixOS.nix_ to /mnt. You can override this directory
-using standard `nixos-install` args.

doc/flk/iso.md

@@ -1 +0,0 @@
-../start/iso.md

doc/flk/up.md

@@ -1,4 +0,0 @@
-# up
-The `up` subcommand is a simple shortcut for `nixos-generate-config` that is
-compatible with devos. There is a short explanation in the the getting started
-[guide](../start/from-nixos.md#generate-configuration).

doc/flk/update.md

@@ -1,22 +0,0 @@
-# update
-The `update` subcommand is a simple alias for:
-```sh
-nix flake update
-```
-As it sounds, this will update your lock file.
-
-## Updating Package Sources
-If you pass directory name then it will update that input if the directory
-contains a flake.nix, with an optional arguement to update only a specific
-input in the subflake.
-
-For example, you can update any
-[package sources](../outputs/pkgs.md#automatic-source-updates) you may have
-declared in _pkgs/flake.nix_:
-```sh
-flk update pkgs
-```
-or just its _nixpkgs_:
-```sh
-flk update pkgs nixpkgs
-```

doc/integrations/nvfetcher.md

@@ -38,6 +38,6 @@ fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
 > ##### _Note:_
 > Please refer to the [NvFetcher Readme][nvf-readme] for more options.
 
-[nvf: https://github.com/berberman/nvfetcher
+[nvf]: https://github.com/berberman/nvfetcher
 [nvf-readme]: https://github.com/berberman/nvfetcher#readme
 [sources.toml]: https://github.com/divnix/devos/tree/core/pkgs/sources.toml

doc/mkFlakeOptions.md

@@ -1,541 +0,0 @@
-## channels
-nixpkgs channels to create
-
-
-*_Type_*:
-attribute set of submodules
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## channels.\<name\>.config
-nixpkgs config for this channel
-
-
-*_Type_*:
-attribute set or path convertible to it
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## channels.\<name\>.input
-nixpkgs flake input to use for this channel
-
-
-*_Type_*:
-nix flake
-
-
-*_Default_*
-```
-"self.inputs.<name>"
-```
-
-
-
-
-## channels.\<name\>.overlays
-overlays to apply to this channel
-these will get exported under the 'overlays' flake output
-as \<channel\>/\<name\> and any overlay pulled from ${inputs}
-will be filtered out
-
-
-*_Type_*:
-list of valid Nixpkgs overlay or path convertible to its or anything convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## channelsConfig
-nixpkgs config for all channels
-
-
-*_Type_*:
-attribute set or path convertible to it
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## devshell
-Modules to include in your devos shell. the `modules` argument
-will be exported under the `devshellModules` output
-
-
-*_Type_*:
-submodule
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## devshell.externalModules
-modules to include that won't be exported
-meant importing modules from external flakes
-
-
-*_Type_*:
-list of valid module or path convertible to its or anything convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## devshell.modules
-modules to include in all hosts and export to devshellModules output
-
-
-*_Type_*:
-list of path to a modules or anything convertible to it or path convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## home
-hosts, modules, suites, and profiles for home-manager
-
-
-*_Type_*:
-submodule
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## home.externalModules
-modules to include that won't be exported
-meant importing modules from external flakes
-
-
-*_Type_*:
-list of valid module or path convertible to its or anything convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## home.importables
-Packages of paths to be passed to modules as `specialArgs`.
-
-
-*_Type_*:
-attribute set
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## home.importables.suites
-collections of profiles
-
-
-*_Type_*:
-attribute set of list of paths or anything convertible to its
-
-
-
-
-
-
-## home.modules
-modules to include in all hosts and export to homeModules output
-
-
-*_Type_*:
-list of path to a modules or anything convertible to it or path convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## home.profiles
-WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-both with the importables option. `rakeLeaves` can be used to create profiles and
-by passing a module or `rec` set to `importables`, suites can access profiles.
-Example:
-```
-importables = rec {
-  profiles = digga.lib.importers.rakeLeaves ./profiles;
-  suites = with profiles; { };
-}
-```
-See https://github.com/divnix/digga/pull/30 for more details
-
-
-*_Type_*:
-list of paths
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## home.suites
-WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-both with the importables option. `rakeLeaves` can be used to create profiles and
-by passing a module or `rec` set to `importables`, suites can access profiles.
-Example:
-```
-importables = rec {
-  profiles = digga.lib.importers.rakeLeaves ./profiles;
-  suites = with profiles; { };
-}
-```
-See https://github.com/divnix/digga/pull/30 for more details
-
-
-*_Type_*:
-function that evaluates to a(n) attrs or path convertible to it
-
-
-
-
-
-
-## nixos
-hosts, modules, suites, and profiles for nixos
-
-
-*_Type_*:
-submodule
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## nixos.hostDefaults
-Defaults for all hosts.
-the modules passed under hostDefaults will be exported
-to the 'nixosModules' flake output.
-They will also be added to all hosts.
-
-
-*_Type_*:
-submodule
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## nixos.hostDefaults.channelName
-Channel this host should follow
-
-
-*_Type_*:
-a channel defined in `channels`
-
-
-*_Default_*
-```
-null
-```
-
-
-
-
-## nixos.hostDefaults.externalModules
-modules to include that won't be exported
-meant importing modules from external flakes
-
-
-*_Type_*:
-list of valid module or path convertible to its or anything convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## nixos.hostDefaults.modules
-modules to include in all hosts and export to nixosModules output
-
-
-*_Type_*:
-list of path to a modules or anything convertible to it or path convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## nixos.hostDefaults.system
-system for this host
-
-
-*_Type_*:
-system defined in `supportedSystems`
-
-
-*_Default_*
-```
-null
-```
-
-
-
-
-## nixos.hosts
-configurations to include in the nixosConfigurations output
-
-
-*_Type_*:
-attribute set of submodules
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## nixos.hosts.\<name\>.channelName
-Channel this host should follow
-
-
-*_Type_*:
-a channel defined in `channels`
-
-
-*_Default_*
-```
-null
-```
-
-
-
-
-## nixos.hosts.\<name\>.modules
-modules to include
-
-
-*_Type_*:
-list of valid module or path convertible to its or anything convertible to it
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## nixos.hosts.\<name\>.system
-system for this host
-
-
-*_Type_*:
-system defined in `supportedSystems`
-
-
-*_Default_*
-```
-null
-```
-
-
-
-
-## nixos.importables
-Packages of paths to be passed to modules as `specialArgs`.
-
-
-*_Type_*:
-attribute set
-
-
-*_Default_*
-```
-{}
-```
-
-
-
-
-## nixos.importables.suites
-collections of profiles
-
-
-*_Type_*:
-attribute set of list of paths or anything convertible to its
-
-
-
-
-
-
-## nixos.profiles
-WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-both with the importables option. `rakeLeaves` can be used to create profiles and
-by passing a module or `rec` set to `importables`, suites can access profiles.
-Example:
-```
-importables = rec {
-  profiles = digga.lib.importers.rakeLeaves ./profiles;
-  suites = with profiles; { };
-}
-```
-See https://github.com/divnix/digga/pull/30 for more details
-
-
-*_Type_*:
-list of paths
-
-
-*_Default_*
-```
-[]
-```
-
-
-
-
-## nixos.suites
-WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
-both with the importables option. `rakeLeaves` can be used to create profiles and
-by passing a module or `rec` set to `importables`, suites can access profiles.
-Example:
-```
-importables = rec {
-  profiles = digga.lib.importers.rakeLeaves ./profiles;
-  suites = with profiles; { };
-}
-```
-See https://github.com/divnix/digga/pull/30 for more details
-
-
-*_Type_*:
-function that evaluates to a(n) attrs or path convertible to it
-
-
-
-
-
-
-## outputsBuilder
-builder for flake system-spaced outputs
-The builder gets passed an attrset of all channels
-
-
-*_Type_*:
-function that evaluates to a(n) attrs
-
-
-*_Default_*
-```
-"channels: { }"
-```
-
-
-
-
-## self
-The flake to create the devos outputs for
-
-*_Type_*:
-nix flake
-
-
-
-
-
-
-## supportedSystems
-The systems supported by this flake
-
-
-*_Type_*:
-list of strings
-
-
-*_Default_*
-```
-["aarch64-linux","i686-linux","x86_64-darwin","x86_64-linux"]
-```
-
-
-

doc/outputs/pkgs.md

@@ -13,16 +13,6 @@ the supported systems listed in the package's `meta.platforms` attribute.
 And, as usual, every package in the overlay is also available to any NixOS
 [host](../concepts/hosts.md).
 
-## Automatic Source Updates
-There is the added, but optional, convenience of declaring your sources in
-_pkgs/flake.nix_ as an input. You can then access them from the `srcs` package.
-This allows updates to be managed automatically by simply
-[updating](../flk/update.md#updating-package-sources) the lock file. No
-more manually entering sha256 hashes!
-
-As an added bonus, version strings are also generated automatically from either
-the flake ref, or the date and git revision of the source.
-
 ## Example
 pkgs/development/libraries/libinih/default.nix:
 ```nix

doc/start/iso.md

@@ -2,13 +2,13 @@
 
 Making and writing an installable iso for `hosts/NixOS.nix` is as simple as:
 ```sh
-flk iso NixOS
+bud build NixOS bootstrapIso
 
 dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
   status=progress oflag=sync
 ```
 
-This works for any file matching `hosts/*.nix` excluding `default.nix`.
+This works for any host.
 
 ## ISO image nix store & cache
 

flake.nix

@@ -152,7 +152,7 @@
       }
     //
     {
-      budModules = { devos = import ./pkgs/bud; };
+      budModules = { devos = import ./bud; };
     }
   ;
 }