docs/phase3a-setup.md

@@ -0,0 +1,158 @@
+# Kugetsu Phase 3a Installation Guide
+
+Guide for setting up the Kugetsu Chat Agent (Phase 3a) on a new host/container.
+
+## Prerequisites
+
+1. **Hermes Agent** installed and configured
+2. **Telegram bot** created via @BotFather
+3. **kugetsu CLI** installed
+4. **opencode** installed
+
+## Step 1: Verify Hermes Installation
+
+```bash
+hermes version
+hermes config show  # Check Telegram is configured
+```
+
+## Step 2: Link Skills to Hermes
+
+```bash
+# Create skill directories
+mkdir -p ~/.hermes/skills/kugetsu-chat
+mkdir -p ~/.hermes/skills/kugetsu-pm
+mkdir -p ~/.hermes/skills/kugetsu-helpers
+
+# Link skills from kugetsu repo (adjust path as needed)
+KUGEETSU_DIR="/path/to/kugetsu"  # e.g., ~/repositories/kugetsu
+
+ln -sf "$KUGEETSU_DIR/skills/kugetsu-chat" ~/.hermes/skills/kugetsu-chat
+ln -sf "$KUGEETSU_DIR/skills/kugetsu-pm ~/.hermes/skills/kugetsu-pm
+ln -sf "$KUGEETSU_DIR/skills/kugetsu-helpers" ~/.hermes/skills/kugetsu-helpers
+```
+
+## Step 3: Install Chat Agent SOUL
+
+```bash
+# Copy SOUL.md to Hermes home (this defines the Chat Agent personality)
+cp "$KUGEETSU_DIR/skills/kugetsu-chat/SOUL.md" ~/.hermes/SOUL-chat.md
+```
+
+## Step 4: Install Helper Scripts
+
+```bash
+# Copy helper script to PATH
+cp "$KUGEETSU_DIR/skills/kugetsu-helpers/scripts/kugetsu-helpers" ~/.local/bin/kugetsu-helper
+chmod +x ~/.local/bin/kugetsu-helper
+
+# Verify
+kugetsu-helper help
+```
+
+## Step 5: Verify Gateway is Running
+
+```bash
+hermes gateway status
+# If stopped:
+hermes gateway start
+```
+
+## Step 6: Initialize kugetsu
+
+**WARNING:** This requires an interactive terminal (TTY) because it spawns the opencode TUI.
+
+You must run this in an **interactive shell**, not via `ssh remote "kugetsu init"`:
+
+```bash
+# Option 1: SSH with TTY allocation
+ssh -t user@host "kugetsu init"
+
+# Option 2: Connect to existing session and run
+ssh user@host
+kugetsu init  # Run manually in the SSH session
+```
+
+This creates:
+- **Base session** (for forking dev agents)
+- **PM Agent session** (persistent coordinator)
+
+If you get `Error: init requires a terminal (TTY)`, you're running via non-interactive SSH. Use `-t` flag or connect directly.
+
+## Step 7: Verify Setup
+
+```bash
+# Check kugetsu status
+kugetsu list
+
+# Check PM agent exists
+kugetsu-helper check-status
+# Should output: ok
+```
+
+## Step 8: Test via Telegram
+
+Start a conversation with your bot (@your_bot_username):
+
+| Message | Expected |
+|---------|----------|
+| `hi` | Responds directly (small talk) |
+| `status?` | Routes to PM Agent |
+| `fix issue #5` | Routes to PM Agent |
+
+## Troubleshooting
+
+### kugetsu-helper not found
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Or add to ~/.bashrc
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+```
+
+### Gateway not responding
+```bash
+hermes gateway restart
+```
+
+### PM agent missing
+```bash
+# Reinitialize
+kugetsu destroy --pm-agent -y
+kugetsu init
+```
+
+## File Locations
+
+| File | Location | Purpose |
+|------|----------|---------|
+| Chat Agent SOUL | `~/.hermes/SOUL-chat.md` | Personality |
+| kugetsu-chat skill | `~/.hermes/skills/kugetsu-chat/` | Routing behavior |
+| kugetsu-pm skill | `~/.hermes/skills/kugetsu-pm/` | PM Agent docs |
+| kugetsu-helpers | `~/.hermes/skills/kugetsu-helpers/` | Helper functions |
+| Helper script | `~/.local/bin/kugetsu-helper` | CLI helper |
+
+## Architecture Summary
+
+```
+~/.hermes/
+├── SOUL-chat.md              # Chat Agent personality
+└── skills/
+    ├── kugetsu-chat/         # Routing + delegation logic
+    ├── kugetsu-pm/           # PM Agent documentation
+    └── kugetsu-helpers/      # Shell helpers for terminal()
+
+~/.kugetsu/
+├── sessions/
+│   ├── base.json             # Base opencode session
+│   └── pm-agent.json         # PM Agent opencode session
+└── index.json                # Session registry
+
+~/.local/bin/
+└── kugetsu-helper            # CLI helper script
+```
+
+## Security Notes
+
+- Never commit `~/.kugetsu/` or SOUL files to version control
+- Bot tokens should be in environment variables, not files
+- PM agent session IDs are internal - don't expose to users

skills/kugetsu/scripts/kugetsu-install.sh

@@ -1,10 +1,13 @@
 #!/bin/bash
+# kugetsu installation script
+# Installs kugetsu CLI and optionally sets up Phase 3a Chat Agent
+
 set -euo pipefail
 
 KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
-BIN_DIR="$KUGETSU_DIR/bin"
+BIN_DIR="${BIN_DIR:-$HOME/.local/bin}"
 
-echo "Installing kugetsu to $KUGETSU_DIR..."
+echo "Installing kugetsu..."
 
 mkdir -p "$BIN_DIR"
 
@@ -13,24 +16,21 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cp "$SCRIPT_DIR/kugetsu" "$BIN_DIR/kugetsu"
 chmod +x "$BIN_DIR/kugetsu"
 
+echo "kugetsu installed at: $BIN_DIR/kugetsu"
+
 add_to_shell() {
     local rc_file="$1"
-    local export_line="export PATH=\"\$HOME/.kugetsu/bin:\$PATH\""
+    local export_line="export PATH=\"\$HOME/.local/bin:\$PATH\""
     
     if [ -f "$rc_file" ]; then
         if grep -q "$export_line" "$rc_file" 2>/dev/null; then
-            echo "$rc_file already has kugetsu in PATH"
+            echo "$rc_file already has .local/bin in PATH"
         else
             echo "" >> "$rc_file"
-            echo "# kugetsu - opencode session manager" >> "$rc_file"
+            echo "# kugetsu and other tools" >> "$rc_file"
             echo "$export_line" >> "$rc_file"
             echo "Added to $rc_file"
         fi
-    else
-        echo "" >> "$rc_file"
-        echo "# kugetsu - opencode session manager" >> "$rc_file"
-        echo "$export_line" >> "$rc_file"
-        echo "Created $rc_file with kugetsu PATH"
     fi
 }
 
@@ -39,29 +39,24 @@ add_to_shell "$HOME/.zshrc"
 
 echo ""
 echo "=== Verifying installation ==="
-if [ ! -f "$BIN_DIR/kugetsu" ]; then
+"$BIN_DIR/kugetsu" help | head -10
-    echo "ERROR: kugetsu was not installed correctly."
-    exit 1
-fi
-echo "kugetsu installed at: $BIN_DIR/kugetsu"
 echo ""
-
 echo "Installation complete!"
+
 echo ""
-echo "Run this to start using kugetsu immediately:"
+echo "=== Phase 3a Chat Agent Setup (Optional) ==="
-echo "    export PATH=\"\$HOME/.kugetsu/bin:\$PATH\""
+echo "To also install the Chat Agent skills for Phase 3a:"
 echo ""
-echo "Or start a new shell."
+echo "  1. Link skills to Hermes:"
+echo "     mkdir -p ~/.hermes/skills/kugetsu-chat ~/.hermes/skills/kugetsu-pm ~/.hermes/skills/kugetsu-helpers"
+echo "     ln -sf /path/to/kugetsu/skills/kugetsu-chat ~/.hermes/skills/"
+echo "     ln -sf /path/to/kugetsu/skills/kugetsu-pm ~/.hermes/skills/"
+echo "     ln -sf /path/to/kugetsu/skills/kugetsu-helpers ~/.hermes/skills/"
 echo ""
-echo "Usage:"
+echo "  2. Install Chat Agent SOUL:"
-echo "    kugetsu init                           Initialize base session (requires TTY)"
+echo "     cp /path/to/kugetsu/skills/kugetsu-chat/SOUL.md ~/.hermes/SOUL-chat.md"
-echo "    kugetsu start <issue-ref> <message>    Start task for issue"
-echo "    kugetsu continue <issue-ref> [msg]     Continue existing task"
-echo "    kugetsu list                           List all sessions"
-echo "    kugetsu prune [--force]                Remove orphaned sessions"
-echo "    kugetsu destroy <issue-ref> [-y]       Delete session for issue"
-echo "    kugetsu destroy --base [-y]            Delete base session"
-echo "    kugetsu help                           Show help"
 echo ""
-echo "Issue ref format: instance/user/repo#number"
+echo "  3. Initialize kugetsu (requires TTY):"
-echo "Example: github.com/shoko/kugetsu#14"
+echo "     kugetsu init"
+echo ""
+echo "See docs/phase3a-setup.md for full installation guide."