@poolzin/pool-bot 2026.1.29 → 2026.1.30

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## v1.0.1 (2026-02-02)
+
+### WhatsApp Gateway Stability
+- Add comprehensive WhatsApp heartbeat troubleshooting guide
+- Document watchdog timeout and reconnection behavior
+- Add configuration validation best practices
+- Document professional incident response workflow
+
+### Configuration
+- Document `web.heartbeatSeconds` override option
+- Clarify `web.reconnect` schema and valid keys
+- Add examples for timeout tuning (30min → 60min → 90min)
+- Provide production-ready configuration templates
+
+### Documentation
+- New: `docs/WHATSAPP-HEARTBEAT-TROUBLESHOOTING.md`
+- Incident analysis: Gateway timeout recovery
+- Lesson learned: Config validation before deployment
+- Professional validation checklist included
+
+### Reliability
+- Improved gateway recovery documentation
+- Added monitoring and diagnostic commands
+- Documented false-positive reduction strategies
+- Best practices for different environments (prod/dev/test)
+
+---
+
 ## v1.0.0 (2026-01-28)
 
 ### Security Release
@@ -57,4 +85,4 @@
 - Migrated from Moltbot core
 - Implemented workspace-based development
 - Added dual model system configuration
-- Created persistent configuration system
+- Created persistent configuration system

package/README.md

@@ -59,6 +59,17 @@ Pool Bot supports an extensible skills system:
 - 🐦 **X/Twitter** - Social media engagement
 - And more...
 
+See [skills directory](skills/) for the full list.
+
+## Companion Apps
+
+Official companion apps for connecting devices to your Pool Bot gateway:
+
+- **[Pool Apps](https://github.com/plcunha/pool-apps)** - Windows, Android, iOS nodes
+  - 🪟 **Windows Node v2** (Python) - Local LLM, STT/TTS, automation
+  - 📱 **Android** - Native mobile app
+  - 🍎 **iOS/macOS** - Apple ecosystem apps
+
 ## Configuration
 
 Pool Bot uses a profile-based configuration system:

package/dist/agents/system-prompt.js

@@ -59,7 +59,7 @@ function buildMessagingSection(params) {
         "## Messaging",
         "- Reply in current session → automatically routes to the source channel (Signal, Telegram, etc.)",
         "- Cross-session messaging → use sessions_send(sessionKey, message)",
-        "- Never use exec/curl for provider messaging; Moltbot handles all routing internally.",
+        "- Never use exec/curl for provider messaging; Pool Bot handles all routing internally.",
         params.availableTools.has("message")
             ? [
                 "",
@@ -95,12 +95,12 @@ function buildDocsSection(params) {
         return [];
     return [
         "## Documentation",
-        `Moltbot docs: ${docsPath}`,
-        "Mirror: https://docs.molt.bot",
-        "Source: https://github.com/poolbot/poolbot",
+        `Pool Bot docs: ${docsPath}`,
+        "Mirror: https://docs.poolbot.dev",
+        "Source: https://github.com/poolzin/pool-bot",
         "Community: https://discord.com/discord.gg/poolbot",
-        "Find new skills: https://clawdhub.com",
-        "For Moltbot behavior, commands, config, or architecture: consult local docs first.",
+        "Find new skills: https://poolhub.com",
+        "For Pool Bot behavior, commands, config, or architecture: consult local docs first.",
         "When diagnosing issues, run `poolbot status` yourself when possible; only ask the user if you lack access (e.g., sandboxed).",
         "",
     ];
@@ -124,7 +124,7 @@ export function buildAgentSystemPrompt(params) {
         nodes: "List/describe/notify/camera/screen on paired nodes",
         cron: "Manage cron jobs and wake events (use for reminders; when scheduling a reminder, write the systemEvent text as something that will read like a reminder when it fires, and mention that it is a reminder depending on the time gap between setting and firing; include recent context in reminder text if appropriate)",
         message: "Send messages and channel actions",
-        gateway: "Restart, apply config, or run updates on the running Moltbot process",
+        gateway: "Restart, apply config, or run updates on the running Pool Bot process",
         agents_list: "List agent ids allowed for sessions_spawn",
         sessions_list: "List other sessions (incl. sub-agents) with filters/last",
         sessions_history: "Fetch history for another session/sub-agent",
@@ -242,10 +242,10 @@ export function buildAgentSystemPrompt(params) {
     const workspaceNotes = (params.workspaceNotes ?? []).map((note) => note.trim()).filter(Boolean);
     // For "none" mode, return just the basic identity line
     if (promptMode === "none") {
-        return "You are a personal assistant running inside Moltbot.";
+        return "You are a personal assistant running inside Pool Bot.";
     }
     const lines = [
-        "You are a personal assistant running inside Moltbot.",
+        "You are a personal assistant running inside Pool Bot.",
         "",
         "## Tooling",
         "Tool availability (filtered by policy):",
@@ -260,7 +260,7 @@ export function buildAgentSystemPrompt(params) {
                 "- apply_patch: apply multi-file patches",
                 `- ${execToolName}: run shell commands (supports background via yieldMs/background)`,
                 `- ${processToolName}: manage background exec sessions`,
-                "- browser: control clawd's dedicated browser",
+                "- browser: control Pool Bot's dedicated browser",
                 "- canvas: present/eval/snapshot the Canvas",
                 "- nodes: list/describe/notify/camera/screen on paired nodes",
                 "- cron: manage cron jobs and wake events (use for reminders; when scheduling a reminder, write the systemEvent text as something that will read like a reminder when it fires, and mention that it is a reminder depending on the time gap between setting and firing; include recent context in reminder text if appropriate)",
@@ -277,8 +277,8 @@ export function buildAgentSystemPrompt(params) {
         "Keep narration brief and value-dense; avoid repeating obvious steps.",
         "Use plain human language for narration unless in a technical context.",
         "",
-        "## Moltbot CLI Quick Reference",
-        "Moltbot is controlled via subcommands. Do not invent commands.",
+        "## Pool Bot CLI Quick Reference",
+        "Pool Bot is controlled via subcommands. Do not invent commands.",
         "To manage the Gateway daemon service (start/stop/restart):",
         "- poolbot gateway status",
         "- poolbot gateway start",
@@ -289,13 +289,13 @@ export function buildAgentSystemPrompt(params) {
         ...skillsSection,
         ...memorySection,
         // Skip self-update for subagent/none modes
-        hasGateway && !isMinimal ? "## Moltbot Self-Update" : "",
+        hasGateway && !isMinimal ? "## Pool Bot Self-Update" : "",
         hasGateway && !isMinimal
             ? [
                 "Get Updates (self-update) is ONLY allowed when the user explicitly asks for it.",
                 "Do not run config.apply or update.run unless the user explicitly requests an update or config change; if it's not explicit, ask first.",
                 "Actions: config.get, config.schema, config.apply (validate + write full config, then restart), update.run (update deps or git, then restart).",
-                "After restart, Moltbot pings the last active session automatically.",
+                "After restart, Pool Bot pings the last active session automatically.",
             ].join("\n")
             : "",
         hasGateway && !isMinimal ? "" : "",
@@ -362,7 +362,7 @@ export function buildAgentSystemPrompt(params) {
             userTimezone,
         }),
         "## Workspace Files (injected)",
-        "These user-editable files are loaded by Moltbot and included below in Project Context.",
+        "These user-editable files are loaded by Pool Bot and included below in Project Context.",
         "",
         ...buildReplyTagsSection(isMinimal),
         ...buildMessagingSection({
@@ -427,7 +427,7 @@ export function buildAgentSystemPrompt(params) {
     }
     // Skip heartbeats for subagent/none modes
     if (!isMinimal) {
-        lines.push("## Heartbeats", heartbeatPromptLine, "If you receive a heartbeat poll (a user message matching the heartbeat prompt above), and there is nothing that needs attention, reply exactly:", "HEARTBEAT_OK", 'Moltbot treats a leading/trailing "HEARTBEAT_OK" as a heartbeat ack (and may discard it).', 'If something needs attention, do NOT include "HEARTBEAT_OK"; reply with the alert text instead.', "");
+        lines.push("## Heartbeats", heartbeatPromptLine, "If you receive a heartbeat poll (a user message matching the heartbeat prompt above), and there is nothing that needs attention, reply exactly:", "HEARTBEAT_OK", 'Pool Bot treats a leading/trailing "HEARTBEAT_OK" as a heartbeat ack (and may discard it).', 'If something needs attention, do NOT include "HEARTBEAT_OK"; reply with the alert text instead.', "");
     }
     lines.push("## Runtime", buildRuntimeLine(runtimeInfo, runtimeChannel, runtimeCapabilities, params.defaultThinkLevel), `Reasoning: ${reasoningLevel} (hidden unless on/stream). Toggle /reasoning; /status shows Reasoning when enabled.`);
     return lines.filter(Boolean).join("\n");

package/dist/agents/tools/memory-tool.js

@@ -32,6 +32,7 @@ export function createMemorySearchTool(options) {
             const query = readStringParam(params, "query", { required: true });
             const maxResults = readNumberParam(params, "maxResults");
             const minScore = readNumberParam(params, "minScore");
+            // Legacy memory search system (PME removed 2026-02-03)
             const { manager, error } = await getMemorySearchManager({
                 cfg,
                 agentId,
@@ -55,7 +56,7 @@ export function createMemorySearchTool(options) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                return jsonResult({ results: [], disabled: true, error: message });
+                return jsonResult({ results: [], error: message });
             }
         },
     };

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026.1.29",
-  "commit": "af438fee8e9b7318099bc741e887ff95b612fbca",
-  "builtAt": "2026-01-29T15:51:40.214Z"
+  "version": "2026.1.30",
+  "commit": "f991fb36d2821d852ed4bbeb0fe411140d236bd4",
+  "builtAt": "2026-02-04T14:14:13.069Z"
 }

package/dist/cli/program/command-registry.js

@@ -8,6 +8,7 @@ import { registerBrowserCli } from "../browser-cli.js";
 import { registerConfigCli } from "../config-cli.js";
 import { registerMemoryCli, runMemoryStatus } from "../memory-cli.js";
 import { registerAgentCommands } from "./register.agent.js";
+import { registerCompletionCommand } from "./register.completion.js";
 import { registerConfigureCommand } from "./register.configure.js";
 import { registerMaintenanceCommands } from "./register.maintenance.js";
 import { registerMessageCommands } from "./register.message.js";
@@ -94,6 +95,10 @@ export const commandRegistry = [
         id: "configure",
         register: ({ program }) => registerConfigureCommand(program),
     },
+    {
+        id: "completion",
+        register: ({ program }) => registerCompletionCommand(program),
+    },
     {
         id: "config",
         register: ({ program }) => registerConfigCli(program),

package/dist/cli/program/register.completion.js

@@ -0,0 +1,355 @@
+import fs from "node:fs";
+import path from "node:path";
+function getBashTemplate(name) {
+    return [
+        "# Bash completion for " + name,
+        "# Installation: " + name + " completion --shell bash > /etc/bash_completion.d/" + name,
+        "#               or source it in ~/.bashrc: source <(" + name + " completion --shell bash)",
+        "",
+        "_" + name + "_completion() {",
+        "    local cur prev words cword",
+        "    _init_completion || return",
+        '    local opts="--help --version --shell --output"',
+        '    local commands="setup configure status health sessions memory agents gateway node message browser channels pairing cron version completion"',
+        "",
+        "    if [[ ${cur} == -* ]]; then",
+        '        COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )',
+        "        return 0",
+        "    fi",
+        "",
+        "    if [[ ${cword} -eq 1 ]]; then",
+        '        COMPREPLY=( $(compgen -W "${commands}" -- "${cur}") )',
+        "        return 0",
+        "    fi",
+        "",
+        "    # Command-specific completions",
+        '    local cmd="${words[1]}"',
+        '    case "${cmd}" in',
+        "        status)",
+        '            COMPREPLY=( $(compgen -W "--json --deep --all --usage --timeout --verbose" -- "${cur}") )',
+        "            ;;",
+        "        sessions)",
+        '            COMPREPLY=( $(compgen -W "--json --store --active" -- "${cur}") )',
+        "            ;;",
+        "        agents)",
+        '            COMPREPLY=( $(compgen -W "list spawn send history status --json --bindings" -- "${cur}") )',
+        "            ;;",
+        "        memory)",
+        '            COMPREPLY=( $(compgen -W "status search --agent --json --deep --index --verbose" -- "${cur}") )',
+        "            ;;",
+        "        gateway)",
+        '            COMPREPLY=( $(compgen -W "status start restart stop config update --help" -- "${cur}") )',
+        "            ;;",
+        "        message)",
+        '            COMPREPLY=( $(compgen -W "send poll react --channel --to --help" -- "${cur}") )',
+        "            ;;",
+        "        channels)",
+        '            COMPREPLY=( $(compgen -W "add status list --help" -- "${cur}") )',
+        "            ;;",
+        "        cron)",
+        '            COMPREPLY=( $(compgen -W "status list add update remove run wake --help" -- "${cur}") )',
+        "            ;;",
+        "        *)",
+        "            ;;",
+        "    esac",
+        "}",
+        "",
+        "complete -F _" + name + "_completion " + name,
+    ].join("\n");
+}
+function getZshTemplate(name) {
+    return [
+        "#compdef " + name,
+        "# Zsh completion for " + name,
+        "# Installation: " +
+            name +
+            " completion --shell zsh > /usr/local/share/zsh/site-functions/_" +
+            name,
+        "#               or ~/.zsh/completion/_" + name,
+        "#               then add: autoload -U compinit && compinit",
+        "",
+        "_" + name + "() {",
+        "    local -a commands",
+        "    commands=(",
+        "        'setup:Run initial setup wizard'",
+        "        'configure:Configure settings'",
+        "        'status:Show system status'",
+        "        'health:Run health check'",
+        "        'sessions:Manage sessions'",
+        "        'memory:Manage memory and knowledge'",
+        "        'agents:Manage AI agents'",
+        "        'gateway:Control gateway daemon'",
+        "        'node:Manage paired nodes'",
+        "        'message:Send messages'",
+        "        'channels:Manage channels'",
+        "        'pairing:Manage pairing requests'",
+        "        'cron:Manage cron jobs'",
+        "        'browser:Control browser'",
+        "        'version:Show version'",
+        "        'completion:Generate shell completion'",
+        "    )",
+        "",
+        "    if [[ ${words[2]} == status ]]; then",
+        "        _arguments -C \\",
+        "            '--deep[Show detailed status]' \\",
+        "            '--all[Show all information]' \\",
+        "            '--usage[Show usage statistics]' \\",
+        "            '--timeout[Timeout in milliseconds]' \\",
+        "            '--help[Show help]' \\",
+        "            '--verbose[Enable verbose output]' \\",
+        "            '--json[Output JSON format]'",
+        "    elif [[ ${words[2]} == sessions ]]; then",
+        "        _arguments -C \\",
+        "            '--store[Session store path]' \\",
+        "            '--active[Show active sessions only]' \\",
+        "            '--help[Show help]' \\",
+        "            '--verbose[Enable verbose output]' \\",
+        "            '--json[Output JSON format]'",
+        "    elif [[ ${words[2]} == agents ]]; then",
+        "        _alternative \\",
+        "            'commands::commands:(list spawn send history status)' \\",
+        "            '--bindings[Show model bindings]' \\",
+        "            '--help[Show help]' \\",
+        "            '--verbose[Enable verbose output]' \\",
+        "            '--json[Output JSON format]'",
+        "    elif [[ ${words[2]} == memory ]]; then",
+        "        _alternative \\",
+        "            'commands::commands:(status search)' \\",
+        "            '--agent[Agent ID]' \\",
+        "            '--deep[Deep scan]' \\",
+        "            '--index[Rebuild index]' \\",
+        "            '--help[Show help]' \\",
+        "            '--verbose[Enable verbose output]' \\",
+        "            '--json[Output JSON format]'",
+        "    elif [[ ${words[2]} == gateway ]]; then",
+        "        _alternative \\",
+        "            'commands::commands:(status start restart stop config update)' \\",
+        "            '--help[Show help]'",
+        "    elif [[ ${words[2]} == message ]]; then",
+        "        _alternative \\",
+        "            'commands::commands:(send poll react)' \\",
+        "            '--channel[Channel ID]' \\",
+        "            '--to[Recipient]' \\",
+        "            '--help[Show help]'",
+        "    elif [[ ${words[2]} == channels ]]; then",
+        "        _alternative \\",
+        "            'commands::commands:(add status list)' \\",
+        "            '--help[Show help]'",
+        "    elif [[ ${words[2]} == cron ]]; then",
+        "        _alternative \\",
+        "            'commands::commands:(status list add update remove run wake)' \\",
+        "            '--help[Show help]'",
+        "    else",
+        "        _describe -V commands commands",
+        "        _arguments -C \\",
+        "            '(-h --help)'{-h,--help}'[Show help]' \\",
+        "            '(-v --verbose)'{-v,--verbose}'[Enable verbose output]' \\",
+        "            '--json[Output JSON format]'",
+        "    fi",
+        "}",
+        "",
+        "_" + name + ' "$@"',
+    ].join("\n");
+}
+function getFishTemplate(name) {
+    return [
+        "# Fish completion for " + name,
+        "# Installation: " +
+            name +
+            " completion --shell fish > ~/.config/fish/completions/" +
+            name +
+            ".fish",
+        "",
+        "complete -c " + name + " -f",
+        "",
+        "# Commands",
+        "complete -c " + name + " -n __fish_use_subcommand -a setup -d 'Run initial setup wizard'",
+        "complete -c " + name + " -n __fish_use_subcommand -a configure -d 'Configure settings'",
+        "complete -c " + name + " -n __fish_use_subcommand -a status -d 'Show system status'",
+        "complete -c " + name + " -n __fish_use_subcommand -a health -d 'Run health check'",
+        "complete -c " + name + " -n __fish_use_subcommand -a sessions -d 'Manage sessions'",
+        "complete -c " + name + " -n __fish_use_subcommand -a memory -d 'Manage memory and knowledge'",
+        "complete -c " + name + " -n __fish_use_subcommand -a agents -d 'Manage AI agents'",
+        "complete -c " + name + " -n __fish_use_subcommand -a gateway -d 'Control gateway daemon'",
+        "complete -c " + name + " -n __fish_use_subcommand -a node -d 'Manage paired nodes'",
+        "complete -c " + name + " -n __fish_use_subcommand -a message -d 'Send messages'",
+        "complete -c " + name + " -n __fish_use_subcommand -a channels -d 'Manage channels'",
+        "complete -c " + name + " -n __fish_use_subcommand -a pairing -d 'Manage pairing requests'",
+        "complete -c " + name + " -n __fish_use_subcommand -a cron -d 'Manage cron jobs'",
+        "complete -c " + name + " -n __fish_use_subcommand -a browser -d 'Control browser'",
+        "complete -c " + name + " -n __fish_use_subcommand -a version -d 'Show version'",
+        "complete -c " +
+            name +
+            " -n __fish_use_subcommand -a completion -d 'Generate shell completion'",
+        "",
+        "# Global options",
+        "complete -c " + name + " -s h -l help -d 'Show help'",
+        "complete -c " + name + " -s v -l verbose -d 'Enable verbose output'",
+        "complete -c " + name + " -l json -d 'Output JSON format'",
+        "",
+        "# Command: status",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from status' -l deep -d 'Show detailed status'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from status' -l all -d 'Show all information'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from status' -l usage -d 'Show usage statistics'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from status' -l timeout -d 'Timeout in milliseconds'",
+        "",
+        "# Command: sessions",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from sessions' -l store -d 'Session store path'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from sessions' -l active -d 'Show active sessions only'",
+        "",
+        "# Command: agents",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from agents' -a list -d 'List available agents'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from agents' -a spawn -d 'Spawn a new agent'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from agents' -a send -d 'Send message to agent'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from agents' -a history -d 'Show agent history'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from agents' -a status -d 'Show agent status'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from agents' -l bindings -d 'Show model bindings'",
+        "",
+        "# Command: memory",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from memory' -a status -d 'Show memory status'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from memory' -a search -d 'Search memory'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from memory' -l agent -d 'Agent ID'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from memory' -l deep -d 'Deep scan'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from memory' -l index -d 'Rebuild index'",
+        "",
+        "# Command: gateway",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from gateway' -a status -d 'Show gateway status'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from gateway' -a start -d 'Start gateway'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from gateway' -a restart -d 'Restart gateway'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from gateway' -a stop -d 'Stop gateway'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from gateway' -a config -d 'Manage config'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from gateway' -a update -d 'Update gateway'",
+        "",
+        "# Command: message",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from message' -a send -d 'Send message'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from message' -a poll -d 'Create poll'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from message' -a react -d 'Add reaction'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from message' -l channel -d 'Channel ID'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from message' -l to -d 'Recipient'",
+        "",
+        "# Command: channels",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from channels' -a add -d 'Add channel'",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from channels' -a status -d 'Show channel status'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from channels' -a list -d 'List channels'",
+        "",
+        "# Command: cron",
+        "complete -c " +
+            name +
+            " -n '__fish_seen_subcommand_from cron' -a status -d 'Show cron status'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from cron' -a list -d 'List cron jobs'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from cron' -a add -d 'Add cron job'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from cron' -a update -d 'Update cron job'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from cron' -a remove -d 'Remove cron job'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from cron' -a run -d 'Run cron job'",
+        "complete -c " + name + " -n '__fish_seen_subcommand_from cron' -a wake -d 'Send wake event'",
+    ].join("\n");
+}
+export function registerCompletionCommand(program) {
+    const binaryName = path.basename(process.argv[1] ?? "poolbot", ".js");
+    program
+        .command("completion")
+        .description("Generate shell completion script")
+        .option("--shell <type>", "Shell type (bash, zsh, fish)", "bash")
+        .option("--output <path>", "Write to file instead of stdout")
+        .action((options) => {
+        const { shell, output } = options;
+        let script;
+        if (shell === "bash") {
+            script = getBashTemplate(binaryName);
+        }
+        else if (shell === "zsh") {
+            script = getZshTemplate(binaryName);
+        }
+        else if (shell === "fish") {
+            script = getFishTemplate(binaryName);
+        }
+        else {
+            console.error("Unsupported shell: " + shell);
+            console.error("Supported shells: bash, zsh, fish");
+            process.exit(1);
+        }
+        if (output) {
+            try {
+                const outputPath = path.resolve(output);
+                fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+                fs.writeFileSync(outputPath, script, "utf-8");
+                console.log("✅ Completion script written to: " + outputPath);
+                console.log("\n📝 Installation instructions:");
+                printInstallInstructions(shell, outputPath, binaryName);
+            }
+            catch (err) {
+                console.error("❌ Failed to write completion script: " + err);
+                process.exit(1);
+            }
+        }
+        else {
+            console.log(script);
+        }
+    });
+}
+function printInstallInstructions(shell, outputPath, binaryName) {
+    const instructions = {
+        bash: [
+            "# Add to ~/.bashrc or run:",
+            "source " + outputPath,
+            "",
+            "# Or system-wide (requires root):",
+            "sudo cp " + outputPath + " /etc/bash_completion.d/" + binaryName,
+        ],
+        zsh: [
+            "# Add to ~/.zshrc:",
+            "fpath=(" + path.dirname(outputPath) + " $fpath)",
+            "autoload -U compinit && compinit",
+            "",
+            "# Or copy to system location:",
+            "sudo cp " + outputPath + " /usr/local/share/zsh/site-functions/_" + binaryName,
+        ],
+        fish: [
+            "# Fish will automatically load completions from:",
+            "# " + outputPath,
+            "",
+            "# Just restart your shell or run:",
+            "source " + outputPath,
+        ],
+    };
+    const lines = instructions[shell] || [];
+    if (lines.length > 0) {
+        console.log(lines.join("\n"));
+    }
+}

package/dist/gateway/hooks/index.js

@@ -0,0 +1,53 @@
+/**
+ * Gateway Hooks Module
+ *
+ * Exports all hook-related functionality for easy importing
+ *
+ * @example
+ * ```ts
+ * import { registerHooks, triggerHook } from "./gateway/hooks/index.js";
+ * ```
+ */
+// Core lifecycle hooks
+export { 
+// Feature flags
+LIFECYCLE_HOOKS_ENABLED, HOOK_DEBUG_MODE, 
+// Registration
+registerHooks, unregisterHooks, getHooks, hasHooks, getRegisteredSessionKeys, 
+// Triggering
+triggerHook, 
+// Stats
+getRegistryStats, 
+// Default hooks
+defaultOnSessionStart, defaultOnSessionEnd, registerDefaultHooks, 
+// Utilities
+clearAllHooks, } from "./lifecycle-hooks.js";
+// Integration with agent events
+export { startLifecycleHooksIntegration, getIntegrationStats, isSessionTracked, getTrackedSessionInfo, clearTrackedSessions, removeTrackedSession, } from "./lifecycle-hooks-integration.js";
+// Tool usage capture (Day 2 - to be implemented)
+// export {
+//   toolUsageCaptureHook,
+//   loadSessionToolUsage,
+//   saveSessionToolUsage,
+// } from "./tool-usage-capture.js";
+// Progressive disclosure (Day 3 - PHASE 5 COMPLETE - FEATURE FLAGGED, OPT-IN)
+// export {
+//   memory_search_v2,
+//   searchIndex,
+//   searchTimeline,
+//   searchDetails,
+//   clearProgressiveDisclosureCache,
+//   resetProgressiveDisclosure,
+//   getProgressiveDisclosureStats,
+//   PROGRESSIVE_DISCLOSURE_ENABLED,
+//   type MemorySearchResultV2,
+//   type SearchResult,
+//   type TimelineEntry,
+//   type MemoryDetail,
+//   type SearchMetadata,
+//   type SearchLayer,
+//   type MemorySearchOptions,
+//   type QueryFilter,
+//   type SearchResultOrError,
+//   type SearchError,
+// } from "./progressive-disclosure.js";