docs: cleanup documentation & add migrations for leaflet fields

* scaffold for leaflet integration

README.md

···
 [![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.
 
···
 **Status**: Work in Progress (MVP completed)
 
 ### Completed
-
-Core functionality is complete and stable:
 
 - Task management with projects and tags
 - Note-taking system

cmd/main.go

···
 )
 
 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
···
 		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

···
+// 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
+}

internal/handlers/publication.go

···
+// 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"
+}

internal/models/models.go

···
 
 // Note represents a markdown note
 type Note struct {
-	ID       int64     `json:"id"`
-	Title    string    `json:"title"`
-	Content  string    `json:"content"`
-	Tags     []string  `json:"tags,omitempty"`
-	Archived bool      `json:"archived"`
-	Created  time.Time `json:"created"`
-	Modified time.Time `json:"modified"`
-	FilePath string    `json:"file_path,omitempty"`
+	ID          int64      `json:"id"`
+	Title       string     `json:"title"`
+	Content     string     `json:"content"`
+	Tags        []string   `json:"tags,omitempty"`
+	Archived    bool       `json:"archived"`
+	Created     time.Time  `json:"created"`
+	Modified    time.Time  `json:"modified"`
+	FilePath    string     `json:"file_path,omitempty"`
+	LeafletRKey *string    `json:"leaflet_rkey,omitempty"` // Leaflet record key
+	LeafletCID  *string    `json:"leaflet_cid,omitempty"`  // Leaflet content identifier
+	PublishedAt *time.Time `json:"published_at,omitempty"` // Publication timestamp
+	IsDraft     bool       `json:"is_draft"`               // Draft vs published status
 }
 
 // Album represents a music album
···
 func (t *Task) IsDeleted() bool { return t.Status == "deleted" }
 
 // HasPriority returns true if the task has a priority set
-func (t *Task) HasPriority() bool { return t.Priority != "" }
-
+func (t *Task) HasPriority() bool  { return t.Priority != "" }
 func (t *Task) IsTodo() bool       { return t.Status == StatusTodo }
 func (t *Task) IsInProgress() bool { return t.Status == StatusInProgress }
 func (t *Task) IsBlocked() bool    { return t.Status == StatusBlocked }
···
 // IsArchived returns true if the note is archived
 func (n *Note) IsArchived() bool {
 	return n.Archived
+}
+
+// HasLeafletAssociation returns true if the note is associated with a leaflet document
+func (n *Note) HasLeafletAssociation() bool {
+	return n.LeafletRKey != nil
+}
+
+// IsPublished returns true if the note is published on leaflet (not a draft)
+func (n *Note) IsPublished() bool {
+	return n.HasLeafletAssociation() && !n.IsDraft
 }
 
 func (n *Note) GetID() int64                { return n.ID }

internal/models/models_test.go

···
 				t.Error("Expected nil tags for empty string")
 			}
 		})
+
+		t.Run("Leaflet Association Methods", func(t *testing.T) {
+			t.Run("has no leaflet association by default", func(t *testing.T) {
+				note := &Note{}
+				if note.HasLeafletAssociation() {
+					t.Error("Note with nil leaflet_rkey should not have association")
+				}
+			})
+
+			t.Run("has leaflet association when rkey is set", func(t *testing.T) {
+				rkey := "test-rkey-123"
+				note := &Note{LeafletRKey: &rkey}
+
+				if !note.HasLeafletAssociation() {
+					t.Error("Note with leaflet_rkey should have association")
+				}
+			})
+
+			t.Run("is not published by default", func(t *testing.T) {
+				note := &Note{IsDraft: true}
+				if note.IsPublished() {
+					t.Error("Draft note should not be published")
+				}
+			})
+
+			t.Run("is published when has association and not draft", func(t *testing.T) {
+				rkey := "published-rkey"
+				note := &Note{
+					LeafletRKey: &rkey,
+					IsDraft:     false,
+				}
+				if !note.IsPublished() {
+					t.Error("Note with leaflet association and not draft should be published")
+				}
+			})
+
+			t.Run("tracks publication metadata", func(t *testing.T) {
+				rkey := "test-rkey"
+				cid := "test-cid"
+				pubTime := time.Now()
+
+				note := &Note{
+					Title:       "Test Note",
+					Content:     "Test content",
+					LeafletRKey: &rkey,
+					LeafletCID:  &cid,
+					PublishedAt: &pubTime,
+					IsDraft:     false,
+				}
+
+				if !note.HasLeafletAssociation() {
+					t.Error("Note should have leaflet association")
+				}
+
+				if !note.IsPublished() {
+					t.Error("Note should be published")
+				}
+
+				if note.LeafletRKey == nil || *note.LeafletRKey != rkey {
+					t.Errorf("Expected rkey %s, got %v", rkey, note.LeafletRKey)
+				}
+
+				if note.LeafletCID == nil || *note.LeafletCID != cid {
+					t.Errorf("Expected cid %s, got %v", cid, note.LeafletCID)
+				}
+
+				if note.PublishedAt == nil || !note.PublishedAt.Equal(pubTime) {
+					t.Errorf("Expected published_at %v, got %v", pubTime, note.PublishedAt)
+				}
+			})
+
+			t.Run("handles draft status", func(t *testing.T) {
+				rkey := "draft-rkey"
+				note := &Note{
+					Title:       "Draft Note",
+					Content:     "Draft content",
+					LeafletRKey: &rkey,
+					IsDraft:     true,
+				}
+
+				if !note.HasLeafletAssociation() {
+					t.Error("Draft should still have leaflet association")
+				}
+
+				if note.IsPublished() {
+					t.Error("Draft should not be published")
+				}
+			})
+		})
 	})
 
 	t.Run("Album Model", func(t *testing.T) {

internal/public/convert.go

···
+// Package public provides conversion between markdown and leaflet block formats
+//
+// TODO: Handle overlapping facets
+// TODO: Implement image handling - requires blob resolution
+package public
+
+import (
+	"bytes"
+	"fmt"
+	"strings"
+
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/gomarkdown/markdown/parser"
+)
+
+// Converter defines the interface for converting between a document and leaflet formats
+type Converter interface {
+	// ToLeaflet converts content to leaflet blocks
+	ToLeaflet(content string) ([]BlockWrap, error)
+	// FromLeaflet converts leaflet blocks back to the original format
+	FromLeaflet(blocks []BlockWrap) (string, error)
+}
+
+// MarkdownConverter implements the [Converter] interface
+type MarkdownConverter struct {
+	extensions parser.Extensions
+}
+
+type formatContext struct {
+	features []FacetFeature
+	start    int
+}
+
+// NewMarkdownConverter creates a new markdown converter
+func NewMarkdownConverter() *MarkdownConverter {
+	extensions := parser.CommonExtensions | parser.AutoHeadingIDs
+	return &MarkdownConverter{
+		extensions: extensions,
+	}
+}
+
+// ToLeaflet converts markdown to leaflet blocks
+func (c *MarkdownConverter) ToLeaflet(markdown string) ([]BlockWrap, error) {
+	p := parser.NewWithExtensions(c.extensions)
+	doc := p.Parse([]byte(markdown))
+
+	var blocks []BlockWrap
+
+	for _, child := range doc.GetChildren() {
+		switch n := child.(type) {
+		case *ast.Heading:
+			if block := c.convertHeading(n); block != nil {
+				blocks = append(blocks, *block)
+			}
+		case *ast.Paragraph:
+			if block := c.convertParagraph(n); block != nil {
+				blocks = append(blocks, *block)
+			}
+		case *ast.CodeBlock:
+			if block := c.convertCodeBlock(n); block != nil {
+				blocks = append(blocks, *block)
+			}
+		case *ast.BlockQuote:
+			if block := c.convertBlockquote(n); block != nil {
+				blocks = append(blocks, *block)
+			}
+		case *ast.List:
+			if block := c.convertList(n); block != nil {
+				blocks = append(blocks, *block)
+			}
+		case *ast.HorizontalRule:
+			blocks = append(blocks, BlockWrap{
+				Type: TypeBlock,
+				Block: HorizontalRuleBlock{
+					Type: TypeHorizontalRuleBlock,
+				},
+			})
+		}
+	}
+
+	return blocks, nil
+}
+
+// convertHeading converts an AST heading to a leaflet HeaderBlock
+func (c *MarkdownConverter) convertHeading(node *ast.Heading) *BlockWrap {
+	text, facets := c.extractTextAndFacets(node)
+	return &BlockWrap{
+		Type: TypeBlock,
+		Block: HeaderBlock{
+			Type:      TypeHeaderBlock,
+			Level:     node.Level,
+			Plaintext: text,
+			Facets:    facets,
+		},
+	}
+}
+
+// convertParagraph converts an AST paragraph to a leaflet TextBlock
+func (c *MarkdownConverter) convertParagraph(node *ast.Paragraph) *BlockWrap {
+	text, facets := c.extractTextAndFacets(node)
+	if strings.TrimSpace(text) == "" {
+		return nil
+	}
+
+	return &BlockWrap{
+		Type: TypeBlock,
+		Block: TextBlock{
+			Type:      TypeTextBlock,
+			Plaintext: text,
+			Facets:    facets,
+		},
+	}
+}
+
+// convertCodeBlock converts an AST code block to a leaflet CodeBlock
+func (c *MarkdownConverter) convertCodeBlock(node *ast.CodeBlock) *BlockWrap {
+	return &BlockWrap{
+		Type: TypeBlock,
+		Block: CodeBlock{
+			Type:                    TypeCodeBlock,
+			Plaintext:               string(node.Literal),
+			Language:                string(node.Info),
+			SyntaxHighlightingTheme: "catppuccin-mocha",
+		},
+	}
+}
+
+// convertBlockquote converts an AST blockquote to a leaflet BlockquoteBlock
+func (c *MarkdownConverter) convertBlockquote(node *ast.BlockQuote) *BlockWrap {
+	text, facets := c.extractTextAndFacets(node)
+	return &BlockWrap{
+		Type: TypeBlock,
+		Block: BlockquoteBlock{
+			Type:      TypeBlockquoteBlock,
+			Plaintext: text,
+			Facets:    facets,
+		},
+	}
+}
+
+// convertList converts an AST list to a leaflet UnorderedListBlock
+func (c *MarkdownConverter) convertList(node *ast.List) *BlockWrap {
+	var items []ListItem
+
+	for _, child := range node.Children {
+		if listItem, ok := child.(*ast.ListItem); ok {
+			item := c.convertListItem(listItem)
+			if item != nil {
+				items = append(items, *item)
+			}
+		}
+	}
+
+	return &BlockWrap{
+		Type: TypeBlock,
+		Block: UnorderedListBlock{
+			Type:     TypeUnorderedListBlock,
+			Children: items,
+		},
+	}
+}
+
+// convertListItem converts an AST list item to a leaflet ListItem
+func (c *MarkdownConverter) convertListItem(node *ast.ListItem) *ListItem {
+	text, facets := c.extractTextAndFacets(node)
+	return &ListItem{
+		Type: TypeListItem,
+		Content: TextBlock{
+			Type:      TypeTextBlock,
+			Plaintext: text,
+			Facets:    facets,
+		},
+	}
+}
+
+// extractTextAndFacets extracts plaintext and facets from an AST node
+func (c *MarkdownConverter) extractTextAndFacets(node ast.Node) (string, []Facet) {
+	var buf bytes.Buffer
+	var facets []Facet
+	offset := 0
+
+	var stack []formatContext
+
+	ast.WalkFunc(node, func(n ast.Node, entering bool) ast.WalkStatus {
+		switch v := n.(type) {
+		case *ast.Text:
+			if entering {
+				content := string(v.Literal)
+				buf.WriteString(content)
+
+				if len(stack) > 0 {
+					ctx := stack[len(stack)-1]
+					facet := Facet{
+						Type: TypeFacet,
+						Index: ByteSlice{
+							Type:      TypeByteSlice,
+							ByteStart: offset,
+							ByteEnd:   offset + len(content),
+						},
+						Features: ctx.features,
+					}
+					facets = append(facets, facet)
+				}
+
+				offset += len(content)
+			}
+		case *ast.Strong:
+			if entering {
+				stack = append(stack, formatContext{
+					features: []FacetFeature{FacetBold{Type: TypeFacetBold}},
+					start:    offset,
+				})
+			} else {
+				if len(stack) > 0 {
+					stack = stack[:len(stack)-1]
+				}
+			}
+		case *ast.Emph:
+			if entering {
+				stack = append(stack, formatContext{
+					features: []FacetFeature{FacetItalic{Type: TypeFacetItalic}},
+					start:    offset,
+				})
+			} else {
+				if len(stack) > 0 {
+					stack = stack[:len(stack)-1]
+				}
+			}
+		case *ast.Del:
+			if entering {
+				stack = append(stack, formatContext{
+					features: []FacetFeature{FacetStrikethrough{Type: TypeFacetStrike}},
+					start:    offset,
+				})
+			} else {
+				if len(stack) > 0 {
+					stack = stack[:len(stack)-1]
+				}
+			}
+		case *ast.Code:
+			if entering {
+				content := string(v.Literal)
+				buf.WriteString(content)
+
+				facet := Facet{
+					Type: TypeFacet,
+					Index: ByteSlice{
+						Type:      TypeByteSlice,
+						ByteStart: offset,
+						ByteEnd:   offset + len(content),
+					},
+					Features: []FacetFeature{FacetCode{Type: TypeFacetCode}},
+				}
+				facets = append(facets, facet)
+
+				offset += len(content)
+			}
+		case *ast.Link:
+			if entering {
+				stack = append(stack, formatContext{
+					features: []FacetFeature{FacetLink{
+						Type: TypeFacetLink,
+						URI:  string(v.Destination),
+					}},
+					start: offset,
+				})
+			} else {
+				if len(stack) > 0 {
+					stack = stack[:len(stack)-1]
+				}
+			}
+		case *ast.Softbreak, *ast.Hardbreak:
+			if entering {
+				buf.WriteString(" ")
+				offset++
+			}
+		}
+		return ast.GoToNext
+	})
+	return buf.String(), facets
+}
+
+// FromLeaflet converts leaflet blocks back to markdown
+func (c *MarkdownConverter) FromLeaflet(blocks []BlockWrap) (string, error) {
+	var buf bytes.Buffer
+	for i, wrap := range blocks {
+		if i > 0 {
+			buf.WriteString("\n\n")
+		}
+
+		switch block := wrap.Block.(type) {
+		case TextBlock:
+			buf.WriteString(c.facetsToMarkdown(block.Plaintext, block.Facets))
+		case HeaderBlock:
+			buf.WriteString(strings.Repeat("#", block.Level))
+			buf.WriteString(" ")
+			buf.WriteString(c.facetsToMarkdown(block.Plaintext, block.Facets))
+		case CodeBlock:
+			buf.WriteString("```")
+			if block.Language != "" {
+				buf.WriteString(block.Language)
+			}
+			buf.WriteString("\n")
+			buf.WriteString(block.Plaintext)
+			if !strings.HasSuffix(block.Plaintext, "\n") {
+				buf.WriteString("\n")
+			}
+			buf.WriteString("```")
+		case BlockquoteBlock:
+			buf.WriteString("> ")
+			buf.WriteString(c.facetsToMarkdown(block.Plaintext, block.Facets))
+		case UnorderedListBlock:
+			c.listToMarkdown(&buf, block.Children, 0)
+		case HorizontalRuleBlock:
+			buf.WriteString("---")
+		case ImageBlock:
+			buf.WriteString("![")
+			buf.WriteString(block.Alt)
+			buf.WriteString("](image-placeholder)")
+		default:
+			return "", fmt.Errorf("unsupported block type: %T", block)
+		}
+	}
+
+	return buf.String(), nil
+}
+
+// facetsToMarkdown applies facets to plaintext and generates markdown
+func (c *MarkdownConverter) facetsToMarkdown(text string, facets []Facet) string {
+	if len(facets) == 0 {
+		return text
+	}
+
+	var buf bytes.Buffer
+	lastEnd := 0
+
+	for _, facet := range facets {
+		if facet.Index.ByteStart > lastEnd {
+			buf.WriteString(text[lastEnd:facet.Index.ByteStart])
+		}
+
+		facetText := text[facet.Index.ByteStart:facet.Index.ByteEnd]
+
+		for _, feature := range facet.Features {
+			switch f := feature.(type) {
+			case FacetBold:
+				facetText = "**" + facetText + "**"
+			case FacetItalic:
+				facetText = "*" + facetText + "*"
+			case FacetCode:
+				facetText = "`" + facetText + "`"
+			case FacetStrikethrough:
+				facetText = "~~" + facetText + "~~"
+			case FacetLink:
+				facetText = "[" + facetText + "](" + f.URI + ")"
+			}
+		}
+
+		buf.WriteString(facetText)
+		lastEnd = facet.Index.ByteEnd
+	}
+
+	if lastEnd < len(text) {
+		buf.WriteString(text[lastEnd:])
+	}
+
+	return buf.String()
+}
+
+// listToMarkdown converts a list to markdown with proper indentation
+func (c *MarkdownConverter) listToMarkdown(buf *bytes.Buffer, items []ListItem, depth int) {
+	indent := strings.Repeat("  ", depth)
+
+	for _, item := range items {
+		buf.WriteString(indent)
+		buf.WriteString("- ")
+
+		switch content := item.Content.(type) {
+		case TextBlock:
+			buf.WriteString(c.facetsToMarkdown(content.Plaintext, content.Facets))
+		case HeaderBlock:
+			buf.WriteString(c.facetsToMarkdown(content.Plaintext, content.Facets))
+		}
+
+		buf.WriteString("\n")
+
+		if len(item.Children) > 0 {
+			c.listToMarkdown(buf, item.Children, depth+1)
+		}
+	}
+}

internal/public/convert_test.go

···
+package public
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stormlightlabs/noteleaf/internal/shared"
+)
+
+func TestMarkdownConverter(t *testing.T) {
+	converter := NewMarkdownConverter()
+
+	t.Run("Conversion", func(t *testing.T) {
+		t.Run("converts heading to HeaderBlock", func(t *testing.T) {
+			markdown := "# Hello World"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			header, ok := blocks[0].Block.(HeaderBlock)
+			shared.AssertTrue(t, ok, "block should be HeaderBlock")
+			shared.AssertEqual(t, TypeHeaderBlock, header.Type, "type should match")
+			shared.AssertEqual(t, 1, header.Level, "level should be 1")
+			shared.AssertEqual(t, "Hello World", header.Plaintext, "text should match")
+		})
+
+		t.Run("converts multiple heading levels", func(t *testing.T) {
+			markdown := "## Level 2\n\n### Level 3\n\n###### Level 6"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 3, len(blocks), "should have 3 blocks")
+
+			h2 := blocks[0].Block.(HeaderBlock)
+			shared.AssertEqual(t, 2, h2.Level, "first heading level")
+
+			h3 := blocks[1].Block.(HeaderBlock)
+			shared.AssertEqual(t, 3, h3.Level, "second heading level")
+
+			h6 := blocks[2].Block.(HeaderBlock)
+			shared.AssertEqual(t, 6, h6.Level, "third heading level")
+		})
+
+		t.Run("converts paragraph to TextBlock", func(t *testing.T) {
+			markdown := "This is a simple paragraph."
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			text, ok := blocks[0].Block.(TextBlock)
+			shared.AssertTrue(t, ok, "block should be TextBlock")
+			shared.AssertEqual(t, TypeTextBlock, text.Type, "type should match")
+			shared.AssertEqual(t, "This is a simple paragraph.", text.Plaintext, "text should match")
+		})
+
+		t.Run("converts code block to CodeBlock", func(t *testing.T) {
+			markdown := "```go\nfunc main() {\n}\n```"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			code, ok := blocks[0].Block.(CodeBlock)
+			shared.AssertTrue(t, ok, "block should be CodeBlock")
+			shared.AssertEqual(t, TypeCodeBlock, code.Type, "type should match")
+			shared.AssertEqual(t, "go", code.Language, "language should match")
+			shared.AssertTrue(t, strings.Contains(code.Plaintext, "func main"), "code content should match")
+		})
+
+		t.Run("converts blockquote to BlockquoteBlock", func(t *testing.T) {
+			markdown := "> This is a quote"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			quote, ok := blocks[0].Block.(BlockquoteBlock)
+			shared.AssertTrue(t, ok, "block should be BlockquoteBlock")
+			shared.AssertEqual(t, TypeBlockquoteBlock, quote.Type, "type should match")
+			shared.AssertTrue(t, strings.Contains(quote.Plaintext, "This is a quote"), "quote text should match")
+		})
+
+		t.Run("converts list to UnorderedListBlock", func(t *testing.T) {
+			markdown := "- Item 1\n- Item 2\n- Item 3"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			list, ok := blocks[0].Block.(UnorderedListBlock)
+			shared.AssertTrue(t, ok, "block should be UnorderedListBlock")
+			shared.AssertEqual(t, TypeUnorderedListBlock, list.Type, "type should match")
+			shared.AssertEqual(t, 3, len(list.Children), "should have 3 items")
+
+			item1 := list.Children[0].Content.(TextBlock)
+			shared.AssertTrue(t, strings.Contains(item1.Plaintext, "Item 1"), "first item text")
+		})
+
+		t.Run("converts horizontal rule to HorizontalRuleBlock", func(t *testing.T) {
+			markdown := "---"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			hr, ok := blocks[0].Block.(HorizontalRuleBlock)
+			shared.AssertTrue(t, ok, "block should be HorizontalRuleBlock")
+			shared.AssertEqual(t, TypeHorizontalRuleBlock, hr.Type, "type should match")
+		})
+
+		t.Run("converts mixed blocks", func(t *testing.T) {
+			markdown := `# Title
+
+This is a paragraph.
+
+## Subtitle
+
+- List item 1
+- List item 2
+
+---
+
+` + "```go\ncode\n```"
+
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			shared.AssertTrue(t, len(blocks) >= 5, "should have multiple blocks")
+		})
+	})
+
+	t.Run("Facets", func(t *testing.T) {
+		t.Run("extracts bold facet", func(t *testing.T) {
+			markdown := "This is **bold** text"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+			shared.AssertTrue(t, strings.Contains(text.Plaintext, "bold"), "text should contain 'bold'")
+		})
+
+		t.Run("extracts italic facet", func(t *testing.T) {
+			markdown := "This is *italic* text"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+		})
+
+		t.Run("extracts inline code facet", func(t *testing.T) {
+			markdown := "This is `code` text"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+			shared.AssertTrue(t, strings.Contains(text.Plaintext, "code"), "text should contain 'code'")
+		})
+
+		t.Run("extracts link facet", func(t *testing.T) {
+			markdown := "This is a [link](https://example.com)"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+			shared.AssertTrue(t, strings.Contains(text.Plaintext, "link"), "text should contain 'link'")
+
+			foundLink := false
+			for _, facet := range text.Facets {
+				for _, feature := range facet.Features {
+					if link, ok := feature.(FacetLink); ok {
+						shared.AssertEqual(t, "https://example.com", link.URI, "link URI should match")
+						foundLink = true
+					}
+				}
+			}
+			shared.AssertTrue(t, foundLink, "should have found link facet")
+		})
+
+		t.Run("extracts strikethrough facet", func(t *testing.T) {
+			markdown := "This is ~~deleted~~ text"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertTrue(t, len(text.Facets) > 0, "should have facets")
+		})
+
+		t.Run("extracts multiple facets", func(t *testing.T) {
+			markdown := "This has **bold** and *italic* and `code`"
+			blocks, err := converter.ToLeaflet(markdown)
+
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+			text := blocks[0].Block.(TextBlock)
+
+			shared.AssertTrue(t, len(text.Facets) >= 3, "should have at least 3 facets")
+		})
+	})
+
+	t.Run("Round-trip Conversion", func(t *testing.T) {
+		t.Run("heading round-trip", func(t *testing.T) {
+			original := "## Hello World"
+			blocks, err := converter.ToLeaflet(original)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+
+			markdown, err := converter.FromLeaflet(blocks)
+			shared.AssertNoError(t, err, "FromLeaflet should succeed")
+			shared.AssertTrue(t, strings.Contains(markdown, "Hello World"), "should contain original text")
+			shared.AssertTrue(t, strings.HasPrefix(markdown, "##"), "should have heading markers")
+		})
+
+		t.Run("text round-trip", func(t *testing.T) {
+			original := "Simple paragraph"
+			blocks, err := converter.ToLeaflet(original)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+
+			markdown, err := converter.FromLeaflet(blocks)
+			shared.AssertNoError(t, err, "FromLeaflet should succeed")
+			shared.AssertTrue(t, strings.Contains(markdown, "Simple paragraph"), "should contain original text")
+		})
+
+		t.Run("code block round-trip", func(t *testing.T) {
+			original := "```go\nfunc test() {}\n```"
+			blocks, err := converter.ToLeaflet(original)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+
+			markdown, err := converter.FromLeaflet(blocks)
+			shared.AssertNoError(t, err, "FromLeaflet should succeed")
+			shared.AssertTrue(t, strings.Contains(markdown, "```"), "should have code fences")
+			shared.AssertTrue(t, strings.Contains(markdown, "func test"), "should contain code")
+		})
+
+		t.Run("list round-trip", func(t *testing.T) {
+			original := "- Item 1\n- Item 2"
+			blocks, err := converter.ToLeaflet(original)
+			shared.AssertNoError(t, err, "ToLeaflet should succeed")
+
+			markdown, err := converter.FromLeaflet(blocks)
+			shared.AssertNoError(t, err, "FromLeaflet should succeed")
+
+			shared.AssertTrue(t, strings.Contains(markdown, "Item 1"), "should contain first item")
+			shared.AssertTrue(t, strings.Contains(markdown, "Item 2"), "should contain second item")
+			shared.AssertTrue(t, strings.Contains(markdown, "-"), "should have list markers")
+		})
+	})
+
+	t.Run("Edge Cases", func(t *testing.T) {
+		t.Run("handles empty markdown", func(t *testing.T) {
+			blocks, err := converter.ToLeaflet("")
+			shared.AssertNoError(t, err, "should handle empty string")
+			shared.AssertEqual(t, 0, len(blocks), "should have no blocks")
+		})
+
+		t.Run("skips empty paragraphs", func(t *testing.T) {
+			markdown := "\n\n\n"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "should succeed")
+			shared.AssertEqual(t, 0, len(blocks), "should skip empty paragraphs")
+		})
+
+		t.Run("handles special characters", func(t *testing.T) {
+			markdown := "Text with *special* characters"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "should handle special characters")
+			shared.AssertEqual(t, 1, len(blocks), "should have 1 block")
+
+			text := blocks[0].Block.(TextBlock)
+			shared.AssertTrue(t, strings.Contains(text.Plaintext, "special"), "should preserve text")
+			shared.AssertTrue(t, strings.Contains(text.Plaintext, "characters"), "should preserve text")
+		})
+
+		t.Run("handles multiple paragraphs", func(t *testing.T) {
+			markdown := "First paragraph\n\nSecond paragraph"
+			blocks, err := converter.ToLeaflet(markdown)
+			shared.AssertNoError(t, err, "should succeed")
+			shared.AssertEqual(t, 2, len(blocks), "should have 2 blocks")
+		})
+	})
+}

internal/public/public.go

···
+// Package public defines leaflet publication schema types
+//
+// These types correspond to the pub.leaflet.* lexicons used by leaflet.pub
+//
+// The types here match the lexicon definitions from:
+//
+//	https://github.com/hyperlink-academy/leaflet/tree/main/lexicons/pub/leaflet/
+package public
+
+import "time"
+
+const (
+	TypeDocument       = "pub.leaflet.document"
+	TypePublication    = "pub.leaflet.publication"
+	TypeLinearDocument = "pub.leaflet.pages.linearDocument"
+	TypeBlock          = "pub.leaflet.pages.linearDocument#block"
+
+	TypeTextBlock           = "pub.leaflet.blocks.text"
+	TypeHeaderBlock         = "pub.leaflet.blocks.header"
+	TypeCodeBlock           = "pub.leaflet.blocks.code"
+	TypeImageBlock          = "pub.leaflet.blocks.image"
+	TypeBlockquoteBlock     = "pub.leaflet.blocks.blockquote"
+	TypeUnorderedListBlock  = "pub.leaflet.blocks.unorderedList"
+	TypeHorizontalRuleBlock = "pub.leaflet.blocks.horizontalRule"
+
+	TypeFacet          = "pub.leaflet.richtext.facet"
+	TypeByteSlice      = "pub.leaflet.richtext.facet#byteSlice"
+	TypeFacetBold      = "pub.leaflet.richtext.facet#bold"
+	TypeFacetItalic    = "pub.leaflet.richtext.facet#italic"
+	TypeFacetCode      = "pub.leaflet.richtext.facet#code"
+	TypeFacetLink      = "pub.leaflet.richtext.facet#link"
+	TypeFacetStrike    = "pub.leaflet.richtext.facet#strikethrough"
+	TypeFacetUnderline = "pub.leaflet.richtext.facet#underline"
+	TypeFacetHighlight = "pub.leaflet.richtext.facet#highlight"
+
+	TypeListItem    = "pub.leaflet.blocks.unorderedList#listItem"
+	TypeAspectRatio = "pub.leaflet.blocks.image#aspectRatio"
+	TypeBlob        = "blob"
+)
+
+// Document represents a leaflet document (pub.leaflet.document)
+type Document struct {
+	Type        string           `json:"$type"`
+	Author      string           `json:"author"`      // DID (Decentralized Identifier)
+	Title       string           `json:"title"`       // Max 128 graphemes
+	Description string           `json:"description"` // Max 300 graphemes
+	PublishedAt string           `json:"publishedAt"` // ISO8601 datetime
+	Publication string           `json:"publication"` // URI: at://did/pub.leaflet.publication/rkey
+	Pages       []LinearDocument `json:"pages"`
+}
+
+// LinearDocument represents a page in a leaflet document (pub.leaflet.pages.linearDocument)
+type LinearDocument struct {
+	Type   string      `json:"$type"`
+	ID     string      `json:"id,omitempty"`
+	Blocks []BlockWrap `json:"blocks"`
+}
+
+// BlockWrap wraps a block with optional metadata (alignment, etc.)
+type BlockWrap struct {
+	Type      string `json:"$type"`
+	Block     any    `json:"block"`               // One of: TextBlock, HeaderBlock, etc.
+	Alignment string `json:"alignment,omitempty"` // #textAlignLeft, etc.
+}
+
+// TextBlock represents a text content block (pub.leaflet.blocks.text)
+type TextBlock struct {
+	Type      string  `json:"$type"`
+	Plaintext string  `json:"plaintext"`
+	Facets    []Facet `json:"facets,omitempty"`
+}
+
+// HeaderBlock represents a heading content block (pub.leaflet.blocks.header)
+type HeaderBlock struct {
+	Type      string  `json:"$type"`
+	Level     int     `json:"level,omitempty"` // h1 - h6
+	Plaintext string  `json:"plaintext"`
+	Facets    []Facet `json:"facets,omitempty"`
+}
+
+// CodeBlock represents a code content block (pub.leaflet.blocks.code)
+type CodeBlock struct {
+	Type                    string `json:"$type"`
+	Plaintext               string `json:"plaintext"`
+	Language                string `json:"language,omitempty"`
+	SyntaxHighlightingTheme string `json:"syntaxHighlightingTheme,omitempty"`
+}
+
+// ImageBlock represents an image content block (pub.leaflet.blocks.image)
+type ImageBlock struct {
+	Type        string      `json:"$type"`
+	Image       Blob        `json:"image"`
+	Alt         string      `json:"alt,omitempty"`
+	AspectRatio AspectRatio `json:"aspectRatio"`
+}
+
+// AspectRatio represents image dimensions (pub.leaflet.blocks.image#aspectRatio)
+type AspectRatio struct {
+	Type   string `json:"$type"`
+	Width  int    `json:"width"`
+	Height int    `json:"height"`
+}
+
+// BlockquoteBlock represents a blockquote content block (pub.leaflet.blocks.blockquote)
+type BlockquoteBlock struct {
+	Type      string  `json:"$type"`
+	Plaintext string  `json:"plaintext"`
+	Facets    []Facet `json:"facets,omitempty"`
+}
+
+// UnorderedListBlock represents an unordered list (pub.leaflet.blocks.unorderedList)
+type UnorderedListBlock struct {
+	Type     string     `json:"$type"`
+	Children []ListItem `json:"children"`
+}
+
+// ListItem represents a single list item (pub.leaflet.blocks.unorderedList#listItem)
+type ListItem struct {
+	Type     string     `json:"$type"`
+	Content  any        `json:"content"`            // [TextBlock], [HeaderBlock], [ImageBlock]
+	Children []ListItem `json:"children,omitempty"` // Nested list items
+}
+
+// HorizontalRuleBlock represents a horizontal rule/thematic break (pub.leaflet.blocks.horizontalRule)
+type HorizontalRuleBlock struct {
+	Type string `json:"$type"`
+}
+
+// Facet represents text annotation (pub.leaflet.richtext.facet)
+type Facet struct {
+	Type     string         `json:"$type"`
+	Index    ByteSlice      `json:"index"`
+	Features []FacetFeature `json:"features"`
+}
+
+// ByteSlice specifies a substring range using UTF-8 byte offsets (pub.leaflet.richtext.facet#byteSlice)
+type ByteSlice struct {
+	Type      string `json:"$type"`
+	ByteStart int    `json:"byteStart"`
+	ByteEnd   int    `json:"byteEnd"`
+}
+
+// FacetFeature is a marker interface for facet features
+type FacetFeature interface {
+	GetFacetType() string
+}
+
+// FacetBold represents bold text styling
+type FacetBold struct {
+	Type string `json:"$type"`
+}
+
+func (f FacetBold) GetFacetType() string { return TypeFacetBold }
+
+// FacetItalic represents italic text styling
+type FacetItalic struct {
+	Type string `json:"$type"`
+}
+
+func (f FacetItalic) GetFacetType() string { return TypeFacetItalic }
+
+// FacetCode represents inline code styling
+type FacetCode struct {
+	Type string `json:"$type"`
+}
+
+func (f FacetCode) GetFacetType() string { return TypeFacetCode }
+
+// FacetLink represents a hyperlink
+type FacetLink struct {
+	Type string `json:"$type"`
+	URI  string `json:"uri"`
+}
+
+func (f FacetLink) GetFacetType() string { return TypeFacetLink }
+
+// FacetStrikethrough represents strikethrough text styling
+type FacetStrikethrough struct {
+	Type string `json:"$type"`
+}
+
+func (f FacetStrikethrough) GetFacetType() string { return TypeFacetStrike }
+
+// FacetUnderline represents underline text styling
+type FacetUnderline struct {
+	Type string `json:"$type"`
+}
+
+func (f FacetUnderline) GetFacetType() string { return TypeFacetUnderline }
+
+// FacetHighlight represents highlighted text
+type FacetHighlight struct {
+	Type string `json:"$type"`
+}
+
+func (f FacetHighlight) GetFacetType() string { return TypeFacetHighlight }
+
+// Blob represents binary content (images, files)
+type Blob struct {
+	Type     string `json:"$type"`
+	Ref      CID    `json:"ref"`
+	MimeType string `json:"mimeType"`
+	Size     int    `json:"size"`
+}
+
+// CID represents a Content Identifier (IPFS CID)
+type CID struct {
+	Link string `json:"$link"`
+}
+
+// Publication represents a leaflet publication (pub.leaflet.publication)
+type Publication struct {
+	Type        string    `json:"$type"`
+	Name        string    `json:"name"`
+	Description string    `json:"description,omitempty"`
+	CreatedAt   time.Time `json:"createdAt"`
+}
+
+// DocumentMeta holds metadata about a fetched document
+type DocumentMeta struct {
+	RKey      string    // Record key (TID)
+	CID       string    // Content identifier
+	URI       string    // Full AT URI
+	IsDraft   bool      // Draft vs published
+	FetchedAt time.Time // When we fetched it
+}

internal/repo/note_repository.go

···
 	var note models.Note
 	var tags string
 	err := s.Scan(&note.ID, &note.Title, &note.Content, &tags, &note.Archived,
-		&note.Created, &note.Modified, &note.FilePath)
+		&note.Created, &note.Modified, &note.FilePath, &note.LeafletRKey,
+		&note.LeafletCID, &note.PublishedAt, &note.IsDraft)
 	if err != nil {
 		return nil, err
 	}
···
 	}
 
 	result, err := r.db.ExecContext(ctx, queryNoteInsert,
-		note.Title, note.Content, tags, note.Archived, note.Created, note.Modified, note.FilePath)
+		note.Title, note.Content, tags, note.Archived, note.Created, note.Modified, note.FilePath,
+		note.LeafletRKey, note.LeafletCID, note.PublishedAt, note.IsDraft)
 	if err != nil {
 		return 0, fmt.Errorf("failed to insert note: %w", err)
 	}
···
 	}
 
 	result, err := r.db.ExecContext(ctx, queryNoteUpdate,
-		note.Title, note.Content, tags, note.Archived, note.Modified, note.FilePath, note.ID)
+		note.Title, note.Content, tags, note.Archived, note.Modified, note.FilePath,
+		note.LeafletRKey, note.LeafletCID, note.PublishedAt, note.IsDraft, note.ID)
 	if err != nil {
 		return fmt.Errorf("failed to update note: %w", err)
 	}
···
 	query, args := r.buildTagsQuery(tags)
 	return r.queryMany(ctx, query, args...)
 }
+
+// GetByLeafletRKey returns a note by its leaflet record key
+func (r *NoteRepository) GetByLeafletRKey(ctx context.Context, rkey string) (*models.Note, error) {
+	query := "SELECT " + noteColumns + " FROM notes WHERE leaflet_rkey = ?"
+	return r.queryOne(ctx, query, rkey)
+}
+
+// ListPublished returns all published leaflet notes (not drafts)
+func (r *NoteRepository) ListPublished(ctx context.Context) ([]*models.Note, error) {
+	query := "SELECT " + noteColumns + " FROM notes WHERE leaflet_rkey IS NOT NULL AND is_draft = false ORDER BY published_at DESC"
+	return r.queryMany(ctx, query)
+}
+
+// ListDrafts returns all draft leaflet notes
+func (r *NoteRepository) ListDrafts(ctx context.Context) ([]*models.Note, error) {
+	query := "SELECT " + noteColumns + " FROM notes WHERE leaflet_rkey IS NOT NULL AND is_draft = true ORDER BY modified DESC"
+	return r.queryMany(ctx, query)
+}
+
+// GetLeafletNotes returns all notes with leaflet association (both published and drafts)
+func (r *NoteRepository) GetLeafletNotes(ctx context.Context) ([]*models.Note, error) {
+	query := "SELECT " + noteColumns + " FROM notes WHERE leaflet_rkey IS NOT NULL ORDER BY modified DESC"
+	return r.queryMany(ctx, query)
+}

internal/repo/note_repository_test.go

···
 import (
 	"context"
 	"testing"
+	"time"
 
 	_ "github.com/mattn/go-sqlite3"
 	"github.com/stormlightlabs/noteleaf/internal/models"
···
 			notes, err := repo.List(ctx, NoteListOptions{Title: "NonexistentTitle"})
 			shared.AssertNoError(t, err, "Should not error when no notes found")
 			shared.AssertEqual(t, 0, len(notes), "Expected empty result set")
+		})
+	})
+
+	t.Run("Leaflet Methods", func(t *testing.T) {
+		db := CreateTestDB(t)
+		repo := NewNoteRepository(db)
+		ctx := context.Background()
+
+		rkey1 := "rkey-published-1"
+		rkey2 := "rkey-draft-1"
+		rkey3 := "rkey-published-2"
+		pubTime := time.Now()
+
+		publishedNote1 := &models.Note{
+			Title:       "Published Note 1",
+			Content:     "Content 1",
+			LeafletRKey: &rkey1,
+			IsDraft:     false,
+			PublishedAt: &pubTime,
+		}
+		_, err := repo.Create(ctx, publishedNote1)
+		shared.AssertNoError(t, err, "create published note 1")
+
+		draftNote := &models.Note{
+			Title:       "Draft Note",
+			Content:     "Draft content",
+			LeafletRKey: &rkey2,
+			IsDraft:     true,
+		}
+		_, err = repo.Create(ctx, draftNote)
+		shared.AssertNoError(t, err, "create draft note")
+
+		publishedNote2 := &models.Note{
+			Title:       "Published Note 2",
+			Content:     "Content 2",
+			LeafletRKey: &rkey3,
+			IsDraft:     false,
+			PublishedAt: &pubTime,
+		}
+		_, err = repo.Create(ctx, publishedNote2)
+		shared.AssertNoError(t, err, "create published note 2")
+
+		regularNote := &models.Note{
+			Title:   "Regular Note",
+			Content: "No leaflet association",
+		}
+		_, err = repo.Create(ctx, regularNote)
+		shared.AssertNoError(t, err, "create regular note")
+
+		t.Run("GetByLeafletRKey finds note by rkey", func(t *testing.T) {
+			note, err := repo.GetByLeafletRKey(ctx, rkey1)
+			shared.AssertNoError(t, err, "get by leaflet rkey")
+			shared.AssertEqual(t, "Published Note 1", note.Title, "title should match")
+			shared.AssertNotNil(t, note.LeafletRKey, "leaflet rkey should be set")
+			shared.AssertEqual(t, rkey1, *note.LeafletRKey, "rkey should match")
+		})
+
+		t.Run("GetByLeafletRKey returns error for non-existent rkey", func(t *testing.T) {
+			_, err := repo.GetByLeafletRKey(ctx, "non-existent-rkey")
+			shared.AssertError(t, err, "should error for non-existent rkey")
+		})
+
+		t.Run("ListPublished returns only published notes", func(t *testing.T) {
+			notes, err := repo.ListPublished(ctx)
+			shared.AssertNoError(t, err, "list published")
+			shared.AssertEqual(t, 2, len(notes), "should have 2 published notes")
+
+			for _, note := range notes {
+				shared.AssertFalse(t, note.IsDraft, "published notes should not be drafts")
+				shared.AssertNotNil(t, note.LeafletRKey, "should have leaflet rkey")
+			}
+		})
+
+		t.Run("ListDrafts returns only draft notes", func(t *testing.T) {
+			notes, err := repo.ListDrafts(ctx)
+			shared.AssertNoError(t, err, "list drafts")
+			shared.AssertEqual(t, 1, len(notes), "should have 1 draft note")
+
+			shared.AssertTrue(t, notes[0].IsDraft, "should be draft")
+			shared.AssertEqual(t, "Draft Note", notes[0].Title, "title should match")
+			shared.AssertNotNil(t, notes[0].LeafletRKey, "should have leaflet rkey")
+		})
+
+		t.Run("GetLeafletNotes returns all notes with leaflet association", func(t *testing.T) {
+			notes, err := repo.GetLeafletNotes(ctx)
+			shared.AssertNoError(t, err, "get leaflet notes")
+			shared.AssertEqual(t, 3, len(notes), "should have 3 leaflet notes")
+
+			for _, note := range notes {
+				shared.AssertNotNil(t, note.LeafletRKey, "all should have leaflet rkey")
+			}
+		})
+
+		t.Run("Context Cancellation", func(t *testing.T) {
+			t.Run("GetByLeafletRKey with cancelled context", func(t *testing.T) {
+				_, err := repo.GetByLeafletRKey(NewCanceledContext(), rkey1)
+				AssertCancelledContext(t, err)
+			})
+
+			t.Run("ListPublished with cancelled context", func(t *testing.T) {
+				_, err := repo.ListPublished(NewCanceledContext())
+				AssertCancelledContext(t, err)
+			})
+
+			t.Run("ListDrafts with cancelled context", func(t *testing.T) {
+				_, err := repo.ListDrafts(NewCanceledContext())
+				AssertCancelledContext(t, err)
+			})
+
+			t.Run("GetLeafletNotes with cancelled context", func(t *testing.T) {
+				_, err := repo.GetLeafletNotes(NewCanceledContext())
+				AssertCancelledContext(t, err)
+			})
 		})
 	})
 }

internal/repo/queries.go

···
 package repo
 
 const (
-	noteColumns     = "id, title, content, tags, archived, created, modified, file_path"
+	noteColumns     = "id, title, content, tags, archived, created, modified, file_path, leaflet_rkey, leaflet_cid, published_at, is_draft"
 	queryNoteByID   = "SELECT " + noteColumns + " FROM notes WHERE id = ?"
-	queryNoteInsert = `INSERT INTO notes (title, content, tags, archived, created, modified, file_path) VALUES (?, ?, ?, ?, ?, ?, ?)`
-	queryNoteUpdate = `UPDATE notes SET title = ?, content = ?, tags = ?, archived = ?, modified = ?, file_path = ? WHERE id = ?`
+	queryNoteInsert = `INSERT INTO notes (title, content, tags, archived, created, modified, file_path, leaflet_rkey, leaflet_cid, published_at, is_draft) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+	queryNoteUpdate = `UPDATE notes SET title = ?, content = ?, tags = ?, archived = ?, modified = ?, file_path = ?, leaflet_rkey = ?, leaflet_cid = ?, published_at = ?, is_draft = ? WHERE id = ?`
 	queryNoteDelete = "DELETE FROM notes WHERE id = ?"
 	queryNotesList  = "SELECT " + noteColumns + " FROM notes"
 )

internal/services/atproto.go

···
+// TODO: Implement authentication using indigo's xrpc client:
+//  1. Create session via com.atproto.server.createSession
+//  2. Store session tokens
+//  3. Handle token refresh
+//
+// TODO: Implement authentication
+//  1. Create XRPC client
+//  2. Call com.atproto.server.createSession
+//  3. Parse response and store session
+//  4. Resolve PDS URL from DID
+//
+// TODO: Implement document fetching:
+//  1. Call com.atproto.sync.getRepo to get repository CAR file
+//  2. Parse CAR (Content Addressable aRchive) format
+//  3. Filter records by collection: pub.leaflet.document
+//  4. Extract documents and metadata
+//  5. Return as []DocumentWithMeta
+//
+// TODO: Implement document pulling
+//  1. GET {pdsURL}/xrpc/com.atproto.sync.getRepo?did={session.DID}
+//  2. Parse CAR stream using github.com/bluesky-social/indigo/repo
+//  3. Iterate over records, filter by collection == "pub.leaflet.document"
+//  4. Parse each record as public.Document
+//  5. Collect metadata (rkey, cid, uri)
+//
+// TODO: Implement publication listing:
+// 1. Query records with collection: pub.leaflet.publication
+// 2. Parse as public.Publication
+// 3. Return list
+//
+// TODO: Implement session clearing: close any open connections
+package services
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/stormlightlabs/noteleaf/internal/public"
+)
+
+// DocumentWithMeta combines a document with its repository metadata
+type DocumentWithMeta struct {
+	Document public.Document
+	Meta     public.DocumentMeta
+}
+
+// PublicationWithMeta combines a publication with its metadata
+type PublicationWithMeta struct {
+	Publication public.Publication
+	RKey        string
+	CID         string
+	URI         string
+}
+
+// Session holds authentication session information
+type Session struct {
+	DID           string    // Decentralized Identifier
+	Handle        string    // User handle (e.g., username.bsky.social)
+	AccessJWT     string    // Access token
+	RefreshJWT    string    // Refresh token
+	PDSURL        string    // Personal Data Server URL
+	ExpiresAt     time.Time // When access token expires
+	Authenticated bool      // Whether session is valid
+}
+
+// ATProtoService provides AT Protocol operations for leaflet integration
+type ATProtoService struct {
+	handle   string
+	password string
+	session  *Session
+	pdsURL   string // Personal Data Server URL
+	// TODO: wrap AT Protocol client from indigo package
+	// client    *xrpc.Client
+}
+
+// NewATProtoService creates a new AT Protocol service
+func NewATProtoService() *ATProtoService {
+	return &ATProtoService{
+		pdsURL: "https://bsky.social",
+	}
+}
+
+// Authenticate logs in with BlueSky/AT Protocol credentials
+func (s *ATProtoService) Authenticate(ctx context.Context, handle, password string) error {
+	if handle == "" || password == "" {
+		return fmt.Errorf("handle and password are required")
+	}
+
+	s.handle = handle
+	s.password = password
+	s.session = &Session{
+		Handle: handle,
+		// TODO: Set to true once auth is implemented
+		Authenticated: false,
+		PDSURL:        s.pdsURL,
+	}
+
+	return fmt.Errorf("TODO: implement com.atproto.server.createSession")
+}
+
+// GetSession returns the current session information
+func (s *ATProtoService) GetSession() (*Session, error) {
+	if s.session == nil || !s.session.Authenticated {
+		return nil, fmt.Errorf("not authenticated - run 'noteleaf pub auth' first")
+	}
+	return s.session, nil
+}
+
+// IsAuthenticated checks if the service has a valid session
+func (s *ATProtoService) IsAuthenticated() bool {
+	return s.session != nil && s.session.Authenticated
+}
+
+// PullDocuments fetches all leaflet documents from the user's repository
+func (s *ATProtoService) PullDocuments(ctx context.Context) ([]DocumentWithMeta, error) {
+	if !s.IsAuthenticated() {
+		return nil, fmt.Errorf("not authenticated")
+	}
+
+	return nil, fmt.Errorf("document pulling not yet implemented - TODO: implement com.atproto.sync.getRepo with CAR parsing")
+}
+
+// ListPublications fetches available publications for the authenticated user
+func (s *ATProtoService) ListPublications(ctx context.Context) ([]PublicationWithMeta, error) {
+	if !s.IsAuthenticated() {
+		return nil, fmt.Errorf("not authenticated")
+	}
+	return nil, fmt.Errorf("publication listing not yet implemented")
+}
+
+// Close cleans up resources
+func (s *ATProtoService) Close() error {
+	s.session = nil
+	return nil
+}

internal/store/sql/migrations/0008_add_leaflet_fields_to_notes_down.sql

···
+-- Remove leaflet fields and indexes
+DROP INDEX IF EXISTS idx_notes_is_draft;
+DROP INDEX IF EXISTS idx_notes_leaflet_rkey;
+ALTER TABLE notes DROP COLUMN is_draft;
+ALTER TABLE notes DROP COLUMN published_at;
+ALTER TABLE notes DROP COLUMN leaflet_cid;
+ALTER TABLE notes DROP COLUMN leaflet_rkey;

internal/store/sql/migrations/0008_add_leaflet_fields_to_notes_up.sql

···
+-- Add leaflet publication fields to notes table
+ALTER TABLE notes ADD COLUMN leaflet_rkey TEXT;
+ALTER TABLE notes ADD COLUMN leaflet_cid TEXT;
+ALTER TABLE notes ADD COLUMN published_at DATETIME;
+ALTER TABLE notes ADD COLUMN is_draft INTEGER DEFAULT 0;
+
+-- Add index for leaflet record key lookups
+CREATE INDEX IF NOT EXISTS idx_notes_leaflet_rkey ON notes(leaflet_rkey);
+
+-- Add index for published vs draft queries
+CREATE INDEX IF NOT EXISTS idx_notes_is_draft ON notes(is_draft);