diff --git a/pkg/cli/cli.go b/pkg/cli/cli.go
index c85a988..c3f515c 100644
--- a/pkg/cli/cli.go
+++ b/pkg/cli/cli.go
@@ -1,3 +1,4 @@
+// Package cli provides the command-line interface for the PM System.
 package cli
 
 import (
@@ -7,7 +8,7 @@ import (
 	"github.com/LazyBachelor/LazyPM/pkg/cli/commands"
 )
 
-// CLIConfig is an alias for service.Config, which contains all the necessary
+// CLIConfig is an alias for service.Config, used to configure the CLI.
 type CLIConfig = service.Config
 
 // Run initializes the services and executes the CLI commands.
diff --git a/pkg/cli/repl/completer.go b/pkg/cli/repl/completer.go
index 9cb119a..99d1b21 100644
--- a/pkg/cli/repl/completer.go
+++ b/pkg/cli/repl/completer.go
@@ -6,23 +6,28 @@ import (
 	"github.com/c-bata/go-prompt"
 )
 
+// completer provides suggestions for the REPL input based on the current input text.
 func completer(d prompt.Document) []prompt.Suggest {
-	text := d.TextBeforeCursor()
-	words := strings.Fields(text)
+	text := d.TextBeforeCursor()  // Gets the text before the cursor as a string.
+	words := strings.Fields(text) // Split the string into words as []string.
 
+	// If there are no words, return no suggestions.
 	if len(words) == 0 {
 		return nil
 	}
 
+	// If the first word is not "pm", only provide root-level suggestions.
 	if words[0] != "pm" {
 		return filterByPrefix(rootSuggestions, words[0])
 	}
 
+	// If the first word is "pm", provide command and flag suggestions based on the context.
 	pmWords := words[1:]
 	if len(words) == 1 || (len(pmWords) == 1 && !strings.HasSuffix(text, " ")) {
 		return commandSuggestions(pmWords)
 	}
 
+	// If the last word starts with a "-", provide flag suggestions for the current command.
 	if len(pmWords) >= 1 {
 		return flagSuggestions(pmWords[0], pmWords, text)
 	}
diff --git a/pkg/cli/repl/executor.go b/pkg/cli/repl/executor.go
index 0ec939f..c0c50a7 100644
--- a/pkg/cli/repl/executor.go
+++ b/pkg/cli/repl/executor.go
@@ -7,6 +7,9 @@ import (
 	"github.com/LazyBachelor/LazyPM/pkg/cli/commands"
 )
 
+// execute processes the input command and returns the output
+// or an error if it occurs. It handles what type of command is being executed,
+// whether it's a PM command or a shell command, and routes it accordingly.
 func execute(input string) (string, error) {
 	if input == "" {
 		return "", nil
@@ -26,6 +29,8 @@ func execute(input string) (string, error) {
 	return executeShellCommand(input)
 }
 
+// executeShellCommand executes a shell command
+// and returns its output or an error if it occurs.
 func executeShellCommand(input string) (string, error) {
 	parts := strings.Fields(input)
 	if len(parts) == 0 {
@@ -37,6 +42,8 @@ func executeShellCommand(input string) (string, error) {
 	return string(output), err
 }
 
+// executePMCommand executes a PM command using the commands package
+// and returns its output or an error if it occurs.
 func executePMCommand(input string) (string, error) {
 	parts := strings.Fields(input)
 	if len(parts) == 0 {
diff --git a/pkg/cli/repl/options.go b/pkg/cli/repl/options.go
index 7ba4e63..0d0918c 100644
--- a/pkg/cli/repl/options.go
+++ b/pkg/cli/repl/options.go
@@ -5,13 +5,8 @@ import "github.com/c-bata/go-prompt"
 const PromptPrefix = "> "
 const OptionMaxSuggestions = 5
 
-const (
-	ReplHelp = `Type 'pm help' for available PM commands.
-You can also run shell commands directly. Type 'exit' or 'quit' to leave.`
-
-	ReplTitle = "Welcome to Project Management CLI! " + ReplHelp
-)
-
+// promptOptions returns a slice of prompt.Option
+// to configure the behavior and appearance of the REPL prompt.
 func promptOptions(history []string) []prompt.Option {
 	return []prompt.Option{
 		prompt.OptionPrefixTextColor(prompt.Cyan),
diff --git a/pkg/cli/repl/repl.go b/pkg/cli/repl/repl.go
index b00fa75..cba9569 100644
--- a/pkg/cli/repl/repl.go
+++ b/pkg/cli/repl/repl.go
@@ -1,3 +1,4 @@
+// Package repl implements the Read-Eval-Print Loop (REPL) for the PM CLI.
 package repl
 
 import (
@@ -14,45 +15,63 @@ import (
 	"golang.org/x/term"
 )
 
+const (
+	ReplHelp = `Type 'pm help' for available PM commands.
+You can also run shell commands directly. Type 'exit' or 'quit' to leave.`
+
+	ReplTitle = "Welcome to Project Management CLI! " + ReplHelp
+)
+
+// RunREPL starts the interactive Read-Eval-Print Loop for the PM CLI.
 func RunREPL(ctx context.Context, config cli.CLIConfig) error {
+	// Set terminal to raw mode to capture input properly in the REPL.
+	// This allows us to handle input character by character and provide a better user experience.
+	// We also ensure that the terminal state is restored when the REPL exits, even if an error occurs.
 	oldState, err := term.GetState(int(os.Stdin.Fd()))
 	if err != nil {
 		return fmt.Errorf("failed to get terminal state: %w", err)
 	}
 	defer term.Restore(int(os.Stdin.Fd()), oldState)
 
+	// Initialize services for beads, config and stats.
 	svc, cleanup, err := service.NewServices(ctx, config)
 	if err != nil {
 		return fmt.Errorf("failed to initialize services: %w", err)
 	}
 	defer cleanup()
 
+	// Make sure to set services, to ensure they are available.
 	commands.SetServices(svc)
 
-	fmt.Println(styles.TitleStyle.Render(ReplTitle))
+	fmt.Println(styles.TitleStyle.Render(ReplTitle)) // Print REPL title.
 
+	// history keeps track of command history.
+	// This enables navigating through previous commands.
 	var history []string
 
+	// Start the REPL loop, which continues until the user types "exit" or "quit".
 	for {
+		// Prompt the user for input, and provide suggestions.
 		input := prompt.Input(
 			PromptPrefix,
 			completer,
 			promptOptions(history)...,
 		)
 
+		// Trim whitespace from the input to ensure consistent command processing.
 		input = strings.TrimSpace(input)
 
+		// If the user types "exit" or "quit", break the loop and exit the REPL.
 		if input == "exit" || input == "quit" {
 			fmt.Println("Goodbye!")
 			break
 		}
 
+		// Add the input to the history for future navigation.
 		history = append(history, input)
 
-		// Ignore errors for now, gives better ux
-		output, _ := execute(input)
-
-		fmt.Println(styles.CommandStyle.Render(output))
+		output, _ := execute(input)                     // Ignore errors for now, gives better ux
+		fmt.Println(styles.CommandStyle.Render(output)) // Print the output of the command in a styled format.
 	}
 
 	return nil
diff --git a/pkg/cli/repl/suggestions.go b/pkg/cli/repl/suggestions.go
index cf8b925..bc347b2 100644
--- a/pkg/cli/repl/suggestions.go
+++ b/pkg/cli/repl/suggestions.go
@@ -9,6 +9,7 @@ import (
 	"github.com/muesli/reflow/truncate"
 )
 
+// rootSuggestions is a list of prompt suggestions for root-level commands.
 var rootSuggestions = []prompt.Suggest{
 	{Text: "pm", Description: "Project Management System"},
 	{Text: "exit", Description: "Exit pm CLI"},
@@ -17,6 +18,7 @@ var rootSuggestions = []prompt.Suggest{
 	{Text: "git", Description: "Version control system"},
 }
 
+// commandSuggestions is a list of prompt suggestions for PM commands.
 var baseSuggestions = []prompt.Suggest{
 	{Text: "help", Description: "Show help information"},
 	{Text: "delete", Description: "Delete an issue by ID"},
@@ -26,6 +28,7 @@ var baseSuggestions = []prompt.Suggest{
 	{Text: "list", Description: "List all issues"},
 }
 
+// createFlags is a list of prompt suggestions for the create command flags.
 var createFlags = []prompt.Suggest{
 	{Text: "--desc", Description: "Issue description"},
 	{Text: "--status", Description: "Issue status (open, closed, in_progress)"},
@@ -33,6 +36,7 @@ var createFlags = []prompt.Suggest{
 	{Text: "--priority", Description: "Issue priority (0-5)"},
 }
 
+// listFlags is a list of prompt suggestions for the list command flags.
 var listFlags = []prompt.Suggest{
 	{Text: "--title", Description: "Filter by title"},
 	{Text: "--desc", Description: "Filter by description"},
@@ -42,27 +46,42 @@ var listFlags = []prompt.Suggest{
 	{Text: "--limit", Description: "Limit number of results"},
 }
 
+// statusValues is a list of prompt suggestions for status types
 var statusValues = []prompt.Suggest{
 	{Text: "open", Description: "Open status"},
 	{Text: "closed", Description: "Closed status"},
 	{Text: "in_progress", Description: "In progress status"},
 }
 
+// typeValues is a list of prompt suggestions for issue types
 var typeValues = []prompt.Suggest{
 	{Text: "bug", Description: "Bug issue type"},
 	{Text: "feature", Description: "Feature issue type"},
 	{Text: "task", Description: "Task issue type"},
 }
 
+// priorityValues is a list of prompt suggestions for issue priority levels
 var priorityValues = []prompt.Suggest{
 	{Text: "0", Description: "Lowest priority"},
 	{Text: "1", Description: "Low priority"},
 	{Text: "2", Description: "Medium-low priority"},
 	{Text: "3", Description: "Medium priority"},
 	{Text: "4", Description: "High priority"},
-	{Text: "5", Description: "Highest priority"},
 }
 
+// isIDCommand maps command names to a boolean indicating whether they expect an issue ID as an argument.
+var isIDCommand = map[string]bool{
+	"describe": true,
+	"delete":   true,
+	"del":      true,
+	"rm":       true,
+	"remove":   true,
+	"get":      true,
+	"read":     true,
+	"close":    true,
+}
+
+// commandSuggestions returns a list of prompt suggestions based on the current input words.
 func commandSuggestions(words []string) []prompt.Suggest {
 	if len(words) == 0 {
 		return baseSuggestions
@@ -70,6 +89,7 @@ func commandSuggestions(words []string) []prompt.Suggest {
 	return filterByPrefix(baseSuggestions, words[0])
 }
 
+// flagSuggestions returns a list of prompt suggestions for command flags based on the current input.
 func flagSuggestions(cmd string, words []string, text string) []prompt.Suggest {
 	lastWord, prevWord := parseWords(words, text)
 
@@ -77,8 +97,7 @@ func flagSuggestions(cmd string, words []string, text string) []prompt.Suggest {
 		return filterByPrefix(values, lastWord)
 	}
 
-	if cmd == "describe" || cmd == "delete" || cmd == "del" ||
-		cmd == "rm" || cmd == "remove" || cmd == "get" || cmd == "read" || cmd == "close" {
+	if isIDCommand[cmd] {
 		// For ID-oriented commands, pass the current partial argument (lastWord)
 		// so issueIDSuggestions can distinguish between completing the command
 		// name and completing the ID itself.
@@ -101,6 +120,7 @@ func flagSuggestions(cmd string, words []string, text string) []prompt.Suggest {
 	return filterByPrefix(flags, lastWord)
 }
 
+// issueIDSuggestions returns a list of prompt suggestions for issue IDs based on the current partial input.
 func issueIDSuggestions(partial string, hasCommand bool) []prompt.Suggest {
 	// Only show suggestions if we've typed the command already
 	if !hasCommand {
@@ -119,6 +139,7 @@ func issueIDSuggestions(partial string, hasCommand bool) []prompt.Suggest {
 	return suggestions
 }
 
+// parseWords extracts the last and previous words from the input for flag suggestion logic.
 func parseWords(words []string, text string) (lastWord, prevWord string) {
 	if len(words) > 0 && !strings.HasSuffix(text, " ") {
 		lastWord = words[len(words)-1]
@@ -131,6 +152,7 @@ func parseWords(words []string, text string) (lastWord, prevWord string) {
 	return
 }
 
+// getFlagValues returns a list of prompt suggestions for flag values based on the given flag.
 func getFlagValues(flag string) []prompt.Suggest {
 	switch flag {
 	case "-s", "--status":
@@ -143,6 +165,7 @@ func getFlagValues(flag string) []prompt.Suggest {
 	return nil
 }
 
+// filterByPrefix filters a list of prompt suggestions based on a given prefix.
 func filterByPrefix(suggestions []prompt.Suggest, prefix string) []prompt.Suggest {
 	if prefix == "" {
 		return suggestions