feat(deploy): add Gitea deployment templates, installer, and CI/CD workflow

deploy/README.md

@@ -0,0 +1,52 @@
+# 🚀 Multi-Agent Mux (MAM) Deployment & Gitea Integration
+
+This directory contains packaging templates and installation scripts to deploy the **Multi-Agent Mux** framework into workspaces hosted on **Gitea** (or GitHub).
+
+---
+
+## 📁 Deployment Directory Structure
+
+*   **`install.sh`**: A self-contained, idempotent shell installer that checks system requirements (`tmux`, `python3`, `pip3`), detects NFS/network filesystem mounts, sets up a local python virtual environment (`.venv`), and initializes environment configuration (`.env`).
+*   **`plugin.json`**: Metadata declaration file to register MAM as an installable plugin for AI Agent coding platforms (such as Claude Code, Antigravity, or other TUI clients).
+*   **`gitea-ci.yml`**: CI/CD pipeline definition template for Gitea Actions (running ShellCheck linting on bash scripts, validation on python scripts, and compilation tests).
+
+---
+
+## 📦 How to Install and Deploy
+
+### 1. Simple One-Liner Installation (from Gitea repository)
+Once you push this repository to your Gitea instance, users can install it in their local workspace directory by running:
+
+```bash
+curl -fsSL https://<your-gitea-domain>/<username>/multi-agent-mux/raw/branch/main/deploy/install.sh | bash
+```
+
+Alternatively, if they have cloned the repository, they can execute:
+```bash
+bash deploy/install.sh
+```
+
+### 2. Registering as a Workspace Plugin
+To register these skills globally or for a specific workspace:
+*   **Workspace Level**: Copy the `.agents/` folder into your project root.
+*   **Global Level (Gemini/Antigravity)**: Register the plugin path in your global config file at `~/.gemini/config/skills.json`:
+    ```json
+    {
+      "entries": [
+        { "path": "/absolute/path/to/multi-agent-mux/.agents/skills" }
+      ]
+    }
+    ```
+
+---
+
+## 🤖 Gitea Actions CI/CD Setup
+
+To automate testing and script linting on your Gitea repository:
+1. Ensure Gitea Actions is enabled on your Gitea instance.
+2. Copy the Gitea CI workflow to your workspace's workflow folder:
+   ```bash
+   mkdir -p .gitea/workflows
+   cp deploy/gitea-ci.yml .gitea/workflows/ci.yml
+   ```
+3. Commit and push to your Gitea repository. The pipeline will validate shell syntax and python file compilation on every push to `main` and pull requests.

deploy/gitea-ci.yml

@@ -0,0 +1,70 @@
+# ==============================================================================
+# Gitea Actions CI/CD Workflow Template
+# ==============================================================================
+# Place this file in '.gitea/workflows/ci.yml' or use it directly in Gitea's CI.
+# It automatically validates shell scripts and checks Python formatting/syntax.
+# ==============================================================================
+name: Multi-Agent Mux CI
+
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint-shell:
+    name: Lint Shell Scripts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Install ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+
+      - name: Run ShellCheck
+        run: |
+          echo "🔍 Linting shell scripts..."
+          shellcheck .agents/skills/lib.sh
+          shellcheck .agents/skills/multi-agent-mux-create/scripts/create_session.sh
+          shellcheck .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh
+          shellcheck .agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh
+          shellcheck deploy/install.sh
+          echo "✅ ShellCheck completed successfully."
+
+  lint-python:
+    name: Lint Python Backplane
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 pylint
+          if [ -f .agents/skills/multi-agent-mux-delegate-job/requirements.txt ]; then
+            pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt
+          fi
+
+      - name: Run Flake8 (Syntax/Error Check)
+        run: |
+          echo "🔍 Checking Python syntax with flake8..."
+          flake8 .agents/skills/multi-agent-mux-delegate-job/scripts/ --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+          flake8 .agents/skills/multi-agent-mux-delegate-job/scripts/ --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+      - name: Run Python Syntax Check (Compile test)
+        run: |
+          echo "🔍 Verifying Python file compilation..."
+          python -m py_compile .agents/skills/multi-agent-mux-delegate-job/scripts/*.py
+          echo "✅ All Python files compiled successfully."

deploy/install.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# install.sh — Multi-Agent Mux (MAM) Orchestration Installer
+# ==============================================================================
+# Idempotent, robust installer to bootstrap MAM orchestration skills
+# and Python backplane dependencies on any local workspace.
+# ==============================================================================
+set -euo pipefail
+
+# --- Configuration & Defaults ---
+TARGET_DIR="${1:-$(pwd)}"
+VENV_NAME=".venv"
+MIN_PYTHON_VERSION="3.9"
+
+echo "===================================================================="
+echo "⚡ Starting Multi-Agent Mux (MAM) Installation"
+echo "📂 Target Workspace: $TARGET_DIR"
+echo "===================================================================="
+
+# --- 1. System Requirements Validation ---
+echo "🔍 Checking system dependencies..."
+
+check_cmd() {
+  local cmd="$1"
+  if ! command -v "$cmd" &>/dev/null; then
+    echo "❌ Error: '$cmd' is not installed. Please install it first." >&2
+    exit 1
+  fi
+}
+
+check_cmd tmux
+check_cmd python3
+check_cmd pip3
+
+# Verify Python Version
+PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+if python3 -c "import sys; exit(0 if sys.version_info >= (3, 9) else 1)"; then
+  echo "✅ Python $PYTHON_VERSION detected."
+else
+  echo "❌ Error: Python version must be $MIN_PYTHON_VERSION or higher. Detected: $PYTHON_VERSION" >&2
+  exit 1
+fi
+
+# --- 2. Workspace Setup ---
+cd "$TARGET_DIR"
+echo "📂 Ensuring metadata directory structure (.mam/)..."
+mkdir -p .mam/jobs .mam/delegate_job_logs
+
+# File permission lockdown on database directory
+chmod 0700 .mam
+
+# --- 3. Check Network File System (NFS) Warnings ---
+echo "💾 Detecting file system mount type..."
+if command -v df &>/dev/null && command -v mount &>/dev/null; then
+  MOUNTPOINT="$(df --output=target . 2>/dev/null | tail -1 || echo "")"
+  if [ -n "$MOUNTPOINT" ]; then
+    if mount | grep -q "$MOUNTPOINT.*nfs\|$MOUNTPOINT.*cifs\|$MOUNTPOINT.*fuse.sshfs"; then
+      echo "⚠️  WARNING: Target directory is on a network filesystem (NFS/CIFS/SSHFS)."
+      echo "   File locks (fcntl.flock) are UNRELIABLE on network storage."
+      echo "   The sqlite3 registry will fall back to 'DELETE' journaling instead of WAL."
+    else
+      echo "✅ File system supports WAL (Local storage detected)."
+    fi
+  fi
+fi
+
+# --- 4. Python Virtual Environment Setup ---
+echo "🐍 Bootstrapping Python virtual environment (.venv)..."
+if [ ! -d "$VENV_NAME" ]; then
+  python3 -m venv "$VENV_NAME"
+  echo "✅ Virtual environment created."
+else
+  echo "ℹ️  Virtual environment (.venv) already exists. Skipping creation."
+fi
+
+# Activate virtual environment
+# shellcheck disable=SC1091
+source "$VENV_NAME"/bin/activate
+
+# Install requirements
+REQ_FILE=".agents/skills/multi-agent-mux-delegate-job/requirements.txt"
+if [ -f "$REQ_FILE" ]; then
+  echo "📦 Installing backplane dependencies from $REQ_FILE..."
+  pip install --upgrade pip
+  pip install -r "$REQ_FILE"
+  echo "✅ Dependencies installed successfully."
+else
+  echo "⚠️  WARNING: Could not find requirements file: $REQ_FILE"
+  echo "   Installing default packages (paho-mqtt, pyyaml) manually..."
+  pip install --upgrade pip
+  pip install "paho-mqtt>=2.0.0" pyyaml
+fi
+
+# --- 5. Generate Environment Template ---
+ENV_FILE=".env"
+ENV_EXAMPLE=".env.example"
+if [ ! -f "$ENV_FILE" ]; then
+  if [ -f "$ENV_EXAMPLE" ]; then
+    echo "📝 Creating configuration from $ENV_EXAMPLE..."
+    cp "$ENV_EXAMPLE" "$ENV_FILE"
+    chmod 0600 "$ENV_FILE"
+  else
+    echo "📝 Creating default $ENV_FILE..."
+    cat <<EOF > "$ENV_FILE"
+# ==============================================================================
+# Multi-Agent Mux (MAM) Environment Settings
+# ==============================================================================
+MQTT_BROKER=broker.hivemq.com
+MQTT_PORT=1883
+MQTT_TLS=0
+MQTT_CLIENT_ID_PREFIX=mam-agent
+TMUX_SERVER_NAME=default
+EOF
+    chmod 0600 "$ENV_FILE"
+  fi
+  echo "✅ Config file .env initialized with chmod 0600."
+else
+  echo "ℹ️  $ENV_FILE already exists. Skipping config override."
+fi
+
+echo "===================================================================="
+echo "🎉 Installation complete!"
+echo "✨ You can now run the status or monitor skills."
+echo "💡 Hint: Try executing: .venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py list"
+echo "===================================================================="

deploy/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "multi-agent-mux",
+  "description": "Multi-Agent Orchestration & Messaging Backplane on Tmux & MQTT.",
+  "disabled": false
+}