@geekbeer/minion 1.6.1 → 2.4.0

package/api.js

@@ -31,7 +31,9 @@ async function request(endpoint, options = {}) {
   const data = await response.json()
 
   if (!response.ok) {
-    throw new Error(data.error || `API request failed: ${response.status}`)
+    const err = new Error(data.error || `API request failed: ${response.status}`)
+    err.statusCode = response.status
+    throw err
   }
 
   return data

package/minion-cli.sh

@@ -438,6 +438,16 @@ SUPEOF
     echo "  -> No bundled skills found (this is OK for development)"
   fi
 
+  # Deploy Claude rules (minion self-knowledge for AI)
+  local BUNDLED_RULES_DIR="${NPM_ROOT}/@geekbeer/minion/rules"
+  local CLAUDE_RULES_DIR="${TARGET_HOME}/.claude/rules"
+
+  if [ -d "$BUNDLED_RULES_DIR" ]; then
+    $RUN_AS mkdir -p "$CLAUDE_RULES_DIR"
+    $RUN_AS cp "$BUNDLED_RULES_DIR"/minion.md "$CLAUDE_RULES_DIR"/minion.md
+    echo "  -> Deployed Claude rules: minion.md"
+  fi
+
   # Step 9 (optional): Cloudflare Tunnel setup
   if [ "$SETUP_TUNNEL" = true ]; then
     echo ""
@@ -585,6 +595,50 @@ case "${1:-}" in
     echo "minion-agent restarted ($PROC_MGR)"
     ;;
 
+  skill)
+    shift
+    SKILL_CMD="${1:-}"
+    shift || true
+    case "$SKILL_CMD" in
+      push)
+        SKILL_NAME="${1:-}"
+        if [ -z "$SKILL_NAME" ]; then
+          echo "Usage: minion-cli skill push <skill-name>"
+          exit 1
+        fi
+        curl -s -X POST "$AGENT_URL/api/skills/push/$SKILL_NAME" \
+          -H "Authorization: Bearer $API_TOKEN" | jq .
+        ;;
+      fetch)
+        SKILL_NAME="${1:-}"
+        if [ -z "$SKILL_NAME" ]; then
+          echo "Usage: minion-cli skill fetch <skill-name>"
+          exit 1
+        fi
+        curl -s -X POST "$AGENT_URL/api/skills/fetch/$SKILL_NAME" \
+          -H "Authorization: Bearer $API_TOKEN" | jq .
+        ;;
+      list)
+        FLAG="${1:-}"
+        if [ "$FLAG" = "--local" ]; then
+          curl -s "$AGENT_URL/api/list-skills" \
+            -H "Authorization: Bearer $API_TOKEN" | jq .
+        else
+          curl -s "$AGENT_URL/api/skills/remote" \
+            -H "Authorization: Bearer $API_TOKEN" | jq .
+        fi
+        ;;
+      *)
+        echo "Usage: minion-cli skill <push|fetch|list> [options]"
+        echo ""
+        echo "Commands:"
+        echo "  push <name>     Push local skill to HQ"
+        echo "  fetch <name>    Fetch skill from HQ to local"
+        echo "  list            List skills on HQ (--local for local skills)"
+        ;;
+    esac
+    ;;
+
   *)
     echo "Minion Agent CLI (@geekbeer/minion) v${CLI_VERSION}"
     echo ""
@@ -596,6 +650,7 @@ case "${1:-}" in
     echo "  minion-cli status                         # Get current status"
     echo "  minion-cli health                         # Health check"
     echo "  minion-cli set-status <status> [task]     # Set status and optional task"
+    echo "  minion-cli skill <push|fetch|list>        # Manage skills with HQ"
     echo "  minion-cli --version                      # Show version"
     echo ""
     echo "Setup options:"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "1.6.1",
+  "version": "2.4.0",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "server.js",
   "bin": {
@@ -17,6 +17,8 @@
     "lib/",
     "routes/",
     "skills/",
+    "rules/",
+    "settings/",
     "minion-cli.sh",
     ".env.example"
   ],

package/routes/files.js

@@ -0,0 +1,288 @@
+/**
+ * File management endpoints
+ *
+ * Provides bidirectional file transfer between HQ and minion.
+ * Files are stored in ~/files/ directory.
+ *
+ * Endpoints:
+ * - GET    /api/files      - List files in directory
+ * - GET    /api/files/*    - Download a file
+ * - POST   /api/files/*    - Upload a file
+ * - DELETE  /api/files/*    - Delete a file
+ */
+
+const fs = require('fs').promises
+const fsSync = require('fs')
+const path = require('path')
+const os = require('os')
+
+const { verifyToken } = require('../lib/auth')
+
+/** Base directory for file storage */
+const FILES_DIR = path.join(os.homedir(), 'files')
+
+/** Max upload size: 50MB */
+const MAX_UPLOAD_SIZE = 50 * 1024 * 1024
+
+/**
+ * Resolve a user-provided path safely within the base directory.
+ * Returns null if the path escapes the sandbox.
+ *
+ * @param {string} basedir - Absolute base directory
+ * @param {string} userPath - User-provided relative path
+ * @returns {string|null} Resolved absolute path, or null if traversal detected
+ */
+function safePath(basedir, userPath) {
+  const decoded = decodeURIComponent(userPath)
+  // Reject null bytes
+  if (decoded.includes('\0')) return null
+  const resolved = path.resolve(basedir, decoded)
+  if (resolved === basedir) return resolved
+  if (!resolved.startsWith(basedir + path.sep)) return null
+  return resolved
+}
+
+/**
+ * Register file routes as Fastify plugin
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+async function fileRoutes(fastify) {
+  // Register binary body parser for octet-stream
+  fastify.addContentTypeParser('application/octet-stream', function (request, payload, done) {
+    const chunks = []
+    let totalSize = 0
+    payload.on('data', chunk => {
+      totalSize += chunk.length
+      if (totalSize > MAX_UPLOAD_SIZE) {
+        done(new Error('File too large (max 50MB)'))
+        return
+      }
+      chunks.push(chunk)
+    })
+    payload.on('end', () => done(null, Buffer.concat(chunks)))
+    payload.on('error', done)
+  })
+
+  // GET /api/files - List files in directory
+  fastify.get('/api/files', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const subPath = request.query.path || ''
+
+    try {
+      let targetDir = FILES_DIR
+      if (subPath) {
+        targetDir = safePath(FILES_DIR, subPath)
+        if (!targetDir) {
+          reply.code(403)
+          return { success: false, error: 'Invalid path' }
+        }
+      }
+
+      // Ensure directory exists
+      await fs.mkdir(targetDir, { recursive: true })
+
+      const entries = await fs.readdir(targetDir, { withFileTypes: true })
+      const files = []
+
+      for (const entry of entries) {
+        const entryPath = path.join(targetDir, entry.name)
+        try {
+          const stat = await fs.lstat(entryPath)
+          // Skip symlinks that point outside FILES_DIR
+          if (stat.isSymbolicLink()) {
+            const realPath = await fs.realpath(entryPath)
+            if (!realPath.startsWith(FILES_DIR)) continue
+          }
+          const relativePath = path.relative(FILES_DIR, entryPath)
+          files.push({
+            name: entry.name,
+            path: relativePath,
+            size: stat.size,
+            modified: stat.mtime.toISOString(),
+            is_directory: entry.isDirectory(),
+          })
+        } catch {
+          // Skip entries we can't stat
+        }
+      }
+
+      // Sort: directories first, then by name
+      files.sort((a, b) => {
+        if (a.is_directory !== b.is_directory) return a.is_directory ? -1 : 1
+        return a.name.localeCompare(b.name)
+      })
+
+      return { success: true, files, current_path: subPath || '' }
+    } catch (error) {
+      console.error(`[Files] List error: ${error.message}`)
+      reply.code(500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // GET /api/files/* - Download a file
+  fastify.get('/api/files/*', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const filePath = request.params['*']
+    if (!filePath) {
+      reply.code(400)
+      return { success: false, error: 'File path is required' }
+    }
+
+    const resolved = safePath(FILES_DIR, filePath)
+    if (!resolved) {
+      reply.code(403)
+      return { success: false, error: 'Invalid path' }
+    }
+
+    try {
+      const stat = await fs.lstat(resolved)
+
+      // Don't allow downloading directories
+      if (stat.isDirectory()) {
+        reply.code(400)
+        return { success: false, error: 'Cannot download a directory' }
+      }
+
+      // Check symlink safety
+      if (stat.isSymbolicLink()) {
+        const realPath = await fs.realpath(resolved)
+        if (!realPath.startsWith(FILES_DIR)) {
+          reply.code(403)
+          return { success: false, error: 'Invalid path' }
+        }
+      }
+
+      const filename = path.basename(resolved)
+      reply
+        .type('application/octet-stream')
+        .header('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`)
+        .header('Content-Length', stat.size)
+
+      return reply.send(fsSync.createReadStream(resolved))
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        reply.code(404)
+        return { success: false, error: 'File not found' }
+      }
+      console.error(`[Files] Download error: ${error.message}`)
+      reply.code(500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // POST /api/files/* - Upload a file
+  fastify.post('/api/files/*', { bodyLimit: MAX_UPLOAD_SIZE }, async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const filePath = request.params['*']
+    if (!filePath) {
+      reply.code(400)
+      return { success: false, error: 'File path is required' }
+    }
+
+    const resolved = safePath(FILES_DIR, filePath)
+    if (!resolved) {
+      reply.code(403)
+      return { success: false, error: 'Invalid path' }
+    }
+
+    // Don't allow overwriting the base directory itself
+    if (resolved === FILES_DIR) {
+      reply.code(400)
+      return { success: false, error: 'Invalid file path' }
+    }
+
+    try {
+      const body = request.body
+      if (!Buffer.isBuffer(body)) {
+        reply.code(400)
+        return { success: false, error: 'Expected binary body (application/octet-stream)' }
+      }
+
+      // Create parent directories
+      await fs.mkdir(path.dirname(resolved), { recursive: true })
+
+      // Write file
+      await fs.writeFile(resolved, body)
+
+      const stat = await fs.stat(resolved)
+      const relativePath = path.relative(FILES_DIR, resolved)
+
+      console.log(`[Files] Uploaded: ${relativePath} (${stat.size} bytes)`)
+
+      return {
+        success: true,
+        file: {
+          name: path.basename(resolved),
+          path: relativePath,
+          size: stat.size,
+        },
+      }
+    } catch (error) {
+      console.error(`[Files] Upload error: ${error.message}`)
+      reply.code(500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // DELETE /api/files/* - Delete a file or directory
+  fastify.delete('/api/files/*', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    const filePath = request.params['*']
+    if (!filePath) {
+      reply.code(400)
+      return { success: false, error: 'File path is required' }
+    }
+
+    const resolved = safePath(FILES_DIR, filePath)
+    if (!resolved) {
+      reply.code(403)
+      return { success: false, error: 'Invalid path' }
+    }
+
+    // Don't allow deleting the base directory itself
+    if (resolved === FILES_DIR) {
+      reply.code(400)
+      return { success: false, error: 'Cannot delete root files directory' }
+    }
+
+    try {
+      await fs.access(resolved)
+    } catch {
+      reply.code(404)
+      return { success: false, error: 'File not found' }
+    }
+
+    try {
+      const stat = await fs.lstat(resolved)
+      await fs.rm(resolved, { recursive: stat.isDirectory(), force: true })
+
+      const relativePath = path.relative(FILES_DIR, resolved)
+      console.log(`[Files] Deleted: ${relativePath}`)
+
+      return { success: true, message: `Deleted ${relativePath}` }
+    } catch (error) {
+      console.error(`[Files] Delete error: ${error.message}`)
+      reply.code(500)
+      return { success: false, error: error.message }
+    }
+  })
+}
+
+module.exports = { fileRoutes }

package/routes/index.js

@@ -34,6 +34,12 @@
  *   GET  /api/terminal/capture      - Capture pane content (auth required)
  *   POST /api/terminal/send         - Send keys to session (auth required)
  *   POST /api/terminal/kill         - Kill a session (auth required)
+ *
+ * Files (routes/files.js)
+ *   GET    /api/files               - List files in directory (auth required)
+ *   GET    /api/files/*             - Download a file (auth required)
+ *   POST   /api/files/*             - Upload a file (auth required)
+ *   DELETE /api/files/*             - Delete a file (auth required)
  * ─────────────────────────────────────────────────────────────────────────────
  */
 
@@ -42,6 +48,7 @@ const { commandRoutes, getProcessManager, getAllowedCommands } = require('./comm
 const { skillRoutes } = require('./skills')
 const { workflowRoutes } = require('./workflows')
 const { terminalRoutes } = require('./terminal')
+const { fileRoutes } = require('./files')
 
 /**
  * Register all routes with Fastify instance
@@ -53,6 +60,7 @@ async function registerRoutes(fastify) {
   await fastify.register(skillRoutes)
   await fastify.register(workflowRoutes)
   await fastify.register(terminalRoutes)
+  await fastify.register(fileRoutes)
 }
 
 module.exports = {

package/routes/skills.js

@@ -2,8 +2,11 @@
  * Skill management endpoints
  *
  * Endpoints:
- * - GET  /api/list-skills   - List deployed skills
- * - POST /api/deploy-skill  - Deploy a skill
+ * - GET  /api/list-skills        - List locally deployed skills
+ * - DELETE /api/skills/:name     - Delete a local skill
+ * - POST /api/skills/push/:name  - Push local skill to HQ
+ * - POST /api/skills/fetch/:name - Fetch skill from HQ and deploy locally
+ * - GET  /api/skills/remote      - List skills on HQ
  */
 
 const fs = require('fs').promises
@@ -11,6 +14,111 @@ const path = require('path')
 const os = require('os')
 
 const { verifyToken } = require('../lib/auth')
+const api = require('../api')
+const { isHqConfigured } = require('../config')
+
+/**
+ * Parse YAML frontmatter from SKILL.md content
+ * @param {string} content - Raw file content
+ * @returns {{ metadata: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
+  if (!match) return { metadata: {}, body: content }
+
+  const metadata = {}
+  for (const line of match[1].split('\n')) {
+    const [key, ...rest] = line.split(':')
+    if (key && rest.length) {
+      metadata[key.trim()] = rest.join(':').trim()
+    }
+  }
+  return { metadata, body: match[2].trimStart() }
+}
+
+/**
+ * Write a skill to the local ~/.claude/skills/ directory.
+ * Shared by deploy-skill and skills/fetch endpoints.
+ *
+ * @param {string} name - Skill slug (e.g. "execution-report")
+ * @param {object} opts
+ * @param {string} opts.content - Skill body (markdown without frontmatter)
+ * @param {string} [opts.description] - Skill description for frontmatter
+ * @param {string} [opts.display_name] - Display name for frontmatter
+ * @param {Array<{filename: string, content: string}>} [opts.references] - Reference files
+ * @returns {Promise<{path: string, references_count: number}>}
+ */
+async function writeSkillToLocal(name, { content, description, display_name, references = [] }) {
+  const skillDir = path.join(os.homedir(), '.claude', 'skills', name)
+  const referencesDir = path.join(skillDir, 'references')
+
+  await fs.mkdir(skillDir, { recursive: true })
+  await fs.mkdir(referencesDir, { recursive: true })
+
+  // Build frontmatter with all available metadata
+  const frontmatterLines = [
+    `name: ${name}`,
+    display_name ? `display_name: ${display_name}` : null,
+    `description: ${description || ''}`,
+  ].filter(Boolean).join('\n')
+
+  await fs.writeFile(
+    path.join(skillDir, 'SKILL.md'),
+    `---\n${frontmatterLines}\n---\n\n${content}`,
+    'utf-8'
+  )
+
+  // Write reference files
+  for (const ref of references) {
+    if (ref.filename && ref.content) {
+      const safeFilename = path.basename(ref.filename)
+      await fs.writeFile(path.join(referencesDir, safeFilename), ref.content, 'utf-8')
+    }
+  }
+
+  return { path: skillDir, references_count: references.length }
+}
+
+/**
+ * Read a local skill and push it to HQ.
+ * Reusable by workflow push to auto-sync pipeline skills.
+ *
+ * @param {string} name - Skill slug (e.g. "execution-report")
+ * @returns {Promise<object>} HQ response
+ * @throws {Error} If skill not found locally or HQ rejects
+ */
+async function pushSkillToHQ(name) {
+  const homeDir = os.homedir()
+  const skillDir = path.join(homeDir, '.claude', 'skills', name)
+  const skillMdPath = path.join(skillDir, 'SKILL.md')
+
+  const rawContent = await fs.readFile(skillMdPath, 'utf-8')
+  const { metadata, body } = parseFrontmatter(rawContent)
+
+  // Read references
+  const referencesDir = path.join(skillDir, 'references')
+  const references = []
+  try {
+    const refEntries = await fs.readdir(referencesDir)
+    for (const filename of refEntries) {
+      const refContent = await fs.readFile(path.join(referencesDir, filename), 'utf-8')
+      references.push({ filename, content: refContent })
+    }
+  } catch {
+    // No references directory
+  }
+
+  return api.request('/skills', {
+    method: 'POST',
+    body: JSON.stringify({
+      name: metadata.name || name,
+      display_name: metadata.display_name || metadata.name || name,
+      description: metadata.description || '',
+      content: body,
+      references,
+    }),
+  })
+}
 
 /**
  * Register skill routes as Fastify plugin
@@ -66,71 +174,105 @@ async function skillRoutes(fastify) {
     }
   })
 
-  // Deploy skill to local .claude/skills directory
-  fastify.post('/api/deploy-skill', async (request, reply) => {
+  // Push local skill to HQ
+  fastify.post('/api/skills/push/:name', async (request, reply) => {
     if (!verifyToken(request)) {
       reply.code(401)
       return { success: false, error: 'Unauthorized' }
     }
 
-    const { name, content, references = [] } = request.body || {}
-
-    if (!name || !content) {
+    if (!isHqConfigured()) {
       reply.code(400)
-      return { success: false, error: 'name and content are required' }
+      return { success: false, error: 'HQ not configured' }
     }
 
-    // Validate skill name (URL-safe slug)
-    if (!/^[a-z0-9-]+$/.test(name)) {
+    const { name } = request.params
+
+    if (!name || !/^[a-z0-9-]+$/.test(name)) {
       reply.code(400)
-      return { success: false, error: 'Skill name must be URL-safe (lowercase letters, numbers, and hyphens only)' }
+      return { success: false, error: 'Invalid skill name' }
     }
 
-    console.log(`[Deploy] Deploying skill: ${name}`)
+    console.log(`[Skills] Pushing skill to HQ: ${name}`)
 
     try {
-      // Create skill directory in ~/.claude/skills/
-      const homeDir = os.homedir()
-      const skillDir = path.join(homeDir, '.claude', 'skills', name)
-      const referencesDir = path.join(skillDir, 'references')
-
-      // Create directories
-      await fs.mkdir(skillDir, { recursive: true })
-      await fs.mkdir(referencesDir, { recursive: true })
-
-      // Write SKILL.md with frontmatter
-      const skillContent = `---
-name: ${name}
-description: Deployed from HQ
----
-
-${content}`
-      await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillContent, 'utf-8')
-
-      // Write reference files
-      for (const ref of references) {
-        if (ref.filename && ref.content) {
-          // Sanitize filename to prevent directory traversal
-          const safeFilename = path.basename(ref.filename)
-          await fs.writeFile(path.join(referencesDir, safeFilename), ref.content, 'utf-8')
-        }
-      }
+      const result = await pushSkillToHQ(name)
+      console.log(`[Skills] Skill pushed to HQ: ${name}`)
+      return { success: true, ...result }
+    } catch (error) {
+      console.error(`[Skills] Failed to push skill: ${error.message}`)
+      reply.code(error.statusCode || 500)
+      return { success: false, error: error.message }
+    }
+  })
 
-      console.log(`[Deploy] Skill deployed successfully: ${name}`)
+  // Fetch skill from HQ and deploy locally
+  fastify.post('/api/skills/fetch/:name', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
 
+    if (!isHqConfigured()) {
+      reply.code(400)
+      return { success: false, error: 'HQ not configured' }
+    }
+
+    const { name } = request.params
+
+    if (!name || !/^[a-z0-9-]+$/.test(name)) {
+      reply.code(400)
+      return { success: false, error: 'Invalid skill name' }
+    }
+
+    console.log(`[Skills] Fetching skill from HQ: ${name}`)
+
+    try {
+      // Fetch from HQ
+      const skill = await api.request(`/skills/${encodeURIComponent(name)}`)
+
+      // Write to local filesystem using shared helper
+      const result = await writeSkillToLocal(name, {
+        content: skill.content,
+        description: skill.description,
+        display_name: skill.display_name,
+        references: skill.references || [],
+      })
+
+      console.log(`[Skills] Skill fetched and deployed: ${name}`)
       return {
         success: true,
-        message: `Skill "${name}" deployed successfully`,
-        path: skillDir,
-        references_count: references.length,
+        message: `Skill "${name}" fetched from HQ`,
+        ...result,
       }
     } catch (error) {
-      console.error(`[Deploy] Failed to deploy skill: ${error.message}`)
-      reply.code(500)
-      return {
-        success: false,
-        error: error.message,
-      }
+      console.error(`[Skills] Failed to fetch skill: ${error.message}`)
+      reply.code(error.statusCode || 500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // List skills on HQ (remote)
+  fastify.get('/api/skills/remote', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    if (!isHqConfigured()) {
+      reply.code(400)
+      return { success: false, error: 'HQ not configured' }
+    }
+
+    console.log('[Skills] Listing remote skills from HQ')
+
+    try {
+      const result = await api.request('/skills')
+      return result
+    } catch (error) {
+      console.error(`[Skills] Failed to list remote skills: ${error.message}`)
+      reply.code(error.statusCode || 500)
+      return { success: false, error: error.message }
     }
   })
 
@@ -185,4 +327,4 @@ ${content}`
   })
 }
 
-module.exports = { skillRoutes }
+module.exports = { skillRoutes, writeSkillToLocal, pushSkillToHQ }

package/routes/terminal.js

@@ -16,6 +16,7 @@
 
 const { exec, spawn } = require('child_process')
 const { promisify } = require('util')
+const path = require('path')
 const net = require('net')
 const os = require('os')
 const execAsync = promisify(exec)
@@ -122,6 +123,17 @@ async function startTtydForSession(session) {
     }
   }
 
+  // Reload tmux.conf to ensure mouse/scroll settings are active
+  const tmuxConf = path.join(homeDir, '.tmux.conf')
+  try {
+    await execAsync(`tmux source-file "${tmuxConf}"`, {
+      timeout: 5000,
+      env: { ...process.env, HOME: homeDir },
+    })
+  } catch {
+    // Ignore: .tmux.conf may not exist yet on first run
+  }
+
   const port = await findAvailablePort()
 
   const proc = spawn('ttyd', [

package/routes/workflows.js

@@ -2,22 +2,32 @@
  * Workflow management endpoints
  *
  * Endpoints:
- * - GET  /api/workflows           - List all workflows with status
- * - POST /api/workflows           - Receive workflows from HQ (upsert/additive)
- * - PUT  /api/workflows/:id       - Update a workflow (schedule, is_active)
- * - DELETE /api/workflows/:id     - Remove a workflow
- * - POST /api/workflows/trigger   - Manual trigger for a workflow
- * - GET  /api/executions          - List execution history
- * - GET  /api/executions/:id      - Get single execution details
- * - GET  /api/executions/:id/log  - Get execution log file content
+ * - GET  /api/workflows              - List all workflows with status
+ * - POST /api/workflows              - Receive workflows from HQ (upsert/additive)
+ * - POST /api/workflows/push/:name   - Push local workflow to HQ
+ * - POST /api/workflows/fetch/:name  - Fetch workflow from HQ and deploy locally
+ * - GET  /api/workflows/remote       - List workflows on HQ
+ * - PUT  /api/workflows/:id/schedule - Update a workflow schedule (cron_expression, is_active)
+ * - DELETE /api/workflows/:id        - Remove a workflow
+ * - POST /api/workflows/trigger      - Manual trigger for a workflow
+ * - GET  /api/executions             - List execution history
+ * - GET  /api/executions/:id         - Get single execution details
+ * - GET  /api/executions/:id/log     - Get execution log file content
  * - POST /api/executions/:id/outcome - Update execution outcome (no auth, local)
  */
 
+const fs = require('fs').promises
+const path = require('path')
+const os = require('os')
+
 const { verifyToken } = require('../lib/auth')
 const workflowRunner = require('../workflow-runner')
 const workflowStore = require('../workflow-store')
 const executionStore = require('../execution-store')
 const logManager = require('../lib/log-manager')
+const api = require('../api')
+const { isHqConfigured } = require('../config')
+const { writeSkillToLocal, pushSkillToHQ } = require('./skills')
 
 /**
  * Register workflow routes as Fastify plugin
@@ -93,8 +103,179 @@ async function workflowRoutes(fastify) {
     return { workflows: result }
   })
 
-  // Update a workflow (schedule, is_active)
-  fastify.put('/api/workflows/:id', async (request, reply) => {
+  // Push local workflow to HQ
+  fastify.post('/api/workflows/push/:name', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    if (!isHqConfigured()) {
+      reply.code(400)
+      return { success: false, error: 'HQ not configured' }
+    }
+
+    const { name } = request.params
+
+    if (!name || !/^[a-z0-9-]+$/.test(name)) {
+      reply.code(400)
+      return { success: false, error: 'Invalid workflow name' }
+    }
+
+    console.log(`[Workflows] Pushing workflow to HQ: ${name}`)
+
+    try {
+      const workflow = await workflowStore.findByName(name)
+      if (!workflow) {
+        reply.code(404)
+        return { success: false, error: `Local workflow not found: ${name}` }
+      }
+
+      const pipelineSkillNames = workflow.pipeline_skill_names || []
+
+      // Auto-push pipeline skills to HQ (ensures they exist before workflow push)
+      const skillsPushed = []
+      const skillsFailed = []
+      for (const skillName of pipelineSkillNames) {
+        try {
+          await pushSkillToHQ(skillName)
+          skillsPushed.push(skillName)
+          console.log(`[Workflows] Auto-pushed pipeline skill: ${skillName}`)
+        } catch (err) {
+          console.log(`[Workflows] Skill "${skillName}" not auto-pushed: ${err.message}`)
+          skillsFailed.push(skillName)
+        }
+      }
+
+      if (skillsFailed.length > 0) {
+        reply.code(400)
+        return {
+          success: false,
+          error: `Pipeline skills not found locally: ${skillsFailed.join(', ')}. Deploy them first with: minion-cli skill fetch <name>`,
+          skills_pushed: skillsPushed,
+        }
+      }
+
+      const result = await api.request('/workflows', {
+        method: 'POST',
+        body: JSON.stringify({
+          name: workflow.name,
+          pipeline_skill_names: pipelineSkillNames,
+          content: workflow.content || '',
+        }),
+      })
+
+      console.log(`[Workflows] Workflow pushed to HQ: ${name}`)
+      return { success: true, skills_pushed: skillsPushed, ...result }
+    } catch (error) {
+      console.error(`[Workflows] Failed to push workflow: ${error.message}`)
+      reply.code(error.statusCode || 500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // Fetch workflow from HQ and deploy locally
+  fastify.post('/api/workflows/fetch/:name', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    if (!isHqConfigured()) {
+      reply.code(400)
+      return { success: false, error: 'HQ not configured' }
+    }
+
+    const { name } = request.params
+
+    if (!name || !/^[a-z0-9-]+$/.test(name)) {
+      reply.code(400)
+      return { success: false, error: 'Invalid workflow name' }
+    }
+
+    console.log(`[Workflows] Fetching workflow from HQ: ${name}`)
+
+    try {
+      // 1. Fetch workflow definition from HQ
+      const workflow = await api.request(`/workflows/${encodeURIComponent(name)}`)
+
+      // 2. Fetch pipeline skills that are not deployed locally
+      const fetchedSkills = []
+      const homeDir = os.homedir()
+
+      for (const skillName of workflow.pipeline_skill_names || []) {
+        const skillMdPath = path.join(homeDir, '.claude', 'skills', skillName, 'SKILL.md')
+        let exists = false
+        try {
+          await fs.access(skillMdPath)
+          exists = true
+        } catch {
+          // Skill not deployed locally
+        }
+
+        if (!exists) {
+          console.log(`[Workflows] Fetching pipeline skill: ${skillName}`)
+          const skill = await api.request(`/skills/${encodeURIComponent(skillName)}`)
+          await writeSkillToLocal(skillName, {
+            content: skill.content,
+            description: skill.description,
+            display_name: skill.display_name,
+            references: skill.references || [],
+          })
+          fetchedSkills.push(skillName)
+        }
+      }
+
+      // 3. Save workflow to local store (upsert by name)
+      const updatedWorkflows = await workflowStore.upsertByName({
+        name: workflow.name,
+        pipeline_skill_names: workflow.pipeline_skill_names,
+        content: workflow.content || '',
+      })
+
+      // 4. Reload cron jobs
+      workflowRunner.loadWorkflows(updatedWorkflows)
+
+      console.log(`[Workflows] Workflow fetched: ${name} (${fetchedSkills.length} skills fetched)`)
+      return {
+        success: true,
+        message: `Workflow "${name}" fetched from HQ`,
+        skills_fetched: fetchedSkills,
+        pipeline: workflow.pipeline_skill_names,
+      }
+    } catch (error) {
+      console.error(`[Workflows] Failed to fetch workflow: ${error.message}`)
+      reply.code(error.statusCode || 500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // List workflows on HQ (remote)
+  fastify.get('/api/workflows/remote', async (request, reply) => {
+    if (!verifyToken(request)) {
+      reply.code(401)
+      return { success: false, error: 'Unauthorized' }
+    }
+
+    if (!isHqConfigured()) {
+      reply.code(400)
+      return { success: false, error: 'HQ not configured' }
+    }
+
+    console.log('[Workflows] Listing remote workflows from HQ')
+
+    try {
+      const result = await api.request('/workflows')
+      return result
+    } catch (error) {
+      console.error(`[Workflows] Failed to list remote workflows: ${error.message}`)
+      reply.code(error.statusCode || 500)
+      return { success: false, error: error.message }
+    }
+  })
+
+  // Update a workflow schedule (cron_expression, is_active)
+  fastify.put('/api/workflows/:id/schedule', async (request, reply) => {
     if (!verifyToken(request)) {
       reply.code(401)
       return { success: false, error: 'Unauthorized' }
@@ -103,7 +284,7 @@ async function workflowRoutes(fastify) {
     const { id } = request.params
     const updates = request.body || {}
 
-    console.log(`[Workflows] Updating workflow: ${id}`)
+    console.log(`[Workflows] Updating workflow schedule: ${id}`)
 
     try {
       const workflows = await workflowStore.load()

package/rules/minion.md

@@ -0,0 +1,195 @@
+# Minion Agent Environment
+
+You are running on a Minion VPS managed by the @geekbeer/minion package.
+A local Agent API server runs at `http://localhost:3001` and a CLI tool `minion-cli` is available.
+
+## CLI Commands
+
+```bash
+minion-cli status                         # Get current status (online/offline/busy)
+minion-cli health                         # Health check
+minion-cli set-status <status> [task]     # Set status and optional task description
+minion-cli skill push <name>              # Push local skill to HQ
+minion-cli skill fetch <name>             # Fetch skill from HQ to local
+minion-cli skill list                     # List skills on HQ
+minion-cli skill list --local             # List local deployed skills
+minion-cli --version                      # Show package version
+# Service management (requires sudo):
+# sudo minion-cli start | stop | restart
+```
+
+## Agent API Endpoints (http://localhost:3001)
+
+Authentication: `Authorization: Bearer $API_TOKEN` header (except where noted).
+
+### Health & Status (no auth required)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/health` | Health check (`{status:'ok', timestamp}`) |
+| GET | `/api/status` | Agent status, uptime, version, HQ connection |
+| POST | `/api/status` | Update status. Body: `{status, current_task}` |
+
+### Skills
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/list-skills` | List local deployed skills |
+| DELETE | `/api/skills/:name` | Delete local skill |
+| POST | `/api/skills/push/:name` | Push local skill to HQ |
+| POST | `/api/skills/fetch/:name` | Fetch skill from HQ and deploy locally |
+| GET | `/api/skills/remote` | List skills on HQ |
+
+### Workflows
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/workflows` | List all workflows with next_run |
+| POST | `/api/workflows` | Receive/upsert workflows from HQ |
+| POST | `/api/workflows/push/:name` | Push local workflow to HQ |
+| POST | `/api/workflows/fetch/:name` | Fetch workflow from HQ and deploy locally (+ pipeline skills) |
+| GET | `/api/workflows/remote` | List workflows on HQ |
+| PUT | `/api/workflows/:id/schedule` | Update workflow schedule (cron_expression, is_active) |
+| DELETE | `/api/workflows/:id` | Remove workflow |
+| POST | `/api/workflows/trigger` | Manual trigger. Body: `{workflow_id}` |
+
+### Executions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/executions` | List execution history (?limit=50) |
+| GET | `/api/executions/:id` | Get single execution |
+| GET | `/api/executions/:id/log` | Get execution log content |
+| POST | `/api/executions/:id/outcome` | Report outcome (no auth). Body: `{outcome}` |
+
+Outcome values: `success`, `failure`, `partial`
+
+### Terminal / tmux
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/terminal/sessions` | List tmux sessions |
+| POST | `/api/terminal/send` | Send keys. Body: `{session, keys}` |
+| POST | `/api/terminal/create` | Create session. Body: `{name, command?}` |
+| POST | `/api/terminal/kill` | Kill session. Body: `{session}` |
+| GET | `/api/terminal/capture` | Capture pane content. Query: `?session=` |
+| GET | `/api/terminal/ttyd/status` | ttyd process status |
+| POST | `/api/terminal/ttyd/start` | Start ttyd. Body: `{session}` |
+| POST | `/api/terminal/ttyd/stop` | Stop ttyd. Body: `{session}` |
+
+### Commands
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/commands` | List available whitelisted commands |
+| POST | `/api/command` | Execute command. Body: `{command}` |
+
+Available commands: `restart-agent`, `update-agent`, `restart-display`, `status-services`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HQ_URL` | HQ server URL (empty = standalone mode) |
+| `API_TOKEN` | Bearer token for HQ and local API auth |
+| `MINION_ID` | UUID assigned by HQ |
+| `AGENT_PORT` | Agent HTTP port (default: 3001) |
+| `MINION_USER` | System user running the agent |
+
+## Skills Directory Structure
+
+Skills are stored in `~/.claude/skills/<name>/`:
+
+```
+~/.claude/skills/<name>/
+  SKILL.md          # Skill definition (YAML frontmatter + markdown body)
+  references/       # Optional supporting files
+```
+
+SKILL.md format:
+```markdown
+---
+name: my-skill
+description: What this skill does
+---
+
+Skill instructions here...
+```
+
+## HQ Connection
+
+When `HQ_URL` and `API_TOKEN` are set, the agent sends heartbeats and syncs with HQ.
+Use `minion-cli skill push/fetch` to sync skills between local and HQ.
+Use the workflow API endpoints (`/api/workflows/push/:name`, `/api/workflows/fetch/:name`) to sync workflows.
+When not configured, the agent runs in standalone mode and HQ-dependent features return errors.
+
+## Workflow Structure
+
+Workflows are stored locally in `workflows.json`. Each workflow object:
+
+```json
+{
+  "id": "uuid",
+  "name": "my-workflow",
+  "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
+  "content": "Markdown description of the workflow",
+  "cron_expression": "0 9 * * 1-5",
+  "is_active": true,
+  "last_run": "2026-02-10T00:00:00.000Z"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | UUID (auto-generated) |
+| `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
+| `pipeline_skill_names` | string[] | Ordered skill names to execute |
+| `content` | string | Markdown body describing the workflow |
+| `cron_expression` | string | Cron schedule (empty = manual only) |
+| `is_active` | boolean | Whether cron scheduling is enabled |
+| `last_run` | string\|null | ISO timestamp of last execution |
+
+### Creating a workflow locally
+
+Use `POST /api/workflows` to create/update workflows:
+
+```bash
+curl -X POST http://localhost:3001/api/workflows \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "workflows": [{
+      "id": "'$(uuidgen)'",
+      "name": "my-workflow",
+      "pipeline_skill_names": ["my-skill", "execution-report"],
+      "content": "Description of what this workflow does",
+      "cron_expression": "",
+      "is_active": false
+    }]
+  }'
+```
+
+Then activate with a schedule:
+
+```bash
+curl -X PUT http://localhost:3001/api/workflows/<id>/schedule \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"cron_expression": "0 9 * * 1-5", "is_active": true}'
+```
+
+### Syncing workflows with HQ
+
+- `POST /api/workflows/push/:name` — Push local workflow to HQ. Pipeline skills are auto-pushed first.
+- `POST /api/workflows/fetch/:name` — Fetch workflow from HQ. Missing pipeline skills are auto-fetched.
+- `GET /api/workflows/remote` — List workflows available on HQ.
+
+Pipeline skills must be deployed locally (in `~/.claude/skills/`) before pushing a workflow.
+
+## Workflow Execution
+
+Workflows run on cron schedules. Each execution:
+1. Creates a tmux session
+2. Runs skills in pipeline order via `claude --dangerously-skip-permissions`
+3. Appends `execution-report` skill to report outcome
+4. Environment variables `MINION_EXECUTION_ID`, `MINION_WORKFLOW_ID`, `MINION_WORKFLOW_NAME` are available during execution

package/server.js

@@ -5,6 +5,10 @@
  * See routes/index.js for API documentation.
  */
 
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
 const fastify = require('fastify')({ logger: true })
 const { config, validate, isHqConfigured } = require('./config')
 const workflowRunner = require('./workflow-runner')
@@ -42,9 +46,96 @@ async function shutdown(signal) {
 process.on('SIGTERM', () => shutdown('SIGTERM'))
 process.on('SIGINT', () => shutdown('SIGINT'))
 
+/**
+ * Sync bundled permissions into ~/.claude/settings.json.
+ * Merges package-defined allow/deny into the existing settings without
+ * removing user-added entries or non-permission keys (e.g. mcpServers).
+ */
+function syncPermissions() {
+  const bundledPath = path.join(__dirname, 'settings', 'permissions.json')
+  const settingsDir = path.join(os.homedir(), '.claude')
+  const settingsPath = path.join(settingsDir, 'settings.json')
+
+  try {
+    if (!fs.existsSync(bundledPath)) return
+
+    const bundled = JSON.parse(fs.readFileSync(bundledPath, 'utf-8'))
+
+    // Read existing settings or start fresh
+    let settings = {}
+    if (fs.existsSync(settingsPath)) {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'))
+    }
+
+    // Replace permissions section with bundled values
+    settings.permissions = {
+      allow: bundled.allow || [],
+      deny: bundled.deny || [],
+    }
+
+    fs.mkdirSync(settingsDir, { recursive: true })
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8')
+    console.log(`[Permissions] Synced: allow=${bundled.allow.length}, deny=${bundled.deny.length}`)
+  } catch (err) {
+    console.error(`[Permissions] Failed to sync permissions: ${err.message}`)
+  }
+}
+
+/**
+ * Sync bundled tmux.conf to ~/.tmux.conf.
+ * Enables mouse-driven scrollback (copy-mode) for the WebSocket terminal.
+ */
+function syncTmuxConfig() {
+  const bundledPath = path.join(__dirname, 'settings', 'tmux.conf')
+  const destPath = path.join(os.homedir(), '.tmux.conf')
+
+  try {
+    if (!fs.existsSync(bundledPath)) return
+
+    fs.copyFileSync(bundledPath, destPath)
+    console.log('[Tmux] Synced tmux.conf')
+  } catch (err) {
+    console.error(`[Tmux] Failed to sync tmux.conf: ${err.message}`)
+  }
+}
+
+/**
+ * Sync bundled rules from the package to ~/.claude/rules/.
+ * Runs on every server start to ensure rules stay up-to-date after package updates.
+ */
+function syncBundledRules() {
+  const bundledRulesDir = path.join(__dirname, 'rules')
+  const targetRulesDir = path.join(os.homedir(), '.claude', 'rules')
+
+  try {
+    if (!fs.existsSync(bundledRulesDir)) return
+
+    fs.mkdirSync(targetRulesDir, { recursive: true })
+
+    for (const file of fs.readdirSync(bundledRulesDir)) {
+      if (!file.endsWith('.md')) continue
+      const src = path.join(bundledRulesDir, file)
+      const dest = path.join(targetRulesDir, file)
+      fs.copyFileSync(src, dest)
+      console.log(`[Rules] Synced: ${file}`)
+    }
+  } catch (err) {
+    console.error(`[Rules] Failed to sync bundled rules: ${err.message}`)
+  }
+}
+
 // Start server
 async function start() {
   try {
+    // Sync bundled rules to ~/.claude/rules/ (keeps rules fresh after package updates)
+    syncBundledRules()
+
+    // Sync bundled permissions to ~/.claude/settings.json (broad allow + deny-list)
+    syncPermissions()
+
+    // Sync tmux.conf for mouse scroll support in WebSocket terminal
+    syncTmuxConfig()
+
     // Register all routes
     await registerRoutes(fastify)
 

package/settings/permissions.json

@@ -0,0 +1,17 @@
+{
+  "allow": [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "mcp__playwright__*"
+  ],
+  "deny": [
+    "Bash(sudo *)",
+    "Bash(git push --force*)",
+    "Bash(git push -f *)",
+    "Bash(git reset --hard*)",
+    "Bash(git clean -f*)",
+    "Bash(dd *)"
+  ]
+}

package/settings/tmux.conf

@@ -0,0 +1,16 @@
+# Minion tmux configuration
+# Enables mouse scroll → copy-mode for WebSocket terminal scrollback
+
+# Enable mouse support (click, drag, scroll)
+set -g mouse on
+
+# Scrollback buffer size (lines)
+set -g history-limit 10000
+
+# Mouse wheel up: enter copy-mode if not already in it,
+# otherwise forward the event (for nested mouse-aware apps)
+bind -n WheelUpPane if-shell -F -t = "#{mouse_any_flag}" "send-keys -M" "if -Ft= '#{pane_in_mode}' 'send-keys -M' 'copy-mode -e'"
+
+# Scroll 1 line per wheel tick (default is 5)
+bind -T copy-mode WheelUpPane send-keys -X -N 1 scroll-up
+bind -T copy-mode WheelDownPane send-keys -X -N 1 scroll-down

package/workflow-store.js

@@ -68,4 +68,48 @@ async function updateLastRun(workflowId) {
   }
 }
 
-module.exports = { load, save, updateLastRun }
+/**
+ * Find a workflow by name
+ * @param {string} name - Workflow name (slug)
+ * @returns {Promise<object|null>} Workflow object or null
+ */
+async function findByName(name) {
+  const workflows = await load()
+  return workflows.find(w => w.name === name) || null
+}
+
+/**
+ * Upsert a workflow by name.
+ * If exists: updates definition only (preserves schedule/local state).
+ * If new: creates with inactive schedule.
+ * @param {object} workflowData - { name, pipeline_skill_names, content }
+ * @returns {Promise<Array>} Updated workflows array
+ */
+async function upsertByName(workflowData) {
+  const crypto = require('crypto')
+  const workflows = await load()
+  const index = workflows.findIndex(w => w.name === workflowData.name)
+
+  if (index >= 0) {
+    // Update definition only (preserve schedule/local state)
+    workflows[index].pipeline_skill_names = workflowData.pipeline_skill_names
+    if (workflowData.content !== undefined) {
+      workflows[index].content = workflowData.content
+    }
+  } else {
+    workflows.push({
+      id: crypto.randomUUID(),
+      name: workflowData.name,
+      pipeline_skill_names: workflowData.pipeline_skill_names,
+      content: workflowData.content || '',
+      cron_expression: '',
+      is_active: false,
+      last_run: null,
+    })
+  }
+
+  await save(workflows)
+  return workflows
+}
+
+module.exports = { load, save, updateLastRun, findByName, upsertByName }