### Document Nix Module Options Clearly

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Provide clear, concise documentation for each option using the `description` attribute. Include an example for clarity.

```nix
{lib, ...}: {
  options.myFeature = lib.mkOption {
    type = lib.types.str;
    default = "default-value";
    description = "Clear, one-line description of this option";
    example = "example-value";
  };
}
```

--------------------------------

### Top-Level Configuration with lib.evalModules

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Alternative method for creating the top-level configuration using lib.evalModules directly. Useful for simpler setups or when flake-parts is not desired.

```nix
# flake.nix
{
  description = "Dendritic configuration";
  
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  };
  
  outputs = inputs@{self, nixpkgs, ...}: let
    lib = nixpkgs.lib;
  in {
    # Manual top-level evaluation
    config = lib.evalModules {
      modules = import-tree ./modules;
      specialArgs = {inherit self inputs;};
    };
  };
}

```

--------------------------------

### Apply NixOS and home-manager Modules

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Example of applying both NixOS and home-manager modules within a single configuration file in the dendritic structure.

```nix
# modules/features/shell.nix
{config, ...}: {
  # Applies to both NixOS and home-manager
  config.nixos.modules.shell = {
    programs.bash.enable = true;
  };
  
  config.home-manager.modules.shell = {
    programs.bash.bashrcExtra = ''
      alias ll='ls -lah'
    '';
  };
}

```

--------------------------------

### Install import-tree Helper

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Instructions to add the `import-tree` utility to your flake inputs. This helper simplifies module imports.

```nix
# Add to inputs in flake.nix
import-tree.url = "github:vic/import-tree";

```

--------------------------------

### Minimal Dendritic Setup (flake.nix)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/01-overview.md

This snippet shows the basic structure of a `flake.nix` file to implement the dendritic pattern using `flake-parts`. It demonstrates how to import all Nix files from a `./modules` directory recursively.

```nix
# flake.nix
{
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
  
  outputs = inputs@{self, flake-parts, ...}:
    flake-parts.lib.mkFlake {inputs;} {
      systems = ["x86_64-linux"];
      
      imports = [ ./modules ]; # Auto-import all modules
      
      # Top-level config is now available in outputs
      # Lower-level configs (nixos, home-manager) can reference it
    };
}
```

--------------------------------

### Flake Configuration: Importing Dendritic Modules

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Example of how to integrate the dendritic modules into a Nix flake. It uses `lib.nixosSystem` to apply the modules defined in the `flake.nix` file.

```nix
nixosConfigurations.my-laptop = lib.nixosSystem {
  modules = [
    (config.nixos.laptop or [])
  ];
};
```

--------------------------------

### Before Migration: Non-Dendritic Nix Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

An example of a monolithic NixOS configuration file before adopting the dendritic pattern. Features are mixed within a single file.

```nix
# nixos/laptop.nix
{inputs, pkgs, ...}:
{
  imports = [ inputs.home-manager.nixosModule ];
  sound.enable = true;
  services.pipewire.enable = true;
  fonts.enableDefaultPackages = true;
  # ... many features mixed together
}
```

--------------------------------

### Examples and Snippets

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/MANIFEST.txt

Information on the examples and code snippets provided for the Dendritic project.

```APIDOC
## Examples

This section covers the examples and code snippets available for the Dendritic project.

### Overview

*   **5 complete working examples**: Demonstrates practical usage scenarios.
*   **150+ code snippets**: Provides numerous small, focused code examples.
*   **All example files with full context**: Ensures examples are self-contained and understandable.
*   **Usage patterns demonstrated**: Illustrates common and advanced usage patterns.

### Location

*   Examples are typically found in dedicated example files, often within a structure like `05-examples.md`.
```

--------------------------------

### Integrating Dendritic with flake-parts

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/02-module-system.md

This example shows how to integrate dendritic modules with flake-parts in a `flake.nix` file. Dendritic's `config` is accessible in per-system evaluations.

```nix
# flake.nix
{
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
  
  outputs = inputs@{flake-parts, ...}:
    flake-parts.lib.mkFlake {inherit inputs;} {
      systems = ["x86_64-linux"];
      
      # All files in modules/ are auto-imported as top-level modules
      imports = [ ./modules ];
      
      # Access dendritic config in per-system evaluation
      perSystem = {config, ...}:
        {
          packages.default = config.myApp.package;
        };
    };
}

```

--------------------------------

### Building Dendritic Configurations with Nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Commands to check the Nix flake configuration, build the NixOS system configuration, and build the home-manager activation package. These commands are used to verify and deploy the dendritic setup.

```bash
# Check configuration
nix flake check

# Build NixOS configuration
nix build '.#nixosConfigurations.my-laptop.config.system.build.toplevel'

# Build home-manager configuration
nix build '.#homeConfigurations."user@my-laptop".activationPackage'

```

--------------------------------

### Migration Guide

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/MANIFEST.txt

Guidance and procedures for migrating existing projects to use the Dendritic framework.

```APIDOC
## Migration

This section provides a guide for migrating existing projects to Dendritic.

### Migration Process

*   **Pre-migration assessment**: Steps to evaluate readiness for migration.
*   **Step-by-step migration path**: A detailed, sequential guide for the migration process.
*   **Incremental strategy**: Guidance on performing migration in stages.

### Patterns and Procedures

*   **Common patterns with before/after**: Illustrates common migration scenarios with comparative code examples.
*   **Rollback procedures**: Outlines steps for rolling back changes if necessary.

### Location

*   Migration details are typically found in a dedicated guide, such as `07-migration-guide.md`.
```

--------------------------------

### Nix Type System Examples

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/02-module-system.md

Demonstrates various types available in the Nix type system for option declarations, such as string, integer, boolean, attribute sets, lists, and optional types.

```nix
mkOption { type = lib.types.str; }
```

```nix
mkOption { type = lib.types.int; }
```

```nix
mkOption { type = lib.types.bool; }
```

```nix
mkOption { type = lib.types.attrs; }
```

```nix
mkOption { type = lib.types.listOf lib.types.str; }
```

```nix
mkOption { type = lib.types.nullOr lib.types.str; }
```

```nix
mkOption { type = lib.types.deferredModule; }
```

```nix
mkOption { type = lib.types.submodule { options = {...}; }; }
```

--------------------------------

### Install import-tree Library in flake.nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Add the `import-tree` library as an input in your `flake.nix` file for automatic recursive module importing.

```nix
inputs.import-tree.url = "github:vic/import-tree";
```

--------------------------------

### Enable Direnv Integration in Nix Project

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Use the 'use flake' command in the .envrc file to enable automatic environment setup for Nix flakes when entering the project directory.

```bash
# .envrc
use flake
```

--------------------------------

### Create Baseline flake.nix for Dendritic Migration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Initial flake.nix structure required to start migrating to the dendritic pattern. It includes necessary inputs like nixpkgs and flake-parts.

```nix
# flake.nix
{ 
  description = "My configuration (migrating to dendritic)";
  
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    home-manager.url = "github:nix-community/home-manager/master";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };
  
  outputs = inputs@{flake-parts, ...}:
    flake-parts.lib.mkFlake {inherit inputs;} {
      systems = ["x86_64-linux"];
      imports = [ ./modules ];
    };
}
```

--------------------------------

### Reusing Base Modules with Deferred Modules

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/01-overview.md

Illustrates how to use a deferred module to reuse base modules in another top-level module. This example shows reusing NixOS base modules for a PC configuration.

```nix
# modules/nixos/pc.nix
{config, lib, ...}:
{
  options.nixos.pc = lib.mkOption {
    type = lib.types.deferredModule;
  };
  config.nixos.pc = config.nixos.base; # Reuse base modules
}
```

--------------------------------

### Selective Nix Module Import with Patterns

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Import Nix modules selectively by specifying a pattern to match filenames. This example imports only files prefixed with 'feature-'.

```nix
# modules/default.nix
{
  imports = let
    inherit (builtins) readDir filter;
    
    loadMatching = pattern: path:
      let entries = readDir path;
      in
        lib.filter (name: lib.hasPrefix pattern name) 
          (lib.attrNames (lib.filterAttrs (n: t: t == "regular" && lib.hasSuffix ".nix" n) entries));
  in
    # Import only feature files, not package files
    map (f: ./. + "/${f}") (loadMatching "feature-" ./.);
}
```

--------------------------------

### Minimal Dendritic NixOS and Home-Manager Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

This Nix flake defines the most basic dendritic setup, integrating NixOS and home-manager. It specifies inputs and outputs for flake-parts, enabling the creation of system and user configurations.

```nix
# flake.nix
{
  description = "Minimal dendritic configuration";
  
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    home-manager.url = "github:nix-community/home-manager/master";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };
  
  outputs = inputs@{flake-parts, ...}:
    flake-parts.lib.mkFlake {inherit inputs;} {
      systems = ["x86_64-linux"];
      imports = [ ./modules ];
      
      flake = let
        inherit (inputs) nixpkgs;
        lib = nixpkgs.lib;
        config = self.config;
      in {
        nixosConfigurations.my-laptop = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";
          modules = [
            config.nixos.laptop
            {
              networking.hostName = "my-laptop";
              system.stateVersion = "24.05";
            }
          ];
        };
        
        homeConfigurations."user@my-laptop" = inputs.home-manager.lib.homeManagerConfiguration {
          pkgs = nixpkgs.legacyPackages.x86_64-linux;
          modules = [
            config.home-manager.user
            {
              home.username = "user";
              home.homeDirectory = "/home/user";
              home.stateVersion = "24.05";
            }
          ];
        };
      };
    };
}

```

```nix
# modules/default.nix
{
  imports = [
    ./nixos/base.nix
  ];
}

```

```nix
# modules/nixos/base.nix
{lib, ...}:
{
  options = {
    nixos.laptop = lib.mkOption {
      type = lib.types.deferredModule;
      default = {};
    };
    
    home-manager.user = lib.mkOption {
      type = lib.types.deferredModule;
      default = {};
    };
  };
  
  config = {
    nixos.laptop = {
      boot.loader.systemd-boot.enable = true;
      boot.loader.efi.canTouchEfiVariables = true;
      services.openssh.enable = true;
    };
    
    home-manager.user = {
      programs.bash.enable = true;
      programs.git = {
        enable = true;
        userName = "User";
        userEmail = "user@example.com";
      };
    };
  };
}

```

--------------------------------

### Create Module Directory and Entry Point

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Sets up the directory structure for modules and creates the main entry point file that imports all sub-modules.

```bash
mkdir -p modules
cd modules

```

```nix
# modules/default.nix
{
  imports = import-tree ./.;
}

```

--------------------------------

### Create Initial modules/default.nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Sets up the main module import file for the dendritic structure. This file will list other modules to be imported.

```nix
# modules/default.nix
{
  imports = [
    ./options.nix
    # More modules will be added here
  ];
}
```

--------------------------------

### lib.mkOption Signature

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/02-module-system.md

Illustrates the common arguments for lib.mkOption, including type constraints, default values, descriptions, and visibility/mutability flags.

```nix
lib.mkOption {
  type = lib.types.str;              # Type constraint
  default = "value";                 # Default value (optional)
  description = "...";               # Human-readable description
  internal = false;                  # Hide from documentation
  readOnly = false;                  # Prevent assignment outside options
  example = "...";                   # Example value
}
```

--------------------------------

### Integrate home-manager Configuration (Before)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Illustrates the directory structure before integrating home-manager configurations into modules.

```tree
nixos/
  configuration.nix
  hardware.nix
home-manager/
  home.nix
  shell.nix
  development.nix

```

--------------------------------

### Defining a Value in Top-Level Config

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/01-overview.md

Example of defining a value, such as a script definition, in the top-level `config` attribute from a module. This value can then be accessed by other modules.

```nix
# modules/scripts/foo.nix
{config, ...}:
{
  config.scripts.foo = { /* script definition */ };
}
```

--------------------------------

### Home-Manager Integration with Dendritic

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Demonstrates a full integration pattern for modular home configurations using Dendritic and Home-Manager. This snippet shows how to map configurations from a JSON file.

```nix
homeConfigurations = lib.mapAttrs (name: config: 
  home-manager.lib.homeManagerConfiguration {
    pkgs = nixpkgs.legacyPackages.x86_64-linux;
    modules = [config.home-manager.base];
  }
) (builtins.fromJSON (builtins.readFile ./systems.json));
```

--------------------------------

### Use `mkDefault` and `mkForce` for Option Values

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Employ `lib.mkDefault` for values that should be overrideable by other modules. Use `lib.mkForce` for high-priority settings that are difficult to override.

```nix
{lib, ...}: {
  config = {
    # Can be overridden by other modules
    networking.firewall.allowedTCPPorts = lib.mkDefault [22];
    
    # High priority, hard to override
    security.sudo.enable = lib.mkForce true;
  };
}
```

--------------------------------

### Create Nix Option Reference Tables

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Generate a markdown table of Nix options, including their key, type, and value, by evaluating the Nix configuration.

```bash
#!/bin/bash
# Generate markdown table of all options

nix eval '.#config' --json |
jq -r '
  to_entries[] | 
  "| \(.key) | \(.value | type) | \(.value) |"
' > options-table.md
```

--------------------------------

### Testing Nix Flakes

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Validate your NixOS configuration by running `nix flake check` within your project directory. This command verifies the integrity and correctness of your flake setup.

```bash
cd dendritic-config
nix flake check
```

--------------------------------

### Configure GTK and Qt Appearance

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Enables GTK and Qt theming with the 'Adwaita-dark' theme. Requires gnome-themes-extra package for GTK theme.

```nix
# modules/home-manager/appearance.nix
{config, pkgs, ...}:
{
  config.home-manager.modules.appearance = {
    gtk = {
      enable = true;
      theme = {
        name = "Adwaita-dark";
        package = pkgs.gnome.gnome-themes-extra;
      };
    };
    
    qt = {
      enable = true;
      style.name = "adwaita-dark";
    };
  };
}
```

--------------------------------

### Top-Level Configuration with flake-parts

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Recommended method for creating the top-level configuration using flake-parts. Ensures proper integration with Nix flakes.

```nix
# flake.nix
{
  description = "Dendritic configuration";
  
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    home-manager.url = "github:nix-community/home-manager/master";
  };
  
  outputs = inputs@{flake-parts, ...}:
    flake-parts.lib.mkFlake {inherit inputs;} {
      systems = ["x86_64-linux"];
      
      # Import all top-level modules
      imports = [ ./modules ];
      
      # The config attribute is now available for use in outputs
    };
}

```

--------------------------------

### Create Acme Corp Datacenter System

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Example flake.nix configuration to create a NixOS system for an Acme Corp datacenter. It includes organization-specific modules and system type definitions.

```nix
# flake.nix - Create system for Acme Corp datacenter
{
  nixosConfigurations."acme-corp-dc1" = nixpkgs.lib.nixosSystem {
    modules = [
      config.org.acme-corp
      config.nixos.modules.datacenter
      {
        networking.hostName = "acme-corp-dc1";
        networking.domain = config.org.acme-corp.domain;
      }
    ];
  };
}
```

--------------------------------

### Generating Nix Module Dependency Graph

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Visualize module imports and dependencies using `nix-tree` and `dot`. This requires `graphviz` to be installed and generates an SVG file of the module graph.

```bash
# Generate module graph (requires graphviz)
nix-tree --derivation 2>&1 | dot -Tsvg > graph.svg
```

--------------------------------

### Reference Merged Modules in NixOS Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/02-module-system.md

Imports and applies the merged dendritic modules into your NixOS system configuration. Ensure this is placed correctly within your `flake.nix` or `flake-parts` setup.

```nix
# In your NixOS system configuration
# (typically in flake.nix or flake-parts modules.default)

lib.nixosSystem {
  modules = [
    # Import the merged dendritic modules
    (config.nixos.modules.desktop)
    # ... other modules
  ];
}
```

--------------------------------

### Reference Scripts in NixOS System Module

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Demonstrates how to include the shared scripts (backup and update-system) into the NixOS environment's system packages.

```nix
# modules/nixos/system.nix
{
config, ...
}: {
  config.nixos.modules.base = {
    environment.systemPackages = [
      config.scripts.backup
      config.scripts.update-system
    ];
  };
}

```

--------------------------------

### Build for Multiple Systems with Nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Execute a Nix build command to compile outputs for multiple systems, including NixOS configurations and home-manager activation packages. The '--print-out-paths' flag displays the resulting output paths.

```bash
# Build for multiple systems
nix build \
  '.#nixosConfigurations.my-system' \
  '.#homeConfigurations."user@my-system".activationPackage' \
  --print-out-paths
```

--------------------------------

### Access Dendritic Config in flake-parts

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/04-configuration-reference.md

Integrate Dendritic configuration within a `flake.nix` file using `flake-parts`. This example shows how to access the Dendritic config in both per-system contexts and flake outputs.

```nix
# flake.nix
{
  outputs = inputs@{flake-parts, ...}:
    flake-parts.lib.mkFlake {inherit inputs;} {
      imports = [ ./modules ];
      
      # Access config in per-system context
      perSystem = {config, pkgs, ...}:
        {
        packages.my-backup = config.scripts.backup;
        
        devShells.default = pkgs.mkShell {
          buildInputs = [config.scripts.deploy];
        };
      };
      
      # Access config in flake output
      flake = {
        nixosConfigurations = {
          my-system = inputs.nixpkgs.lib.nixosSystem {
            modules = [(config.nixos.laptop or [])];
          };
        };
      };
    };
}

```

--------------------------------

### Hybrid Nix Module Organization (Recommended)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

This recommended approach for complex projects combines feature-based and configuration-class organization. It uses 'shared' directories for cross-configuration features and specific directories for NixOS, home-manager, and Darwin modules.

```nix
modules/
├── options.nix            # Option declarations
├── shared/                # Cross-configuration features
│   ├── fonts.nix
│   ├── shell.nix
│   └── scripts/
├── nixos/                 # NixOS-specific features
│   ├── audio.nix
│   ├── graphics.nix
│   └── configurations/
│       ├── desktop.nix
│       ├── server.nix
│       └── laptop.nix
├── home-manager/          # home-manager-specific features
│   ├── git.nix
│   ├── editor.nix
│   └── configurations/
│       ├── desktop.nix
│       └── development.nix
└── scripts/               # Shared value definitions
    ├── backup.nix
    └── deploy.nix

```

--------------------------------

### Helper Library Functions

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Provides utility functions for Nix configurations, including formatting environment variables and conditional module inclusion.

```nix
# modules/lib/helpers.nix
{lib, ...}:
{
  options.lib = lib.mkOption {
    type = lib.types.attrs;
    default = {};
  };
  
  config.lib = {
    # Format attribute set as environment variables
    mkEnvironmentString = attrs:
      lib.concatMapStringsSep "\n"
        (name: "export ${name}='${lib.escapeShellArg (toString attrs.${name})}'")
        (lib.attrNames attrs);
    
    # Conditionally include modules based on flag
    mkModuleIf = flag: module:
      lib.mkIf flag module;
    
    # Select packages based on system type
    selectBySystem = {x86_64-linux, aarch64-linux, ...}:
      if lib.systems.elaborate lib.systems.flakeExposed.currentSystem == "x86_64-linux"
      then x86_64-linux
      else aarch64-linux;
  };
}
```

--------------------------------

### Pre-Migration Baseline Check

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Before migration, run these commands to check the current configuration and record the build hash for comparison.

```bash
cd /current/config
nix flake check
nix build '.#nixosConfigurations.my-system'
```

--------------------------------

### Configure Git and Direnv for Development

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Enables Git with specified user information and pull configuration, and integrates Direnv for automatic environment loading in shells. Requires Git and Direnv to be available in pkgs.

```nix
# modules/home-manager/development.nix
{config, pkgs, ...}:
{
  config.home-manager.modules.development = {
    home.packages = with pkgs; [
      git
      github-cli
      nix-direnv
      direnv
    ];
    
    programs.git = {
      enable = true;
      userName = "User Name";
      userEmail = "user@example.com";
      
      extraConfig = {
        pull.rebase = true;
        init.defaultBranch = "main";
      };
    };
    
    programs.direnv = {
      enable = true;
      enableBashIntegration = true;
      enableZshIntegration = true;
    };
  };
}
```

--------------------------------

### Generate Nix Options Documentation

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Use Nix eval and jq to extract and format option descriptions into a JSON file for documentation generation.

```bash
# Generate documentation from options
nix eval '.#nixosConfigurations.my-system.options' --json |
  jq 'to_entries[] | {name: .key, description: .value.description.text}' > options.json
```

--------------------------------

### Update flake.nix Outputs (After)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Demonstrates the updated `flake.nix` structure using `flake-parts` and importing dendritic modules for NixOS and home-manager configurations.

```nix
outputs = inputs@{self, flake-parts, ...}:
  flake-parts.lib.mkFlake {inherit inputs;} {
    systems = ["x86_64-linux"];
    imports = [ ./modules ];
    
    flake = let
      inherit (inputs) nixpkgs;
      lib = nixpkgs.lib;
      config = self.config;
    in {
      nixosConfigurations.my-laptop = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          config.nixos.laptop
          ./hardware.nix  # Still needed if hardware-specific
          {
            networking.hostName = "my-laptop";
          }
        ];
      };
      
      homeConfigurations."user@my-laptop" = inputs.home-manager.lib.homeManagerConfiguration {
        pkgs = nixpkgs.legacyPackages.x86_64-linux;
        modules = [
          {
            imports = [
              config.home-manager.modules.shell
              config.home-manager.modules.development
            ];
            
            home.username = "user";
            home.homeDirectory = "/home/user";
            home.stateVersion = "24.05";
          }
        ];
      };
    };
  };

```

--------------------------------

### Integrate home-manager Configuration (After)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Shows the directory structure after integrating home-manager configurations into the dendritic module system.

```tree
modules/
├── features/
│   ├── shell.nix
│   └── development.nix
├── nixos/
│   └── laptop.nix
├── home-manager/
│   ├── shell.nix
│   └── development.nix
└── options.nix

```

--------------------------------

### Building NixOS Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Build a specific NixOS configuration, such as `my-laptop`, using the `nix build` command. This is useful for generating the system's top-level configuration before deployment.

```bash
nix build '.#nixosConfigurations.my-laptop.config.system.build.toplevel'
```

--------------------------------

### Dendritic Project Structure

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/README.md

Illustrates the typical file organization for a dendritic project, showing the entry point (flake.nix) and the modular structure for options, constants, features, NixOS configurations, and Home Manager configurations.

```nix
flake.nix (entry point)
  ↓ imports
modules/
  ├── options.nix (declare all options)
  ├── constants.nix (shared constants)
  ├── features/
  │   ├── audio.nix (feature: audio across all configs)
  │   ├── fonts.nix (feature: fonts across all configs)
  │   └── shell.nix (feature: shell across all configs)
  ├── nixos/
  │   ├── laptop.nix (compose features → complete NixOS config)
  │   └── desktop.nix
  └── home-manager/
      ├── shell.nix (HM-specific modules)
      └── editor.nix
```

--------------------------------

### Inspecting NixOS Configuration in Nix REPL

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Use the Nix REPL to inspect the complete merged configuration and specific sections. Load your configuration and query options directly.

```bash
# View complete merged configuration
nix repl
> :load ./flake.nix
> config                    # Show all config
> config.nixos              # Show nixos section
> config.scripts            # Show scripts section
```

--------------------------------

### Standard Configuration Paths

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/INDEX.md

Illustrates the typical directory structure for configuration files in a Dendritic project, including constants, scripts, libraries, and NixOS, home-manager, and Darwin specific modules.

```plaintext
config.
├── constants.*		# Shared constant values
├── scripts.*		# Executable scripts
├── lib.*		# Shared library functions
├── nixos.
│	├── modules.*		# NixOS feature modules (deferredModule)
│	├── laptop 		# NixOS laptop configuration
│	├── desktop 		# NixOS desktop configuration
│	└── server 		# NixOS server configuration
├── home-manager.
│	├── modules.*		# home-manager feature modules
│	├── user 		# User home-manager configuration
│	└── development 		# Development environment modules
└── darwin.
	├── modules.*		# nix-darwin feature modules
	└── system 		# macOS system configuration
```

--------------------------------

### Switching to NixOS Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Apply and activate your NixOS configuration by using `sudo nixos-rebuild switch`. This command builds the new system generation and makes it the active one.

```bash
sudo nixos-rebuild switch --flake '.#my-laptop'
```

--------------------------------

### Importing Modules with import-tree

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/01-overview.md

Demonstrates how to import all non-entry-point Nix files as modules within a flake-parts configuration. This is typically done in flake.nix or within flake-parts modules.

```nix
# flake.nix (or within flake-parts modules.default)
lib.evalModules {
  modules = import-tree ./modules;
  # ... other options
}
```

--------------------------------

### Use lib.mkDefault for Overrideable Values

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/04-configuration-reference.md

Employ `lib.mkDefault` to set configuration values that can be easily overridden by other modules or configurations. This promotes flexibility.

```nix
config = lib.mkDefault {
  timeZone = "UTC";  # Can be overridden
};

```

--------------------------------

### Main Module Imports

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

This file imports all the individual feature and system-specific modules into a central `modules/default.nix` file.

```nix
# modules/default.nix
{
  imports = [
    ./options.nix
    ./features/audio.nix
    ./features/fonts.nix
    ./features/shell.nix
    ./features/graphics.nix
    ./nixos/laptop.nix
    ./nixos/desktop.nix
    ./nixos/server.nix
    ./home-manager/shell.nix
    ./home-manager/editor.nix
  ];
}
```

--------------------------------

### Home Manager Editor Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Enables Vim and Neovim editors within the Home Manager configuration.

```nix
# modules/home-manager/editor.nix
{config, ...}: {
  config.home-manager.modules.editor = {
    programs.vim.enable = true;
    programs.neovim.enable = true;
  };
}
```

--------------------------------

### Validate and Build Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Commands to check flake integrity, build the NixOS configuration, and switch to the new configuration after migration steps.

```bash
# After each migration step
nix flake check

# Build the configuration
nix build '.#nixosConfigurations.my-laptop'

# Switch to new configuration
sudo nixos-rebuild switch --flake '.#my-laptop'
```

--------------------------------

### Build Specific Nix Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Build a specific part of your NixOS configuration, such as the toplevel system configuration. Use --show-trace for detailed build information.

```bash
nix build '.#nixosConfigurations.my-system.config.system.build.toplevel' --show-trace
```

--------------------------------

### Update flake.nix Outputs (Before)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Shows the `flake.nix` structure before migrating to dendritic, using traditional module imports and home-manager integration.

```nix
outputs = {nixpkgs, home-manager, ...}: {
  nixosConfigurations.my-laptop = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux";
    modules = [
      ./nixos/configuration.nix
      ./nixos/hardware.nix
      home-manager.nixosModule
      {
        home-manager.users.user = import ./home-manager/home.nix;
      }
    ];
  };
};

```

--------------------------------

### Configure Development Shell with Nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Define a development shell using pkgs.mkShell, specifying build inputs such as nix, git, and vim.

```nix
# modules/dev-environment.nix
{
pkgs,
...}: {
  config.devShell = pkgs.mkShell {
    buildInputs = with pkgs;
      [
        nix
        git
        vim
      ];
  };
}
```

--------------------------------

### Define Base Security Policy

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Sets up base security configurations including sudo and SSH access. This module should be included early to establish fundamental security settings.

```nix
# modules/shared/security.nix
{
  config,
  lib,
  ...}: {
  options.security.basePolicy = lib.mkOption {
    type = lib.types.deferredModule;
    default = {};
  };
  
  config.security.basePolicy = {
    security.sudo.enable = true;
    security.sudo.wheelNeedsPassword = false;
    security.ssh.enable = true;
  };
}
```

--------------------------------

### Apply Conditional Configuration in Nix Modules

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Use `lib.mkIf` to conditionally apply configuration settings based on other system settings. This allows for flexible and dynamic module behavior.

```nix
{config, lib, ...}: {
  config = lib.mkMerge [
    # Always apply base config
    {
      services.ssh.enable = true;
    }
    
    # Conditionally extend based on other config
    (lib.mkIf config.services.ssh.enable {
      services.ssh.permitRootLogin = "no";
    })
  ];
}
```

--------------------------------

### Creating a New Configuration with Dendritic Template

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Command to create a new project using the Dendritic development environment template. This command clones the template and initializes a new flake-based configuration.

```bash
nix flake new my-config -t github:mightyiam/dendritic
```

--------------------------------

### Compare Nix Configurations

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Generate a diff between two Nix configuration states. This involves evaluating the current configuration, saving it, and comparing it with a previous version using 'git show' and 'diff'.

```bash
# Generate config diff
nix eval '.#config' --json > config-new.json
git show HEAD:modules/config.json > config-old.json
diff -u config-old.json config-new.json | less
```

--------------------------------

### After Migration: Dendritic Laptop Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

The main dendritic configuration file for a laptop, which imports other modular configurations like audio and fonts. This central file orchestrates the inclusion of various features.

```nix
# modules/nixos/laptop.nix
{config, ...}: {
  config.nixos.laptop = [
    config.nixos.modules.audio
    config.nixos.modules.fonts
  ];
}
```

--------------------------------

### Desktop NixOS Configuration

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Merges fonts, audio, graphics, and shell modules with systemd-boot and SSH configurations for a desktop system.

```nix
# modules/nixos/desktop.nix
{config, lib, ...}: {
  config.nixos.desktop = lib.mkMerge [
    (config.nixos.modules.fonts or {})
    (config.nixos.modules.audio or {})
    (config.nixos.modules.graphics or {})
    (config.nixos.modules.shell or {})
    {
      boot.loader.systemd-boot.enable = true;
      services.openssh.enable = true;
    }
  ];
}
```

--------------------------------

### Check Nix Configuration Syntax

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Use this command to perform a syntax check on your Nix configuration. It evaluates the flake and displays the first 20 lines of output, redirecting errors to standard output.

```bash
nix eval '.#' --impure 2>&1 | head -20
```

--------------------------------

### Define Options Module for Configuration Classes

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Defines the structure for options within the dendritic pattern, specifically for NixOS and home-manager configurations. This module helps in organizing and accessing configuration settings.

```nix
# modules/options.nix
{lib, ...}: {
  options = {
    # For each configuration class you use
    nixos = lib.mkOption {
      type = lib.types.attrs;
      default = {};
    };
    
    nixos.modules = lib.mkOption {
      type = lib.types.lazyAttrsOf lib.types.deferredModule;
      default = {};
    };
    
    home-manager = lib.mkOption {
      type = lib.types.attrs;
      default = {};
    };
    
    home-manager.modules = lib.mkOption {
      type = lib.types.lazyAttrsOf lib.types.deferredModule;
      default = {};
    };
  };
}
```

--------------------------------

### Configure Bash and Zsh Shell Settings

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Enables Bash and Zsh with custom configurations, including environment variables, aliases, and Oh My Zsh for Zsh. Ensure DOTFILES_DIR is set if using the 'cd-dotfiles' alias.

```nix
# modules/home-manager/shell.nix
{config, pkgs, ...}:
{
  config.home-manager.modules.shell = {
    programs.bash = {
      enable = true;
      bashrcExtra = ''
        export EDITOR=vim
        export PAGER=less
        
        alias ll='ls -lah'
        alias cd-dotfiles='cd ''${DOTFILES_DIR:-.}'
      '';
    };
    
    programs.zsh = {
      enable = true;
      oh-my-zsh = {
        enable = true;
        theme = "robbyrussell";
      };
      shellAliases = {
        ll = "ls -lah";
        cd-dotfiles = "cd ''${DOTFILES_DIR:-.}";
      };
    };
  };
}
```

--------------------------------

### NixVim Configuration with Dendritic

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Integrate NeoVim configuration using dendritic within a Nix Home-Manager module. Ensure 'enable' and 'defaultEditor' are set to true for full functionality.

```nix
# modules/home-manager/neovim.nix
{config, pkgs, ...}:
{
  config.home-manager.modules.neovim = {
    programs.neovim = {
      enable = true;
      defaultEditor = true;
      plugins = with pkgs.vimPlugins; [
        vim-nix
        vim-commentary
        nvim-lspconfig
      ];
    };
  };
}
```

--------------------------------

### Define Laptop System Configuration (Nix)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/04-configuration-reference.md

Defines a complete NixOS laptop configuration by merging base, audio, graphics, networking, and shell modules, along with specific settings for hostname, GRUB, and TLP.

```nix
# modules/nixos/laptop.nix
{config, lib, ...}: {
  options.nixos.laptop = lib.mkOption {
    type = lib.types.deferredModule;
    description = "Complete laptop NixOS configuration";
  };
  
  config.nixos.laptop = lib.mkMerge [
    # Include selected modules
    (config.nixos.modules.base or {})
    (config.nixos.modules.audio or {})
    (config.nixos.modules.graphics or {})
    (config.nixos.modules.networking or {})
    (config.nixos.modules.shell or {})
    
    # Add configuration-specific settings
    {
      networking.hostName = "laptop";
      boot.loader.grub.enable = true;
      services.tlp.enable = true;
    }
  ];
}
```

--------------------------------

### Integrate Home-Manager Modules in flake.nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Sets up a Home-Manager configuration within a Nix flake, importing various modules for shell, development, editor, and appearance. Ensure 'inputs.home-manager' is correctly defined in your flake inputs.

```nix
# flake.nix
homeConfigurations."user@my-system" = inputs.home-manager.lib.homeManagerConfiguration {
  pkgs = nixpkgs.legacyPackages.x86_64-linux;
  modules = [
    {
      imports = [
        config.home-manager.modules.shell
        config.home-manager.modules.development
        config.home-manager.modules.editor
        config.home-manager.modules.appearance
      ];
      
      home.username = "user";
      home.homeDirectory = "/home/user";
      home.stateVersion = "24.05";
    }
  ];
};
```

--------------------------------

### Import Modules in modules/default.nix

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Ensure all modules are imported in `modules/default.nix` to prevent 'Module not being loaded' issues. Verify file paths and naming conventions.

```nix
# modules/default.nix must have all imports
{
  imports = [
    ./options.nix
    ./features/audio.nix
    ./features/fonts.nix
  ];
}
```

--------------------------------

### Trace Nix Module Load Order

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/06-tools-and-helpers.md

Utilize 'nix build --trace-function-calls' and 'grep' to trace the module import order, identifying when modules are entered and exited.

```bash
# Trace module imports
nix build '.#nixosConfigurations.my-system' --trace-function-calls 2>&1 | grep "entering\|exiting"
```

--------------------------------

### Configuration Details

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/MANIFEST.txt

In-depth documentation on configuration options, hierarchy, and validation within the Dendritic project.

```APIDOC
## Configuration

This section provides detailed information about the configuration system in Dendritic.

### Option Paths and Hierarchy

*   **Standard option paths**: Documents the conventional paths for configuration options.
*   **Hierarchy**: Explains the hierarchical structure of configuration settings.

### Option Types

*   **Option type reference**: A reference guide to all available option types.
*   **All constructor parameters documented**: Details the parameters for all configuration constructors.

### Special Arguments

*   **Environment variables (via specialArgs)**: Explains how environment variables are accessed and used through `specialArgs`.

### Patterns

*   **Validation patterns**: Describes the patterns and methods used for validating configuration data.
*   **Type checking**: Details the type checking mechanisms employed.
```

--------------------------------

### Dendritic Module Import (modules/default.nix)

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/01-overview.md

This Nix file defines how modules are imported in the dendritic pattern. It uses `import-tree` to recursively import all Nix files within the specified directory.

```nix
# modules/default.nix
{
  imports = import-tree ./.;
}
```

--------------------------------

### Functional Testing with NixOS Rebuild

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/07-migration-guide.md

Build and test new configurations. This includes creating a temporary system for testing or switching directly to the new configuration with rollback capabilities.

```bash
# Build and test new configuration
nix build '.#nixosConfigurations.my-laptop'

# Create temporary system to test
sudo nixos-rebuild build-vm --flake '.#my-laptop'
./result/bin/run-nixos-vm

# Or switch directly (with ability to rollback)
sudo nixos-rebuild switch --flake '.#my-laptop'
# Test functionality...
sudo nixos-rebuild switch --flake '.#my-system'  # Rollback to previous
```

--------------------------------

### Graphics Feature Module

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Enables the X server with GDM display manager and GNOME desktop environment.

```nix
# modules/features/graphics.nix
{config, ...}: {
  config.nixos.modules.graphics = {
    services.xserver.enable = true;
    services.xserver.displayManager.gdm.enable = true;
    services.xserver.desktopManager.gnome.enable = true;
  };
}
```

--------------------------------

### NixOS Audio Feature Module

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/03-implementation-guide.md

Implements audio configuration for NixOS, enabling PipeWire and its ALSA integration.

```nix
# modules/audio.nix
{
config,
lib,
...
}: {
  config.nixos.modules.audio = {
    sound.enable = true;
    services.pipewire.enable = true;
    services.pipewire.alsa.enable = true;
  };
}

```

--------------------------------

### Multi-Configuration Feature Module

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/04-configuration-reference.md

A feature module designed to apply to multiple configuration classes, such as NixOS and Home Manager.

```nix
# modules/features/shell.nix
{
config,
lib,
...
}: {
  config.nixos.modules.shell = {
    programs.bash.enable = true;
    programs.zsh.enable = true;
  };
  
  config.home-manager.modules.shell = {
    programs.bash.enable = true;
    programs.bash.bashrcExtra = ''
      # Custom bash configuration
    '';
  };
}
```

--------------------------------

### Define Backup and Check Updates Shell Scripts

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Defines two shell scripts for backing up files and checking for NixOS updates using `pkgs.writeShellScriptBin`.

```nix
# modules/scripts/default.nix
{config, pkgs, ...}:
{
  options.scripts = lib.mkOption {
    type = lib.types.attrs;
    default = {};
  };
  
  config.scripts = {
    backup = pkgs.writeShellScriptBin "backup" ''
      #!/bin/bash
      set -euo pipefail
      
      SOURCE="''${1:-.}"
      DEST="''${2:-/mnt/backup}"
      
      echo "Backing up $SOURCE to $DEST"
      rsync -av --delete --exclude='.git' \
        --exclude='target' \
        --exclude='node_modules' \
        "$SOURCE" "$DEST"
    '';
    
    check-updates = pkgs.writeShellScriptBin "check-updates" ''
      #!/bin/bash
      echo "Checking for NixOS updates..."
      nix flake update --flake .
      git diff flake.lock
    '';
  };
}
```

--------------------------------

### Module Options Definition

Source: https://github.com/mightyiam/dendritic/blob/master/_autodocs/05-examples.md

Defines the structure for NixOS and Home Manager options, including types for modules and specific system configurations.

```nix
# modules/options.nix
{lib, ...}: {
  options = {
    nixos = lib.mkOption {
      type = lib.types.attrs;
      default = {};
    };
    
    nixos.modules = lib.mkOption {
      type = lib.types.lazyAttrsOf lib.types.deferredModule;
      default = {};
    };
    
    nixos.laptop = lib.mkOption {
      type = lib.types.deferredModule;
      default = {};
    };
    
    nixos.desktop = lib.mkOption {
      type = lib.types.deferredModule;
      default = {};
    };
    
    nixos.server = lib.mkOption {
      type = lib.types.deferredModule;
      default = {};
    };
    
    home-manager = lib.mkOption {
      type = lib.types.attrs;
      default = {};
    };
    
    home-manager.modules = lib.mkOption {
      type = lib.types.lazyAttrsOf lib.types.deferredModule;
      default = {};
    };
  };
}
```