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)

docs/modules/home-manager/ports.md

@@ -0,0 +1,272 @@
+# ports Home Manager Module
+
+Port management module for Home Manager.
+
+## Overview
+
+This module provides centralized port management for user-level services, similar to the NixOS version but with additional support for generating environment variables.
+
+See [Port Management Guide](../../guides/port-management.md) for detailed usage.
+
+## Quick Start
+
+```nix
+{config, ...}: {
+  m3ta.ports = {
+    enable = true;
+
+    # Define default ports
+    definitions = {
+      dev-server = 3000;
+      nextjs = 3001;
+      vite = 5173;
+    };
+
+    # Host-specific overrides
+    hostOverrides = {
+      laptop = {
+        vite = 5174;
+      };
+    };
+
+    # Current host
+    currentHost = "desktop";
+
+    # Generate environment variables (Home Manager only)
+    generateEnvVars = true;
+  };
+}
+```
+
+## Module Options
+
+### `m3ta.ports.enable`
+
+Enable port management.
+
+- Type: `boolean`
+- Default: `false`
+
+### `m3ta.ports.definitions`
+
+Default port definitions.
+
+- Type: `attrsOf int`
+- Default: `{}`
+
+Example:
+
+```nix
+definitions = {
+  dev-server = 3000;
+  nextjs = 3001;
+  vite = 5173;
+};
+```
+
+### `m3ta.ports.hostOverrides`
+
+Host-specific port overrides.
+
+- Type: `attrsOf (attrsOf int)`
+- Default: `{}`
+
+Example:
+
+```nix
+hostOverrides = {
+  laptop = {
+    vite = 5174;
+  };
+  desktop = {
+    vite = 5173;
+  };
+};
+```
+
+### `m3ta.ports.currentHost`
+
+Current hostname.
+
+- Type: `string`
+- Example: `"desktop"`
+
+### `m3ta.ports.generateEnvVars`
+
+Generate environment variables from ports.
+
+- Type: `boolean`
+- Default: `false`
+- Home Manager only
+
+When enabled, generates environment variables like:
+
+```bash
+PORT_DEV_SERVER=3000
+PORT_NEXTJS=3001
+PORT_VITE=5173
+```
+
+## Functions
+
+### `config.m3ta.ports.get "service"`
+
+Get port for a service with host-specific override.
+
+```nix
+home.sessionVariables = {
+  DEV_PORT = toString (config.m3ta.ports.get "dev-server");
+};
+```
+
+### `config.m3ta.ports.getHostPorts "hostname"`
+
+Get all ports for a specific host.
+
+```nix
+laptopPorts = config.m3ta.ports.getHostPorts "laptop";
+# Returns: { dev-server = 3000; vite = 5174; ... }
+```
+
+### `config.m3ta.ports.listServices`
+
+List all defined service names.
+
+```nix
+allServices = config.m3ta.ports.listServices;
+# Returns: ["dev-server" "nextjs" "vite"]
+```
+
+## Environment Variables
+
+When `generateEnvVars = true`, the following environment variables are generated:
+
+```
+PORT_<SERVICE_UPPERCASE>=<port_number>
+```
+
+Example:
+
+```nix
+m3ta.ports = {
+  enable = true;
+  definitions = {
+    dev-server = 3000;
+    nextjs = 3001;
+  };
+  generateEnvVars = true;
+};
+```
+
+Generates:
+
+```bash
+PORT_DEV_SERVER=3000
+PORT_NEXTJS=3001
+```
+
+You can then use these in scripts:
+
+```bash
+#!/usr/bin/env bash
+# Use environment variable directly
+npm start --port=$PORT_DEV_SERVER
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```nix
+{config, ...}: {
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      dev-server = 3000;
+    };
+    currentHost = "desktop";
+  };
+
+  home.sessionVariables = {
+    DEV_PORT = toString (config.m3ta.ports.get "dev-server");
+  };
+}
+```
+
+### With Environment Variables
+
+```nix
+{config, ...}: {
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      dev-server = 3000;
+      nextjs = 3001;
+      vite = 5173;
+    };
+    currentHost = "desktop";
+    generateEnvVars = true;
+  };
+
+  # Now available as environment variables
+  # PORT_DEV_SERVER=3000
+  # PORT_NEXTJS=3001
+  # PORT_VITE=5173
+}
+```
+
+### With Multi-Host Setup
+
+```nix
+{config, ...}: {
+  m3ta.ports = {
+    enable = true;
+    definitions = {
+      dev-server = 3000;
+      vite = 5173;
+    };
+    hostOverrides = {
+      laptop = {
+        vite = 5174;
+      };
+      desktop = {
+        vite = 5173;
+      };
+    };
+    currentHost = config.networking.hostName;
+    generateEnvVars = true;
+  };
+}
+```
+
+### With Shell Scripts
+
+Create `~/.config/zellij/scripts/dev.ksh`:
+
+```ksh
+#!/usr/bin/env ksh
+# Start dev server using environment variable
+cd ~/projects/my-app
+npm start --port=$PORT_DEV_SERVER
+```
+
+## Difference from NixOS Module
+
+The Home Manager version has one additional feature:
+
+### `generateEnvVars`
+
+Not available in NixOS module. Generates environment variables for all defined ports:
+
+```nix
+# Home Manager
+m3ta.ports.generateEnvVars = true;  # Available
+
+# NixOS
+# Not available
+```
+
+## Related
+
+- [Port Management Guide](../../guides/port-management.md) - Detailed guide
+- [NixOS Ports Module](../nixos/ports.md) - System-level port management