@gmickel/gno 0.9.2 → 0.9.3

package/README.md

@@ -295,7 +295,7 @@ graph TD
 1. **Query Expansion**: LLM generates lexical variants, semantic rephrases, and a [HyDE](https://arxiv.org/abs/2212.10496) passage
 2. **Parallel Retrieval**: Document-level BM25 + chunk-level vector search on all variants
 3. **Fusion**: RRF with 2× weight for original query, tiered bonus for top ranks
-4. **Reranking**: Qwen3-Reranker scores full documents (32K context), blended with fusion
+4. **Reranking**: Qwen3-Reranker scores best chunk per document (4K), blended with fusion
 
 > **Deep dive**: [How Search Works](https://gno.sh/docs/HOW-SEARCH-WORKS/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/src/cli/commands/completion/completion.ts

@@ -0,0 +1,201 @@
+/**
+ * Shell completion commands - output scripts or auto-install.
+ *
+ * @module src/cli/commands/completion/completion
+ */
+
+// node:fs/promises - no Bun equivalent for mkdir/appendFile/writeFile
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { CLI_NAME } from "../../../app/constants.js";
+import { CliError } from "../../errors.js";
+import {
+  getCompletionScript,
+  SUPPORTED_SHELLS,
+  type Shell,
+} from "./scripts.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface OutputOptions {
+  shell: Shell;
+}
+
+export interface InstallOptions {
+  /** Override shell detection */
+  shell?: Shell;
+  /** JSON output */
+  json?: boolean;
+}
+
+interface InstallResult {
+  shell: Shell;
+  path: string;
+  action: "installed" | "already_installed";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shell Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Detect user's current shell.
+ */
+function detectShell(): Shell | undefined {
+  // Check $SHELL env
+  const shellEnv = process.env.SHELL || "";
+  if (shellEnv.includes("zsh")) return "zsh";
+  if (shellEnv.includes("bash")) return "bash";
+  if (shellEnv.includes("fish")) return "fish";
+
+  // Check parent process name on Unix
+  // This is less reliable but can help
+  const parentName = process.env._ || "";
+  if (parentName.includes("zsh")) return "zsh";
+  if (parentName.includes("bash")) return "bash";
+  if (parentName.includes("fish")) return "fish";
+
+  return undefined;
+}
+
+/**
+ * Get the appropriate rc file for a shell.
+ */
+function getShellRcPath(shell: Shell): string {
+  const home = homedir();
+  switch (shell) {
+    case "bash":
+      // Prefer .bashrc, but .bash_profile on macOS
+      return process.platform === "darwin"
+        ? join(home, ".bash_profile")
+        : join(home, ".bashrc");
+    case "zsh":
+      return join(home, ".zshrc");
+    case "fish":
+      return join(home, ".config", "fish", "completions", `${CLI_NAME}.fish`);
+  }
+}
+
+/**
+ * Check if completion is already installed.
+ */
+async function isCompletionInstalled(shell: Shell): Promise<boolean> {
+  const path = getShellRcPath(shell);
+
+  // For fish, check if file exists
+  if (shell === "fish") {
+    return await Bun.file(path).exists();
+  }
+
+  // For bash/zsh, check for shell-specific patterns
+  try {
+    const content = await Bun.file(path).text();
+    // Generic header comment
+    const header = `# ${CLI_NAME}`;
+    // Bash function name
+    const bashFn = `_${CLI_NAME}_completions`;
+    // Zsh-specific patterns (function definition or completion header)
+    const zshFn = `_${CLI_NAME}()`;
+
+    if (shell === "bash") {
+      return content.includes(header) || content.includes(bashFn);
+    }
+    if (shell === "zsh") {
+      return content.includes(header) || content.includes(zshFn);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commands
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Output completion script to stdout.
+ */
+export function completionOutput(options: OutputOptions): string {
+  const { shell } = options;
+
+  if (!SUPPORTED_SHELLS.includes(shell)) {
+    throw new CliError(
+      "VALIDATION",
+      `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
+    );
+  }
+
+  return getCompletionScript(shell);
+}
+
+/**
+ * Auto-install completion to user's shell config.
+ */
+export async function completionInstall(
+  options: InstallOptions
+): Promise<void> {
+  const { json = false } = options;
+  let { shell } = options;
+
+  // Auto-detect shell if not specified
+  if (!shell) {
+    shell = detectShell();
+    if (!shell) {
+      throw new CliError(
+        "VALIDATION",
+        "Could not detect shell. Please specify: gno completion install --shell <bash|zsh|fish>"
+      );
+    }
+  }
+
+  if (!SUPPORTED_SHELLS.includes(shell)) {
+    throw new CliError(
+      "VALIDATION",
+      `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
+    );
+  }
+
+  // Check if already installed
+  const alreadyInstalled = await isCompletionInstalled(shell);
+  const rcPath = getShellRcPath(shell);
+  const script = getCompletionScript(shell);
+
+  let result: InstallResult;
+
+  if (alreadyInstalled) {
+    result = { shell, path: rcPath, action: "already_installed" };
+  } else {
+    // Install completion
+    if (shell === "fish") {
+      // Fish uses a separate file in completions dir
+      const dir = join(homedir(), ".config", "fish", "completions");
+      await mkdir(dir, { recursive: true });
+      await writeFile(rcPath, script, "utf-8");
+    } else {
+      // Bash/zsh append to rc file
+      const separator = "\n\n";
+      await appendFile(rcPath, separator + script, "utf-8");
+    }
+    result = { shell, path: rcPath, action: "installed" };
+  }
+
+  // Output result
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    if (result.action === "already_installed") {
+      process.stdout.write(`Completion already installed for ${shell}.\n`);
+      process.stdout.write(`Config: ${result.path}\n`);
+    } else {
+      process.stdout.write(`Completion installed for ${shell}.\n`);
+      process.stdout.write(`Config: ${result.path}\n`);
+      process.stdout.write(`\nRestart your shell or run:\n`);
+      process.stdout.write(`  source ${result.path}\n`);
+    }
+  }
+}

package/src/cli/commands/completion/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Shell completion command - output or install completion scripts.
+ *
+ * @module src/cli/commands/completion
+ */
+
+export { completionOutput, completionInstall } from "./completion.js";
+export { SUPPORTED_SHELLS, type Shell } from "./scripts.js";

package/src/cli/commands/completion/scripts.ts

@@ -0,0 +1,365 @@
+/**
+ * Shell completion scripts for bash, zsh, and fish.
+ *
+ * @module src/cli/commands/completion/scripts
+ */
+
+import { CLI_NAME } from "../../../app/constants.js";
+
+export type Shell = "bash" | "zsh" | "fish";
+export const SUPPORTED_SHELLS: Shell[] = ["bash", "zsh", "fish"];
+
+/**
+ * All gno commands and subcommands for completion.
+ */
+const COMMANDS = [
+  "init",
+  "index",
+  "update",
+  "embed",
+  "status",
+  "doctor",
+  "cleanup",
+  "reset",
+  "search",
+  "vsearch",
+  "query",
+  "ask",
+  "get",
+  "multi-get",
+  "ls",
+  "serve",
+  "mcp",
+  "mcp serve",
+  "mcp install",
+  "mcp uninstall",
+  "mcp status",
+  "collection",
+  "collection add",
+  "collection list",
+  "collection remove",
+  "collection rename",
+  "context",
+  "context add",
+  "context list",
+  "context check",
+  "context rm",
+  "models",
+  "models list",
+  "models pull",
+  "models clear",
+  "models path",
+  "models use",
+  "skill",
+  "skill install",
+  "skill uninstall",
+  "skill show",
+  "skill paths",
+  "completion",
+  "completion output",
+  "completion install",
+];
+
+/**
+ * Global flags available on all commands.
+ */
+const GLOBAL_FLAGS = [
+  "--index",
+  "--config",
+  "--no-color",
+  "--no-pager",
+  "--verbose",
+  "--yes",
+  "--quiet",
+  "--json",
+  "--offline",
+  "--help",
+  "--version",
+];
+
+/**
+ * Generate bash completion script.
+ */
+export function generateBashCompletion(): string {
+  const commands = COMMANDS.filter((c) => !c.includes(" ")).join(" ");
+  const subcommands: Record<string, string> = {};
+
+  for (const cmd of COMMANDS) {
+    if (cmd.includes(" ")) {
+      const parts = cmd.split(" ");
+      const parent = parts[0];
+      const sub = parts[1];
+      if (parent && sub) {
+        subcommands[parent] = subcommands[parent]
+          ? `${subcommands[parent]} ${sub}`
+          : sub;
+      }
+    }
+  }
+
+  const subCases = Object.entries(subcommands)
+    .map(
+      ([parent, subs]) =>
+        `      ${parent}) COMPREPLY=($(compgen -W "${subs}" -- "\${cur}")) ;;`
+    )
+    .join("\n");
+
+  return `# ${CLI_NAME} bash completion
+# Add to ~/.bashrc or ~/.bash_completion
+
+_${CLI_NAME}_completions() {
+  local cur prev cword
+  # Portable: don't rely on _init_completion (requires bash-completion package)
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  cword="\${COMP_CWORD}"
+
+  local commands="${commands}"
+  local global_flags="${GLOBAL_FLAGS.join(" ")}"
+
+  # Complete subcommands for parent commands
+  case "\${COMP_WORDS[1]}" in
+${subCases}
+  esac
+
+  # Complete global flags
+  if [[ "\${cur}" == -* ]]; then
+    COMPREPLY=($(compgen -W "\${global_flags}" -- "\${cur}"))
+    return
+  fi
+
+  # Complete top-level commands
+  if [[ \${cword} -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "\${commands}" -- "\${cur}"))
+    return
+  fi
+
+  # Dynamic collection completion for -c/--collection flag
+  if [[ "\${prev}" == "-c" || "\${prev}" == "--collection" ]]; then
+    local collections
+    collections=$(${CLI_NAME} collection list --json 2>/dev/null | grep -o '"name":"[^"]*"' | cut -d'"' -f4)
+    COMPREPLY=($(compgen -W "\${collections}" -- "\${cur}"))
+    return
+  fi
+}
+
+complete -F _${CLI_NAME}_completions ${CLI_NAME}
+`;
+}
+
+/**
+ * Generate zsh completion script.
+ */
+export function generateZshCompletion(): string {
+  const topLevel = COMMANDS.filter((c) => !c.includes(" "));
+  const subcommands: Record<string, string[]> = {};
+
+  for (const cmd of COMMANDS) {
+    if (cmd.includes(" ")) {
+      const parts = cmd.split(" ");
+      const parent = parts[0];
+      const sub = parts[1];
+      if (parent && sub) {
+        subcommands[parent] = subcommands[parent] || [];
+        subcommands[parent].push(sub);
+      }
+    }
+  }
+
+  const subCases = Object.entries(subcommands)
+    .map(
+      ([parent, subs]) =>
+        `    ${parent})
+      _arguments '2:subcommand:(${subs.join(" ")})'
+      ;;`
+    )
+    .join("\n");
+
+  return `# ${CLI_NAME} zsh completion
+# Add to ~/.zshrc or copy to a directory in $fpath
+# If autoloading from fpath, add "#compdef ${CLI_NAME}" as first line
+
+_${CLI_NAME}() {
+  local -a commands
+  commands=(
+${topLevel.map((c) => `    '${c}:${getCommandDescription(c)}'`).join("\n")}
+  )
+
+  local -a global_flags
+  global_flags=(
+    '--index[index name]:name:'
+    '--config[config file path]:file:_files'
+    '-c[filter by collection]:collection:_${CLI_NAME}_collections'
+    '--collection[filter by collection]:collection:_${CLI_NAME}_collections'
+    '--no-color[disable colors]'
+    '--no-pager[disable paging]'
+    '--verbose[verbose logging]'
+    '--yes[non-interactive mode]'
+    '--quiet[suppress non-essential output]'
+    '--json[JSON output]'
+    '--offline[offline mode]'
+    '--help[show help]'
+    '--version[show version]'
+  )
+
+  _arguments -C \\
+    "\${global_flags[@]}" \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case "$state" in
+    command)
+      _describe -t commands 'gno commands' commands
+      ;;
+    args)
+      # words[1] is the program name in zsh, words[2] is the command
+      case "\${words[2]}" in
+${subCases}
+      esac
+      ;;
+  esac
+}
+
+# Dynamic collection completion
+_${CLI_NAME}_collections() {
+  local -a collections
+  collections=(\${(f)"$($CLI_NAME collection list --json 2>/dev/null | grep -o '"name":"[^"]*"' | cut -d'"' -f4)"})
+  _describe -t collections 'collections' collections
+}
+
+# Register completion (works when sourced or autoloaded)
+(( $+functions[compdef] )) && compdef _${CLI_NAME} ${CLI_NAME}
+`;
+}
+
+/**
+ * Generate fish completion script.
+ */
+export function generateFishCompletion(): string {
+  const topLevel = COMMANDS.filter((c) => !c.includes(" "));
+  const subcommands: Record<string, string[]> = {};
+
+  for (const cmd of COMMANDS) {
+    if (cmd.includes(" ")) {
+      const parts = cmd.split(" ");
+      const parent = parts[0];
+      const sub = parts[1];
+      if (parent && sub) {
+        subcommands[parent] = subcommands[parent] || [];
+        subcommands[parent].push(sub);
+      }
+    }
+  }
+
+  const topLevelCompletions = topLevel
+    .map(
+      (c) =>
+        `complete -c ${CLI_NAME} -f -n "__fish_use_subcommand" -a "${c}" -d "${getCommandDescription(c)}"`
+    )
+    .join("\n");
+
+  const subCompletions = Object.entries(subcommands)
+    .flatMap(([parent, subs]) =>
+      subs.map(
+        (sub) =>
+          `complete -c ${CLI_NAME} -f -n "__fish_seen_subcommand_from ${parent}" -a "${sub}" -d "${getCommandDescription(`${parent} ${sub}`)}"`
+      )
+    )
+    .join("\n");
+
+  return `# ${CLI_NAME} fish completion
+# Copy to ~/.config/fish/completions/${CLI_NAME}.fish
+
+# Disable file completion by default
+complete -c ${CLI_NAME} -f
+
+# Global flags
+complete -c ${CLI_NAME} -l index -d "index name" -r
+complete -c ${CLI_NAME} -l config -d "config file path" -r
+complete -c ${CLI_NAME} -l no-color -d "disable colors"
+complete -c ${CLI_NAME} -l verbose -d "verbose logging"
+complete -c ${CLI_NAME} -l yes -d "non-interactive mode"
+complete -c ${CLI_NAME} -l quiet -d "suppress non-essential output"
+complete -c ${CLI_NAME} -l json -d "JSON output"
+complete -c ${CLI_NAME} -l offline -d "offline mode"
+complete -c ${CLI_NAME} -s h -l help -d "show help"
+complete -c ${CLI_NAME} -s V -l version -d "show version"
+
+# Top-level commands
+${topLevelCompletions}
+
+# Subcommands
+${subCompletions}
+
+# Dynamic collection completion for -c/--collection
+complete -c ${CLI_NAME} -s c -l collection -d "filter by collection" -xa "(${CLI_NAME} collection list --json 2>/dev/null | string match -r '"name":"[^"]*"' | string replace -r '"name":"([^"]*)"' '$1')"
+`;
+}
+
+/**
+ * Get script for a specific shell.
+ */
+export function getCompletionScript(shell: Shell): string {
+  switch (shell) {
+    case "bash":
+      return generateBashCompletion();
+    case "zsh":
+      return generateZshCompletion();
+    case "fish":
+      return generateFishCompletion();
+  }
+}
+
+/**
+ * Get brief description for a command.
+ */
+function getCommandDescription(cmd: string): string {
+  const descriptions: Record<string, string> = {
+    init: "Initialize GNO configuration",
+    index: "Index files from collections",
+    update: "Sync files from disk",
+    embed: "Generate embeddings",
+    status: "Show index status",
+    doctor: "Diagnose configuration issues",
+    cleanup: "Clean orphaned data",
+    reset: "Delete all GNO data",
+    search: "BM25 keyword search",
+    vsearch: "Vector similarity search",
+    query: "Hybrid search with reranking",
+    ask: "Query with grounded answer",
+    get: "Get document by URI",
+    "multi-get": "Get multiple documents",
+    ls: "List indexed documents",
+    serve: "Start web UI server",
+    mcp: "MCP server and configuration",
+    "mcp serve": "Start MCP server",
+    "mcp install": "Install MCP server to client",
+    "mcp uninstall": "Remove MCP server from client",
+    "mcp status": "Show MCP installation status",
+    collection: "Manage collections",
+    "collection add": "Add a collection",
+    "collection list": "List collections",
+    "collection remove": "Remove a collection",
+    "collection rename": "Rename a collection",
+    context: "Manage context items",
+    "context add": "Add context metadata",
+    "context list": "List context items",
+    "context check": "Check context configuration",
+    "context rm": "Remove context item",
+    models: "Manage LLM models",
+    "models list": "List available models",
+    "models pull": "Download models",
+    "models clear": "Clear model cache",
+    "models path": "Show model cache path",
+    "models use": "Switch active model preset",
+    skill: "Manage GNO agent skill",
+    "skill install": "Install GNO skill",
+    "skill uninstall": "Uninstall GNO skill",
+    "skill show": "Preview skill files",
+    "skill paths": "Show skill installation paths",
+    completion: "Shell completion scripts",
+    "completion output": "Output completion script",
+    "completion install": "Install shell completions",
+  };
+  return descriptions[cmd] || cmd;
+}

package/src/cli/context.ts

@@ -21,6 +21,7 @@ export interface GlobalOptions {
   quiet: boolean;
   json: boolean;
   offline: boolean;
+  noPager: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -58,6 +59,8 @@ export function parseGlobalOptions(
     quiet: Boolean(raw.quiet),
     json: Boolean(raw.json),
     offline: offlineEnabled,
+    // Commander: --no-pager => opts().pager === false
+    noPager: raw.pager === false,
   };
 }
 

package/src/cli/pager.ts

@@ -0,0 +1,200 @@
+/**
+ * Pager utility for long CLI output.
+ * Pipes output through less/more when terminal height exceeded.
+ *
+ * @module src/cli/pager
+ */
+
+// node:os - no Bun equivalent for platform()
+import { platform } from "node:os";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PagerOptions {
+  /** Force disable paging (--no-pager flag) */
+  noPager?: boolean;
+  /** Override terminal height detection */
+  terminalHeight?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pager Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Find available pager command.
+ * Priority: $PAGER env → less (with -R for colors) → more
+ */
+function findPager(): string[] | null {
+  // Check $PAGER env first (cross-platform)
+  const pagerEnv = process.env.PAGER;
+  if (pagerEnv) {
+    // Split in case user has args like "less -R"
+    return pagerEnv.split(/\s+/);
+  }
+
+  // Platform-specific fallbacks
+  const isWindows = platform() === "win32";
+
+  if (isWindows) {
+    // Windows: use more.com (basic but universally available)
+    return ["more.com"];
+  }
+
+  // Unix: prefer less with -R (preserve ANSI colors)
+  return ["less", "-R"];
+}
+
+/**
+ * Check if paging should be enabled.
+ */
+function shouldPage(options: PagerOptions): boolean {
+  // Explicitly disabled
+  if (options.noPager) {
+    return false;
+  }
+
+  // Not a TTY (piped output)
+  if (!process.stdout.isTTY) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Get terminal height.
+ */
+function getTerminalHeight(options: PagerOptions): number {
+  if (options.terminalHeight !== undefined) {
+    return options.terminalHeight;
+  }
+  return process.stdout.rows || 24; // Default to 24 if unknown
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pager Class
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Pager that buffers output and pipes through pager if needed.
+ */
+export class Pager {
+  private options: PagerOptions;
+  private buffer: string[] = [];
+  private terminalHeight: number;
+  private pagerProcess: ReturnType<typeof Bun.spawn> | null = null;
+  private enabled: boolean;
+
+  constructor(options: PagerOptions = {}) {
+    this.options = options;
+    this.terminalHeight = getTerminalHeight(options);
+    this.enabled = shouldPage(options);
+  }
+
+  /**
+   * Write a line to the pager buffer.
+   */
+  writeLine(line: string): void {
+    this.buffer.push(line);
+  }
+
+  /**
+   * Write multiple lines to the pager buffer.
+   */
+  writeLines(lines: string[]): void {
+    this.buffer.push(...lines);
+  }
+
+  /**
+   * Write raw content (may contain newlines).
+   */
+  write(content: string): void {
+    const lines = content.split("\n");
+    // Don't add empty string from trailing newline
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines.pop();
+    }
+    this.buffer.push(...lines);
+  }
+
+  /**
+   * Flush buffer to stdout, using pager if content exceeds terminal height.
+   */
+  async flush(): Promise<void> {
+    const content = this.buffer.join("\n");
+    const lineCount = this.buffer.length;
+
+    // If paging disabled or content fits in terminal, write directly
+    if (!this.enabled || lineCount <= this.terminalHeight - 1) {
+      if (content) {
+        process.stdout.write(content + "\n");
+      }
+      return;
+    }
+
+    // Try to spawn pager
+    const pagerCmd = findPager();
+    if (!pagerCmd) {
+      // No pager available, write directly
+      process.stdout.write(content + "\n");
+      return;
+    }
+
+    // Spawn pager and pipe content
+    await this.spawnPager(pagerCmd, content);
+  }
+
+  /**
+   * Spawn pager process and pipe content.
+   */
+  private async spawnPager(pagerCmd: string[], content: string): Promise<void> {
+    const [cmd, ...args] = pagerCmd;
+    if (!cmd) {
+      process.stdout.write(content + "\n");
+      return;
+    }
+
+    try {
+      const proc = Bun.spawn([cmd, ...args], {
+        stdin: "pipe",
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      this.pagerProcess = proc;
+
+      // Write content to pager stdin
+      if (proc.stdin) {
+        proc.stdin.write(content + "\n");
+        await proc.stdin.end();
+      }
+
+      // Wait for pager to exit
+      await proc.exited;
+      this.pagerProcess = null;
+    } catch {
+      // Spawn failed - fall back to direct output
+      process.stdout.write(content + "\n");
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Function
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Convenience function to page content.
+ * @param content Content to potentially page
+ * @param options Pager options
+ */
+export async function pageContent(
+  content: string,
+  options: PagerOptions = {}
+): Promise<void> {
+  const pager = new Pager(options);
+  pager.write(content);
+  await pager.flush();
+}

package/src/cli/program.ts

@@ -110,6 +110,25 @@ function getFormat(
   return "terminal";
 }
 
+/**
+ * Write output with optional paging for terminal format.
+ * Paging only applies to terminal format with list-like output.
+ */
+async function writeOutput(
+  content: string,
+  format: "terminal" | "json" | "files" | "csv" | "md" | "xml"
+): Promise<void> {
+  const globals = getGlobals();
+
+  // Only page terminal output when paging enabled
+  if (format === "terminal" && !globals.noPager) {
+    const { pageContent } = await import("./pager.js");
+    await pageContent(content);
+  } else {
+    process.stdout.write(content + "\n");
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Program Factory
 // ─────────────────────────────────────────────────────────────────────────────
@@ -134,7 +153,8 @@ export function createProgram(): Command {
     .option("--yes", "non-interactive mode")
     .option("-q, --quiet", "suppress non-essential output")
     .option("--json", "JSON output (for errors and supported commands)")
-    .option("--offline", "offline mode (use cached models only)");
+    .option("--offline", "offline mode (use cached models only)")
+    .option("--no-pager", "disable automatic paging of long output");
 
   // Resolve globals ONCE before any command runs (ensures consistency)
   program.hook("preAction", (thisCommand) => {
@@ -152,6 +172,7 @@ export function createProgram(): Command {
   wireMcpCommand(program);
   wireSkillCommands(program);
   wireServeCommand(program);
+  wireCompletionCommand(program);
 
   // Add docs/support links to help footer
   program.addHelpText(
@@ -226,17 +247,16 @@ function wireSearchCommands(program: Command): void {
           result.error
         );
       }
-      process.stdout.write(
-        `${formatSearch(result, {
-          json: format === "json",
-          md: format === "md",
-          csv: format === "csv",
-          xml: format === "xml",
-          files: format === "files",
-          full: Boolean(cmdOpts.full),
-          lineNumbers: Boolean(cmdOpts.lineNumbers),
-        })}\n`
-      );
+      const output = formatSearch(result, {
+        json: format === "json",
+        md: format === "md",
+        csv: format === "csv",
+        xml: format === "xml",
+        files: format === "files",
+        full: Boolean(cmdOpts.full),
+        lineNumbers: Boolean(cmdOpts.lineNumbers),
+      });
+      await writeOutput(output, format);
     });
 
   // vsearch - Vector similarity search
@@ -291,17 +311,16 @@ function wireSearchCommands(program: Command): void {
       if (!result.success) {
         throw new CliError("RUNTIME", result.error);
       }
-      process.stdout.write(
-        `${formatVsearch(result, {
-          json: format === "json",
-          md: format === "md",
-          csv: format === "csv",
-          xml: format === "xml",
-          files: format === "files",
-          full: Boolean(cmdOpts.full),
-          lineNumbers: Boolean(cmdOpts.lineNumbers),
-        })}\n`
-      );
+      const output = formatVsearch(result, {
+        json: format === "json",
+        md: format === "md",
+        csv: format === "csv",
+        xml: format === "xml",
+        files: format === "files",
+        full: Boolean(cmdOpts.full),
+        lineNumbers: Boolean(cmdOpts.lineNumbers),
+      });
+      await writeOutput(output, format);
     });
 
   // query - Hybrid search with expansion and reranking
@@ -388,13 +407,12 @@ function wireSearchCommands(program: Command): void {
       if (!result.success) {
         throw new CliError("RUNTIME", result.error);
       }
-      process.stdout.write(
-        `${formatQuery(result, {
-          format,
-          full: Boolean(cmdOpts.full),
-          lineNumbers: Boolean(cmdOpts.lineNumbers),
-        })}\n`
-      );
+      const output = formatQuery(result, {
+        format,
+        full: Boolean(cmdOpts.full),
+        lineNumbers: Boolean(cmdOpts.lineNumbers),
+      });
+      await writeOutput(output, format);
     });
 
   // ask - Human-friendly query with grounded answer
@@ -464,9 +482,12 @@ function wireSearchCommands(program: Command): void {
       if (!result.success) {
         throw new CliError("RUNTIME", result.error);
       }
-      process.stdout.write(
-        `${formatAsk(result, { json: format === "json", md: format === "md", showSources })}\n`
-      );
+      const output = formatAsk(result, {
+        json: format === "json",
+        md: format === "md",
+        showSources,
+      });
+      await writeOutput(output, format);
     });
 }
 
@@ -738,13 +759,12 @@ function wireRetrievalCommands(program: Command): void {
           );
         }
 
-        process.stdout.write(
-          `${formatLs(result, {
-            json: format === "json",
-            files: format === "files",
-            md: format === "md",
-          })}\n`
-        );
+        const output = formatLs(result, {
+          json: format === "json",
+          files: format === "files",
+          md: format === "md",
+        });
+        await writeOutput(output, format);
       }
     );
 }
@@ -1407,3 +1427,68 @@ function wireServeCommand(program: Command): void {
       // Server runs until SIGINT/SIGTERM - no output needed here
     });
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Completion Command (shell completions)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function wireCompletionCommand(program: Command): void {
+  const completionCmd = program
+    .command("completion")
+    .description("Shell completion scripts");
+
+  // Output completion script
+  completionCmd
+    .command("output <shell>", { isDefault: true })
+    .description("Output completion script for a shell (bash, zsh, fish)")
+    .action(async (shell: string) => {
+      const { completionOutput, SUPPORTED_SHELLS } =
+        await import("./commands/completion/index.js");
+
+      if (!SUPPORTED_SHELLS.includes(shell as "bash" | "zsh" | "fish")) {
+        throw new CliError(
+          "VALIDATION",
+          `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
+        );
+      }
+
+      const script = completionOutput({
+        shell: shell as "bash" | "zsh" | "fish",
+      });
+      process.stdout.write(script);
+    });
+
+  // Install completion to user's shell config
+  completionCmd
+    .command("install")
+    .description("Auto-install completion to shell config")
+    .option(
+      "-s, --shell <shell>",
+      "shell to install for (bash, zsh, fish) - auto-detected if omitted"
+    )
+    .option("--json", "JSON output")
+    .action(async (...args: unknown[]) => {
+      // Last arg is the Command object - use optsWithGlobals for subcommands
+      const cmd = args[args.length - 1] as Command;
+      const cmdOpts = cmd.optsWithGlobals<{ shell?: string; json?: boolean }>();
+      const { shell, json } = cmdOpts;
+
+      const { completionInstall, SUPPORTED_SHELLS } =
+        await import("./commands/completion/index.js");
+
+      if (
+        shell &&
+        !SUPPORTED_SHELLS.includes(shell as "bash" | "zsh" | "fish")
+      ) {
+        throw new CliError(
+          "VALIDATION",
+          `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
+        );
+      }
+
+      await completionInstall({
+        shell: shell as "bash" | "zsh" | "fish" | undefined,
+        json: Boolean(json),
+      });
+    });
+}