1. Update flake.nix

Add Juna to your inputs. To maintain a lean dependency tree and prevent nix-store bloat, ensure you follow your system's nixpkgs instance.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    juna = {
      url = "git+https://codeberg.org/juna-lab/juna";
      inputs.nixpkgs.follows = "nixpkgs"; # Critical for store hygiene
    };

    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, juna, home-manager, ... }: {
    # Your configuration logic here
  };
}

2. Inject the Module

Juna operates as a Home Manager module. You must import the default module into your home-manager configuration block to expose the juna.* options.

Standalone Home Manager

homeConfigurations.your-user = home-manager.lib.homeManagerConfiguration {
  ...
  modules = [
    juna.homeManagerModules.default
    ./home.nix
  ];
};

NixOS Module (via Home Manager)

home-manager.users.gurjaka = {
  imports = [ juna.homeManagerModules.default ];
};

3. Initial Activation

Juna is inert by default. To bootstrap the engine, you must explicitly enable it and select a theme. Add this to your home.nix or equivalent module:

{
  juna = {
    enable = true;
    theme = "nord"; # Ensure this theme exists in junaAllThemes

    ...
  };
}

Check out usage guide for a deeper dive into options.

Verification

Juna uses a state-aware synchronization engine. After a home-manager switch, you can verify the deployment and audit the engine's logic via the following interfaces:

1. Audit the Logs: Check the persistent log to see exactly what changes Juna made during activation:

tail -f ~/.local/share/juna/juna_log.txt

2. Inspect Engine State: Juna stores the current "Ground Truth" for every domain in a flat-file database. This allows external scripts to query Juna without overhead:

ls ~/.local/share/juna/vars/
cat ~/.local/share/juna/vars/.theme

3. Validate Wallpaper Collections: Ensure your pigments are physically realized in the local store:

ls ~/.local/share/juna/wallpapers/

4. Reference API: Visit Modules to see the generated Nix documentation for all available domain modules and force-override options.

Troubleshooting

• Missing Themes: If you get an "attribute missing" error, ensure the string passed to juna.theme matches a key in junaAllThemes (check themes gallery).