docs: update zellij-ps to reflect project switcher functionality

- Update package description and fix mainProgram typo - Rewrite documentation to describe project switching, not process viewing - Add PROJECT_FOLDERS configuration and usage examples - Update all references across docs (README, guides, module overviews)
2025-12-30 15:42:52 +01:00
parent 744b6a8243
commit 44485c4c72
28 changed files with 8096 additions and 24 deletions
--- a/docs/guides/using-modules.md
+++ b/docs/guides/using-modules.md
@@ -0,0 +1,605 @@
+# Using Modules Guide
+
+How to use NixOS and Home Manager modules from m3ta-nixpkgs.
+
+## Overview
+
+Modules in m3ta-nixpkgs provide reusable configuration for NixOS (system-level) and Home Manager (user-level) settings. All modules use the `m3ta.*` namespace.
+
+## Module Organization
+
+### NixOS Modules
+
+Located in `modules/nixos/`:
+
+```
+modules/nixos/
+├── default.nix    # Aggregates all NixOS modules
+├── ports.nix      # Port management
+└── mem0.nix      # Mem0 REST API server
+```
+
+### Home Manager Modules
+
+Located in `modules/home-manager/` with categories:
+
+```
+modules/home-manager/
+├── default.nix      # Aggregates all HM modules
+├── ports.nix       # Port management
+├── cli/            # CLI tools
+│   ├── default.nix # Aggregates CLI modules
+│   └── zellij-ps.nix
+└── coding/         # Development tools
+    ├── default.nix # Aggregates coding modules
+    └── editors.nix
+```
+
+## Importing Modules
+
+### NixOS Modules
+
+#### Import All Modules
+
+```nix
+{config, ...}: {
+  imports = [
+    m3ta-nixpkgs.nixosModules.default
+  ];
+}
+```
+
+#### Import Specific Module
+
+```nix
+{config, ...}: {
+  imports = [
+    m3ta-nixpkgs.nixosModules.mem0
+  ];
+}
+```
+
+#### Import from Local Path
+
+```nix
+{config, ...}: {
+  imports = [
+    ./modules/nixos/mem0.nix
+  ];
+}
+```
+
+### Home Manager Modules
+
+#### Import All Modules
+
+```nix
+{config, ...}: {
+  imports = [
+    m3ta-nixpkgs.homeManagerModules.default
+  ];
+}
+```
+
+#### Import Specific Module
+
+```nix
+{config, ...}: {
+  imports = [
+    m3ta-nixpkgs.homeManagerModules.ports
+  ];
+}
+```
+
+#### Import Category
+
+```nix
+{config, ...}: {
+  imports = [
+    # Import all CLI modules
+    m3ta-nixpkgs.homeManagerModules.cli.zellij-ps
+  ];
+}
+```
+
+## Available Modules
+
+### NixOS Modules
+
+#### `m3ta.ports`
+
+Port management across hosts.
+
+```nix
+m3ta.ports = {
+  enable = true;
+  definitions = {
+    nginx = 80;
+    grafana = 3000;
+  };
+  hostOverrides.laptop = {
+    nginx = 8080;
+  };
+  currentHost = config.networking.hostName;
+};
+```
+
+**Documentation**: [Port Management Guide](./port-management.md)
+
+#### `m3ta.mem0`
+
+Mem0 REST API server for AI memory.
+
+```nix
+m3ta.mem0 = {
+  enable = true;
+  port = 8000;
+  llm = {
+    provider = "openai";
+    apiKeyFile = "/run/secrets/openai-api-key";
+    model = "gpt-4o-mini";
+  };
+  vectorStore = {
+    provider = "qdrant";
+    config = {
+      host = "localhost";
+      port = 6333;
+    };
+  };
+};
+```
+
+**Documentation**: [mem0 Module](../modules/nixos/mem0.md)
+
+### Home Manager Modules
+
+#### `m3ta.ports`
+
+Port management (similar to NixOS, with `generateEnvVars`).
+
+```nix
+m3ta.ports = {
+  enable = true;
+  definitions = {
+    dev-server = 3000;
+  };
+  generateEnvVars = true;
+  currentHost = config.networking.hostName;
+};
+```
+
+**Documentation**: [Port Management Guide](./port-management.md)
+
+#### `m3ta.cli.zellij-ps`
+
+Zellij project switcher for quickly navigating between project folders.
+
+```nix
+m3ta.cli.zellij-ps = {
+  enable = true;
+  package = pkgs.zellij-ps;
+};
+```
+
+**Documentation**: [zellij-ps Module](../modules/home-manager/cli/zellij-ps.md)
+
+#### `m3ta.coding.editors`
+
+Editor configurations.
+
+```nix
+m3ta.coding.editors = {
+  enable = true;
+  neovim.enable = true;
+  zed.enable = true;
+};
+```
+
+**Documentation**: [Editors Module](../modules/home-manager/coding/editors.md)
+
+## Common Patterns
+
+### Module Configuration
+
+All modules follow this pattern:
+
+```nix
+{ config, lib, pkgs, ... }:
+with lib; let
+  cfg = config.m3ta.myModule;
+in {
+  options.m3ta.myModule = {
+    enable = mkEnableOption "description";
+    # ... other options
+  };
+
+  config = mkIf cfg.enable {
+    # ... configuration
+  };
+}
+```
+
+### Conditional Configuration
+
+Use `mkIf` to conditionally apply config:
+
+```nix
+config = mkIf cfg.enable {
+  # Only applied when cfg.enable = true
+  services.my-service = {
+    enable = true;
+  };
+}
+```
+
+### Multiple Conditions
+
+Use `mkMerge` for multiple conditions:
+
+```nix
+config = mkMerge [
+  (mkIf cfg.feature1.enable {
+    # Applied when feature1 is enabled
+  })
+  (mkIf cfg.feature2.enable {
+    # Applied when feature2 is enabled
+  })
+];
+```
+
+### Optional Dependencies
+
+```nix
+options.m3ta.myModule = {
+  enable = mkEnableOption "my module";
+  package = mkOption {
+    type = types.package;
+    default = pkgs.defaultPackage;
+  };
+};
+
+config = mkIf cfg.enable {
+  services.my-service = {
+    package = cfg.package;
+  };
+};
+```
+
+## Configuration Examples
+
+### Minimal NixOS Configuration
+
+```nix
+{pkgs, ...}: {
+  imports = [
+    m3ta-nixpkgs.nixosModules.default
+  ];
+
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      my-service = 8080;
+    };
+    currentHost = "laptop";
+  };
+
+  services.my-custom-service = {
+    enable = true;
+    port = config.m3ta.ports.get "my-service";
+  };
+}
+```
+
+### Full NixOS Configuration
+
+```nix
+{config, pkgs, ...}: {
+  imports = [
+    m3ta-nixpkgs.nixosModules.default
+  ];
+
+  # Port management
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      nginx = 80;
+      grafana = 3000;
+      prometheus = 9090;
+      mem0 = 8000;
+    };
+    hostOverrides.laptop = {
+      nginx = 8080;
+      mem0 = 8081;
+    };
+    currentHost = config.networking.hostName;
+  };
+
+  # Mem0 service
+  m3ta.mem0 = {
+    enable = true;
+    port = config.m3ta.ports.get "mem0";
+    llm = {
+      provider = "openai";
+      apiKeyFile = "/run/secrets/openai-api-key";
+    };
+    vectorStore = {
+      provider = "qdrant";
+      config = {
+        host = "localhost";
+        port = 6333;
+      };
+    };
+  };
+
+  # Nginx
+  services.nginx = {
+    enable = true;
+    httpConfig = ''
+      server {
+        listen ${toString (config.m3ta.ports.get "nginx")};
+        root /var/www;
+      }
+    '';
+  };
+
+  # Grafana
+  services.grafana = {
+    enable = true;
+    settings.server.http_port = config.m3ta.ports.get "grafana";
+  };
+}
+```
+
+### Minimal Home Manager Configuration
+
+```nix
+{pkgs, ...}: {
+  imports = [
+    m3ta-nixpkgs.homeManagerModules.default
+  ];
+
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      dev-server = 3000;
+    };
+    currentHost = "desktop";
+  };
+
+  home.sessionVariables = {
+    DEV_PORT = toString (config.m3ta.ports.get "dev-server");
+  };
+}
+```
+
+### Full Home Manager Configuration
+
+```nix
+{config, pkgs, ...}: {
+  imports = [
+    m3ta-nixpkgs.homeManagerModules.default
+  ];
+
+  # Port management
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      dev-server = 3000;
+      nextjs = 3001;
+      vite = 5173;
+    };
+    hostOverrides.laptop = {
+      vite = 5174;
+    };
+    currentHost = config.networking.hostName;
+  };
+
+  # CLI tools
+  m3ta.cli.zellij-ps = {
+    enable = true;
+  };
+
+  # Coding tools
+  m3ta.coding.editors = {
+    enable = true;
+    neovim.enable = true;
+  };
+
+  # Packages
+  home.packages = with pkgs; [
+    code2prompt
+    zellij-ps
+  ];
+
+  # Environment variables
+  home.sessionVariables = {
+    EDITOR = "nvim";
+    DEV_SERVER_PORT = toString (config.m3ta.ports.get "dev-server");
+  };
+}
+```
+
+## Module Options Reference
+
+### Standard Options
+
+All modules typically include:
+
+| Option | Type | Description |
+|---------|-------|-------------|
+| `enable` | `boolean` | Enable the module |
+| `package` | `package` | Custom package to use |
+| `extraConfig` | `attrs` | Additional configuration |
+
+### Port Management Options
+
+| Option | Type | Description |
+|---------|-------|-------------|
+| `definitions` | `attrsOf int` | Default port definitions |
+| `hostOverrides` | `attrsOf attrs` | Host-specific overrides |
+| `currentHost` | `string` | Current hostname |
+| `generateEnvVars` | `boolean` | Generate environment variables (HM only) |
+
+## Combining with Other Flakes
+
+### Using Multiple Module Sources
+
+```nix
+{config, ...}: {
+  imports = [
+    # m3ta-nixpkgs modules
+    m3ta-nixpkgs.nixosModules.default
+
+    # Other flake modules
+    inputs.impermanence.nixosModules.impermanence
+    inputs.sops-nix.nixosModules.sops
+  ];
+
+  # Configure all modules
+  m3ta.ports = {
+    enable = true;
+    definitions = {nginx = 80;};
+    currentHost = config.networking.hostName;
+  };
+
+  environment.persistence = {
+    "/persist" = {
+      directories = ["/var/lib/mem0"];
+    };
+  };
+}
+```
+
+### Using with Secrets
+
+```nix
+{config, ...}: {
+  imports = [
+    m3ta-nixpkgs.nixosModules.default
+    inputs.sops-nix.nixosModules.sops
+  ];
+
+  sops.secrets = {
+    openai-api-key = {};
+  };
+
+  m3ta.mem0 = {
+    enable = true;
+    llm = {
+      apiKeyFile = config.sops.secrets.openai-api-key.path;
+    };
+  };
+}
+```
+
+## Troubleshooting
+
+### Module Not Found
+
+Error: `error: The option 'm3ta.mymodule' does not exist`
+
+**Solutions**:
+1. Make sure you imported the module:
+
+```nix
+imports = [
+  m3ta-nixpkgs.nixosModules.default
+];
+```
+
+2. Check module name is correct
+
+```nix
+# Correct
+m3ta.mem0.enable = true;
+
+# Wrong
+m3ta.mymodule.enable = true;  # Doesn't exist
+```
+
+### Option Type Mismatch
+
+Error: `type mismatch at 'm3ta.mymodule.enable', expected a boolean but got a list`
+
+**Solution**: Check option types in documentation
+
+```nix
+# Correct
+m3ta.mymodule.enable = true;
+
+# Wrong
+m3ta.mymodule.enable = [true];  # Should be boolean
+```
+
+### Port Not Defined
+
+Error: `Service "foo" not defined`
+
+**Solution**: Add to port definitions
+
+```nix
+m3ta.ports = {
+  definitions = {
+    foo = 8080;  # Add this
+  };
+};
+```
+
+## Best Practices
+
+### Use Namespaces
+
+Always use the `m3ta.*` namespace:
+
+```nix
+# Good
+m3ta.mem0.enable = true;
+
+# Bad (potential conflicts)
+mem0.enable = true;
+```
+
+### Document Your Configuration
+
+Add comments explaining module usage:
+
+```nix
+# Port management for multi-host setup
+m3ta.ports = {
+  enable = true;
+  definitions = {
+    nginx = 80;
+    grafana = 3000;
+  };
+  hostOverrides.laptop = {
+    nginx = 8080;  # Use different port on laptop
+  };
+  currentHost = config.networking.hostName;
+};
+
+# Mem0 AI memory service
+m3ta.mem0 = {
+  enable = true;
+  port = config.m3ta.ports.get "mem0";
+};
+```
+
+### Test Configuration
+
+```bash
+# Test NixOS configuration without applying
+sudo nixos-rebuild test --flake .#hostname
+
+# Check configuration
+nix flake check
+
+# Show all options
+nix eval .#nixosConfigurations.hostname.config.m3ta --apply builtins.attrNames
+```
+
+## Next Steps
+
+- [Port Management](./port-management.md) - Detailed port management guide
+- [Adding Packages](./adding-packages.md) - How to add new packages
+- [Architecture](../ARCHITECTURE.md) - Understanding module structure
+- [Contributing](../CONTRIBUTING.md) - Code style and guidelines