diff --git a/README.md b/README.md
index 9019a1d..1cdb366 100644
--- a/README.md
+++ b/README.md
@@ -2,14 +2,31 @@
 
 Nix configurations for iscg infra hosts.
 
-Hosts and naming scheme: see [garden.md](./garden.md).
+## hosts
 
-## rebuild
+- **poppy** - MacBook Air M1 (nix-darwin)
+- **muscari** - NixOS server with k3s
+- **rosemary** - backup VM (planned)
+
+See `docs/` for detailed documentation.
+
+## quick rebuild
 
 ```bash
 # poppy (macOS)
 darwin-rebuild switch --flake .#poppy
 
-# muscari, rosemary (NixOS)
-sudo nixos-rebuild switch --flake .#<host>
-```
\ No newline at end of file
+# muscari (NixOS)
+sudo nixos-rebuild switch --flake .#muscari
+```
+
+## documentation
+
+- [docs/structure.md](docs/structure.md) - how the config is organized
+- [docs/poppy.md](docs/poppy.md) - MacBook specific
+- [docs/muscari.md](docs/muscari.md) - server + k3s
+- [docs/shell.md](docs/shell.md) - zsh, prompt, aliases
+- [docs/terminal.md](docs/terminal.md) - kitty + themes
+- [docs/cheatsheet.md](docs/cheatsheet.md) - quick commands
+
+See also [garden.md](garden.md) for host naming scheme.
diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md
new file mode 100644
index 0000000..71030e7
--- /dev/null
+++ b/docs/cheatsheet.md
@@ -0,0 +1,57 @@
+# cheatsheet
+
+quick commands for daily use.
+
+## rebuild
+
+```bash
+# poppy (macbook)
+darwin-rebuild switch --flake .#poppy
+
+# muscari (server)
+sudo nixos-rebuild switch --flake .#muscari
+```
+
+## update
+
+```bash
+# update flakes then rebuild
+nix flake update && darwin-rebuild switch --flake .#poppy
+```
+
+## check
+
+```bash
+# validate before applying
+nix flake check
+
+# dry run (see what would change)
+darwin-rebuild switch --flake .#poppy --dry-run
+```
+
+## cleanup
+
+```bash
+# remove old generations
+nix-collect-garbage -d
+
+# or with sudo on nixos
+sudo nix-collect-garbage -d
+```
+
+## shell
+
+```bash
+ll          # detailed list with icons
+cd <dir>    # actually zoxide - remembers frequent paths
+ff          # fastfetch system info
+```
+
+## navigation
+
+```bash
+cd <partial>      # zoxide - jump to frequent dir
+cd ..             # parent directory
+ctrl+r            # fzf history search
+ctrl+t            # fzf file finder
+```
diff --git a/docs/muscari.md b/docs/muscari.md
new file mode 100644
index 0000000..fd0215b
--- /dev/null
+++ b/docs/muscari.md
@@ -0,0 +1,39 @@
+# muscari
+
+NixOS server on Yandex Cloud. k3s single-node cluster.
+
+## specs
+
+- VM: 2 vCPU / 8 GB RAM / 64 GB SSD
+- IP: 158.160.166.30
+- Network: Legacy BIOS (no EFI)
+
+## quick rebuild
+
+```bash
+sudo nixos-rebuild switch --flake .#muscari
+```
+
+## imports
+
+- `disk-config.nix` - disko partitioning
+- `k3s.nix` - kubernetes cluster setup
+- `hosts/common/` - shared nixos settings
+
+## networking
+
+open ports:
+- 22 - ssh
+- 80 - http (traefik ingress)
+- 443 - https (traefik ingress)
+
+6443 is closed - kubectl via ssh tunnel only.
+
+## ssh keys
+
+fetched from `https://git.iscg.dev/mikl.keys` with sha256 pinning.
+
+## TODO
+
+- [ ] k8s aliases (k, kx, kl, kd, etc)
+- [ ] add nix-specific aliases (switch, update, cleanup with sudo)
diff --git a/docs/poppy.md b/docs/poppy.md
new file mode 100644
index 0000000..bf3ca82
--- /dev/null
+++ b/docs/poppy.md
@@ -0,0 +1,34 @@
+# poppy
+
+MacBook Air M1 - daily driver.
+
+## quick rebuild
+
+```bash
+darwin-rebuild switch --flake .#poppy
+```
+
+## what's specific here
+
+### darwin system
+
+- `nixpkgs.config.allowUnfree = true` - needed for some macos tools
+- `services.nix-daemon.enable = true` - multi-user install
+- home path: `/Users/mikl` (not `/home/mikl`)
+
+### home-manager imports
+
+- `home/kitty.nix` - terminal with catppuccin theme
+
+### aliases
+
+| alias | command |
+|-------|---------|
+| `switch` | `darwin-rebuild switch --flake .#poppy` |
+| `update` | `nix flake update && darwin-rebuild switch --flake .#poppy` |
+| `cleanup` | `nix-collect-garbage -d` |
+
+## TODO
+
+- [ ] telegram mcp aliases (tg-login, tg-reset)
+- [ ] apple music tools (gamdl)
diff --git a/docs/shell.md b/docs/shell.md
new file mode 100644
index 0000000..a2e0f74
--- /dev/null
+++ b/docs/shell.md
@@ -0,0 +1,41 @@
+# shell
+
+zsh configuration across all hosts.
+
+## prompt
+
+**pure** - minimal, fast, shows git status.
+- green `>` on success
+- red `>` on error
+- right prompt: current time in gray
+
+## plugins
+
+| plugin | source | purpose |
+|--------|--------|---------|
+| pure | github (v1.23.0) | prompt theme |
+| zsh-syntax-highlighting | nixpkgs | command coloring |
+| zsh-autosuggestions | nixpkgs | gray command hints |
+
+## history
+
+- size: 10000
+- shared between sessions
+- ignores duplicates
+- stored in `~/.local/share/zsh/history` (xdg)
+
+## universal aliases
+
+| alias | what |
+|-------|------|
+| `ll` | `eza -l --icons --git` |
+| `la` | `eza -la --icons --git` |
+| `ff` | `fastfetch` |
+
+## startup
+
+fastfetch runs automatically when opening new shell.
+
+## host-specific
+
+see `docs/poppy.md` and `docs/muscari.md` for per-host aliases (nix rebuild commands differ).
diff --git a/docs/structure.md b/docs/structure.md
new file mode 100644
index 0000000..679f18c
--- /dev/null
+++ b/docs/structure.md
@@ -0,0 +1,63 @@
+# structure
+
+how the config is organized.
+
+## top-level
+
+```
+nix-config/
+├── flake.nix          # entry point - dispatches to hosts
+├── home/              # home-manager (user space)
+├── hosts/             # system-level configs
+├── secrets/           # sops-nix encrypted files
+└── docs/              # this folder
+```
+
+## flake.nix flow
+
+```
+flake.nix
+├── nixosConfigurations
+│   ├── muscari  → hosts/muscari/ + home/
+│   └── rosemary → hosts/rosemary/ + home/
+└── darwinConfigurations
+    └── poppy    → hosts/poppy/ + home/
+```
+
+## home/ vs hosts/
+
+| what | where | why |
+|------|-------|-----|
+| shell config | `home/` | same on all machines |
+| terminal emulator | `home/` | gui apps belong here |
+| system packages | `hosts/<name>/` | os-specific |
+| networking | `hosts/<name>/` | per-host |
+| hostname | `hosts/<name>/` | obviously |
+
+## adding things
+
+**new package for all hosts:**
+→ add to `home/cli.nix` in `home.packages`
+
+**new package for one host:**
+→ add to `hosts/<name>/default.nix` in `environment.systemPackages`
+
+**new alias for all hosts:**
+→ add to `home/zsh.nix` in `programs.zsh.shellAliases`
+
+**new alias for one host:**
+→ add to `hosts/<name>/default.nix` in `home-manager.users.mikl.programs.zsh.shellAliases`
+
+## host-specific imports
+
+poppy imports `home/kitty.nix` because it has a screen. muscari doesn't.
+
+```nix
+# hosts/poppy/default.nix
+home-manager.users.mikl = {
+  imports = [ ../../home/kitty.nix ];
+  programs.zsh.shellAliases = {
+    switch = "darwin-rebuild switch --flake .#poppy";
+  };
+};
+```
diff --git a/docs/terminal.md b/docs/terminal.md
new file mode 100644
index 0000000..5e570ae
--- /dev/null
+++ b/docs/terminal.md
@@ -0,0 +1,36 @@
+# terminal
+
+kitty configuration for gui hosts.
+
+## where
+
+`home/kitty.nix` - imported only by poppy (macbook).
+
+## theme
+
+**Catppuccin-Mocha** - dark, soft colors.
+
+## font
+
+JetBrainsMono Nerd Font, size 12.
+
+## features
+
+- **tabs**: powerline style, at bottom, slanted separators
+- **transparency**: background blur 16
+- **cursor**: beam shape
+- **scrollback**: 10000 lines
+- **cyrillic shortcuts**: cmd+м = paste, cmd+с = copy
+
+## cyrillic config
+
+loads `~/.config/kitty/cyrillic-shortcuts.conf` for additional layout fixes.
+
+## applying changes
+
+kitty reloads config automatically. if not:
+
+```bash
+killall kitty
+# or ctrl+shift+f5 inside kitty
+```
diff --git a/flake.lock b/flake.lock
index 1753b05..eff8e51 100644
--- a/flake.lock
+++ b/flake.lock
@@ -27,11 +27,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1782423922,
-        "narHash": "sha256-qPNd6lUohHP5gcJhqQ7rLV87RwIx0xYR2A4Frb9Zjc4=",
+        "lastModified": 1782657028,
+        "narHash": "sha256-PHTCpYZCMzJYS3phhywqRAZphKVr2zjvlGYa+H20ZZ4=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "5d320ab301cfaaca7d32514f13815d19d109f5f4",
+        "rev": "4ad9aaae70c9aaab504127f926c0fa9cfbc2b365",
         "type": "github"
       },
       "original": {
@@ -62,16 +62,16 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1782335603,
-        "narHash": "sha256-sZkQH1CkiZtdvcaLx4sGQD9Q9h+A8qB04DRpqQCN530=",
+        "lastModified": 1782545840,
+        "narHash": "sha256-PkBPmP5ofNtunCU7/tfn6wi9OLlzFGcHAqqmY+/mwUI=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "03c72920da828594fae523aaef96f33dff10b340",
+        "rev": "3d46470bb3030020f7e1361f33514854f5bfa86d",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-25.11",
+        "ref": "nixpkgs-unstable",
         "repo": "nixpkgs",
         "type": "github"
       }
diff --git a/flake.nix b/flake.nix
index 8289a3c..ee27839 100644
--- a/flake.nix
+++ b/flake.nix
@@ -2,7 +2,7 @@
   description = "nix-config — multi-host Nix configurations";
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
 
     nix-darwin = {
       url = "github:LnL7/nix-darwin";
@@ -41,7 +41,7 @@
               home-manager = {
                 useGlobalPkgs = true;
                 useUserPackages = true;
-                users.mikl = import ./home;
+                users.michaotic = import ./home;
               };
             }
           ];
@@ -57,7 +57,7 @@
               home-manager = {
                 useGlobalPkgs = true;
                 useUserPackages = true;
-                users.mikl = import ./home;
+                users.michaotic = import ./home;
               };
             }
           ];
@@ -66,7 +66,7 @@
     {
       nixosConfigurations = {
         muscari = mkNixos "muscari";
-        rosemary = mkNixos "rosemary";
+        # rosemary = mkNixos "rosemary";  # TODO: add disk config
       };
 
       darwinConfigurations = {
diff --git a/garden.md b/garden.md
index 07d9b06..a2f3e9b 100644
--- a/garden.md
+++ b/garden.md
@@ -24,9 +24,21 @@ Hosts in this repo are named after plants and flowers.
 - `hosts/<name>/default.nix` — per-host config
 - `hosts/common/default.nix` — shared NixOS config
 - `hosts/common-darwin/default.nix` — shared darwin config
-- `home/default.nix` — shared home-manager config for user `mikl`
+- `home/default.nix` — shared home-manager config for user `michaotic` (plan to migrate to `mikl` later)
 - `secrets/` — sops-encrypted secrets per host
 
 ## migrations
 
-- `nix-config-legacy/` — previous muscari-only config (preserved for reference)
\ No newline at end of file
+- `nix-config-legacy/` — previous muscari-only config (preserved for reference)
+
+## future plans
+
+### username migration
+
+currently using `michaotic` as username (historical). plan to migrate to `mikl` across all hosts for consistency.
+
+**why not now:**
+- macOS: changing username requires careful handling of home folder, keychain, permissions
+- linux: easier, but better to do in one coordinated change
+
+**when:** after setting up proper backups and testing migration procedure
\ No newline at end of file
diff --git a/home/cli.nix b/home/cli.nix
new file mode 100644
index 0000000..bc91d81
--- /dev/null
+++ b/home/cli.nix
@@ -0,0 +1,53 @@
+{ pkgs, ... }:
+{
+  # Universal CLI tools for all hosts
+  home.packages = with pkgs; [
+    eza
+    bat
+    ripgrep
+    fd
+    fzf
+    tree
+    htop
+    tldr
+  ];
+
+  # FZF fuzzy finder
+  programs.fzf = {
+    enable = true;
+    enableZshIntegration = true;
+    defaultCommand = "fd --type f --hidden --exclude .git";
+    defaultOptions = [
+      "--height 40%"
+      "--layout=reverse"
+      "--border"
+    ];
+  };
+
+  # Zoxide - smarter cd
+  programs.zoxide = {
+    enable = true;
+    enableZshIntegration = true;
+    options = [ "--cmd cd" ];
+  };
+
+  # Bat - cat with syntax highlighting
+  programs.bat = {
+    enable = true;
+    config = {
+      theme = "Catppuccin-mocha";
+      italic-text = "always";
+      style = "numbers,changes,header";
+    };
+  };
+
+  # Eza - modern ls replacement
+  programs.eza = {
+    enable = true;
+    icons = "auto";
+    git = true;
+  };
+
+  # Fastfetch - system info (using package only, no home-manager module)
+  # Config is in ~/.config/fastfetch/config.jsonc manually for now
+}
diff --git a/home/default.nix b/home/default.nix
index 8dd75fe..58e9575 100644
--- a/home/default.nix
+++ b/home/default.nix
@@ -1,13 +1,11 @@
 { pkgs, ... }:
 {
-  home.stateVersion = "25.11";
+  imports = [
+    ./cli.nix
+    ./zsh.nix
+  ];
 
-  programs.zsh.enable = true;
+  home.stateVersion = "24.11";
 
   programs.git.enable = true;
-
-  home.packages = [
-    pkgs.ripgrep
-    pkgs.fd
-  ];
-}
\ No newline at end of file
+}
diff --git a/home/kitty.nix b/home/kitty.nix
new file mode 100644
index 0000000..eadc072
--- /dev/null
+++ b/home/kitty.nix
@@ -0,0 +1,46 @@
+{ pkgs, ... }:
+{
+  programs.kitty = {
+    enable = true;
+
+    font = {
+      name = "JetBrainsMono Nerd Font";
+      size = 12;
+    };
+
+    themeFile = "Catppuccin-Mocha";
+
+    settings = {
+      background_opacity = "1";
+      dynamic_background_opacity = "yes";
+      background_blur = 16;
+      cursor_shape = "beam";
+      modify_font = "cell_height 110%";
+      bold_font = "auto";
+      disable_ligatures = "never";
+      adjust_line_height = "0";
+      adjust_column_width = "0";
+
+      tab_bar_min_tabs = 1;
+      tab_bar_edge = "bottom";
+      tab_bar_style = "powerline";
+      tab_powerline_style = "slanted";
+
+      tab_title_template = "{title}{' :{}:'.format(num_windows) if num_windows > 1 else ''}";
+
+      scrollback_lines = 10000;
+
+      # Copy/paste with non-latin layouts
+      map_cmd_v = "paste_from_clipboard";
+      map_cmd_c = "copy_to_clipboard";
+
+      # Russian layout aliases (Cmd)
+      "map cmd+м" = "paste_from_clipboard";
+      "map cmd+с" = "copy_to_clipboard";
+    };
+
+    extraConfig = ''
+      include ~/.config/kitty/cyrillic-shortcuts.conf
+    '';
+  };
+}
diff --git a/home/zsh.nix b/home/zsh.nix
new file mode 100644
index 0000000..368980e
--- /dev/null
+++ b/home/zsh.nix
@@ -0,0 +1,64 @@
+{ pkgs, ... }:
+{
+  programs.zsh = {
+    enable = true;
+    enableCompletion = true;
+    
+    autosuggestion.enable = true;
+    syntaxHighlighting.enable = true;
+
+    # History
+    history = {
+      size = 10000;
+      save = 10000;
+      ignoreDups = true;
+      share = true;
+      extended = true;
+    };
+
+    # Pure prompt
+    plugins = [
+      {
+        name = "pure";
+        src = pkgs.fetchFromGitHub {
+          owner = "sindresorhus";
+          repo = "pure";
+          rev = "v1.23.0";
+          sha256 = "sha256-BmQO4xqd/3QnpLUitD2obVxL0UulpboT8jGNEh4ri8k=";
+        };
+      }
+      {
+        name = "zsh-syntax-highlighting";
+        file = "share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh";
+        src = pkgs.zsh-syntax-highlighting;
+      }
+      {
+        name = "zsh-autosuggestions";
+        file = "share/zsh-autosuggestions/zsh-autosuggestions.zsh";
+        src = pkgs.zsh-autosuggestions;
+      }
+    ];
+
+    # Base aliases (universal)
+    shellAliases = {
+      ll = "eza -l --icons --git";
+      la = "eza -la --icons --git";
+    };
+
+    # Init content - runs on shell start
+    initContent = ''
+      # Load pure prompt
+      autoload -U promptinit; promptinit
+      prompt pure
+      
+      # Right prompt - time in gray
+      RPROMPT='%F{240}%D{%H:%M:%S}%f'
+      
+      # Pure prompt customization
+      zstyle ':prompt:pure:prompt:success' color green
+      zstyle ':prompt:pure:prompt:success' symbol ">"
+      zstyle ':prompt:pure:prompt:error' color red
+      zstyle ':prompt:pure:prompt:error' symbol ">"
+    '';
+  };
+}
diff --git a/hosts/common/default.nix b/hosts/common/default.nix
index d3862f2..2e570d2 100644
--- a/hosts/common/default.nix
+++ b/hosts/common/default.nix
@@ -6,10 +6,13 @@
     "flakes"
   ];
 
-  users.users.mikl = {
+  # Required when using zsh as user shell
+  programs.zsh.enable = true;
+
+  users.users.michaotic = {
     isNormalUser = true;
     shell = pkgs.zsh;
-    home = "/home/mikl";
+    home = "/home/michaotic";
   };
 
   environment.systemPackages = [
diff --git a/hosts/muscari/default.nix b/hosts/muscari/default.nix
index 342905b..56cb3b0 100644
--- a/hosts/muscari/default.nix
+++ b/hosts/muscari/default.nix
@@ -31,9 +31,9 @@
   boot.loader.systemd-boot.enable = lib.mkForce false;
   boot.loader.efi.canTouchEfiVariables = lib.mkForce false;
 
-  # SSH ключи для mikl: forgejo .keys endpoint с sha256-pinning
+  # SSH ключи для michaotic: forgejo .keys endpoint с sha256-pinning
   # + hardcoded fallback ключ для восстановления
-  users.users.mikl.openssh.authorizedKeys.keyFiles = [
+  users.users.michaotic.openssh.authorizedKeys.keyFiles = [
     (pkgs.fetchurl {
       url = "https://git.iscg.dev/mikl.keys";
       sha256 = "sha256-4n6QLUPozdhHOmsRCuFn7HR9BU3nF0/GR2E7s5Lpz+Q=";
diff --git a/hosts/poppy/default.nix b/hosts/poppy/default.nix
index 0bc6467..8ba1668 100644
--- a/hosts/poppy/default.nix
+++ b/hosts/poppy/default.nix
@@ -13,15 +13,25 @@
     "flakes"
   ];
 
-  # nix daemon (multi-user install)
-  services.nix-daemon.enable = true;
-
-  users.users.mikl = {
-    home = "/Users/mikl";
+  users.users.michaotic = {
+    home = "/Users/michaotic";
     shell = pkgs.zsh;
   };
 
   environment.systemPackages = [
     pkgs.vim
   ];
-}
\ No newline at end of file
+
+  system.stateVersion = 7;
+
+  # Home-manager configuration specific to poppy
+  home-manager.users.michaotic = {
+    imports = [ ../../home/kitty.nix ];
+
+    programs.zsh.shellAliases = {
+      switch = "darwin-rebuild switch --flake .#poppy";
+      update = "nix flake update && darwin-rebuild switch --flake .#poppy";
+      cleanup = "nix-collect-garbage -d";
+    };
+  };
+}