feat: static article handlers

cmd/commands.go

···
 	Create() *cobra.Command
 }
 
-// MovieCommand implements CommandGroup for movie-related commands
+// MovieCommand implements [CommandGroup] for movie-related commands
 type MovieCommand struct {
 	handler *handlers.MovieHandler
 }
···
 	return root
 }
 
-// BookCommand implements CommandGroup for book-related commands
+// BookCommand implements [CommandGroup] for book-related commands
 type BookCommand struct {
 	handler *handlers.BookHandler
 }
···
 
 	return root
 }
+
+// ArticleCommand implements [CommandGroup] for article-related commands
+type ArticleCommand struct {
+	handler *handlers.ArticleHandler
+}
+
+// NewArticleCommand creates a new ArticleCommand with the given handler
+func NewArticleCommand(handler *handlers.ArticleHandler) *ArticleCommand {
+	return &ArticleCommand{handler: handler}
+}
+
+func (c *ArticleCommand) Create() *cobra.Command {
+	root := &cobra.Command{Use: "article", Short: "Manage saved articles"}
+
+	addCmd := &cobra.Command{
+		Use:   "add <url>",
+		Short: "Parse and save article from URL",
+		Long: `Parse and save article content from a supported website.
+
+The article will be parsed using domain-specific XPath rules and saved
+as both Markdown and HTML files. Article metadata is stored in the database.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+
+			defer c.handler.Close()
+			return c.handler.Add(cmd.Context(), args[0])
+		},
+	}
+	root.AddCommand(addCmd)
+
+	listCmd := &cobra.Command{
+		Use:     "list [query]",
+		Short:   "List saved articles",
+		Aliases: []string{"ls"},
+		Long: `List saved articles with optional filtering.
+
+Use query to filter by title, or use flags for more specific filtering.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			author, _ := cmd.Flags().GetString("author")
+			limit, _ := cmd.Flags().GetInt("limit")
+
+			var query string
+			if len(args) > 0 {
+				query = strings.Join(args, " ")
+			}
+
+			defer c.handler.Close()
+			return c.handler.List(cmd.Context(), query, author, limit)
+		},
+	}
+	listCmd.Flags().String("author", "", "Filter by author")
+	listCmd.Flags().IntP("limit", "l", 0, "Limit number of results (0 = no limit)")
+	root.AddCommand(listCmd)
+
+	viewCmd := &cobra.Command{
+		Use:     "view <id>",
+		Short:   "View article details and content preview",
+		Aliases: []string{"show"},
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if articleID, err := parseID("article", args); err != nil {
+				return err
+			} else {
+				defer c.handler.Close()
+				return c.handler.View(cmd.Context(), articleID)
+			}
+		},
+	}
+	root.AddCommand(viewCmd)
+
+	removeCmd := &cobra.Command{
+		Use:     "remove <id>",
+		Short:   "Remove article and associated files",
+		Aliases: []string{"rm", "delete"},
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if articleID, err := parseID("article", args); err != nil {
+				return err
+			} else {
+				defer c.handler.Close()
+				return c.handler.Remove(cmd.Context(), articleID)
+			}
+		},
+	}
+	root.AddCommand(removeCmd)
+
+	originalHelpFunc := root.HelpFunc()
+	root.SetHelpFunc(func(cmd *cobra.Command, args []string) {
+		originalHelpFunc(cmd, args)
+
+		fmt.Println()
+		defer c.handler.Close()
+		c.handler.Help()
+	})
+
+	return root
+}

cmd/commands_test.go

···
 	}
 }
 
+func createTestArticleHandler(t *testing.T) (*handlers.ArticleHandler, func()) {
+	cleanup := setupCommandTest(t)
+	handler, err := handlers.NewArticleHandler()
+	if err != nil {
+		cleanup()
+		t.Fatalf("Failed to create test article handler: %v", err)
+	}
+	return handler, func() {
+		handler.Close()
+		cleanup()
+	}
+}
+
 func findSubcommand(commands []string, target string) bool {
 	return slices.Contains(commands, target)
 }
···
 		bookHandler, bookCleanup := createTestBookHandler(t)
 		defer bookCleanup()
 
+		articleHandler, articleCleanup := createTestArticleHandler(t)
+		defer articleCleanup()
+
 		var _ CommandGroup = NewTaskCommand(taskHandler)
 		var _ CommandGroup = NewMovieCommand(movieHandler)
 		var _ CommandGroup = NewTVCommand(tvHandler)
 		var _ CommandGroup = NewNoteCommand(noteHandler)
 		var _ CommandGroup = NewBookCommand(bookHandler)
+		var _ CommandGroup = NewArticleCommand(articleHandler)
 	})
 
 	t.Run("Create", func(t *testing.T) {
···
 			}
 		})
 
+		t.Run("ArticleCommand", func(t *testing.T) {
+			handler, cleanup := createTestArticleHandler(t)
+			defer cleanup()
+
+			commands := NewArticleCommand(handler)
+			cmd := commands.Create()
+
+			if cmd == nil {
+				t.Fatal("Create returned nil")
+			}
+			if cmd.Use != "article" {
+				t.Errorf("Expected Use to be 'article', got '%s'", cmd.Use)
+			}
+			if cmd.Short != "Manage saved articles" {
+				t.Errorf("Expected Short to be 'Manage saved articles', got '%s'", cmd.Short)
+			}
+			if !cmd.HasSubCommands() {
+				t.Error("Expected command to have subcommands")
+			}
+
+			subcommands := cmd.Commands()
+			subcommandNames := make([]string, len(subcommands))
+			for i, subcmd := range subcommands {
+				subcommandNames[i] = subcmd.Use
+			}
+
+			for _, expected := range []string{"add <url>", "list [query]", "view <id>", "remove <id>"} {
+				if !findSubcommand(subcommandNames, expected) {
+					t.Errorf("Expected subcommand '%s' not found in %v", expected, subcommandNames)
+				}
+			}
+		})
+
 		t.Run("all command groups implement Create", func(t *testing.T) {
 			taskHandler, taskCleanup := createTestTaskHandler(t)
 			defer taskCleanup()
···
 			bookHandler, bookCleanup := createTestBookHandler(t)
 			defer bookCleanup()
 
+			articleHandler, articleCleanup := createTestArticleHandler(t)
+			defer articleCleanup()
+
 			groups := []CommandGroup{
 				NewTaskCommand(taskHandler),
 				NewMovieCommand(movieHandler),
 				NewTVCommand(tvHandler),
 				NewNoteCommand(noteHandler),
 				NewBookCommand(bookHandler),
+				NewArticleCommand(articleHandler),
 			}
 
 			for i, group := range groups {
···
 			err := cmd.Execute()
 			if err == nil {
 				t.Error("expected book update command to fail with invalid status")
+			}
+		})
+	})
+
+	t.Run("Article Commands", func(t *testing.T) {
+		handler, cleanup := createTestArticleHandler(t)
+		defer cleanup()
+
+		t.Run("list command - default", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"list"})
+			err := cmd.Execute()
+			if err != nil {
+				t.Errorf("article list command failed: %v", err)
+			}
+		})
+
+		t.Run("help command", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"help"})
+			err := cmd.Execute()
+			if err != nil {
+				t.Errorf("article help command failed: %v", err)
+			}
+		})
+
+		t.Run("add command with empty args", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"add"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Error("expected article add command to fail with empty args")
+			}
+		})
+
+		t.Run("add command with invalid URL", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"add", "not-a-url"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Error("expected article add command to fail with invalid URL")
+			}
+		})
+
+		t.Run("view command with non-existent article ID", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"view", "999"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Error("expected article view command to fail with non-existent ID")
+			}
+		})
+
+		t.Run("view command with non-numeric ID", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"view", "invalid"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Error("expected article view command to fail with non-numeric ID")
+			}
+		})
+
+		t.Run("remove command with non-existent article ID", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"remove", "999"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Error("expected article remove command to fail with non-existent ID")
+			}
+		})
+
+		t.Run("remove command with non-numeric ID", func(t *testing.T) {
+			cmd := NewArticleCommand(handler).Create()
+			cmd.SetArgs([]string{"remove", "invalid"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Error("expected article remove command to fail with non-numeric ID")
 			}
 		})
 	})

cmd/main.go

···
 		log.Fatalf("failed to create book handler: %v", err)
 	}
 
+	articleHandler, err := handlers.NewArticleHandler()
+	if err != nil {
+		log.Fatalf("failed to create article handler: %v", err)
+	}
+
 	root := rootCmd()
 
 	coreGroups := []CommandGroup{
 		NewTaskCommand(taskHandler),
 		NewNoteCommand(noteHandler),
+		NewArticleCommand(articleHandler),
 	}
 
 	for _, group := range coreGroups {

docs/cli.md

···
 Handlers are created once in `main.go` during application startup. Initialization errors prevent application launch rather than causing runtime failures.
 Handlers persist for the application lifetime without requiring cleanup. Commands access handlers through struct fields rather than creating new instances.
 
-### Testing Benefits
+### Testing
 
 `CommandGroup` structs accept handlers as constructor parameters, enabling easy dependency injection of mock handlers for testing.
 Command logic can be tested independently of handler implementations. The interface allows mocking entire command groups for integration testing.
 
-### Registry Pattern
+### Registry
 
 `main.go` uses a registry pattern to organize command groups by category. Core commands include task, note, and media functionality.
 Management commands handle configuration, setup, and maintenance operations. The pattern provides clean separation and easy extension for new command groups.
+
+## UI and Styling System
+
+The application uses a structured color palette system located in `internal/ui/colors.go` for consistent terminal output styling.
+
+### Color Architecture
+
+The color system implements a `Key` type with 74 predefined colors from the Charm ecosystem, including warm tones (Cumin, Tang, Paprika), cool tones (Sapphire, Oceania, Zinc), and neutral grays (Pepper through Butter). Each color provides hex values via the `Hex()` method and implements Go's `color.Color` interface through `RGBA()`.
+
+### Predefined Styles
+
+Three core lipgloss styles handle common UI elements:
+
+- `TitleColorStyle` uses color 212 with bold formatting for command titles
+- `SelectedColorStyle` provides white-on-212 highlighting for selected items
+- `HeaderColorStyle` applies color 240 with bold formatting for section headers
+
+### Color Categories
+
+Colors are organized into primary, secondary, and tertiary categories are accessed through `IsPrimary()`, `IsSecondary()`, and `IsTertiary()` methods on the `Key` type.
+
+### Lipgloss Integration
+
+The styling system integrates with the Charmbracelet lipgloss library for terminal UI rendering.
+Colors from the `Key` type convert to lipgloss color values through their `Hex()` method. The predefined `TitleColorStyle`, `SelectedColorStyle`, and `HeaderColorStyle` variables provide lipgloss styles that can be applied to strings with `.Render()`.

internal/handlers/articles.go

···
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/stormlightlabs/noteleaf/internal/articles"
+	"github.com/stormlightlabs/noteleaf/internal/models"
+	"github.com/stormlightlabs/noteleaf/internal/repo"
+	"github.com/stormlightlabs/noteleaf/internal/store"
+	"github.com/stormlightlabs/noteleaf/internal/ui"
+	"github.com/stormlightlabs/noteleaf/internal/utils"
+)
+
+// ArticleHandler handles all article-related commands
+type ArticleHandler struct {
+	db     *store.Database
+	config *store.Config
+	repos  *repo.Repositories
+	parser articles.Parser
+}
+
+// NewArticleHandler creates a new article handler
+func NewArticleHandler() (*ArticleHandler, error) {
+	db, err := store.NewDatabase()
+	if err != nil {
+		return nil, fmt.Errorf("failed to initialize database: %w", err)
+	}
+
+	config, err := store.LoadConfig()
+	if err != nil {
+		return nil, fmt.Errorf("failed to load configuration: %w", err)
+	}
+
+	repos := repo.NewRepositories(db.DB)
+
+	parser, err := articles.NewArticleParser(http.DefaultClient)
+	if err != nil {
+		return nil, fmt.Errorf("failed to initialize article parser: %w", err)
+	}
+
+	return &ArticleHandler{
+		db:     db,
+		config: config,
+		repos:  repos,
+		parser: parser,
+	}, nil
+}
+
+// Close cleans up resources
+func (h *ArticleHandler) Close() error {
+	if h.db != nil {
+		return h.db.Close()
+	}
+	return nil
+}
+
+// Add handles adding an article from a URL
+func (h *ArticleHandler) Add(ctx context.Context, url string) error {
+	logger := utils.GetLogger()
+
+	existing, err := h.repos.Articles.GetByURL(ctx, url)
+	if err == nil {
+		fmt.Printf("Article already exists: %s (ID: %d)\n", ui.TitleColorStyle.Render(existing.Title), existing.ID)
+		return nil
+	}
+
+	logger.Info("Parsing article", "url", url)
+	fmt.Printf("Parsing article from: %s\n", url)
+
+	dir, err := h.getStorageDirectory()
+	if err != nil {
+		return fmt.Errorf("failed to get article storage dir %w", err)
+	}
+
+	content, err := h.parser.ParseURL(url)
+	if err != nil {
+		return fmt.Errorf("failed to parse article: %w", err)
+	}
+
+	mdPath, htmlPath, err := h.parser.SaveArticle(content, dir)
+	if err != nil {
+		return fmt.Errorf("failed to save article: %w", err)
+	}
+
+	article := &models.Article{
+		URL:          url,
+		Title:        content.Title,
+		Author:       content.Author,
+		Date:         content.Date,
+		MarkdownPath: mdPath,
+		HTMLPath:     htmlPath,
+		Created:      time.Now(),
+		Modified:     time.Now(),
+	}
+
+	id, err := h.repos.Articles.Create(ctx, article)
+	if err != nil {
+		os.Remove(article.MarkdownPath)
+		os.Remove(article.HTMLPath)
+		return fmt.Errorf("failed to save article to database: %w", err)
+	}
+
+	fmt.Printf("Article saved successfully!\n")
+	fmt.Printf("ID: %d\n", id)
+	fmt.Printf("Title: %s\n", ui.TitleColorStyle.Render(article.Title))
+	if article.Author != "" {
+		fmt.Printf("Author: %s\n", ui.HeaderColorStyle.Render(article.Author))
+	}
+	if article.Date != "" {
+		fmt.Printf("Date: %s\n", article.Date)
+	}
+	fmt.Printf("Markdown: %s\n", article.MarkdownPath)
+	fmt.Printf("HTML: %s\n", article.HTMLPath)
+
+	logger.Info("Article saved", "id", id, "title", article.Title)
+
+	return nil
+}
+
+// List handles listing articles with optional filtering
+func (h *ArticleHandler) List(ctx context.Context, query string, author string, limit int) error {
+	opts := &repo.ArticleListOptions{
+		Title:  query,
+		Author: author,
+		Limit:  limit,
+	}
+
+	articles, err := h.repos.Articles.List(ctx, opts)
+	if err != nil {
+		return fmt.Errorf("failed to list articles: %w", err)
+	}
+
+	if len(articles) == 0 {
+		fmt.Println("No articles found.")
+		return nil
+	}
+
+	fmt.Printf("Found %d article(s):\n\n", len(articles))
+
+	for _, article := range articles {
+		fmt.Printf("ID: %d\n", article.ID)
+		fmt.Printf("Title: %s\n", ui.TitleColorStyle.Render(article.Title))
+		if article.Author != "" {
+			fmt.Printf("Author: %s\n", ui.HeaderColorStyle.Render(article.Author))
+		}
+		if article.Date != "" {
+			fmt.Printf("Date: %s\n", article.Date)
+		}
+		fmt.Printf("URL: %s\n", article.URL)
+		fmt.Printf("Added: %s\n", article.Created.Format("2006-01-02 15:04:05"))
+		fmt.Println("---")
+	}
+
+	return nil
+}
+
+// View handles viewing an article by ID
+func (h *ArticleHandler) View(ctx context.Context, id int64) error {
+
+	article, err := h.repos.Articles.Get(ctx, id)
+	if err != nil {
+		return fmt.Errorf("failed to get article: %w", err)
+	}
+
+	fmt.Printf("Title: %s\n", ui.TitleColorStyle.Render(article.Title))
+	if article.Author != "" {
+		fmt.Printf("Author: %s\n", ui.HeaderColorStyle.Render(article.Author))
+	}
+	if article.Date != "" {
+		fmt.Printf("Date: %s\n", article.Date)
+	}
+	fmt.Printf("URL: %s\n", article.URL)
+	fmt.Printf("Added: %s\n", article.Created.Format("2006-01-02 15:04:05"))
+	fmt.Printf("Modified: %s\n", article.Modified.Format("2006-01-02 15:04:05"))
+	fmt.Println()
+
+	fmt.Printf("Markdown file: %s", article.MarkdownPath)
+	if _, err := os.Stat(article.MarkdownPath); os.IsNotExist(err) {
+		fmt.Printf(" (file not found)")
+	}
+	fmt.Println()
+
+	fmt.Printf("HTML file: %s", article.HTMLPath)
+	if _, err := os.Stat(article.HTMLPath); os.IsNotExist(err) {
+		fmt.Printf(" (file not found)")
+	}
+	fmt.Println()
+
+	if _, err := os.Stat(article.MarkdownPath); err == nil {
+		fmt.Printf("\n%s\n", ui.HeaderColorStyle.Render("--- Content Preview ---"))
+		content, err := os.ReadFile(article.MarkdownPath)
+		if err == nil {
+			lines := strings.Split(string(content), "\n")
+			previewLines := min(len(lines), 20)
+
+			for i := range previewLines {
+				fmt.Println(lines[i])
+			}
+
+			if len(lines) > previewLines {
+				fmt.Printf("\n... (%d more lines)\n", len(lines)-previewLines)
+				fmt.Printf("Read full content: %s\n", article.MarkdownPath)
+			}
+		}
+	}
+
+	return nil
+}
+
+// Remove handles removing an article by ID
+func (h *ArticleHandler) Remove(ctx context.Context, id int64) error {
+	article, err := h.repos.Articles.Get(ctx, id)
+	if err != nil {
+		return fmt.Errorf("failed to get article: %w", err)
+	}
+
+	err = h.repos.Articles.Delete(ctx, id)
+	if err != nil {
+		return fmt.Errorf("failed to remove article from database: %w", err)
+	}
+
+	if _, err := os.Stat(article.MarkdownPath); err == nil {
+		if rmErr := os.Remove(article.MarkdownPath); rmErr != nil {
+			fmt.Printf("Warning: failed to remove markdown file: %v\n", rmErr)
+		}
+	}
+
+	if _, err := os.Stat(article.HTMLPath); err == nil {
+		if rmErr := os.Remove(article.HTMLPath); rmErr != nil {
+			fmt.Printf("Warning: failed to remove HTML file: %v\n", rmErr)
+		}
+	}
+
+	fmt.Printf("Article removed: %s (ID: %d)\n", ui.TitleColorStyle.Render(article.Title), id)
+
+	return nil
+}
+
+// Help shows supported domains (to complement default cobra/fang help)
+func (h *ArticleHandler) Help() error {
+	domains := h.parser.GetSupportedDomains()
+
+	fmt.Println()
+
+	if len(domains) > 0 {
+		fmt.Printf("%s\n", ui.HeaderColorStyle.Render(fmt.Sprintf("Supported sites (%d):", len(domains))))
+		for _, domain := range domains {
+			fmt.Printf("  - %s\n", domain)
+		}
+	} else {
+		fmt.Println("No parsing rules loaded.")
+	}
+
+	fmt.Println()
+	dir, err := h.getStorageDirectory()
+	if err != nil {
+		return fmt.Errorf("failed to get storage directory: %w", err)
+	}
+	fmt.Printf("%s %s\n", ui.HeaderColorStyle.Render("Storage directory:"), dir)
+
+	return nil
+}
+
+// TODO: Try to get from config first (could be added later)
+// For now, use default ~/Documents/Leaf/
+func (h *ArticleHandler) getStorageDirectory() (string, error) {
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+
+	return filepath.Join(homeDir, "Documents", "Leaf"), nil
+}

internal/handlers/articles_test.go

···
+package handlers
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stormlightlabs/noteleaf/internal/articles"
+	"github.com/stormlightlabs/noteleaf/internal/models"
+	"github.com/stormlightlabs/noteleaf/internal/repo"
+)
+
+func TestArticleHandler(t *testing.T) {
+	t.Run("NewArticleHandler", func(t *testing.T) {
+		t.Run("creates handler successfully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+
+			if helper.ArticleHandler == nil {
+				t.Fatal("Handler should not be nil")
+			}
+
+			if helper.db == nil {
+				t.Error("Handler database should not be nil")
+			}
+			if helper.config == nil {
+				t.Error("Handler config should not be nil")
+			}
+			if helper.repos == nil {
+				t.Error("Handler repos should not be nil")
+			}
+			if helper.parser == nil {
+				t.Error("Handler parser should not be nil")
+			}
+		})
+
+		t.Run("handles database initialization error", func(t *testing.T) {
+			envHelper := NewEnvironmentTestHelper()
+			defer envHelper.RestoreEnv()
+
+			if runtime.GOOS == "windows" {
+				envHelper.UnsetEnv("APPDATA")
+			} else {
+				envHelper.UnsetEnv("XDG_CONFIG_HOME")
+				envHelper.UnsetEnv("HOME")
+			}
+
+			_, err := NewArticleHandler()
+			Expect.AssertError(t, err, "failed to initialize database", "NewArticleHandler should fail when database initialization fails")
+		})
+
+	})
+
+	t.Run("Add", func(t *testing.T) {
+		t.Run("adds article successfully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte(`<html>
+					<head><title>Test Article</title></head>
+					<body>
+						<h1 id="firstHeading">Test Article Title</h1>
+						<div class="author">Test Author</div>
+						<div class="date">2024-01-01</div>
+						<div id="bodyContent">
+							<p>This is test content for the article.</p>
+						</div>
+					</body>
+				</html>`))
+			}))
+			defer server.Close()
+
+			testRule := &articles.ParsingRule{
+				Domain: "127.0.0.1",
+				Title:  "//h1[@id='firstHeading']",
+				Author: "//div[@class='author']",
+				Date:   "//div[@class='date']",
+				Body:   "//div[@id='bodyContent']",
+			}
+			helper.AddTestRule("127.0.0.1", testRule)
+
+			err := helper.Add(ctx, server.URL+"/test-article")
+			Expect.AssertNoError(t, err, "Add should succeed with valid URL")
+
+			articles, err := helper.repos.Articles.List(ctx, &repo.ArticleListOptions{})
+			if err != nil {
+				t.Fatalf("Failed to list articles: %v", err)
+			}
+
+			if len(articles) != 1 {
+				t.Errorf("Expected 1 article, got %d", len(articles))
+			}
+
+			article := articles[0]
+			if article.Title != "Test Article Title" {
+				t.Errorf("Expected title 'Test Article Title', got '%s'", article.Title)
+			}
+			if article.Author != "Test Author" {
+				t.Errorf("Expected author 'Test Author', got '%s'", article.Author)
+			}
+		})
+
+		t.Run("handles duplicate article", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			duplicateURL := "https://example.com/duplicate"
+
+			existingArticle := &models.Article{
+				URL:          duplicateURL,
+				Title:        "Existing Article",
+				Author:       "Existing Author",
+				Date:         "2024-01-01",
+				MarkdownPath: "/path/to/existing.md",
+				HTMLPath:     "/path/to/existing.html",
+				Created:      time.Now(),
+				Modified:     time.Now(),
+			}
+
+			_, err := helper.repos.Articles.Create(ctx, existingArticle)
+			if err != nil {
+				t.Fatalf("Failed to create existing article: %v", err)
+			}
+
+			err = helper.Add(ctx, duplicateURL)
+			Expect.AssertNoError(t, err, "Add should succeed with duplicate URL and return existing")
+		})
+
+		t.Run("handles unsupported domain", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte("<html><head><title>Test</title></head><body><p>Content</p></body></html>"))
+			}))
+			defer server.Close()
+
+			err := helper.Add(ctx, server.URL+"/unsupported")
+			Expect.AssertError(t, err, "failed to parse article", "Add should fail with unsupported domain")
+		})
+
+		t.Run("handles HTTP error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusNotFound)
+			}))
+			defer server.Close()
+
+			err := helper.Add(ctx, server.URL+"/404")
+			Expect.AssertError(t, err, "failed to parse article", "Add should fail with HTTP error")
+		})
+
+		t.Run("handles storage directory error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			envHelper := NewEnvironmentTestHelper()
+			defer envHelper.RestoreEnv()
+
+			if runtime.GOOS == "windows" {
+				envHelper.UnsetEnv("USERPROFILE")
+				envHelper.UnsetEnv("HOMEDRIVE")
+				envHelper.UnsetEnv("HOMEPATH")
+			} else {
+				envHelper.UnsetEnv("HOME")
+			}
+
+			err := helper.Add(ctx, "https://example.com/test-article")
+			Expect.AssertError(t, err, "failed to get article storage dir", "Add should fail when storage directory cannot be determined")
+		})
+
+		t.Run("handles database save error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte(`<html>
+					<head><title>Test Article</title></head>
+					<body>
+						<h1 id="firstHeading">Test Article</h1>
+						<div id="bodyContent">Test content</div>
+					</body>
+				</html>`))
+			}))
+			defer server.Close()
+
+			testRule := &articles.ParsingRule{
+				Domain: "127.0.0.1",
+				Title:  "//h1[@id='firstHeading']",
+				Body:   "//div[@id='bodyContent']",
+			}
+			helper.AddTestRule("127.0.0.1", testRule)
+
+			helper.db.Exec("DROP TABLE articles")
+
+			err := helper.Add(ctx, server.URL+"/test")
+			Expect.AssertError(t, err, "failed to save article to database", "Add should fail when database save fails")
+		})
+	})
+
+	t.Run("List", func(t *testing.T) {
+		t.Run("lists all articles", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			id1 := helper.CreateTestArticle(t, "https://example.com/article1", "First Article", "John Doe", "2024-01-01")
+			id2 := helper.CreateTestArticle(t, "https://example.com/article2", "Second Article", "Jane Smith", "2024-01-02")
+
+			err := helper.List(ctx, "", "", 0)
+			Expect.AssertNoError(t, err, "List should succeed")
+
+			Expect.AssertArticleExists(t, helper, id1)
+			Expect.AssertArticleExists(t, helper, id2)
+		})
+
+		t.Run("lists with title filter", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			helper.CreateTestArticle(t, "https://example.com/first", "First Article", "John", "2024-01-01")
+			helper.CreateTestArticle(t, "https://example.com/second", "Second Article", "Jane", "2024-01-02")
+
+			err := helper.List(ctx, "First", "", 0)
+			Expect.AssertNoError(t, err, "List with title filter should succeed")
+		})
+
+		t.Run("lists with author filter", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			helper.CreateTestArticle(t, "https://example.com/john1", "Article by John", "John Doe", "2024-01-01")
+			helper.CreateTestArticle(t, "https://example.com/jane1", "Article by Jane", "Jane Smith", "2024-01-02")
+
+			err := helper.List(ctx, "", "John", 0)
+			Expect.AssertNoError(t, err, "List with author filter should succeed")
+		})
+
+		t.Run("lists with limit", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			helper.CreateTestArticle(t, "https://example.com/1", "Article 1", "Author", "2024-01-01")
+			helper.CreateTestArticle(t, "https://example.com/2", "Article 2", "Author", "2024-01-02")
+			helper.CreateTestArticle(t, "https://example.com/3", "Article 3", "Author", "2024-01-03")
+
+			err := helper.List(ctx, "", "", 2)
+			Expect.AssertNoError(t, err, "List with limit should succeed")
+		})
+
+		t.Run("handles empty results", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			err := helper.List(ctx, "nonexistent", "", 0)
+			Expect.AssertNoError(t, err, "List with no matches should succeed")
+		})
+
+		t.Run("handles database error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			helper.db.Exec("DROP TABLE articles")
+
+			err := helper.List(ctx, "", "", 0)
+			Expect.AssertError(t, err, "failed to list articles", "List should fail when database is corrupted")
+		})
+	})
+
+	t.Run("View", func(t *testing.T) {
+		t.Run("views article successfully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			id := helper.CreateTestArticle(t, "https://example.com/test", "Test Article", "Test Author", "2024-01-01")
+
+			err := helper.View(ctx, id)
+			Expect.AssertNoError(t, err, "View should succeed with valid article ID")
+		})
+
+		t.Run("handles non-existent article", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			err := helper.View(ctx, 99999)
+			Expect.AssertError(t, err, "failed to get article", "View should fail with non-existent article ID")
+		})
+
+		t.Run("handles missing files gracefully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			article := &models.Article{
+				URL:          "https://example.com/missing-files",
+				Title:        "Missing Files Article",
+				Author:       "Test Author",
+				Date:         "2024-01-01",
+				MarkdownPath: "/non/existent/path.md",
+				HTMLPath:     "/non/existent/path.html",
+				Created:      time.Now(),
+				Modified:     time.Now(),
+			}
+
+			id, err := helper.repos.Articles.Create(ctx, article)
+			if err != nil {
+				t.Fatalf("Failed to create article with missing files: %v", err)
+			}
+
+			err = helper.View(ctx, id)
+			Expect.AssertNoError(t, err, "View should succeed even when files are missing")
+		})
+
+		t.Run("handles database error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			helper.db.Exec("DROP TABLE articles")
+
+			err := helper.View(ctx, 1)
+			Expect.AssertError(t, err, "failed to get article", "View should fail when database is corrupted")
+		})
+	})
+
+	t.Run("Remove", func(t *testing.T) {
+		t.Run("removes article successfully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			id := helper.CreateTestArticle(t, "https://example.com/remove", "Remove Test", "Author", "2024-01-01")
+
+			Expect.AssertArticleExists(t, helper, id)
+
+			err := helper.Remove(ctx, id)
+			Expect.AssertNoError(t, err, "Remove should succeed")
+
+			Expect.AssertArticleNotExists(t, helper, id)
+		})
+
+		t.Run("handles non-existent article", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			err := helper.Remove(ctx, 99999)
+			Expect.AssertError(t, err, "failed to get article", "Remove should fail with non-existent article ID")
+		})
+
+		t.Run("handles missing files gracefully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			article := &models.Article{
+				URL:          "https://example.com/missing-files",
+				Title:        "Missing Files Article",
+				Author:       "Test Author",
+				Date:         "2024-01-01",
+				MarkdownPath: "/non/existent/path.md",
+				HTMLPath:     "/non/existent/path.html",
+				Created:      time.Now(),
+				Modified:     time.Now(),
+			}
+
+			id, err := helper.repos.Articles.Create(ctx, article)
+			if err != nil {
+				t.Fatalf("Failed to create article with missing files: %v", err)
+			}
+
+			err = helper.Remove(ctx, id)
+			Expect.AssertNoError(t, err, "Remove should succeed even when files don't exist")
+		})
+
+		t.Run("handles database error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			ctx := context.Background()
+
+			id := helper.CreateTestArticle(t, "https://example.com/db-error", "DB Error Test", "Author", "2024-01-01")
+
+			helper.db.Exec("DROP TABLE articles")
+
+			err := helper.Remove(ctx, id)
+			Expect.AssertError(t, err, "failed to get article", "Remove should fail when database is corrupted")
+		})
+	})
+
+	t.Run("Help", func(t *testing.T) {
+		t.Run("shows supported domains", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+
+			err := helper.Help()
+			Expect.AssertNoError(t, err, "Help should succeed")
+		})
+
+		t.Run("handles storage directory error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+
+			envHelper := NewEnvironmentTestHelper()
+			defer envHelper.RestoreEnv()
+
+			if runtime.GOOS == "windows" {
+				envHelper.UnsetEnv("USERPROFILE")
+				envHelper.UnsetEnv("HOMEDRIVE")
+				envHelper.UnsetEnv("HOMEPATH")
+			} else {
+				envHelper.UnsetEnv("HOME")
+			}
+
+			err := helper.Help()
+			Expect.AssertError(t, err, "failed to get storage directory", "Help should fail when storage directory cannot be determined")
+		})
+	})
+
+	t.Run("Close", func(t *testing.T) {
+		t.Run("closes successfully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+
+			err := helper.Close()
+			Expect.AssertNoError(t, err, "Close should succeed")
+		})
+
+		t.Run("handles nil database gracefully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+			helper.db = nil
+
+			err := helper.Close()
+			Expect.AssertNoError(t, err, "Close should succeed with nil database")
+		})
+	})
+
+	t.Run("getStorageDirectory", func(t *testing.T) {
+		t.Run("returns storage directory successfully", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+
+			dir, err := helper.getStorageDirectory()
+			Expect.AssertNoError(t, err, "getStorageDirectory should succeed")
+
+			if dir == "" {
+				t.Error("Storage directory should not be empty")
+			}
+
+			if !strings.Contains(dir, "Documents/Leaf") {
+				t.Errorf("Expected storage directory to contain 'Documents/Leaf', got: %s", dir)
+			}
+		})
+
+		t.Run("handles user home directory error", func(t *testing.T) {
+			helper := NewArticleTestHelper(t)
+
+			envHelper := NewEnvironmentTestHelper()
+			defer envHelper.RestoreEnv()
+
+			if runtime.GOOS == "windows" {
+				envHelper.UnsetEnv("USERPROFILE")
+				envHelper.UnsetEnv("HOMEDRIVE")
+				envHelper.UnsetEnv("HOMEPATH")
+			} else {
+				envHelper.UnsetEnv("HOME")
+			}
+
+			_, err := helper.getStorageDirectory()
+			Expect.AssertError(t, err, "", "getStorageDirectory should fail when home directory cannot be determined")
+		})
+	})
+}
+
+func TestArticleHandlerIntegration(t *testing.T) {
+	t.Run("end-to-end workflow", func(t *testing.T) {
+		helper := NewArticleTestHelper(t)
+		ctx := context.Background()
+
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(`<html>
+				<head><title>Integration Test Article</title></head>
+				<body>
+					<h1 id="firstHeading">Integration Test Article</h1>
+					<div class="author">Integration Author</div>
+					<div id="bodyContent">
+						<p>Integration test content.</p>
+					</div>
+				</body>
+			</html>`))
+		}))
+		defer server.Close()
+
+		testRule := &articles.ParsingRule{
+			Domain: "127.0.0.1",
+			Title:  "//h1[@id='firstHeading']",
+			Author: "//div[@class='author']",
+			Body:   "//div[@id='bodyContent']",
+		}
+		helper.AddTestRule("127.0.0.1", testRule)
+
+		err := helper.Add(ctx, server.URL+"/integration-test")
+		Expect.AssertNoError(t, err, "Add should succeed in integration test")
+
+		err = helper.List(ctx, "", "", 0)
+		Expect.AssertNoError(t, err, "List should succeed in integration test")
+
+		articles, err := helper.repos.Articles.List(ctx, &repo.ArticleListOptions{})
+		if err != nil {
+			t.Fatalf("Failed to get articles for integration test: %v", err)
+		}
+
+		if len(articles) == 0 {
+			t.Fatal("Expected at least one article for integration test")
+		}
+
+		articleID := articles[0].ID
+
+		err = helper.View(ctx, articleID)
+		Expect.AssertNoError(t, err, "View should succeed in integration test")
+
+		err = helper.Help()
+		Expect.AssertNoError(t, err, "Help should succeed in integration test")
+
+		err = helper.Remove(ctx, articleID)
+		Expect.AssertNoError(t, err, "Remove should succeed in integration test")
+
+		Expect.AssertArticleNotExists(t, helper, articleID)
+	})
+}

internal/handlers/test_utilities.go

···
 	"testing"
 	"time"
 
+	"github.com/stormlightlabs/noteleaf/internal/articles"
 	"github.com/stormlightlabs/noteleaf/internal/models"
 	"github.com/stormlightlabs/noteleaf/internal/store"
 )
···
 	}
 }
 
+// AssertArticleExists checks that an article exists in the database
+func (ah AssertionHelpers) AssertArticleExists(t *testing.T, handler *ArticleTestHelper, id int64) {
+	t.Helper()
+	ctx := context.Background()
+	_, err := handler.repos.Articles.Get(ctx, id)
+	if err != nil {
+		t.Errorf("Article %d should exist but got error: %v", id, err)
+	}
+}
+
+// AssertArticleNotExists checks that an article does not exist in the database
+func (ah AssertionHelpers) AssertArticleNotExists(t *testing.T, handler *ArticleTestHelper, id int64) {
+	t.Helper()
+	ctx := context.Background()
+	_, err := handler.repos.Articles.Get(ctx, id)
+	if err == nil {
+		t.Errorf("Article %d should not exist but was found", id)
+	}
+}
+
 // EnvironmentTestHelper provides environment manipulation utilities for testing
 type EnvironmentTestHelper struct {
 	originalVars map[string]string
···
 	}
 }
 
+// CreateTestDir creates a temporary test directory and sets up environment
+func (eth *EnvironmentTestHelper) CreateTestDir(t *testing.T) (string, error) {
+	tempDir, err := os.MkdirTemp("", "noteleaf-test-*")
+	if err != nil {
+		return "", err
+	}
+
+	eth.SetEnv("XDG_CONFIG_HOME", tempDir)
+
+	ctx := context.Background()
+	err = Setup(ctx, []string{})
+	if err != nil {
+		os.RemoveAll(tempDir)
+		return "", err
+	}
+
+	t.Cleanup(func() {
+		eth.RestoreEnv()
+		os.RemoveAll(tempDir)
+	})
+
+	return tempDir, nil
+}
+
 // Helper function to check if string contains substring (case-insensitive)
 func containsString(haystack, needle string) bool {
 	if needle == "" {
···
 		os.Remove(file)
 	}
 	fth.tempFiles = nil
+}
+
+// ArticleTestHelper wraps ArticleHandler with test-specific functionality
+type ArticleTestHelper struct {
+	*ArticleHandler
+	tempDir string
+	cleanup func()
+}
+
+// NewArticleTestHelper creates an ArticleHandler with isolated test database
+func NewArticleTestHelper(t *testing.T) *ArticleTestHelper {
+	tempDir, err := os.MkdirTemp("", "noteleaf-article-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+
+	oldConfigHome := os.Getenv("XDG_CONFIG_HOME")
+	os.Setenv("XDG_CONFIG_HOME", tempDir)
+
+	cleanup := func() {
+		os.Setenv("XDG_CONFIG_HOME", oldConfigHome)
+		os.RemoveAll(tempDir)
+	}
+
+	ctx := context.Background()
+	err = Setup(ctx, []string{})
+	if err != nil {
+		cleanup()
+		t.Fatalf("Failed to setup database: %v", err)
+	}
+
+	handler, err := NewArticleHandler()
+	if err != nil {
+		cleanup()
+		t.Fatalf("Failed to create article handler: %v", err)
+	}
+
+	testHelper := &ArticleTestHelper{
+		ArticleHandler: handler,
+		tempDir:        tempDir,
+		cleanup:        cleanup,
+	}
+
+	t.Cleanup(func() {
+		testHelper.Close()
+		testHelper.cleanup()
+	})
+
+	return testHelper
+}
+
+// CreateTestArticle creates a test article and returns its ID
+func (ath *ArticleTestHelper) CreateTestArticle(t *testing.T, url, title, author, date string) int64 {
+	ctx := context.Background()
+
+	mdPath := filepath.Join(ath.tempDir, fmt.Sprintf("%s.md", title))
+	htmlPath := filepath.Join(ath.tempDir, fmt.Sprintf("%s.html", title))
+
+	mdContent := fmt.Sprintf("# %s\n\n**Author:** %s\n**Date:** %s\n\nTest content", title, author, date)
+	err := os.WriteFile(mdPath, []byte(mdContent), 0644)
+	if err != nil {
+		t.Fatalf("Failed to create test markdown file: %v", err)
+	}
+
+	htmlContent := fmt.Sprintf("<h1>%s</h1><p>Author: %s</p><p>Date: %s</p><p>Test content</p>", title, author, date)
+	err = os.WriteFile(htmlPath, []byte(htmlContent), 0644)
+	if err != nil {
+		t.Fatalf("Failed to create test HTML file: %v", err)
+	}
+
+	article := &models.Article{
+		URL:          url,
+		Title:        title,
+		Author:       author,
+		Date:         date,
+		MarkdownPath: mdPath,
+		HTMLPath:     htmlPath,
+		Created:      time.Now(),
+		Modified:     time.Now(),
+	}
+
+	id, err := ath.repos.Articles.Create(ctx, article)
+	if err != nil {
+		t.Fatalf("Failed to create test article: %v", err)
+	}
+	return id
+}
+
+// AddTestRule adds a parsing rule to the handler's parser for testing
+func (ath *ArticleTestHelper) AddTestRule(domain string, rule *articles.ParsingRule) {
+	if parser, ok := ath.parser.(*articles.ArticleParser); ok {
+		parser.AddRule(domain, rule)
+	} else {
+		panic("Could not cast parser to ArticleParser")
+	}
 }
 
 var Expect = AssertionHelpers{}