docs: cleanup documentation & add migrations for leaflet fields

* scaffold for leaflet integration

Author: desertthunder

README.md

@@ -5,17 +5,6 @@
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Go Version](https://img.shields.io/github/go-mod/go-version/stormlightlabs/noteleaf)](go.mod)
 
-```sh
-                                    ,,                       ,...
-`7MN.   `7MF'         mm          `7MM                     .d' ""
-  MMN.    M           MM            MM                     dM`
-  M YMb   M  ,pW"Wq.mmMMmm .gP"Ya   MM  .gP"Ya   ,6"Yb.   mMMmm
-  M  `MN. M 6W'   `Wb MM  ,M'   Yb  MM ,M'   Yb 8)   MM    MM
-  M   `MM.M 8M     M8 MM  8M""""""  MM 8M""""""  ,pm9MM    MM
-  M     YMM YA.   ,A9 MM  YM.    ,  MM YM.    , 8M   MM    MM
-.JML.    YM  `Ybmd9'  `Mbmo`Mbmmd'.JMML.`Mbmmd' `Moo9^Yo..JMML.
-```
-
 Noteleaf is a unified personal productivity CLI that combines task management, note-taking, and media tracking in one place.
 It provides TaskWarrior-inspired task management with additional support for notes, articles, books, movies, and TV shows - all built with Golang & Charm.sh libs. Inspired by TaskWarrior & todo.txt CLI applications.
 
@@ -72,8 +61,6 @@ noteleaf docgen --format docusaurus --out ./website/docs/manual
 
 ### Completed
 
-Core functionality is complete and stable:
-
 - Task management with projects and tags
 - Note-taking system
 - Article parsing from URLs

cmd/main.go

@@ -17,13 +17,14 @@ import (
 )
 
 var (
-	newTaskHandler    = handlers.NewTaskHandler
-	newMovieHandler   = handlers.NewMovieHandler
-	newTVHandler      = handlers.NewTVHandler
-	newNoteHandler    = handlers.NewNoteHandler
-	newBookHandler    = handlers.NewBookHandler
-	newArticleHandler = handlers.NewArticleHandler
-	exc               = fang.Execute
+	newTaskHandler        = handlers.NewTaskHandler
+	newMovieHandler       = handlers.NewMovieHandler
+	newTVHandler          = handlers.NewTVHandler
+	newNoteHandler        = handlers.NewNoteHandler
+	newBookHandler        = handlers.NewBookHandler
+	newArticleHandler     = handlers.NewArticleHandler
+	newPublicationHandler = handlers.NewPublicationHandler
+	exc                   = fang.Execute
 )
 
 // App represents the main CLI application
@@ -206,10 +207,17 @@ func run() int {
 		return 1
 	}
 
+	publicationHandler, err := newPublicationHandler()
+	if err != nil {
+		log.Error("failed to create publication handler", "err", err)
+		return 1
+	}
+
 	root := rootCmd()
 
 	coreGroups := []CommandGroup{
 		NewTaskCommand(taskHandler), NewNoteCommand(noteHandler), NewArticleCommand(articleHandler),
+		NewPublicationCommand(publicationHandler),
 	}
 
 	for _, group := range coreGroups {

cmd/publication_commands.go

@@ -0,0 +1,154 @@
+// TODO: implement prompt for password
+//
+//	See: https://github.com/charmbracelet/bubbletea/blob/main/examples/textinputs/main.go
+package main
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"github.com/stormlightlabs/noteleaf/internal/handlers"
+)
+
+// PublicationCommand implements [CommandGroup] for leaflet publication commands
+type PublicationCommand struct {
+	handler *handlers.PublicationHandler
+}
+
+// NewPublicationCommand creates a new [PublicationCommand] with the given handler
+func NewPublicationCommand(handler *handlers.PublicationHandler) *PublicationCommand {
+	return &PublicationCommand{handler: handler}
+}
+
+func (c *PublicationCommand) Create() *cobra.Command {
+	root := &cobra.Command{
+		Use:   "pub",
+		Short: "Manage leaflet publication sync",
+		Long: `Sync notes with leaflet.pub (AT Protocol publishing platform).
+
+Authenticate with your BlueSky account to pull drafts and published documents
+from leaflet.pub into your local notes. Track publication status and manage
+your writing workflow across platforms.
+
+Authentication uses AT Protocol (the same system as BlueSky). You'll need:
+- BlueSky handle (e.g., username.bsky.social)
+- App password (generated at bsky.app/settings/app-passwords)
+
+Getting Started:
+  1. Authenticate: noteleaf pub auth <handle>
+  2. Pull documents: noteleaf pub pull
+  3. List publications: noteleaf pub list`,
+	}
+
+	authCmd := &cobra.Command{
+		Use:   "auth [handle]",
+		Short: "Authenticate with BlueSky/leaflet",
+		Long: `Authenticate with AT Protocol (BlueSky) for leaflet access.
+
+Your handle is typically: username.bsky.social
+
+For the password, use an app password (not your main password):
+1. Go to bsky.app/settings/app-passwords
+2. Create a new app password named "noteleaf"
+3. Use that password here
+
+The password will be prompted securely if not provided via flag.`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var handle string
+			if len(args) > 0 {
+				handle = args[0]
+			}
+
+			password, _ := cmd.Flags().GetString("password")
+
+			if handle == "" {
+				return fmt.Errorf("handle is required")
+			}
+
+			if password == "" {
+				return fmt.Errorf("password is required (use --password flag)")
+			}
+
+			defer c.handler.Close()
+			return c.handler.Auth(cmd.Context(), handle, password)
+		},
+	}
+	authCmd.Flags().StringP("password", "p", "", "App password (will be prompted if not provided)")
+	root.AddCommand(authCmd)
+
+	pullCmd := &cobra.Command{
+		Use:   "pull",
+		Short: "Pull documents from leaflet",
+		Long: `Fetch all drafts and published documents from leaflet.pub.
+
+This will:
+- Connect to your BlueSky/leaflet account
+- Fetch all documents in your repository
+- Create new notes for documents not yet synced
+- Update existing notes that have changed
+
+Notes are matched by their leaflet record key (rkey) stored in the database.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			defer c.handler.Close()
+			return c.handler.Pull(cmd.Context())
+		},
+	}
+	root.AddCommand(pullCmd)
+
+	// List command
+	listCmd := &cobra.Command{
+		Use:     "list [--published|--draft|--all]",
+		Short:   "List notes synced with leaflet",
+		Aliases: []string{"ls"},
+		Long: `Display notes that have been pulled from or pushed to leaflet.
+
+Shows publication metadata including:
+- Publication status (draft vs published)
+- Published date
+- Leaflet record key (rkey)
+- Content identifier (cid) for change tracking
+
+Use filters to show specific subsets:
+  --published  Show only published documents
+  --draft      Show only drafts
+  --all        Show all leaflet documents (default)`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			published, _ := cmd.Flags().GetBool("published")
+			draft, _ := cmd.Flags().GetBool("draft")
+			all, _ := cmd.Flags().GetBool("all")
+
+			filter := "all"
+			if published {
+				filter = "published"
+			} else if draft {
+				filter = "draft"
+			} else if all {
+				filter = "all"
+			}
+
+			defer c.handler.Close()
+			return c.handler.List(cmd.Context(), filter)
+		},
+	}
+	listCmd.Flags().Bool("published", false, "Show only published documents")
+	listCmd.Flags().Bool("draft", false, "Show only drafts")
+	listCmd.Flags().Bool("all", false, "Show all leaflet documents")
+	root.AddCommand(listCmd)
+
+	statusCmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show leaflet authentication status",
+		Long:  "Display current authentication status and session information.",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			defer c.handler.Close()
+			status := c.handler.GetAuthStatus()
+			fmt.Println("Leaflet Status:")
+			fmt.Printf("  %s\n", status)
+			return nil
+		},
+	}
+	root.AddCommand(statusCmd)
+
+	return root
+}

ROADMAP.md internal/docs/ROADMAP.mdROADMAP.md renamed to internal/docs/ROADMAP.md

@@ -0,0 +1,125 @@
+// TODO: Store credentials securely in [PublicationHandler.Auth]
+// Options:
+//  1. Use system keyring (go-keyring)
+//  2. Store encrypted in config file
+//  3. Store in environment variables
+//
+// TODO: Implement document processing
+// For each document:
+//  1. Check if note with this leaflet_rkey exists
+//  2. If exists: Update note content, title, metadata
+//  3. If new: Create new note with leaflet metadata
+//  4. Convert document blocks to markdown
+//  5. Save to database
+//
+// TODO: Implement list functionality
+//  1. Query notes where leaflet_rkey IS NOT NULL
+//  2. Apply filter (published vs draft) - "all", "published", "draft", or empty (default: all)
+//  3. Use prior art from package ui and other handlers to render
+//
+// TODO: Implmenent pull command
+//  1. Authenticates with AT Protocol
+//  2. Fetches all pub.leaflet.document records
+//  3. Creates new notes for documents not seen before
+//  4. Updates existing notes (matched by leaflet_rkey)
+//  5. Shows summary of pulled documents
+package handlers
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/stormlightlabs/noteleaf/internal/repo"
+	"github.com/stormlightlabs/noteleaf/internal/services"
+	"github.com/stormlightlabs/noteleaf/internal/store"
+)
+
+// PublicationHandler handles leaflet publication commands
+type PublicationHandler struct {
+	db      *store.Database
+	config  *store.Config
+	repos   *repo.Repositories
+	atproto *services.ATProtoService
+}
+
+// NewPublicationHandler creates a new publication handler
+func NewPublicationHandler() (*PublicationHandler, 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)
+	atproto := services.NewATProtoService()
+
+	return &PublicationHandler{
+		db:      db,
+		config:  config,
+		repos:   repos,
+		atproto: atproto,
+	}, nil
+}
+
+// Close cleans up resources
+func (h *PublicationHandler) Close() error {
+	if h.atproto != nil {
+		if err := h.atproto.Close(); err != nil {
+			return err
+		}
+	}
+	if h.db != nil {
+		return h.db.Close()
+	}
+	return nil
+}
+
+// Auth handles authentication with BlueSky/leaflet
+func (h *PublicationHandler) Auth(ctx context.Context, handle, password string) error {
+	if handle == "" {
+		return fmt.Errorf("handle is required")
+	}
+
+	if password == "" {
+		return fmt.Errorf("password is required")
+	}
+
+	fmt.Printf("Authenticating as %s...\n", handle)
+
+	if err := h.atproto.Authenticate(ctx, handle, password); err != nil {
+		return fmt.Errorf("authentication failed: %w", err)
+	}
+
+	fmt.Println("✓ Authentication successful!")
+	fmt.Println("TODO: Implement persistent credential storage")
+	return nil
+}
+
+// Pull fetches all documents from leaflet and creates/updates local notes
+func (h *PublicationHandler) Pull(ctx context.Context) error {
+	fmt.Println("TODO: Implement document conversion and note creation")
+	return nil
+}
+
+// List displays notes with leaflet publication metadata, showing all notes that
+// have been pulled from or pushed to leaflet
+func (h *PublicationHandler) List(ctx context.Context, filter string) error {
+	fmt.Println("TODO: Implement leaflet document listing")
+	return nil
+}
+
+// GetAuthStatus returns the current authentication status
+func (h *PublicationHandler) GetAuthStatus() string {
+	if h.atproto.IsAuthenticated() {
+		session, _ := h.atproto.GetSession()
+		if session != nil {
+			return fmt.Sprintf("Authenticated as %s", session.Handle)
+		}
+		return "Authenticated (session details unavailable)"
+	}
+	return "Not authenticated"
+}