24 files changed, 705 insertions, 184 deletions

diff --git a/README.md b/README.md
index b17983d..dc79489 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 Hexai, the AI LSP for the Helix editor and also a simple command line tool to interact with LLMs in general.
 
-At the moment this project is only in the proof of PoC phase.
+At the moment this project is in the alpha state.
 
 ## LLM provider
 
@@ -74,6 +74,22 @@ Notes for `hexai` (CLI):
   - Add the word `explain` in your prompt to request a verbose explanation.
 - Exit codes: `0` success, `1` provider/config error, `2` no input.
 
+### Internal CLI package
+
+- Package `internal/hexaicli` contains the CLI logic extracted from `cmd/hexai`.
+- Entry points:
+- `Run(ctx, args, stdin, stdout, stderr)`: Full CLI flow; parses input and builds the LLM client from config/env.
+- `RunWithClient(ctx, args, stdin, stdout, stderr, client)`: Same flow using a provided `llm.Client` (useful for tests and embedding).
+- Behavior is identical to the `hexai` binary: provider/model banner on stderr, streamed output when available, and a final summary line.
+
+### Internal LSP package
+
+- Package `internal/hexailsp` contains the LSP binary logic extracted from `cmd/hexai-lsp`.
+- Entry points:
+- `Run(logPath, stdin, stdout, stderr)`: Configures logging, loads config, builds the LLM client, and runs the LSP server over stdio.
+- `RunWithFactory(logPath, stdin, stdout, logger, cfg, client, factory)`: Testable entry that accepts a prebuilt `llm.Client` and a factory for `lsp.Server` creation.
+- Mirrors the behavior of the `hexai-lsp` binary while enabling unit tests without invoking the full server loop.
+
 Examples:
 
 ```
diff --git a/cmd/hexai-lsp/main.go b/cmd/hexai-lsp/main.go
index 065b6e2..a473ad7 100644
--- a/cmd/hexai-lsp/main.go
+++ b/cmd/hexai-lsp/main.go
@@ -1,82 +1,26 @@
+// Summary: Hexai LSP entrypoint; parses flags and delegates to internal/hexailsp.
+// Not yet reviewed by a human
 package main
 
 import (
-    "flag"
-    "log"
-    "os"
-    "strings"
+	"flag"
+	"log"
+	"os"
 
-    "hexai/internal"
-    "hexai/internal/appconfig"
-    "hexai/internal/llm"
-    "hexai/internal/logging"
-    "hexai/internal/lsp"
+	"hexai/internal"
+	"hexai/internal/hexailsp"
 )
 
 func main() {
-    logPath := flag.String("log", "/tmp/hexai-lsp.log", "path to log file (optional)")
-    showVersion := flag.Bool("version", false, "print version and exit")
-    flag.Parse()
-    if *showVersion {
-        log.Println(internal.Version)
-        return
-    }
-
-    // Configure logging (path flag only)
-    logger := log.New(os.Stderr, "hexai-lsp ", log.LstdFlags|log.Lmsgprefix)
-    if *logPath != "" {
-        f, err := os.OpenFile(*logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
-        if err != nil {
-            logger.Fatalf("failed to open log file: %v", err)
-        }
-        defer f.Close()
-        logger.SetOutput(f)
-    }
-    logging.Bind(logger)
-
-    // Load config file
-    cfg := appconfig.Load(logger)
-
-    // Normalize and apply logging config
-    cfg.ContextMode = strings.ToLower(strings.TrimSpace(cfg.ContextMode))
-    if cfg.LogPreviewLimit >= 0 {
-        logging.SetLogPreviewLimit(cfg.LogPreviewLimit)
-    }
-
-    // Build LLM client from config
-    var client llm.Client
-    {
-        llmCfg := llm.Config{
-            Provider:       cfg.Provider,
-            OpenAIBaseURL:  cfg.OpenAIBaseURL,
-            OpenAIModel:    cfg.OpenAIModel,
-            OllamaBaseURL:  cfg.OllamaBaseURL,
-            OllamaModel:    cfg.OllamaModel,
-            CopilotBaseURL: cfg.CopilotBaseURL,
-            CopilotModel:   cfg.CopilotModel,
-        }
-        oaKey := os.Getenv("OPENAI_API_KEY")
-        cpKey := os.Getenv("COPILOT_API_KEY")
-        if c, err := llm.NewFromConfig(llmCfg, oaKey, cpKey); err != nil {
-            logging.Logf("lsp ", "llm disabled: %v", err)
-        } else {
-            client = c
-            logging.Logf("lsp ", "llm enabled provider=%s model=%s", c.Name(), c.DefaultModel())
-        }
-    }
-
-    server := lsp.NewServer(os.Stdin, os.Stdout, logger, lsp.ServerOptions{
-        LogContext:        *logPath != "",
-        MaxTokens:         cfg.MaxTokens,
-        ContextMode:       cfg.ContextMode,
-        WindowLines:       cfg.ContextWindowLines,
-        MaxContextTokens:  cfg.MaxContextTokens,
-        NoDiskIO:          cfg.NoDiskIO,
-        Client:            client,
-        TriggerCharacters: cfg.TriggerCharacters,
-    })
-    if err := server.Run(); err != nil {
-        logger.Fatalf("server error: %v", err)
-    }
+	logPath := flag.String("log", "/tmp/hexai-lsp.log", "path to log file (optional)")
+	showVersion := flag.Bool("version", false, "print version and exit")
+	flag.Parse()
+	if *showVersion {
+		log.Println(internal.Version)
+		return
+	}
+
+	if err := hexailsp.Run(*logPath, os.Stdin, os.Stdout, os.Stderr); err != nil {
+		log.Fatalf("server error: %v", err)
+	}
 }
-
diff --git a/cmd/hexai/main.go b/cmd/hexai/main.go
index 6cbd288..2a0e81b 100644
--- a/cmd/hexai/main.go
+++ b/cmd/hexai/main.go
@@ -1,116 +1,26 @@
+// Summary: Hexai CLI entrypoint; parses flags and delegates to internal/hexaicli.
+// Not yet reviewed by a human
 package main
 
 import (
-    "bufio"
-    "context"
-    "flag"
-    "fmt"
-    "io"
-    "os"
-    "strings"
-    "time"
+	"context"
+	"flag"
+	"fmt"
+	"os"
 
-    "hexai/internal"
-    "hexai/internal/appconfig"
-    "hexai/internal/llm"
-    "hexai/internal/logging"
+	"hexai/internal"
+	"hexai/internal/hexaicli"
 )
 
 func main() {
-    showVersion := flag.Bool("version", false, "print version and exit")
-    flag.Parse()
-    if *showVersion {
-        fmt.Fprintln(os.Stdout, internal.Version)
-        return
-    }
-
-    // Read stdin if present
-    var stdinData string
-    if fi, err := os.Stdin.Stat(); err == nil && (fi.Mode()&os.ModeCharDevice) == 0 {
-        b, _ := io.ReadAll(bufio.NewReader(os.Stdin))
-        stdinData = string(b)
-    }
-
-    // Read argument input (join all remaining args with space)
-    argData := strings.TrimSpace(strings.Join(flag.Args(), " "))
-
-    // Combine inputs
-    var input string
-    switch {
-    case stdinData != "" && argData != "":
-        input = strings.TrimSpace(stdinData) + "\n\n" + argData
-    case stdinData != "":
-        input = strings.TrimSpace(stdinData)
-    case argData != "":
-        input = argData
-    default:
-        fmt.Fprintln(os.Stderr, logging.AnsiBase+"hexai: no input provided; pass text as an argument or via stdin"+logging.AnsiReset)
-        os.Exit(2)
-    }
-
-    // Load config (no external logging for CLI)
-    cfg := appconfig.Load(nil)
-
-    // Build LLM client
-    llmCfg := llm.Config{
-        Provider:       cfg.Provider,
-        OpenAIBaseURL:  cfg.OpenAIBaseURL,
-        OpenAIModel:    cfg.OpenAIModel,
-        OllamaBaseURL:  cfg.OllamaBaseURL,
-        OllamaModel:    cfg.OllamaModel,
-        CopilotBaseURL: cfg.CopilotBaseURL,
-        CopilotModel:   cfg.CopilotModel,
-    }
-    oaKey := os.Getenv("OPENAI_API_KEY")
-    cpKey := os.Getenv("COPILOT_API_KEY")
-    client, err := llm.NewFromConfig(llmCfg, oaKey, cpKey)
-    if err != nil {
-        fmt.Fprintf(os.Stderr, logging.AnsiBase+"hexai: LLM disabled: %v"+logging.AnsiReset+"\n", err)
-        os.Exit(1)
-    }
-
-    // Print provider/model immediately to stderr
-    fmt.Fprintf(os.Stderr, logging.AnsiBase+"provider=%s model=%s"+logging.AnsiReset+"\n", client.Name(), client.DefaultModel())
-
-    // Prepare and send request
-    start := time.Now()
-    lower := strings.ToLower(input)
-    system := "You are Hexai CLI. Default to very short, concise answers. If the user asks for commands, output only the commands (one per line) with no commentary or explanation. Only when the word 'explain' appears in the prompt, produce a verbose explanation."
-    if strings.Contains(lower, "explain") {
-        system = "You are Hexai CLI. The user requested an explanation. Provide a clear, verbose explanation with reasoning and details. If commands are needed, include them with brief context."
-    }
-    msgs := []llm.Message{
-        {Role: "system", Content: system},
-        {Role: "user", Content: input},
-    }
-    var out string
-    if s, ok := client.(llm.Streamer); ok {
-        var b strings.Builder
-        err := s.ChatStream(context.Background(), msgs, func(chunk string) {
-            b.WriteString(chunk)
-            fmt.Fprint(os.Stdout, chunk)
-        })
-        dur := time.Since(start)
-        if err != nil {
-            fmt.Fprintf(os.Stderr, logging.AnsiBase+"hexai: error: %v"+logging.AnsiReset+"\n", err)
-            os.Exit(1)
-        }
-        out = b.String()
-        // Summary
-        inSize := len(input)
-        outSize := len(out)
-        fmt.Fprintf(os.Stderr, "\n"+logging.AnsiBase+"done provider=%s model=%s time=%s in_bytes=%d out_bytes=%d"+logging.AnsiReset+"\n", client.Name(), client.DefaultModel(), dur.Round(time.Millisecond), inSize, outSize)
-    } else {
-        outText, err := client.Chat(context.Background(), msgs)
-        dur := time.Since(start)
-        if err != nil {
-            fmt.Fprintf(os.Stderr, logging.AnsiBase+"hexai: error: %v"+logging.AnsiReset+"\n", err)
-            os.Exit(1)
-        }
-        out = outText
-        fmt.Fprint(os.Stdout, out)
-        inSize := len(input)
-        outSize := len(out)
-        fmt.Fprintf(os.Stderr, "\n"+logging.AnsiBase+"done provider=%s model=%s time=%s in_bytes=%d out_bytes=%d"+logging.AnsiReset+"\n", client.Name(), client.DefaultModel(), dur.Round(time.Millisecond), inSize, outSize)
-    }
+	showVersion := flag.Bool("version", false, "print version and exit")
+	flag.Parse()
+	if *showVersion {
+		fmt.Fprintln(os.Stdout, internal.Version)
+		return
+	}
+
+	if err := hexaicli.Run(context.Background(), flag.Args(), os.Stdin, os.Stdout, os.Stderr); err != nil {
+		os.Exit(1)
+	}
 }
diff --git a/internal/appconfig/config.go b/internal/appconfig/config.go
index d12bdbe..c0f28d2 100644
--- a/internal/appconfig/config.go
+++ b/internal/appconfig/config.go
@@ -1,3 +1,5 @@
+// Summary: Application configuration model and loader; reads ~/.config/hexai/config.json and merges defaults.
+// Not yet reviewed by a human
 package appconfig
 
 import (
@@ -99,4 +101,3 @@ func Load(logger *log.Logger) App {
     }
     return cfg
 }
-
diff --git a/internal/hexaicli/run.go b/internal/hexaicli/run.go
new file mode 100644
index 0000000..018b5d2
--- /dev/null
+++ b/internal/hexaicli/run.go
@@ -0,0 +1,129 @@
+// Summary: Hexai CLI runner; reads input, creates an LLM client, builds messages,
+// streams or collects the model output, and prints a short summary to stderr.
+// Not yet reviewed by a human
+package hexaicli
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"hexai/internal/appconfig"
+	"hexai/internal/llm"
+	"hexai/internal/logging"
+)
+
+// Run executes the Hexai CLI behavior given arguments and I/O streams.
+// It assumes flags have already been parsed by the caller.
+func Run(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer) error {
+	cfg := appconfig.Load(nil)
+	client, err := newClientFromConfig(cfg)
+	if err != nil {
+		fmt.Fprintf(stderr, logging.AnsiBase+"hexai: LLM disabled: %v"+logging.AnsiReset+"\n", err)
+		return err
+	}
+
+	return RunWithClient(ctx, args, stdin, stdout, stderr, client)
+}
+
+// RunWithClient executes the CLI flow using an already-constructed client.
+// Useful for testing and embedding.
+func RunWithClient(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer, client llm.Client) error {
+	input, err := readInput(stdin, args)
+	if err != nil {
+		fmt.Fprintln(stderr, logging.AnsiBase+err.Error()+logging.AnsiReset)
+		return err
+	}
+	printProviderInfo(stderr, client)
+	msgs := buildMessages(input)
+	if err := runChat(ctx, client, msgs, input, stdout, stderr); err != nil {
+		fmt.Fprintf(stderr, logging.AnsiBase+"hexai: error: %v"+logging.AnsiReset+"\n", err)
+		return err
+	}
+	return nil
+}
+
+// readInput reads from stdin and args, then combines them per CLI rules.
+func readInput(stdin io.Reader, args []string) (string, error) {
+	var stdinData string
+	if fi, err := os.Stdin.Stat(); err == nil && (fi.Mode()&os.ModeCharDevice) == 0 {
+		b, _ := io.ReadAll(bufio.NewReader(stdin))
+		stdinData = strings.TrimSpace(string(b))
+	}
+	argData := strings.TrimSpace(strings.Join(args, " "))
+	switch {
+	case stdinData != "" && argData != "":
+		return fmt.Sprintf("%s:\n\n%s", argData, stdinData), nil
+	case stdinData != "":
+		return stdinData, nil
+	case argData != "":
+		return argData, nil
+	default:
+		return "", fmt.Errorf("hexai: no input provided; pass text as an argument or via stdin")
+	}
+}
+
+// newClientFromConfig builds an LLM client from the app config and env keys.
+func newClientFromConfig(cfg appconfig.App) (llm.Client, error) {
+	llmCfg := llm.Config{
+		Provider:       cfg.Provider,
+		OpenAIBaseURL:  cfg.OpenAIBaseURL,
+		OpenAIModel:    cfg.OpenAIModel,
+		OllamaBaseURL:  cfg.OllamaBaseURL,
+		OllamaModel:    cfg.OllamaModel,
+		CopilotBaseURL: cfg.CopilotBaseURL,
+		CopilotModel:   cfg.CopilotModel,
+	}
+	oaKey := os.Getenv("OPENAI_API_KEY")
+	cpKey := os.Getenv("COPILOT_API_KEY")
+	return llm.NewFromConfig(llmCfg, oaKey, cpKey)
+}
+
+// buildMessages creates system and user messages based on input content.
+func buildMessages(input string) []llm.Message {
+	lower := strings.ToLower(input)
+	system := "You are Hexai CLI. Default to very short, concise answers. If the user asks for commands, output only the commands (one per line) with no commentary or explanation. Only when the word 'explain' appears in the prompt, produce a verbose explanation."
+	if strings.Contains(lower, "explain") {
+		system = "You are Hexai CLI. The user requested an explanation. Provide a clear, verbose explanation with reasoning and details. If commands are needed, include them with brief context."
+	}
+	return []llm.Message{
+		{Role: "system", Content: system},
+		{Role: "user", Content: input},
+	}
+}
+
+// runChat executes the chat request, handling streaming and summary output.
+func runChat(ctx context.Context, client llm.Client, msgs []llm.Message, input string, out io.Writer, errw io.Writer) error {
+	start := time.Now()
+	var output string
+	if s, ok := client.(llm.Streamer); ok {
+		var b strings.Builder
+		if err := s.ChatStream(ctx, msgs, func(chunk string) {
+			b.WriteString(chunk)
+			fmt.Fprint(out, chunk)
+		}); err != nil {
+			return err
+		}
+		output = b.String()
+	} else {
+		txt, err := client.Chat(ctx, msgs)
+		if err != nil {
+			return err
+		}
+		output = txt
+		fmt.Fprint(out, output)
+	}
+	dur := time.Since(start)
+	fmt.Fprintf(errw, "\n"+logging.AnsiBase+"done provider=%s model=%s time=%s in_bytes=%d out_bytes=%d"+logging.AnsiReset+"\n",
+		client.Name(), client.DefaultModel(), dur.Round(time.Millisecond), len(input), len(output))
+	return nil
+}
+
+// printProviderInfo writes the provider/model line to stderr.
+func printProviderInfo(errw io.Writer, client llm.Client) {
+	fmt.Fprintf(errw, logging.AnsiBase+"provider=%s model=%s"+logging.AnsiReset+"\n", client.Name(), client.DefaultModel())
+}
diff --git a/internal/hexaicli/run_test.go b/internal/hexaicli/run_test.go
new file mode 100644
index 0000000..f9c8443
--- /dev/null
+++ b/internal/hexaicli/run_test.go
@@ -0,0 +1,194 @@
+// Summary: Unit tests for Hexai CLI helpers and run flow (input parsing, messages, streaming).
+// Not yet reviewed by a human
+package hexaicli
+
+import (
+	"bytes"
+	"context"
+	"strings"
+	"testing"
+)
+
+// helpers moved to testhelpers_test.go
+
+func TestReadInput_ArgsOnly(t *testing.T) {
+	restore, f := setStdin(t, "")
+	defer restore()
+	// Pass the same file reader used for os.Stdin (empty)
+	got, err := readInput(f, []string{"hello", "world"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := "hello world"
+	if got != want {
+		t.Fatalf("want %q, got %q", want, got)
+	}
+}
+
+func TestReadInput_StdinOnly(t *testing.T) {
+	restore, f := setStdin(t, "payload")
+	defer restore()
+	got, err := readInput(f, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "payload" {
+		t.Fatalf("want %q, got %q", "payload", got)
+	}
+}
+
+func TestReadInput_Combined(t *testing.T) {
+	restore, f := setStdin(t, "payload")
+	defer restore()
+	got, err := readInput(f, []string{"subject"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := "subject:\n\npayload"
+	if got != want {
+		t.Fatalf("want %q, got %q", want, got)
+	}
+}
+
+func TestReadInput_EmptyError(t *testing.T) {
+	restore, f := setStdin(t, "")
+	defer restore()
+	_, err := readInput(f, nil)
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "no input") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestBuildMessages_DefaultAndExplain(t *testing.T) {
+	// Default concise
+	msgs := buildMessages("list files in folder")
+	if len(msgs) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(msgs))
+	}
+	if msgs[0].Role != "system" || msgs[1].Role != "user" {
+		t.Fatalf("unexpected roles: %+v", msgs)
+	}
+	if !strings.Contains(msgs[0].Content, "very short, concise answers") {
+		t.Fatalf("unexpected system message: %q", msgs[0].Content)
+	}
+	if msgs[1].Content != "list files in folder" {
+		t.Fatalf("unexpected user content: %q", msgs[1].Content)
+	}
+
+	// Verbose explain
+	msgs2 := buildMessages("please explain how this works")
+	if len(msgs2) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(msgs2))
+	}
+	if !strings.Contains(strings.ToLower(msgs2[0].Content), "requested an explanation") {
+		t.Fatalf("unexpected system message: %q", msgs2[0].Content)
+	}
+	if msgs2[1].Content != "please explain how this works" {
+		t.Fatalf("unexpected user content: %q", msgs2[1].Content)
+	}
+}
+
+func TestRunChat_NonStreaming(t *testing.T) {
+	var out bytes.Buffer
+	var errb bytes.Buffer
+	fc := fakeClient{name: "fake", model: "m", resp: "OUTPUT"}
+	if err := runChat(context.Background(), &fc, nil, "input", &out, &errb); err != nil {
+		t.Fatalf("runChat error: %v", err)
+	}
+	if out.String() != "OUTPUT" {
+		t.Fatalf("stdout want %q, got %q", "OUTPUT", out.String())
+	}
+	es := errb.String()
+	if !strings.Contains(es, "done provider=fake model=m") {
+		t.Fatalf("stderr missing provider/model: %q", es)
+	}
+	if !strings.Contains(es, "in_bytes=5") || !strings.Contains(es, "out_bytes=6") {
+		t.Fatalf("stderr missing byte counts: %q", es)
+	}
+}
+
+func TestRunChat_Streaming(t *testing.T) {
+	var out bytes.Buffer
+	var errb bytes.Buffer
+	fs := fakeStreamer{fakeClient: fakeClient{name: "fake", model: "m"}, chunks: []string{"OUT", "PUT"}}
+	if err := runChat(context.Background(), &fs, nil, "input", &out, &errb); err != nil {
+		t.Fatalf("runChat error: %v", err)
+	}
+	if out.String() != "OUTPUT" {
+		t.Fatalf("stdout want %q, got %q", "OUTPUT", out.String())
+	}
+	es := errb.String()
+	if !strings.Contains(es, "done provider=fake model=m") {
+		t.Fatalf("stderr missing provider/model: %q", es)
+	}
+	if !strings.Contains(es, "in_bytes=5") || !strings.Contains(es, "out_bytes=6") {
+		t.Fatalf("stderr missing byte counts: %q", es)
+	}
+}
+
+func TestPrintProviderInfo(t *testing.T) {
+	var b bytes.Buffer
+	fc := fakeClient{name: "fake", model: "m"}
+	printProviderInfo(&b, &fc)
+	s := b.String()
+	if !strings.Contains(s, "provider=fake model=m") {
+		t.Fatalf("unexpected banner: %q", s)
+	}
+}
+
+func TestRunWithClient_NonStreaming(t *testing.T) {
+	restore, f := setStdin(t, "")
+	defer restore()
+	var out bytes.Buffer
+	var errb bytes.Buffer
+	fc := fakeClient{name: "fake", model: "m", resp: "OK"}
+	if err := RunWithClient(context.Background(), []string{"ask"}, f, &out, &errb, &fc); err != nil {
+		t.Fatalf("RunWithClient error: %v", err)
+	}
+	if out.String() != "OK" {
+		t.Fatalf("stdout want %q, got %q", "OK", out.String())
+	}
+	if !strings.Contains(errb.String(), "provider=fake model=m") {
+		t.Fatalf("missing banner: %q", errb.String())
+	}
+}
+
+func TestRunWithClient_Streaming(t *testing.T) {
+	restore, f := setStdin(t, "")
+	defer restore()
+	var out bytes.Buffer
+	var errb bytes.Buffer
+	fs := fakeStreamer{fakeClient: fakeClient{name: "fake", model: "m"}, chunks: []string{"A", "B"}}
+	if err := RunWithClient(context.Background(), []string{"ask"}, f, &out, &errb, &fs); err != nil {
+		t.Fatalf("RunWithClient error: %v", err)
+	}
+	if out.String() != "AB" {
+		t.Fatalf("stdout want %q, got %q", "AB", out.String())
+	}
+	if !strings.Contains(errb.String(), "provider=fake model=m") {
+		t.Fatalf("missing banner: %q", errb.String())
+	}
+}
+
+func TestRunWithClient_CombinedInput_UsesCombinedMessage(t *testing.T) {
+	restore, f := setStdin(t, "payload")
+	defer restore()
+	var out bytes.Buffer
+	var errb bytes.Buffer
+	fc := fakeClient{name: "fake", model: "m", resp: "OK"}
+	if err := RunWithClient(context.Background(), []string{"subject"}, f, &out, &errb, &fc); err != nil {
+		t.Fatalf("RunWithClient error: %v", err)
+	}
+	if out.String() != "OK" {
+		t.Fatalf("stdout want %q, got %q", "OK", out.String())
+	}
+	if len(fc.gotMsgs) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(fc.gotMsgs))
+	}
+	if fc.gotMsgs[1].Content != "subject:\n\npayload" {
+		t.Fatalf("unexpected user message: %q", fc.gotMsgs[1].Content)
+	}
+}
diff --git a/internal/hexaicli/testhelpers_test.go b/internal/hexaicli/testhelpers_test.go
new file mode 100644
index 0000000..4a25ff1
--- /dev/null
+++ b/internal/hexaicli/testhelpers_test.go
@@ -0,0 +1,63 @@
+// Summary: Test helpers for Hexai CLI tests (stdin swapping and fake LLM clients/streamers).
+// Not yet reviewed by a human
+package hexaicli
+
+import (
+    "context"
+    "os"
+    "path/filepath"
+    "testing"
+
+    "hexai/internal/llm"
+)
+
+// setStdin sets os.Stdin from a string and returns a restore func and reader.
+func setStdin(t *testing.T, content string) (func(), *os.File) {
+    t.Helper()
+    tmpDir := t.TempDir()
+    fpath := filepath.Join(tmpDir, "stdin.txt")
+    if err := os.WriteFile(fpath, []byte(content), 0o600); err != nil {
+        t.Fatalf("write temp stdin: %v", err)
+    }
+    f, err := os.Open(fpath)
+    if err != nil {
+        t.Fatalf("open temp stdin: %v", err)
+    }
+    old := os.Stdin
+    os.Stdin = f
+    restore := func() {
+        f.Close()
+        os.Stdin = old
+    }
+    return restore, f
+}
+
+// fakeClient implements llm.Client for tests.
+type fakeClient struct {
+    name    string
+    model   string
+    resp    string
+    gotMsgs []llm.Message
+}
+
+func (f *fakeClient) Chat(ctx context.Context, messages []llm.Message, opts ...llm.RequestOption) (string, error) {
+    f.gotMsgs = append([]llm.Message{}, messages...)
+    return f.resp, nil
+}
+func (f fakeClient) Name() string        { return f.name }
+func (f fakeClient) DefaultModel() string { return f.model }
+
+// fakeStreamer implements llm.Streamer over fakeClient.
+type fakeStreamer struct {
+    fakeClient
+    chunks []string
+    sMsgs  []llm.Message
+}
+
+func (s *fakeStreamer) ChatStream(ctx context.Context, messages []llm.Message, onDelta func(string), opts ...llm.RequestOption) error {
+    s.sMsgs = append([]llm.Message{}, messages...)
+    for _, c := range s.chunks {
+        onDelta(c)
+    }
+    return nil
+}
diff --git a/internal/hexailsp/run.go b/internal/hexailsp/run.go
new file mode 100644
index 0000000..2231fc2
--- /dev/null
+++ b/internal/hexailsp/run.go
@@ -0,0 +1,91 @@
+// Summary: Hexai LSP runner; configures logging, loads config, builds the LLM client,
+// and constructs/runs the LSP server (with injectable factory for tests).
+// Not yet reviewed by a human
+package hexailsp
+
+import (
+    "log"
+    "os"
+    "strings"
+    "io"
+
+    "hexai/internal/appconfig"
+    "hexai/internal/llm"
+    "hexai/internal/logging"
+    "hexai/internal/lsp"
+)
+
+// ServerRunner is the minimal interface satisfied by lsp.Server.
+type ServerRunner interface{ Run() error }
+
+// ServerFactory creates a ServerRunner. Default uses lsp.NewServer.
+type ServerFactory func(r io.Reader, w io.Writer, logger *log.Logger, opts lsp.ServerOptions) ServerRunner
+
+// Run configures logging, loads config, builds the LLM client and runs the LSP server.
+// It is thin and delegates to RunWithFactory for testability.
+func Run(logPath string, stdin io.Reader, stdout io.Writer, stderr io.Writer) error {
+    logger := log.New(stderr, "hexai-lsp ", log.LstdFlags|log.Lmsgprefix)
+    if strings.TrimSpace(logPath) != "" {
+        f, err := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+        if err != nil {
+            logger.Fatalf("failed to open log file: %v", err)
+        }
+        defer f.Close()
+        logger.SetOutput(f)
+    }
+    logging.Bind(logger)
+    cfg := appconfig.Load(logger)
+    return RunWithFactory(logPath, stdin, stdout, logger, cfg, nil, nil)
+}
+
+// RunWithFactory is the testable entrypoint. When client is nil, it is built from cfg+env.
+// When factory is nil, lsp.NewServer is used.
+func RunWithFactory(logPath string, stdin io.Reader, stdout io.Writer, logger *log.Logger, cfg appconfig.App, client llm.Client, factory ServerFactory) error {
+    // Normalize and apply logging config
+    cfg.ContextMode = strings.ToLower(strings.TrimSpace(cfg.ContextMode))
+    if cfg.LogPreviewLimit >= 0 {
+        logging.SetLogPreviewLimit(cfg.LogPreviewLimit)
+    }
+
+    // Build LLM client if not provided
+    if client == nil {
+        llmCfg := llm.Config{
+            Provider:       cfg.Provider,
+            OpenAIBaseURL:  cfg.OpenAIBaseURL,
+            OpenAIModel:    cfg.OpenAIModel,
+            OllamaBaseURL:  cfg.OllamaBaseURL,
+            OllamaModel:    cfg.OllamaModel,
+            CopilotBaseURL: cfg.CopilotBaseURL,
+            CopilotModel:   cfg.CopilotModel,
+        }
+        oaKey := os.Getenv("OPENAI_API_KEY")
+        cpKey := os.Getenv("COPILOT_API_KEY")
+        if c, err := llm.NewFromConfig(llmCfg, oaKey, cpKey); err != nil {
+            logging.Logf("lsp ", "llm disabled: %v", err)
+        } else {
+            client = c
+            logging.Logf("lsp ", "llm enabled provider=%s model=%s", c.Name(), c.DefaultModel())
+        }
+    }
+
+    if factory == nil {
+        factory = func(r io.Reader, w io.Writer, logger *log.Logger, opts lsp.ServerOptions) ServerRunner {
+            return lsp.NewServer(r, w, logger, opts)
+        }
+    }
+
+    server := factory(stdin, stdout, logger, lsp.ServerOptions{
+        LogContext:        strings.TrimSpace(logPath) != "",
+        MaxTokens:         cfg.MaxTokens,
+        ContextMode:       cfg.ContextMode,
+        WindowLines:       cfg.ContextWindowLines,
+        MaxContextTokens:  cfg.MaxContextTokens,
+        NoDiskIO:          cfg.NoDiskIO,
+        Client:            client,
+        TriggerCharacters: cfg.TriggerCharacters,
+    })
+    if err := server.Run(); err != nil {
+        logger.Fatalf("server error: %v", err)
+    }
+    return nil
+}
diff --git a/internal/hexailsp/run_test.go b/internal/hexailsp/run_test.go
new file mode 100644
index 0000000..2c0fcaf
--- /dev/null
+++ b/internal/hexailsp/run_test.go
@@ -0,0 +1,143 @@
+// Summary: Tests for the Hexai LSP runner using a fake server factory and environment keys.
+// Not yet reviewed by a human
+package hexailsp
+
+import (
+    "bytes"
+    "log"
+    "io"
+    "os"
+    "path/filepath"
+    "testing"
+
+    "hexai/internal/appconfig"
+    "hexai/internal/llm"
+    "hexai/internal/lsp"
+    "hexai/internal/logging"
+)
+
+// fake server capturing options and recording run calls
+type fakeServer struct{
+    ran bool
+    opts lsp.ServerOptions
+}
+func (f *fakeServer) Run() error { f.ran = true; return nil }
+
+func TestRunWithFactory_UsesDefaultsAndCallsServer(t *testing.T) {
+    var stderr bytes.Buffer
+    logger := log.New(&stderr, "hexai-lsp ", 0)
+    cfg := appconfig.Load(nil) // defaults
+    var gotOpts lsp.ServerOptions
+    factory := func(r io.Reader, w io.Writer, logger *log.Logger, opts lsp.ServerOptions) ServerRunner {
+        gotOpts = opts
+        return &fakeServer{opts: opts}
+    }
+    if err := RunWithFactory("", bytes.NewBuffer(nil), bytes.NewBuffer(nil), logger, cfg, nil, factory); err != nil {
+        t.Fatalf("RunWithFactory error: %v", err)
+    }
+    if gotOpts.MaxTokens != cfg.MaxTokens {
+        t.Fatalf("MaxTokens want %d got %d", cfg.MaxTokens, gotOpts.MaxTokens)
+    }
+    if gotOpts.ContextMode != cfg.ContextMode {
+        t.Fatalf("ContextMode want %q got %q", cfg.ContextMode, gotOpts.ContextMode)
+    }
+    if gotOpts.WindowLines != cfg.ContextWindowLines {
+        t.Fatalf("WindowLines want %d got %d", cfg.ContextWindowLines, gotOpts.WindowLines)
+    }
+    if gotOpts.MaxContextTokens != cfg.MaxContextTokens {
+        t.Fatalf("MaxContextTokens want %d got %d", cfg.MaxContextTokens, gotOpts.MaxContextTokens)
+    }
+    if gotOpts.NoDiskIO != cfg.NoDiskIO {
+        t.Fatalf("NoDiskIO want %v got %v", cfg.NoDiskIO, gotOpts.NoDiskIO)
+    }
+    if gotOpts.Client != nil { // with no env, openai client fails to build
+        t.Fatalf("expected nil client when API key missing")
+    }
+}
+
+func TestRunWithFactory_BuildsClientWhenKeysPresent(t *testing.T) {
+    // Set a dummy OpenAI key to allow client creation
+    old := os.Getenv("OPENAI_API_KEY")
+    t.Cleanup(func(){ _ = os.Setenv("OPENAI_API_KEY", old) })
+    _ = os.Setenv("OPENAI_API_KEY", "dummy")
+
+    var stderr bytes.Buffer
+    logger := log.New(&stderr, "hexai-lsp ", 0)
+    cfg := appconfig.Load(nil) // defaults, provider=openai by default
+    var got llm.Client
+    factory := func(r io.Reader, w io.Writer, logger *log.Logger, opts lsp.ServerOptions) ServerRunner {
+        got = opts.Client
+        return &fakeServer{opts: opts}
+    }
+    if err := RunWithFactory("", bytes.NewBuffer(nil), bytes.NewBuffer(nil), logger, cfg, nil, factory); err != nil {
+        t.Fatalf("RunWithFactory error: %v", err)
+    }
+    if got == nil {
+        t.Fatalf("expected non-nil client when OPENAI_API_KEY is set")
+    }
+}
+
+func TestRun_RespectsLogPathFlag(t *testing.T) {
+    tmp := t.TempDir()
+    logFile := filepath.Join(tmp, "hexai-lsp.log")
+    // Run with real Run but nil env key so client disabled; ensure no panic and file created
+    if err := Run(logFile, bytes.NewBuffer(nil), bytes.NewBuffer(nil), bytes.NewBuffer(nil)); err != nil {
+        t.Fatalf("Run error: %v", err)
+    }
+    if _, err := os.Stat(logFile); err != nil {
+        t.Fatalf("expected log file to be created: %v", err)
+    }
+}
+
+func TestRunWithFactory_NormalizesContextMode_AndSetsPreviewLimit(t *testing.T) {
+    t.Cleanup(func(){ logging.SetLogPreviewLimit(0) })
+    var stderr bytes.Buffer
+    logger := log.New(&stderr, "hexai-lsp ", 0)
+    cfg := appconfig.App{
+        ContextMode:     "  File-On-New-Func  ",
+        LogPreviewLimit: 3,
+    }
+    var gotOpts lsp.ServerOptions
+    factory := func(r io.Reader, w io.Writer, logger *log.Logger, opts lsp.ServerOptions) ServerRunner {
+        gotOpts = opts
+        return &fakeServer{opts: opts}
+    }
+    if err := RunWithFactory("", bytes.NewBuffer(nil), bytes.NewBuffer(nil), logger, cfg, nil, factory); err != nil {
+        t.Fatalf("RunWithFactory error: %v", err)
+    }
+    if gotOpts.ContextMode != "file-on-new-func" {
+        t.Fatalf("ContextMode not normalized: %q", gotOpts.ContextMode)
+    }
+    if logging.PreviewForLog("abcdef") != "abc…" {
+        t.Fatalf("PreviewForLog not respecting limit: %q", logging.PreviewForLog("abcdef"))
+    }
+}
+
+func TestRunWithFactory_LogContextFlag(t *testing.T) {
+    var stderr bytes.Buffer
+    logger := log.New(&stderr, "hexai-lsp ", 0)
+    cfg := appconfig.App{}
+    var got1, got2 lsp.ServerOptions
+    first := true
+    factory := func(r io.Reader, w io.Writer, logger *log.Logger, opts lsp.ServerOptions) ServerRunner {
+        if first {
+            got1 = opts
+            first = false
+        } else {
+            got2 = opts
+        }
+        return &fakeServer{opts: opts}
+    }
+    if err := RunWithFactory("/tmp/some.log", bytes.NewBuffer(nil), bytes.NewBuffer(nil), logger, cfg, nil, factory); err != nil {
+        t.Fatalf("RunWithFactory error: %v", err)
+    }
+    if !got1.LogContext {
+        t.Fatalf("expected LogContext true when logPath is non-empty")
+    }
+    if err := RunWithFactory("", bytes.NewBuffer(nil), bytes.NewBuffer(nil), logger, cfg, nil, factory); err != nil {
+        t.Fatalf("RunWithFactory error: %v", err)
+    }
+    if got2.LogContext {
+        t.Fatalf("expected LogContext false when logPath is empty")
+    }
+}
diff --git a/internal/llm/copilot.go b/internal/llm/copilot.go
index a31022f..1e36bb7 100644
--- a/internal/llm/copilot.go
+++ b/internal/llm/copilot.go
@@ -1,3 +1,5 @@
+// Summary: GitHub Copilot client implementation for chat completions using the Copilot API.
+// Not yet reviewed by a human
 package llm
 
 import (
diff --git a/internal/llm/ollama.go b/internal/llm/ollama.go
index ffee354..774eaf1 100644
--- a/internal/llm/ollama.go
+++ b/internal/llm/ollama.go
@@ -1,3 +1,5 @@
+// Summary: Ollama client against a local server; supports chat responses and streaming via /api/chat.
+// Not yet reviewed by a human
 package llm
 
 import (
diff --git a/internal/llm/openai.go b/internal/llm/openai.go
index 080d4e9..288622f 100644
--- a/internal/llm/openai.go
+++ b/internal/llm/openai.go
@@ -1,3 +1,5 @@
+// Summary: OpenAI client implementation for chat completions with optional streaming and detailed logging.
+// Not yet reviewed by a human
 package llm
 
 import (
diff --git a/internal/llm/provider.go b/internal/llm/provider.go
index 3e3023e..09e97e6 100644
--- a/internal/llm/provider.go
+++ b/internal/llm/provider.go
@@ -1,3 +1,5 @@
+// Summary: LLM provider interfaces, request options, configuration, and factory to build a client from config.
+// Not yet reviewed by a human
 package llm
 
 import (
diff --git a/internal/logging/logging.go b/internal/logging/logging.go
index 80231ab..b82ee99 100644
--- a/internal/logging/logging.go
+++ b/internal/logging/logging.go
@@ -1,3 +1,5 @@
+// Summary: ANSI-styled logging utilities with a bound standard logger and configurable preview truncation.
+// Not yet reviewed by a human
 package logging
 
 import (
diff --git a/internal/lsp/context.go b/internal/lsp/context.go
index e746058..02aa40a 100644
--- a/internal/lsp/context.go
+++ b/internal/lsp/context.go
@@ -1,3 +1,5 @@
+// Summary: Builds additional context snippets based on configured mode and truncates text by token heuristic.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/context_test.go b/internal/lsp/context_test.go
index fe5d73b..54553d6 100644
--- a/internal/lsp/context_test.go
+++ b/internal/lsp/context_test.go
@@ -1,3 +1,5 @@
+// Summary: Tests for context-building logic (window, full-file) and truncation behavior.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/document.go b/internal/lsp/document.go
index 05f024f..dbecd5e 100644
--- a/internal/lsp/document.go
+++ b/internal/lsp/document.go
@@ -1,3 +1,5 @@
+// Summary: In-memory document model for the LSP; tracks text, lines, and applies edits.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/document_test.go b/internal/lsp/document_test.go
index e8fa6bb..da17cc5 100644
--- a/internal/lsp/document_test.go
+++ b/internal/lsp/document_test.go
@@ -1,3 +1,5 @@
+// Summary: Tests for LSP document model (line management, edits, and transformations).
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/handlers.go b/internal/lsp/handlers.go
index a16affb..7903c73 100644
--- a/internal/lsp/handlers.go
+++ b/internal/lsp/handlers.go
@@ -1,3 +1,5 @@
+// Summary: LSP JSON-RPC handlers; implements core methods and integrates with the LLM client when enabled.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/handlers_test.go b/internal/lsp/handlers_test.go
index 0ba29cf..9a490e3 100644
--- a/internal/lsp/handlers_test.go
+++ b/internal/lsp/handlers_test.go
@@ -1,3 +1,5 @@
+// Summary: Tests for LSP handlers and request processing, including diagnostics and code actions.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/server.go b/internal/lsp/server.go
index cc7d88e..9fb02c3 100644
--- a/internal/lsp/server.go
+++ b/internal/lsp/server.go
@@ -1,3 +1,5 @@
+// Summary: Minimal LSP server over stdio; manages documents, dispatches requests, and tracks stats.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/transport.go b/internal/lsp/transport.go
index 4d352f8..0c63aa8 100644
--- a/internal/lsp/transport.go
+++ b/internal/lsp/transport.go
@@ -1,3 +1,5 @@
+// Summary: LSP transport utilities to read and write JSON-RPC messages with Content-Length framing.
+// Not yet reviewed by a human
 package lsp
 
 import (
diff --git a/internal/lsp/types.go b/internal/lsp/types.go
index dbd7331..42a315f 100644
--- a/internal/lsp/types.go
+++ b/internal/lsp/types.go
@@ -1,3 +1,5 @@
+// Summary: LSP protocol types used by the server (requests, responses, params, capabilities).
+// Not yet reviewed by a human
 package lsp
 
 import "encoding/json"
diff --git a/internal/version.go b/internal/version.go
index 0894830..a6b1527 100644
--- a/internal/version.go
+++ b/internal/version.go
@@ -1,3 +1,5 @@
+// Summary: Hexai semantic version identifier used by CLI and LSP binaries.
+// Not yet reviewed by a human
 package internal
 
 const Version = "0.1.0"