build: setup ldflags & switch to Taskfile from justfile

README.md

···
 [![Go Version](https://img.shields.io/github/go-mod/go-version/stormlightlabs/noteleaf)](go.mod)
 
 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.
+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.
 
 ## Why?
 
-- **Fragmented productivity tools**: Instead of juggling multiple apps for tasks, notes, reading lists, and media queues, Noteleaf provides a single CLI interface
-- **Terminal-native workflow**: For developers and power users who prefer staying in the terminal, Noteleaf offers rich TUIs without leaving your command line
-    - **Lightweight and fast**: No desktop apps or web interfaces - just a fast, focused CLI tool
+- **Fragmented Ecosystem**: Instead of juggling multiple apps for tasks, notes, reading lists, and media queues, Noteleaf provides a single CLI interface
+- **Terminal-native**: For developers and power users who prefer staying in the terminal, Noteleaf offers rich TUIs without leaving your command line
+    - **Lightweight**: No desktop apps or web interfaces, just a fast, focused CLI tool
 - **Unified data model**: Tasks, notes, and media items can reference each other, creating a connected knowledge and productivity system
 
-## Getting started
-
-### Prerequisites
-
-Go v1.24+
+## Getting Started
 
-### Installation
+### Quick Install
 
 ```sh
 git clone https://github.com/stormlightlabs/noteleaf
···
 go install
 ```
 
-### Basic usage
-
-```sh
-# Initialize the application
-noteleaf setup
-
-# Add sample data for exploration
-noteleaf setup seed
-
-# Create your first task
-noteleaf task add "Learn Noteleaf CLI"
-
-# View tasks
-noteleaf task list
-
-# Create a note
-noteleaf note add "My first note"
-
-# Add a book to your reading list
-noteleaf media book add "The Name of the Wind"
-
-# Generate docs
-noteleaf docgen --format docusaurus --out ./website/docs/manual
-```
-
-## Status
-
-**Status**: Work in Progress (MVP completed)
-
-### Completed
+### First Steps
 
-- Task management with projects and tags
-- Note-taking system
-- Article parsing from URLs
-- Media tracking (books, movies, TV shows)
-
-### Planned
-
-- Time tracking integration
-- Advanced search and filtering
-- Export/import functionality
-- Plugin system
+For a comprehensive walkthrough including task management, time tracking, notes, and media tracking, see the [Quickstart Guide](website/docs/Quickstart.md).

Taskfile.yml

···
+version: '3'
+
+vars:
+  BINARY_NAME: noteleaf
+  BUILD_DIR: ./tmp
+  CMD_DIR: ./cmd
+  COVERAGE_FILE: coverage.out
+  COVERAGE_HTML: coverage.html
+  VERSION_PKG: github.com/stormlightlabs/noteleaf/internal/version
+
+  # Git version detection
+  GIT_COMMIT:
+    sh: git rev-parse --short HEAD 2>/dev/null || echo "none"
+  GIT_TAG:
+    sh: git describe --tags --exact-match 2>/dev/null || echo ""
+  GIT_DESCRIBE:
+    sh: git describe --tags --always --dirty 2>/dev/null || echo "dev"
+  BUILD_DATE:
+    sh: date -u +"%Y-%m-%dT%H:%M:%SZ"
+
+tasks:
+  default:
+    desc: Show available tasks
+    silent: true
+    cmds:
+      - task --list
+
+  test:
+    desc: Run all tests
+    cmds:
+      - go test ./...
+
+  coverage:
+    desc: Generate HTML coverage report
+    cmds:
+      - go test -coverprofile={{.COVERAGE_FILE}} ./...
+      - go tool cover -html={{.COVERAGE_FILE}} -o {{.COVERAGE_HTML}}
+      - echo "Coverage report generated at {{.COVERAGE_HTML}}"
+
+  cov:
+    desc: Show coverage in terminal
+    cmds:
+      - go test -coverprofile={{.COVERAGE_FILE}} ./...
+      - go tool cover -func={{.COVERAGE_FILE}}
+
+  build:
+    desc: Build binary (simple build without version injection)
+    cmds:
+      - mkdir -p {{.BUILD_DIR}}
+      - go build -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
+      - echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}}"
+
+  build:dev:
+    desc: Build binary with dev version (includes git commit hash)
+    vars:
+      VERSION: "{{.GIT_DESCRIBE}}"
+      LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.Commit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
+    cmds:
+      - mkdir -p {{.BUILD_DIR}}
+      - go build -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
+      - 'echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}} (version: {{.VERSION}})"'
+
+  build:rc:
+    desc: Build release candidate binary (requires git tag with -rc suffix)
+    vars:
+      VERSION: "{{.GIT_TAG}}"
+      LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.Commit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
+    preconditions:
+      - sh: '[ -n "{{.GIT_TAG}}" ]'
+        msg: "No git tag found. Create a tag with 'git tag v1.0.0-rc1' first."
+      - sh: 'echo "{{.GIT_TAG}}" | grep -q "\-rc"'
+        msg: "Git tag must contain '-rc' for release candidate builds (e.g., v1.0.0-rc1)"
+    cmds:
+      - mkdir -p {{.BUILD_DIR}}
+      - go build -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
+      - 'echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}} (version: {{.VERSION}})"'
+
+  build:prod:
+    desc: Build production binary (requires clean semver git tag)
+    vars:
+      VERSION: "{{.GIT_TAG}}"
+      LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.Commit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
+    preconditions:
+      - sh: '[ -n "{{.GIT_TAG}}" ]'
+        msg: "No git tag found. Create a tag with 'git tag v1.0.0' first."
+      - sh: 'echo "{{.GIT_TAG}}" | grep -qE "^v?[0-9]+\.[0-9]+\.[0-9]+$"'
+        msg: "Git tag must be a clean semver version (e.g., v1.0.0 or 1.0.0) without prerelease suffix"
+      - sh: '[ -z "$(git status --porcelain)" ]'
+        msg: "Working directory must be clean (no uncommitted changes) for production builds"
+    cmds:
+      - mkdir -p {{.BUILD_DIR}}
+      - go build -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
+      - 'echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}} (version: {{.VERSION}})"'
+
+  clean:
+    desc: Remove build artifacts and coverage files
+    cmds:
+      - rm -f {{.COVERAGE_FILE}} {{.COVERAGE_HTML}}
+      - rm -rf {{.BUILD_DIR}}
+      - echo "Cleaned build artifacts"
+
+  lint:
+    desc: Run linters (go vet and go fmt)
+    cmds:
+      - go vet ./...
+      - go fmt ./...
+
+  check:
+    desc: Run linters and coverage tests
+    cmds:
+      - task: lint
+      - task: cov
+
+  deps:
+    desc: Download and tidy dependencies
+    cmds:
+      - go mod download
+      - go mod tidy
+
+  run:
+    desc: Build and run the application
+    deps: [build]
+    cmds:
+      - '{{.BUILD_DIR}}/{{.BINARY_NAME}}'
+
+  status:
+    desc: Show Go version, module info, and dependencies
+    silent: true
+    cmds:
+      - echo "=== Go Version ==="
+      - go version
+      - echo ""
+      - echo "=== Module Info ==="
+      - go list -m
+      - echo ""
+      - echo "=== Dependencies ==="
+      - go list -m all
+
+  dev:
+    desc: Full development workflow (clean, lint, test, build)
+    cmds:
+      - task: clean
+      - task: lint
+      - task: test
+      - task: build
+
+  docs:generate:
+    desc: Generate documentation in all formats
+    cmds:
+      - go run tools/docgen.go -output website/docs/manual -format docusaurus
+      - go run tools/docgen.go -output docs/manual -format man
+      - echo "Documentation generated"
+
+  docs:man:
+    desc: Generate man pages
+    cmds:
+      - mkdir -p docs/manual
+      - go run tools/docgen.go -output docs/manual -format man
+      - echo "Man pages generated in docs/manual"
+
+  docs:serve:
+    desc: Start docusaurus development server
+    dir: website
+    cmds:
+      - npm run start
+
+  version:show:
+    desc: Display current version information
+    silent: true
+    cmds:
+      - echo "Version info:"
+      - 'echo "  Git tag: {{.GIT_TAG}}"'
+      - 'echo "  Git commit: {{.GIT_COMMIT}}"'
+      - 'echo "  Git describe: {{.GIT_DESCRIBE}}"'
+      - 'echo "  Build date: {{.BUILD_DATE}}"'
+
+  version:validate:
+    desc: Validate git tag format for releases
+    cmds:
+      - |
+        if [ -z "{{.GIT_TAG}}" ]; then
+          echo "No git tag found"
+          exit 1
+        fi
+        if echo "{{.GIT_TAG}}" | grep -qE "^v?[0-9]+\.[0-9]+\.[0-9]+(-rc[0-9]+)?$"; then
+          echo "Valid version tag: {{.GIT_TAG}}"
+        else
+          echo "Invalid version tag: {{.GIT_TAG}}"
+          echo "Expected format: v1.0.0 or v1.0.0-rc1"
+          exit 1
+        fi

cmd/main.go

···
 	"github.com/stormlightlabs/noteleaf/internal/store"
 	"github.com/stormlightlabs/noteleaf/internal/ui"
 	"github.com/stormlightlabs/noteleaf/internal/utils"
+	"github.com/stormlightlabs/noteleaf/internal/version"
 	"github.com/stormlightlabs/noteleaf/tools"
 )
 
···
 	root.AddCommand(tools.NewDocGenCommand(root))
 
 	opts := []fang.Option{
-		fang.WithVersion("0.1.0"),
+		fang.WithVersion(version.String()),
 		fang.WithoutCompletions(),
 		fang.WithColorSchemeFunc(ui.NoteleafColorScheme),
 	}

docs/dev/ARCHITECTURE.md website/docs/development/ARCHITECTURE.md

···
 
 ### Business Logic
 
-**Handlers** - Business logic resides in `internal/handlers/` with one handler per domain (TaskHandler, NoteHandler, ArticleHandler, etc.). Handlers receive repository dependencies through constructor injection.
+**Handlers** - Business logic resides in `internal/handlers/` with one handler per domain (TaskHandler, NoteHandler, ArticleHandler, etc.).
+Handlers receive repository dependencies through constructor injection.
 
 **Services** - Domain-specific operations in `internal/services/` handle complex business workflows and external integrations.
 
···
 
 ### Content Management
 
-**Articles** - Web scraping using `gocolly/colly` with domain-specific extraction rules stored in `internal/articles/rules/`. Articles are parsed to markdown and stored with dual file references (markdown + HTML).
+**Articles** - Web scraping using `gocolly/colly` with domain-specific extraction rules stored in `internal/articles/rules/`.
+Articles are parsed to markdown and stored with dual file references (markdown + HTML).
 
 **Tasks** - Todo/task management inspired by TaskWarrior with filtering, status tracking, and interactive TUI views.
 
···
 
 ### Technology Choices
 
-**Go over Rust** - Go was selected for its simplicity, excellent CLI ecosystem (Cobra, Charm libraries), and faster development velocity. While Rust + Ratatui would provide better memory safety and potentially superior performance, Go's straightforward concurrency model and mature tooling ecosystem made it the pragmatic choice for rapid prototyping and iteration.
+**Go over Rust** - Go was selected for its simplicity, excellent CLI ecosystem (Cobra, Charm libraries), and faster development velocity.
+While Rust + Ratatui would provide better memory safety and potentially superior performance, Go's straightforward concurrency model and mature tooling ecosystem made it the pragmatic choice for rapid prototyping and iteration.
 
-**SQLite over PostgreSQL** - SQLite provides zero-configuration deployment and sufficient performance for single-user CLI applications. The embedded database eliminates setup complexity while supporting full SQL features needed for filtering and querying. PostgreSQL would add deployment overhead without meaningful benefits for this use case.
+**SQLite over PostgreSQL** - SQLite provides zero-configuration deployment and sufficient performance for single-user CLI applications.
+The embedded database eliminates setup complexity while supporting full SQL features needed for filtering and querying.
+PostgreSQL would add deployment overhead without meaningful benefits for this use case.
 
-**Repository Pattern over Active Record** - Repository interfaces enable clean separation between business logic and data access, facilitating testing through dependency injection. This pattern scales better than Active Record for complex domain logic while maintaining clear boundaries between layers.
+**Repository Pattern over Active Record** - Repository interfaces enable clean separation between business logic and data access, facilitating testing through dependency injection.
+This pattern scales better than Active Record for complex domain logic while maintaining clear boundaries between layers.
 
 ### Architectural Tradeoffs
 
-**CommandGroup Interface** - Centralizes command registration while enabling modular command organization. The pattern requires additional abstraction but provides consistent dependency injection and testing capabilities across all command groups.
+**CommandGroup Interface** - Centralizes command registration while enabling modular command organization.
+The pattern requires additional abstraction but provides consistent dependency injection and testing capabilities across all command groups.
 
-**Handler-based Business Logic** - Business logic in handlers rather than rich domain models keeps the codebase simple and avoids over-engineering. While this approach may not scale to complex business rules, it provides clear separation of concerns for the current feature set.
+**Handler-based Business Logic** - Business logic in handlers rather than rich domain models keeps the codebase simple and avoids over-engineering.
+While this approach may not scale to complex business rules, it provides clear separation of concerns for the current feature set.
 
-**Dual Storage for Articles** - Articles store both markdown and HTML versions to balance processing speed with format flexibility. This doubles storage requirements but eliminates runtime conversion overhead and preserves original formatting.
+**Dual Storage for Articles** - Articles store both markdown and HTML versions to balance processing speed with format flexibility.
+This doubles storage requirements but eliminates runtime conversion overhead and preserves original formatting.
 
 ### Component Interactions
 
-**Handler → Repository → Database** - Request flow follows a linear path from CLI commands through business logic to data persistence. This pattern ensures consistent validation and error handling while maintaining clear separation of concerns.
+**Handler → Repository → Database** - Request flow follows a linear path from CLI commands through business logic to data persistence.
+This pattern ensures consistent validation and error handling while maintaining clear separation of concerns.
 
-**TUI State Management** - Bubbletea's unidirectional data flow provides predictable state updates for interactive components. The model-view-update pattern ensures consistent UI behavior across different terminal environments.
+**TUI State Management** - Bubbletea's unidirectional data flow provides predictable state updates for interactive components.
+The model-view-update pattern ensures consistent UI behavior across different terminal environments.
 
-**Configuration and Migration** - Application startup validates configuration and runs database migrations before initializing handlers. This fail-fast approach prevents runtime errors and ensures consistent database schema across deployments.
+**Configuration and Migration** - Application startup validates configuration and runs database migrations before initializing handlers.
+This fail-fast approach prevents runtime errors and ensures consistent database schema across deployments.

docs/dev/TESTING.md website/docs/development/TESTING.md

···
 
 ## Overview
 
-The codebase follows Go's standard testing practices with specialized testing utilities for complex scenarios. Tests use the standard library along with carefully selected dependencies like faker for data generation and BubbleTea for TUI testing. This approach keeps dependencies minimal while providing robust testing infrastructure for interactive components and complex integrations.
+The codebase follows Go's standard testing practices with specialized testing utilities for complex scenarios.
+Tests use the standard library along with carefully selected dependencies like faker for data generation and BubbleTea for TUI testing.
+This approach keeps dependencies minimal while providing robust testing infrastructure for interactive components and complex integrations.
 
 ### Organization
 
-Each package contains its own test files alongside the source code. Test files are organized by functionality and mirror the structure of the source code they test. The codebase includes four main test utility files that provide specialized testing infrastructure:
+Each package contains its own test files alongside the source code. Test files are organized by functionality and mirror the structure of the source code they test.
+The codebase includes four main test utility files that provide specialized testing infrastructure:
 
 - `internal/services/test_utilities.go` - HTTP mocking and media service testing
 - `internal/repo/test_utilities.go` - Database testing and data generation
···
 
 ### Handler Creation
 
-Tests create real handler instances using temporary databases to ensure test isolation. Factory functions handle both database setup and handler initialization, returning both the handler and a cleanup function.
+Tests create real handler instances using temporary databases to ensure test isolation.
+Factory functions handle both database setup and handler initialization, returning both the handler and a cleanup function.
 
 ### Database Isolation
 
-Tests use temporary directories and environment variable manipulation to create isolated database instances. Each test gets its own temporary SQLite database that is automatically cleaned up after the test completes.
+Tests use temporary directories and environment variable manipulation to create isolated database instances.
+Each test gets its own temporary SQLite database that is automatically cleaned up after the test completes.
 
-The `setupCommandTest` function creates a temporary directory, sets `XDG_CONFIG_HOME` to point to it, and initializes the database schema. This ensures tests don't interfere with each other or with development data.
+The `setupCommandTest` function creates a temporary directory, sets `XDG_CONFIG_HOME` to point to it, and initializes the database schema.
+This ensures tests don't interfere with each other or with development data.
 
 ### Resource Management
 
-Tests properly manage resources using cleanup functions returned by factory methods. The cleanup function handles both handler closure and temporary directory removal. This pattern ensures complete resource cleanup even if tests fail.
+Tests properly manage resources using cleanup functions returned by factory methods.
+The cleanup function handles both handler closure and temporary directory removal.
+This pattern ensures complete resource cleanup even if tests fail.
 
 ### Error Handling
 
-Tests use `t.Fatal` for setup errors that prevent test execution and `t.Error` for test assertion failures. Fatal errors stop test execution while errors allow tests to continue checking other conditions.
+Tests use `t.Fatal` for setup errors that prevent test execution and `t.Error` for test assertion failures.
+Fatal errors stop test execution while errors allow tests to continue checking other conditions.
 
 ### Context Cancellation
 
-Error case testing frequently uses context cancellation to simulate database and network failures. The pattern creates a context, immediately cancels it, then calls the function under test to verify error handling. This provides a reliable way to test error paths without requiring complex mock setups or external failure injection.
+Error case testing frequently uses context cancellation to simulate database and network failures.
+The pattern creates a context, immediately cancels it, then calls the function under test to verify error handling.
+This provides a reliable way to test error paths without requiring complex mock setups or external failure injection.
 
 ### Command Structure
 
-Command group tests verify cobra command structure including use strings, aliases, short descriptions, and subcommand presence. Tests check that commands are properly configured without executing their logic.
+Command group tests verify cobra command structure including use strings, aliases, short descriptions, and subcommand presence.
+Tests check that commands are properly configured without executing their logic.
 
 ### Interface Compliance
 
-Tests verify interface compliance using compile-time checks with blank identifier assignments. This ensures structs implement expected interfaces without runtime overhead.
+Tests verify interface compliance using compile-time checks with blank identifier assignments.
+This ensures structs implement expected interfaces without runtime overhead.
 
 ## Test Infrastructure
 
 ### Test Utility Frameworks
 
-The codebase provides comprehensive testing utilities organized by layer and functionality. Each test utility file contains specialized helpers, mocks, and test infrastructure for its respective domain.
+The codebase provides comprehensive testing utilities organized by layer and functionality.
+Each test utility file contains specialized helpers, mocks, and test infrastructure for its respective domain.
 
 #### Database Testing Utilities
 
···
 
 #### TUI Testing with BubbleTea Framework
 
-The TUI testing framework addresses the fundamental challenge of testing interactive terminal applications in a deterministic, concurrent environment. BubbleTea's message-passing architecture creates unique testing requirements that standard Go testing patterns cannot adequately address.
+The TUI testing framework addresses the fundamental challenge of testing interactive terminal applications in a deterministic, concurrent environment.
+BubbleTea's message-passing architecture creates unique testing requirements that standard Go testing patterns cannot adequately address.
 
-The framework implements a controlled execution environment that replaces BubbleTea's typical program loop with a deterministic testing harness. Rather than running an actual terminal program, the "testing suite" directly manages model state transitions by simulating the Update/View cycle. This approach eliminates the non-deterministic behavior inherent in real terminal interactions while preserving the exact message flow patterns that production code experiences.
+The framework implements a controlled execution environment that replaces BubbleTea's typical program loop with a deterministic testing harness.
+Rather than running an actual terminal program, the "testing suite" directly manages model state transitions by simulating the Update/View cycle.
+This approach eliminates the non-deterministic behavior inherent in real terminal interactions while preserving the exact message flow patterns that production code experiences.
 
-State verification relies on function composition patterns where test conditions are expressed as closures that capture specific model states. The `WaitFor` mechanism uses polling with configurable timeouts, addressing the async nature of BubbleTea model updates without creating race conditions. This pattern bridges imperative test assertions with BubbleTea's declarative update model.
+State verification relies on function composition patterns where test conditions are expressed as closures that capture specific model states.
+The `WaitFor` mechanism uses polling with configurable timeouts, addressing the async nature of BubbleTea model updates without creating race conditions.
+This pattern bridges imperative test assertions with BubbleTea's declarative update model.
 This is inspired by front-end/TS/JS testing patterns.
 
 The framework's I/O abstraction layer replaces terminal input/output with controlled buffers that implement standard Go interfaces.
-This design maintains interface compatibility while providing complete control over timing and content. The controlled I/O system captures all output for later verification and injects precise input sequences, enabling complex interaction testing without external dependencies.
+This design maintains interface compatibility while providing complete control over timing and content.
+The controlled I/O system captures all output for later verification and injects precise input sequences, enabling complex interaction testing without external dependencies.
 
 Concurrency management uses channels and context propagation to coordinate between the testing framework and the model under test.
-The suite manages goroutine lifecycle and ensures proper cleanup, preventing test interference and resource leaks. This architecture supports testing of models that perform background operations or handle async events.
+The suite manages goroutine lifecycle and ensures proper cleanup, preventing test interference and resource leaks.
+This architecture supports testing of models that perform background operations or handle async events.
 
 #### HTTP Service Mocking
 
···
 
 ### Single Root Test
 
-The preferred test organization pattern uses a single root test function with nested subtests using `t.Run`. This provides clear hierarchical organization and allows running specific test sections while maintaining shared setup and context. This pattern offers several advantages: clear test hierarchy with logical grouping, ability to run specific test sections, consistent test structure across the codebase, and shared setup that can be inherited by subtests.
+The preferred test organization pattern uses a single root test function with nested subtests using `t.Run`.
+This provides clear hierarchical organization and allows running specific test sections while maintaining shared setup and context.
+This pattern offers several advantages: clear test hierarchy with logical grouping, ability to run specific test sections, consistent test structure across the codebase, and shared setup that can be inherited by subtests.
 
 ### Integration vs Unit Testing
 
-The codebase emphasizes integration testing over heavy mocking by using real handlers and services to verify actual behavior rather than mocked interactions. The goal is to catch integration issues while maintaining test reliability.
+The codebase emphasizes integration testing over heavy mocking by using real handlers and services to verify actual behavior rather than mocked interactions.
+The goal is to catch integration issues while maintaining test reliability.
 
 ### Static Output
 
···
 
 ### Standard Output Redirection
 
-For testing functions that write to stdout, tests use a pipe redirection pattern with goroutines to capture output. The pattern saves the original stdout, redirects to a pipe, captures output in a separate goroutine, and restores stdout after the test. This ensures clean output capture without interfering with the testing framework.
+For testing functions that write to stdout, tests use a pipe redirection pattern with goroutines to capture output.
+The pattern saves the original stdout, redirects to a pipe, captures output in a separate goroutine, and restores stdout after the test.
+This ensures clean output capture without interfering with the testing framework.
 
 ## Utilities
 
···
 
 ## Testing CLI Commands
 
-Command group tests focus on structure verification rather than execution testing. Tests check command configuration, subcommand presence, and interface compliance. This approach ensures command trees are properly constructed without requiring complex execution mocking.
+Command group tests focus on structure verification rather than execution testing.
+Tests check command configuration, subcommand presence, and interface compliance. This approach ensures command trees are properly constructed without requiring complex execution mocking.
 
 ### CommandGroup Interface Testing
 
-The CommandGroup interface enables testable CLI architecture. Tests verify that command groups implement the interface correctly and return properly configured cobra commands. This pattern separates command structure from command execution.
+The CommandGroup interface enables testable CLI architecture. Tests verify that command groups implement the interface correctly and return properly configured cobra commands.
+This pattern separates command structure from command execution.
 
 Interface compliance is tested using compile-time checks within the "Interface Implementations" subtest, ensuring all command structs properly implement the CommandGroup interface without runtime overhead.
 
 ## Performance Considerations
 
-Tests avoid expensive operations in setup functions. Handler creation uses real instances but tests focus on structure verification rather than full execution paths. This keeps test suites fast while maintaining coverage of critical functionality.
+Tests avoid expensive operations in setup functions. Handler creation uses real instances but tests focus on structure verification rather than full execution paths.
+This keeps test suites fast while maintaining coverage of critical functionality.
 
 The single root test pattern allows for efficient resource management where setup costs can be amortized across multiple related test cases.
 

go.mod

···
 
 require (
 	github.com/BurntSushi/toml v1.5.0
-	github.com/charmbracelet/fang v0.4.2
+	github.com/charmbracelet/fang v0.4.3
 	github.com/mattn/go-sqlite3 v1.14.32
 	github.com/spf13/cobra v1.9.1
 )
···
 	github.com/bluesky-social/indigo v0.0.0-20251031012455-0b4bd2478a61
 	github.com/gomarkdown/markdown v0.0.0-20250810172220-2e2c11897d1a
 	github.com/ipfs/go-cid v0.4.1
-	github.com/jaswdr/faker/v2 v2.8.0
+	github.com/jaswdr/faker/v2 v2.8.1
 )
 
 require (

go.sum

···
 github.com/charmbracelet/bubbletea v1.3.4/go.mod h1:dtcUCyCGEX3g9tosuYiut3MXgY/Jsv9nKVdibKKRRXo=
 github.com/charmbracelet/colorprofile v0.3.2 h1:9J27WdztfJQVAQKX2WOlSSRB+5gaKqqITmrvb1uTIiI=
 github.com/charmbracelet/colorprofile v0.3.2/go.mod h1:mTD5XzNeWHj8oqHb+S1bssQb7vIHbepiebQ2kPKVKbI=
-github.com/charmbracelet/fang v0.4.2 h1:nWr7Tb82/TTNNGMGG35aTZ1X68loAOQmpb0qxkKXjas=
-github.com/charmbracelet/fang v0.4.2/go.mod h1:wHJKQYO5ReYsxx+yZl+skDtrlKO/4LLEQ6EXsdHhRhg=
+github.com/charmbracelet/fang v0.4.3 h1:qXeMxnL4H6mSKBUhDefHu8NfikFbP/MBNTfqTrXvzmY=
+github.com/charmbracelet/fang v0.4.3/go.mod h1:wHJKQYO5ReYsxx+yZl+skDtrlKO/4LLEQ6EXsdHhRhg=
 github.com/charmbracelet/glamour v0.10.0 h1:MtZvfwsYCx8jEPFJm3rIBFIMZUfUJ765oX8V6kXldcY=
 github.com/charmbracelet/glamour v0.10.0/go.mod h1:f+uf+I/ChNmqo087elLnVdCiVgjSKWuXa/l6NU2ndYk=
 github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 h1:ZR7e0ro+SZZiIZD7msJyA+NjkCNNavuiPBLgerbOziE=
···
 github.com/ipld/go-ipld-prime v0.21.0/go.mod h1:3RLqy//ERg/y5oShXXdx5YIp50cFGOanyMctpPjsvxQ=
 github.com/jackpal/go-nat-pmp v1.0.2 h1:KzKSgb7qkJvOUTqYl9/Hg/me3pWgBmERKrTGD7BdWus=
 github.com/jackpal/go-nat-pmp v1.0.2/go.mod h1:QPH045xvCAeXUZOxsnwmrtiCoxIr9eob+4orBN1SBKc=
-github.com/jaswdr/faker/v2 v2.8.0 h1:3AxdXW9U7dJmWckh/P0YgRbNlCcVsTyrUNUnLVP9b3Q=
-github.com/jaswdr/faker/v2 v2.8.0/go.mod h1:jZq+qzNQr8/P+5fHd9t3txe2GNPnthrTfohtnJ7B+68=
+github.com/jaswdr/faker/v2 v2.8.1 h1:2AcPgHDBXYQregFUH9LgVZKfFupc4SIquYhp29sf5wQ=
+github.com/jaswdr/faker/v2 v2.8.1/go.mod h1:jZq+qzNQr8/P+5fHd9t3txe2GNPnthrTfohtnJ7B+68=
 github.com/jbenet/go-cienv v0.1.0/go.mod h1:TqNnHUmJgXau0nCzC7kXWeotg3J9W34CUv5Djy1+FlA=
 github.com/jbenet/goprocess v0.1.4 h1:DRGOFReOMqqDNXwW70QkacFW0YN9QnwLV0Vqk+3oU0o=
 github.com/jbenet/goprocess v0.1.4/go.mod h1:5yspPrukOVuOLORacaBi858NqyClJPQxYZlqdZVfqY4=

internal/docs/ROADMAP.md

···
 
 ### CORE
 
-- [ ] Ensure **all documented subcommands** exist and work:
+- [x] Ensure **all documented subcommands** exist and work:
     - Tasks: add, list, view, update, edit, delete, projects, tags, contexts, done, start, stop, timesheet
     - Notes: create, list, read, edit, remove
     - Books: add, list, reading, finished, remove, progress, update
     - Movies: add, list, watched, remove
     - TV: add, list, watching, watched, remove
     - Articles: add, list, view, read, remove
-- [ ] Confirm all **aliases** work (`todo`, `ls`, `rm`, etc.).
-- [ ] Verify **flags** and argument parsing match man page (priority, project, context, due, tags, etc.).
-- [ ] Implement or finish stubs (e.g. `config management` noted in code).
+- [x] Confirm all **aliases** work (`todo`, `ls`, `rm`, etc.).
+- [x] Verify **flags** and argument parsing match man page (priority, project, context, due, tags, etc.).
+- [x] Implement or finish stubs (e.g. `config management` noted in code).
 
 ### Task Management Domain
 
-- [ ] Verify tasks can be created with all attributes (priority, project, context, due date, tags).
-- [ ] Confirm task listing supports interactive and static modes.
-- [ ] Implement status filtering (`pending`, `completed`, etc.).
-- [ ] Validate time tracking (start/stop) writes entries and timesheet summarizes correctly.
-- [ ] Ensure update supports add/remove tags and all fields.
-- [ ] Test interactive editor (`task edit`).
+- [x] Verify tasks can be created with all attributes (priority, project, context, due date, tags).
+- [x] Confirm task listing supports interactive and static modes.
+- [x] Implement status filtering (`pending`, `completed`, etc.).
+- [x] Validate time tracking (start/stop) writes entries and timesheet summarizes correctly.
+- [x] Ensure update supports add/remove tags and all fields.
+- [x] Test interactive editor (`task edit`).
 
 ### Notes Domain
 
-- [ ] Implement note creation from:
+- [x] Implement note creation from:
     - Inline text
     - File (`--file`)
     - Interactive input (`--interactive`)
-- [ ] Verify note list interactive TUI works, static list fallback works.
-- [ ] Confirm filtering by tags and `--archived`.
-- [ ] Ensure notes can be opened, edited in `$EDITOR`, and deleted.
+- [x] Verify note list interactive TUI works, static list fallback works.
+- [x] Confirm filtering by tags and `--archived`.
+- [x] Ensure notes can be opened, edited in `$EDITOR`, and deleted.
 
 ### Media Domains
 
 #### Books
 
-- [ ] Implement search + add (possibly external API).
-- [ ] Verify list supports statuses (`queued`, `reading`, `finished`).
-- [ ] Progress updates (`book progress`) work with percentages.
-- [ ] Status update (`book update`) accepts valid values.
+- [x] Implement search + add (possibly external API).
+- [x] Verify list supports statuses (`queued`, `reading`, `finished`).
+- [x] Progress updates (`book progress`) work with percentages.
+- [x] Status update (`book update`) accepts valid values.
 
 #### Movies
 
-- [ ] Implement search + add.
-- [ ] Verify `list` with status filtering (`all`, `queued`, `watched`).
-- [ ] Confirm `watched`/`remove` commands update correctly.
+- [x] Implement search + add.
+- [x] Verify `list` with status filtering (`all`, `queued`, `watched`).
+- [x] Confirm `watched`/`remove` commands update correctly.
 
 #### TV
 
-- [ ] Implement search + add.
-- [ ] Verify `list` with multiple statuses (`queued`, `watching`, `watched`).
-- [ ] Ensure `watching`, `watched`, `remove` commands behave correctly.
+- [x] Implement search + add.
+- [x] Verify `list` with multiple statuses (`queued`, `watching`, `watched`).
+- [x] Ensure `watching`, `watched`, `remove` commands behave correctly.
 
 #### Articles
 
-- [ ] Implement article parser (XPath/domain-specific rules).
-- [ ] Save articles in Markdown + HTML.
-- [ ] Verify metadata is stored in DB.
-- [ ] Confirm list supports query, author filter, limit.
-- [ ] Test article view/read/remove.
+- [x] Implement article parser (XPath/domain-specific rules).
+- [x] Save articles in Markdown + HTML.
+- [x] Verify metadata is stored in DB.
+- [x] Confirm list supports query, author filter, limit.
+- [x] Test article view/read/remove.
 
 ### Configuration & Data
 
-- [ ] Implement **config management**
-- [ ] Define config file format (TOML, YAML, JSON).
-- [ ] Set default config/data paths:
+- [x] Implement **config management**
+- [x] Define config file format (TOML, YAML, JSON).
+- [x] Set default config/data paths:
     - Linux: `~/.config/noteleaf`, `~/.local/share/noteleaf`
     - macOS: `~/Library/Application Support/noteleaf`
     - Windows: `%APPDATA%\noteleaf`
-- [ ] Implement overrides with environment variables (`NOTELEAF_CONFIG`, `NOTELEAF_DATA_DIR`).
-- [ ] Ensure consistent DB schema migrations and versioning.
+- [x] Implement overrides with environment variables (`NOTELEAF_CONFIG`, `NOTELEAF_DATA_DIR`).
+- [x] Ensure consistent DB schema migrations and versioning.
 
 ### Documentation
 
-- [ ] Finalize **man page** (plaintext + roff).
-- [ ] Write quickstart guide in `README.md`.
-- [ ] Add examples for each command.
-- [ ] Document config file with defaults and examples.
-- [ ] Provide developer docs for contributing.
+- [x] Finalize **man page** - use `tools/docgen.go` as a dev only command for `website/docs/manual`
+- [x] Strictly follow <https://diataxis.fr/>
+    - [x] Write quickstart guide in `README.md` & add `website/docs/Quickstart.md`
+    - [x] Add examples for each command (`website/docs/examples`)
+    - [x] Document config file with defaults and examples in `website/docs/Configuration.md`
+    - [x] Provide developer docs for contributing in `docs/dev`
+        - [x] Move to `website/docs/development`
 
 ### QA
 

internal/services/services.go

···
 	"time"
 
 	"github.com/stormlightlabs/noteleaf/internal/models"
+	"github.com/stormlightlabs/noteleaf/internal/version"
 	"golang.org/x/time/rate"
 )
 
···
 	// Rate limiting: 180 requests per minute = 3 requests per second
 	requestsPerSecond int = 3
 	burstLimit        int = 5
+)
 
-	// User agent
-	// TODO: See https://www.digitalocean.com/community/tutorials/using-ldflags-to-set-version-information-for-go-applications
-	userAgent string = "Noteleaf/1.0.0 ([e-mail])"
+var (
+	// User agent for HTTP requests - uses version information set at build time
+	userAgent = version.UserAgent("Noteleaf", "[e-mail]")
 )
 
 // APIService defines the contract for API interactions

internal/services/services_test.go

···
 		})
 	})
 
-	t.Run("UserAgent header", func(t *testing.T) {
-		expectedFormat := "Noteleaf/1.0.0 ([e-mail])"
-		if userAgent != expectedFormat {
-			t.Errorf("User agent should follow the required format. Expected %s, got %s", expectedFormat, userAgent)
+	t.Run("UserAgent header format", func(t *testing.T) {
+		expectedPrefix := "Noteleaf/"
+		expectedSuffix := " ([e-mail])"
+		if !strings.HasPrefix(userAgent, expectedPrefix) || !strings.HasSuffix(userAgent, expectedSuffix) {
+			t.Errorf("User agent should follow format 'Noteleaf/<version> ([e-mail])', got %s", userAgent)
 		}
 	})
 

internal/version/version.go

···
+package version
+
+import "fmt"
+
+var (
+	// Version is the semantic version (e.g., "1.0.0", "1.0.0-rc1")
+	Version string = "dev"
+	// Commit is the git commit hash
+	Commit string = "none"
+	// BuildDate is the build timestamp
+	BuildDate string = "unknown"
+)
+
+// String returns a formatted version string
+func String() string {
+	if Version == "dev" && Commit != "none" {
+		return fmt.Sprintf("%s+%s", Version, Commit)
+	}
+	return Version
+}
+
+// UserAgent returns a formatted user agent string for HTTP requests
+func UserAgent(appName, contactEmail string) string {
+	return fmt.Sprintf("%s/%s (%s)", appName, Version, contactEmail)
+}

website/.markdownlint.json

···
 {
     "MD040": false,
     "MD013": false,
+    "MD024": false,
     "MD025": false
 }

website/docs/Configuration.md

···
+# Configuration
+
+Noteleaf stores its configuration in a TOML file. The configuration file location depends on your operating system and can be overridden with environment variables.
+
+## Configuration File Location
+
+### Default Paths
+
+**Linux:**
+
+```sh
+~/.config/noteleaf/.noteleaf.conf.toml
+```
+
+**macOS:**
+
+```sh
+~/Library/Application Support/noteleaf/.noteleaf.conf.toml
+```
+
+**Windows:**
+
+```sh
+%APPDATA%\noteleaf\.noteleaf.conf.toml
+```
+
+### Environment Variable Override
+
+Set `NOTELEAF_CONFIG` to use a custom configuration file location:
+
+```sh
+export NOTELEAF_CONFIG=/path/to/custom/config.toml
+```
+
+## Configuration Options
+
+### General Settings
+
+#### date_format
+
+Format for displaying dates throughout the application.
+
+**Type:** String
+**Default:** `"2006-01-02"` (ISO 8601)
+**Example:**
+
+```toml
+date_format = "2006-01-02"
+```
+
+Common formats:
+
+- `"2006-01-02"` - ISO format: 2024-03-15
+- `"01/02/2006"` - US format: 03/15/2024
+- `"02-Jan-2006"` - Short month: 15-Mar-2024
+
+#### color_scheme
+
+Color scheme for terminal output.
+
+**Type:** String
+**Default:** `"default"`
+**Example:**
+
+```toml
+color_scheme = "default"
+```
+
+#### default_view
+
+Default view mode for interactive lists.
+
+**Type:** String
+**Default:** `"list"`
+**Example:**
+
+```toml
+default_view = "list"
+```
+
+#### default_priority
+
+Default priority for new tasks when not specified.
+
+**Type:** String
+**Default:** None
+**Options:** `"low"`, `"medium"`, `"high"`, `"urgent"`
+**Example:**
+
+```toml
+default_priority = "medium"
+```
+
+#### editor
+
+Text editor for editing notes and tasks. Falls back to `$EDITOR` environment variable if not set.
+
+**Type:** String
+**Default:** None (uses `$EDITOR`)
+**Example:**
+
+```toml
+editor = "vim"
+```
+
+### Data Storage
+
+#### database_path
+
+Custom path to SQLite database file. Leave empty to use default location.
+
+**Type:** String
+**Default:** Platform-specific data directory
+**Example:**
+
+```toml
+database_path = "/custom/path/noteleaf.db"
+```
+
+#### data_dir
+
+Directory for storing application data (articles, notes, attachments).
+
+**Type:** String
+**Default:** Platform-specific data directory
+**Example:**
+
+```toml
+data_dir = "/custom/data/directory"
+```
+
+You can also use the `NOTELEAF_DATA_DIR` environment variable:
+
+```sh
+export NOTELEAF_DATA_DIR=/custom/data/directory
+```
+
+#### articles_dir
+
+Directory for storing saved articles.
+
+**Type:** String
+**Default:** `<data_dir>/articles`
+**Example:**
+
+```toml
+articles_dir = "/path/to/articles"
+```
+
+#### notes_dir
+
+Directory for storing notes.
+
+**Type:** String
+**Default:** `<data_dir>/notes`
+**Example:**
+
+```toml
+notes_dir = "/path/to/notes"
+```
+
+### Archive and Export
+
+#### auto_archive
+
+Automatically archive completed tasks after a specified period.
+
+**Type:** Boolean
+**Default:** `false`
+**Example:**
+
+```toml
+auto_archive = true
+```
+
+#### export_format
+
+Default format for exporting data.
+
+**Type:** String
+**Default:** `"json"`
+**Options:** `"json"`, `"csv"`, `"markdown"`
+**Example:**
+
+```toml
+export_format = "json"
+```
+
+### Synchronization
+
+Synchronization features are planned for future releases.
+
+#### sync_enabled
+
+Enable synchronization with remote server.
+
+**Type:** Boolean
+**Default:** `false`
+**Example:**
+
+```toml
+sync_enabled = false
+```
+
+#### sync_endpoint
+
+URL of the synchronization server.
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+sync_endpoint = "https://sync.example.com/api"
+```
+
+#### sync_token
+
+Authentication token for synchronization.
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+sync_token = "your-secret-token"
+```
+
+### API Keys
+
+#### movie_api_key
+
+API key for movie database services (future feature).
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+movie_api_key = "your-api-key"
+```
+
+#### book_api_key
+
+API key for book database services. Currently uses Open Library which doesn't require an API key.
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+book_api_key = "your-api-key"
+```
+
+### AT Protocol / Bluesky Integration
+
+Configuration for publishing content to Bluesky/AT Protocol.
+
+#### atproto_did
+
+Your Decentralized Identifier (DID) on the AT Protocol network.
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+atproto_did = "did:plc:abcd1234efgh5678"
+```
+
+#### atproto_handle
+
+Your Bluesky/AT Protocol handle.
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+atproto_handle = "username.bsky.social"
+```
+
+#### atproto_pds_url
+
+Personal Data Server URL.
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+atproto_pds_url = "https://bsky.social"
+```
+
+#### atproto_access_jwt
+
+Access token for authentication (managed automatically).
+
+**Type:** String
+**Default:** None
+**Example:**
+
+```toml
+atproto_access_jwt = "eyJhbGc..."
+```
+
+#### atproto_refresh_jwt
+
+Refresh token for authentication (managed automatically).
+
+**Type:** String
+**Default:** None
+
+#### atproto_expires_at
+
+Token expiration timestamp (managed automatically).
+
+**Type:** String (ISO8601)
+**Default:** None
+
+## Managing Configuration
+
+### View Current Configuration
+
+```sh
+noteleaf config show
+```
+
+### Set Configuration Value
+
+```sh
+noteleaf config set <key> <value>
+```
+
+Examples:
+
+```sh
+noteleaf config set editor "nvim"
+noteleaf config set default_priority "high"
+noteleaf config set date_format "01/02/2006"
+```
+
+### Get Configuration Value
+
+```sh
+noteleaf config get <key>
+```
+
+Example:
+
+```sh
+noteleaf config get editor
+```
+
+## Example Configuration
+
+Complete example configuration with common settings:
+
+```toml
+# General settings
+date_format = "2006-01-02"
+color_scheme = "default"
+default_view = "list"
+default_priority = "medium"
+editor = "vim"
+
+# Data storage
+# database_path = ""  # Use default location
+# data_dir = ""       # Use default location
+
+# Archive and export
+auto_archive = false
+export_format = "json"
+
+# Synchronization (future feature)
+sync_enabled = false
+# sync_endpoint = ""
+# sync_token = ""
+
+# API keys (optional)
+# movie_api_key = ""
+# book_api_key = ""
+
+# AT Protocol / Bluesky (optional)
+# atproto_did = ""
+# atproto_handle = ""
+# atproto_pds_url = "https://bsky.social"
+```
+
+## Environment Variables
+
+Noteleaf respects the following environment variables:
+
+- `NOTELEAF_CONFIG` - Custom path to configuration file
+- `NOTELEAF_DATA_DIR` - Custom path to data directory
+- `EDITOR` - Default text editor (fallback if `editor` config not set)
+
+Example:
+
+```sh
+export NOTELEAF_CONFIG=~/.config/noteleaf/config.toml
+export NOTELEAF_DATA_DIR=~/Documents/noteleaf-data
+export EDITOR=nvim
+```

website/docs/Quickstart.md

···
+# Quickstart Guide
+
+This guide will walk you through installing Noteleaf and getting productive with tasks, notes, and media tracking in under 15 minutes.
+
+## Installation
+
+### Requirements
+
+- Go 1.24 or higher
+- Git (for cloning the repository)
+
+### Build and Install
+
+Clone the repository and build the binary:
+
+```sh
+git clone https://github.com/stormlightlabs/noteleaf
+cd noteleaf
+go build -o ./tmp/noteleaf ./cmd
+```
+
+Optionally, install to your GOPATH:
+
+```sh
+go install
+```
+
+## Initialize Noteleaf
+
+Set up the database and configuration:
+
+```sh
+noteleaf setup
+```
+
+This creates:
+
+- Database at `~/.local/share/noteleaf/noteleaf.db` (Linux) or `~/Library/Application Support/noteleaf/noteleaf.db` (macOS)
+- Configuration file at `~/.config/noteleaf/config.toml` (Linux) or `~/Library/Application Support/noteleaf/config.toml` (macOS)
+
+### Optional: Add Sample Data
+
+Explore with pre-populated examples:
+
+```sh
+noteleaf setup seed
+```
+
+## Task Management
+
+### Create Your First Task
+
+```sh
+noteleaf task add "Write project proposal"
+```
+
+### Add a Task with Priority and Project
+
+```sh
+noteleaf task add "Review pull requests" --priority high --project work
+```
+
+### List Tasks
+
+Interactive mode with arrow key navigation:
+
+```sh
+noteleaf task list
+```
+
+Static output for scripting:
+
+```sh
+noteleaf task list --static
+```
+
+### Mark a Task as Done
+
+```sh
+noteleaf task done 1
+```
+
+### Track Time
+
+Start tracking:
+
+```sh
+noteleaf task start 1
+```
+
+Stop tracking:
+
+```sh
+noteleaf task stop 1
+```
+
+View timesheet:
+
+```sh
+noteleaf task timesheet
+```
+
+## Note Taking
+
+### Create a Note
+
+Quick note from command line:
+
+```sh
+noteleaf note create "Meeting Notes" "Discussed Q4 roadmap and priorities"
+```
+
+Create with your editor:
+
+```sh
+noteleaf note create --interactive
+```
+
+Create from a file:
+
+```sh
+noteleaf note create --file notes.md
+```
+
+### List and Read Notes
+
+List all notes (interactive):
+
+```sh
+noteleaf note list
+```
+
+Read a specific note:
+
+```sh
+noteleaf note read 1
+```
+
+### Edit a Note
+
+Opens in your `$EDITOR`:
+
+```sh
+noteleaf note edit 1
+```
+
+## Media Tracking
+
+### Books
+
+Search and add from Open Library:
+
+```sh
+noteleaf media book add "Project Hail Mary"
+```
+
+List your reading queue:
+
+```sh
+noteleaf media book list
+```
+
+Update reading progress:
+
+```sh
+noteleaf media book progress 1 45
+```
+
+Mark as finished:
+
+```sh
+noteleaf media book finished 1
+```
+
+### Movies
+
+Add a movie:
+
+```sh
+noteleaf media movie add "The Matrix"
+```
+
+Mark as watched:
+
+```sh
+noteleaf media movie watched 1
+```
+
+### TV Shows
+
+Add a show:
+
+```sh
+noteleaf media tv add "Breaking Bad"
+```
+
+Update status:
+
+```sh
+noteleaf media tv watching 1
+```
+
+## Articles
+
+### Save an Article
+
+Parse and save from URL:
+
+```sh
+noteleaf article add https://example.com/interesting-post
+```
+
+### List Articles
+
+```sh
+noteleaf article list
+```
+
+Filter by author:
+
+```sh
+noteleaf article list --author "Jane Smith"
+```
+
+### Read an Article
+
+View in terminal:
+
+```sh
+noteleaf article view 1
+```
+
+## Configuration
+
+### View Current Configuration
+
+```sh
+noteleaf config show
+```
+
+### Set Configuration Values
+
+```sh
+noteleaf config set editor vim
+noteleaf config set default_priority medium
+```
+
+### Check Status
+
+View application status and paths:
+
+```sh
+noteleaf status
+```
+
+## Getting Help
+
+View help for any command:
+
+```sh
+noteleaf --help
+noteleaf task --help
+noteleaf task add --help
+```
+
+## Next Steps
+
+Now that you have the basics down:
+
+- Explore advanced task filtering and queries
+- Create custom projects and contexts for organizing tasks
+- Link notes to tasks and media items
+- Set up recurring tasks and dependencies
+- Configure the application to match your workflow
+
+For detailed documentation on each command, see the CLI reference in the manual section.

website/docs/examples/articles.md

···
+# Article Examples
+
+Examples of saving and managing articles using Noteleaf.
+
+## Saving Articles
+
+### Save Article from URL
+
+```sh
+noteleaf article add https://example.com/interesting-article
+```
+
+### Save with Custom Title
+
+```sh
+noteleaf article add https://example.com/article --title "My Custom Title"
+```
+
+### Save Multiple Articles
+
+```sh
+noteleaf article add https://example.com/article-1
+noteleaf article add https://example.com/article-2
+noteleaf article add https://example.com/article-3
+```
+
+## Viewing Articles
+
+### List All Articles
+
+```sh
+noteleaf article list
+```
+
+### Filter by Author
+
+```sh
+noteleaf article list --author "Jane Smith"
+noteleaf article list --author "John Doe"
+```
+
+### Filter with Query
+
+```sh
+noteleaf article list --query "golang"
+noteleaf article list --query "machine learning"
+```
+
+### Limit Results
+
+```sh
+noteleaf article list --limit 10
+noteleaf article list --limit 5
+```
+
+### View Article Content
+
+Display in terminal:
+
+```sh
+noteleaf article view 1
+```
+
+Read in browser:
+
+```sh
+noteleaf article read 1
+```
+
+## Managing Articles
+
+### Update Article Metadata
+
+Update title:
+
+```sh
+noteleaf article update 1 --title "Updated Title"
+```
+
+Update author:
+
+```sh
+noteleaf article update 1 --author "Jane Doe"
+```
+
+Add notes:
+
+```sh
+noteleaf article update 1 --notes "Great insights on API design"
+```
+
+### Remove Article
+
+```sh
+noteleaf article remove 1
+```
+
+Remove multiple:
+
+```sh
+noteleaf article remove 1 2 3
+```
+
+## Common Workflows
+
+### Reading List Management
+
+Save articles to read later:
+
+```sh
+noteleaf article add https://blog.example.com/microservices
+noteleaf article add https://dev.to/understanding-async
+noteleaf article add https://medium.com/best-practices
+
+# View reading list
+noteleaf article list
+```
+
+### Research Collection
+
+Collect articles for research:
+
+```sh
+# Save research articles
+noteleaf article add https://arxiv.org/paper1 --notes "Research: ML optimization"
+noteleaf article add https://arxiv.org/paper2 --notes "Research: Neural networks"
+
+# Find research articles
+noteleaf article list --query "Research"
+```
+
+### Technical Documentation
+
+Archive technical articles:
+
+```sh
+noteleaf article add https://docs.example.com/api-guide --notes "Category: Documentation"
+noteleaf article add https://tutorials.example.com/setup --notes "Category: Tutorial"
+
+# Find documentation
+noteleaf article list --query "Documentation"
+```
+
+### Author Following
+
+Track articles by favorite authors:
+
+```sh
+# Save articles
+noteleaf article add https://blog.author1.com/post1 --author "Martin Fowler"
+noteleaf article add https://blog.author1.com/post2 --author "Martin Fowler"
+
+# View articles by author
+noteleaf article list --author "Martin Fowler"
+```
+
+### Topic Collections
+
+Organize by topic using notes:
+
+```sh
+# Backend articles
+noteleaf article add https://example.com/databases --notes "Topic: Backend, Database"
+noteleaf article add https://example.com/caching --notes "Topic: Backend, Performance"
+
+# Frontend articles
+noteleaf article add https://example.com/react --notes "Topic: Frontend, React"
+noteleaf article add https://example.com/css --notes "Topic: Frontend, CSS"
+
+# Find by topic
+noteleaf article list --query "Backend"
+noteleaf article list --query "Frontend"
+```
+
+### Daily Reading Routine
+
+Save articles during the day:
+
+```sh
+# Morning
+noteleaf article add https://news.ycombinator.com/article1
+noteleaf article add https://reddit.com/r/programming/article2
+
+# Evening - review saved articles
+noteleaf article list
+noteleaf article view 1
+noteleaf article view 2
+```
+
+### Offline Reading
+
+Save articles for offline access:
+
+```sh
+# Save articles before travel
+noteleaf article add https://longform.com/essay1
+noteleaf article add https://magazine.com/feature
+
+# Read offline (articles are saved locally)
+noteleaf article view 1
+noteleaf article view 2
+```
+
+### Archive and Cleanup
+
+Remove read articles:
+
+```sh
+# List articles
+noteleaf article list
+
+# Remove articles you've read
+noteleaf article remove 1 2 3 4 5
+
+# Keep only recent articles (manual filtering)
+noteleaf article list --limit 20
+```
+
+### Share-worthy Content
+
+Mark articles worth sharing:
+
+```sh
+noteleaf article add https://excellent.article.com --notes "Share: Twitter, Newsletter"
+noteleaf article add https://must-read.com/post --notes "Share: Team, Blog"
+
+# Find share-worthy articles
+noteleaf article list --query "Share"
+```
+
+### Learning Path
+
+Create structured learning collections:
+
+```sh
+# Beginner articles
+noteleaf article add https://tutorial.com/intro --notes "Level: Beginner, Go"
+noteleaf article add https://tutorial.com/basics --notes "Level: Beginner, Go"
+
+# Advanced articles
+noteleaf article add https://advanced.com/patterns --notes "Level: Advanced, Go"
+
+# Find by level
+noteleaf article list --query "Beginner"
+noteleaf article list --query "Advanced"
+```
+
+### Weekly Digests
+
+Collect interesting articles weekly:
+
+```sh
+# Week 1
+noteleaf article add https://example.com/week1-1 --notes "Week: 2024-W01"
+noteleaf article add https://example.com/week1-2 --notes "Week: 2024-W01"
+
+# Week 2
+noteleaf article add https://example.com/week2-1 --notes "Week: 2024-W02"
+
+# Review week's articles
+noteleaf article list --query "2024-W01"
+```
+
+## Exporting Articles
+
+### Export Article to File
+
+```sh
+noteleaf article export 1 --format markdown > article.md
+noteleaf article export 1 --format html > article.html
+```
+
+### Export Multiple Articles
+
+```sh
+noteleaf article export --all --format markdown --output articles/
+```
+
+### Export by Query
+
+```sh
+noteleaf article export --query "golang" --format markdown --output go-articles/
+```
+
+## Integration with Notes
+
+### Create Note from Article
+
+After reading:
+
+```sh
+# Read article
+noteleaf article view 1
+
+# Create summary note
+noteleaf note create "Article Summary: Title" "
+Source: [Article URL]
+Author: [Author Name]
+
+Key Points:
+- Point 1
+- Point 2
+
+My Thoughts:
+- Observation 1
+- Observation 2
+" --tags article-summary,topic
+```
+
+### Link Article to Task
+
+Create follow-up task:
+
+```sh
+# Save article
+noteleaf article add https://example.com/implement-feature
+
+# Create related task
+noteleaf task add "Implement feature from article #1" --tags implementation
+```
+
+## Article Statistics
+
+### Count Articles
+
+```sh
+noteleaf article list | wc -l
+```
+
+### Articles by Author
+
+```sh
+noteleaf article list --author "Author Name" | wc -l
+```
+
+### Articles by Topic
+
+```sh
+noteleaf article list --query "topic" | wc -l
+```

website/docs/examples/media.md

···
+# Media Examples
+
+Examples of managing your reading lists and watch queues using Noteleaf.
+
+## Books
+
+### Adding Books
+
+Search and add from Open Library:
+
+```sh
+noteleaf media book add "The Name of the Wind"
+noteleaf media book add "Project Hail Mary"
+noteleaf media book add "Dune"
+```
+
+Add by author:
+
+```sh
+noteleaf media book add "Foundation by Isaac Asimov"
+```
+
+Add with specific year:
+
+```sh
+noteleaf media book add "1984 by George Orwell 1949"
+```
+
+### Viewing Books
+
+List all books:
+
+```sh
+noteleaf media book list
+```
+
+Filter by status:
+
+```sh
+noteleaf media book list --status queued
+noteleaf media book list --status reading
+noteleaf media book list --status finished
+```
+
+### Managing Reading Status
+
+Start reading:
+
+```sh
+noteleaf media book reading 1
+```
+
+Mark as finished:
+
+```sh
+noteleaf media book finished 1
+```
+
+### Tracking Progress
+
+Update reading progress (percentage):
+
+```sh
+noteleaf media book progress 1 25
+noteleaf media book progress 1 50
+noteleaf media book progress 1 75
+```
+
+Update with page numbers:
+
+```sh
+noteleaf media book progress 1 150 --total 400
+```
+
+### Book Details
+
+View book details:
+
+```sh
+noteleaf media book view 1
+```
+
+### Updating Book Information
+
+Update book notes:
+
+```sh
+noteleaf media book update 1 --notes "Excellent worldbuilding and magic system"
+```
+
+Add rating:
+
+```sh
+noteleaf media book update 1 --rating 5
+```
+
+### Removing Books
+
+Remove from list:
+
+```sh
+noteleaf media book remove 1
+```
+
+## Movies
+
+### Adding Movies
+
+Add movie:
+
+```sh
+noteleaf media movie add "The Matrix"
+noteleaf media movie add "Inception"
+noteleaf media movie add "Interstellar"
+```
+
+Add with year:
+
+```sh
+noteleaf media movie add "Blade Runner 1982"
+```
+
+### Viewing Movies
+
+List all movies:
+
+```sh
+noteleaf media movie list
+```
+
+Filter by status:
+
+```sh
+noteleaf media movie list --status queued
+noteleaf media movie list --status watched
+```
+
+### Managing Watch Status
+
+Mark as watched:
+
+```sh
+noteleaf media movie watched 1
+```
+
+### Movie Details
+
+View movie details:
+
+```sh
+noteleaf media movie view 1
+```
+
+### Updating Movie Information
+
+Add notes and rating:
+
+```sh
+noteleaf media movie update 1 --notes "Mind-bending sci-fi" --rating 5
+```
+
+### Removing Movies
+
+Remove from list:
+
+```sh
+noteleaf media movie remove 1
+```
+
+## TV Shows
+
+### Adding TV Shows
+
+Add TV show:
+
+```sh
+noteleaf media tv add "Breaking Bad"
+noteleaf media tv add "The Wire"
+noteleaf media tv add "Better Call Saul"
+```
+
+### Viewing TV Shows
+
+List all shows:
+
+```sh
+noteleaf media tv list
+```
+
+Filter by status:
+
+```sh
+noteleaf media tv list --status queued
+noteleaf media tv list --status watching
+noteleaf media tv list --status watched
+```
+
+### Managing Watch Status
+
+Start watching:
+
+```sh
+noteleaf media tv watching 1
+```
+
+Mark as finished:
+
+```sh
+noteleaf media tv watched 1
+```
+
+Put on hold:
+
+```sh
+noteleaf media tv update 1 --status on-hold
+```
+
+### TV Show Details
+
+View show details:
+
+```sh
+noteleaf media tv view 1
+```
+
+### Updating TV Show Information
+
+Update current episode:
+
+```sh
+noteleaf media tv update 1 --season 2 --episode 5
+```
+
+Add notes and rating:
+
+```sh
+noteleaf media tv update 1 --notes "Intense character development" --rating 5
+```
+
+### Removing TV Shows
+
+Remove from list:
+
+```sh
+noteleaf media tv remove 1
+```
+
+## Common Workflows
+
+### Weekend Watch List
+
+Plan your weekend viewing:
+
+```sh
+# Add movies
+noteleaf media movie add "The Shawshank Redemption"
+noteleaf media movie add "Pulp Fiction"
+noteleaf media movie add "Forrest Gump"
+
+# View queue
+noteleaf media movie list --status queued
+```
+
+### Reading Challenge
+
+Track annual reading goal:
+
+```sh
+# Add books to queue
+noteleaf media book add "The Lord of the Rings"
+noteleaf media book add "The Hobbit"
+noteleaf media book add "Mistborn"
+
+# Check progress
+noteleaf media book list --status finished
+noteleaf media book list --status reading
+```
+
+### Binge Watching Tracker
+
+Track TV series progress:
+
+```sh
+# Start series
+noteleaf media tv add "Game of Thrones"
+noteleaf media tv watching 1
+
+# Update progress
+noteleaf media tv update 1 --season 1 --episode 1
+noteleaf media tv update 1 --season 1 --episode 2
+
+# View current shows
+noteleaf media tv list --status watching
+```
+
+### Media Recommendations
+
+Keep track of recommendations:
+
+```sh
+# Add recommended items
+noteleaf media book add "Sapiens" --notes "Recommended by John"
+noteleaf media movie add "Parasite" --notes "Won Best Picture 2020"
+noteleaf media tv add "Succession" --notes "From Reddit recommendations"
+
+# View recommendations
+noteleaf media book list --static | grep "Recommended"
+```
+
+### Review and Rating
+
+After finishing, add review:
+
+```sh
+# Book review
+noteleaf media book finished 1
+noteleaf media book update 1 \
+  --rating 5 \
+  --notes "Masterful storytelling. The magic system is one of the best in fantasy."
+
+# Movie review
+noteleaf media movie watched 2
+noteleaf media movie update 2 \
+  --rating 4 \
+  --notes "Great cinematography but slow pacing in second act."
+
+# TV show review
+noteleaf media tv watched 3
+noteleaf media tv update 3 \
+  --rating 5 \
+  --notes "Best character development I've seen. Final season was perfect."
+```
+
+### Genre Organization
+
+Organize by genre using notes:
+
+```sh
+noteleaf media book add "Snow Crash" --notes "Genre: Cyberpunk"
+noteleaf media book add "Neuromancer" --notes "Genre: Cyberpunk"
+noteleaf media book add "The Expanse" --notes "Genre: Space Opera"
+
+# Find by genre
+noteleaf media book list --static | grep "Cyberpunk"
+```
+
+### Currently Consuming
+
+See what you're currently reading/watching:
+
+```sh
+noteleaf media book list --status reading
+noteleaf media tv list --status watching
+```
+
+### Completed This Month
+
+View completed items:
+
+```sh
+noteleaf media book list --status finished
+noteleaf media movie list --status watched
+noteleaf media tv list --status watched
+```
+
+### Clear Finished Items
+
+Archive or remove completed media:
+
+```sh
+# Remove watched movies
+noteleaf media movie remove 1 2 3
+
+# Remove finished books
+noteleaf media book remove 4 5 6
+```
+
+## Statistics and Reports
+
+### Reading Statistics
+
+Count books by status:
+
+```sh
+echo "Queued: $(noteleaf media book list --status queued --static | wc -l)"
+echo "Reading: $(noteleaf media book list --status reading --static | wc -l)"
+echo "Finished: $(noteleaf media book list --status finished --static | wc -l)"
+```
+
+### Viewing Habits
+
+Track watch queue size:
+
+```sh
+echo "Movies to watch: $(noteleaf media movie list --status queued --static | wc -l)"
+echo "Shows in progress: $(noteleaf media tv list --status watching --static | wc -l)"
+```

website/docs/examples/notes.md

···
+# Note Examples
+
+Examples of note-taking workflows using Noteleaf.
+
+## Creating Notes
+
+### Create Note from Command Line
+
+```sh
+noteleaf note create "Meeting Notes" "Discussed Q4 roadmap and priorities"
+```
+
+### Create Note with Tags
+
+```sh
+noteleaf note create "API Design Ideas" "REST vs GraphQL considerations" --tags api,design
+```
+
+### Create Note from File
+
+```sh
+noteleaf note create --file notes.md
+```
+
+### Create Note Interactively
+
+Opens your editor for composition:
+
+```sh
+noteleaf note create --interactive
+```
+
+Specify editor:
+
+```sh
+EDITOR=vim noteleaf note create --interactive
+```
+
+### Create Note with Multiple Paragraphs
+
+```sh
+noteleaf note create "Project Retrospective" "
+What went well:
+- Good team collaboration
+- Met all deadlines
+- Quality code reviews
+
+What to improve:
+- Better documentation
+- More automated tests
+- Earlier stakeholder feedback
+"
+```
+
+## Viewing Notes
+
+### List All Notes
+
+Interactive mode:
+
+```sh
+noteleaf note list
+```
+
+Static output:
+
+```sh
+noteleaf note list --static
+```
+
+### Filter by Tags
+
+```sh
+noteleaf note list --tags meeting
+noteleaf note list --tags api,design
+```
+
+### View Archived Notes
+
+```sh
+noteleaf note list --archived
+```
+
+### Read a Note
+
+Display note content:
+
+```sh
+noteleaf note read 1
+```
+
+### Search Notes
+
+```sh
+noteleaf note search "API design"
+noteleaf note search "meeting notes"
+```
+
+## Editing Notes
+
+### Edit Note in Editor
+
+Opens note in your editor:
+
+```sh
+noteleaf note edit 1
+```
+
+With specific editor:
+
+```sh
+EDITOR=nvim noteleaf note edit 1
+```
+
+### Update Note Title
+
+```sh
+noteleaf note update 1 --title "Updated Meeting Notes"
+```
+
+### Add Tags to Note
+
+```sh
+noteleaf note tag 1 --add important,todo
+```
+
+### Remove Tags from Note
+
+```sh
+noteleaf note tag 1 --remove draft
+```
+
+## Organizing Notes
+
+### Archive a Note
+
+```sh
+noteleaf note archive 1
+```
+
+### Unarchive a Note
+
+```sh
+noteleaf note unarchive 1
+```
+
+### Delete a Note
+
+```sh
+noteleaf note remove 1
+```
+
+With confirmation:
+
+```sh
+noteleaf note remove 1 --confirm
+```
+
+## Common Workflows
+
+### Quick Meeting Notes
+
+```sh
+noteleaf note create "Team Standup $(date +%Y-%m-%d)" --interactive --tags meeting,standup
+```
+
+### Project Documentation
+
+```sh
+noteleaf note create "Project Architecture" "$(cat architecture.md)" --tags docs,architecture
+```
+
+### Research Notes
+
+Create research note:
+
+```sh
+noteleaf note create "GraphQL Research" --interactive --tags research,api
+```
+
+List all research notes:
+
+```sh
+noteleaf note list --tags research
+```
+
+### Code Snippets
+
+```sh
+noteleaf note create "Useful Git Commands" "
+# Rebase last 3 commits
+git rebase -i HEAD~3
+
+# Undo last commit
+git reset --soft HEAD~1
+
+# Show files changed in commit
+git show --name-only <commit>
+" --tags git,snippets,reference
+```
+
+### Daily Journal
+
+```sh
+noteleaf note create "Journal $(date +%Y-%m-%d)" --interactive --tags journal
+```
+
+### Ideas and Brainstorming
+
+```sh
+noteleaf note create "Product Ideas" --interactive --tags ideas,product
+```
+
+List all ideas:
+
+```sh
+noteleaf note list --tags ideas
+```
+
+## Exporting Notes
+
+### Export Single Note
+
+```sh
+noteleaf note export 1 --format markdown > note.md
+noteleaf note export 1 --format html > note.html
+```
+
+### Export All Notes
+
+```sh
+noteleaf note export --all --format markdown --output notes/
+```
+
+### Export Notes by Tag
+
+```sh
+noteleaf note export --tags meeting --format markdown --output meetings/
+```
+
+## Advanced Usage
+
+### Template-based Notes
+
+Create a note template file:
+
+```sh
+cat > ~/templates/meeting.md << 'EOF'
+# Meeting: [TITLE]
+Date: [DATE]
+Attendees: [NAMES]
+
+## Agenda
+-
+
+## Discussion
+-
+
+## Action Items
+- [ ]
+
+## Next Meeting
+Date:
+EOF
+```
+
+Use template:
+
+```sh
+noteleaf note create --file ~/templates/meeting.md
+```
+
+### Linking Notes
+
+Reference other notes in content:
+
+```sh
+noteleaf note create "Implementation Plan" "
+Based on the design in Note #5, we will:
+1. Set up database schema (see Note #12)
+2. Implement API endpoints
+3. Add frontend components
+
+Related: Note #5 (Design), Note #12 (Schema)
+" --tags implementation,plan
+```
+
+### Note Statistics
+
+View note count by tag:
+
+```sh
+noteleaf note list --static | grep -c "tag:meeting"
+```

website/docs/examples/publication.md

···
+# Publication Examples
+
+Examples of publishing notes to leaflet.pub using the AT Protocol integration.
+
+## Overview
+
+The publication system allows you to sync your local notes with leaflet.pub, an AT Protocol-based publishing platform. You can pull drafts from leaflet, publish local notes, and maintain a synchronized writing workflow across platforms.
+
+## Authentication
+
+### Initial Authentication
+
+Authenticate with your BlueSky account:
+
+```sh
+noteleaf pub auth username.bsky.social
+```
+
+This will prompt for your app password interactively.
+
+### Authenticate with Password Flag
+
+Provide credentials directly:
+
+```sh
+noteleaf pub auth username.bsky.social --password "your-app-password"
+```
+
+### Creating an App Password
+
+1. Visit [bsky.app/settings/app-passwords](https://bsky.app/settings/app-passwords)
+2. Create a new app password named "noteleaf"
+3. Use that password (not your main password) for authentication
+
+### Check Authentication Status
+
+```sh
+noteleaf pub status
+```
+
+## Pulling Documents from Leaflet
+
+### Pull All Documents
+
+Fetch all drafts and published documents:
+
+```sh
+noteleaf pub pull
+```
+
+This will:
+- Connect to your leaflet account
+- Fetch all documents in your repository
+- Create new notes for documents not yet synced
+- Update existing notes that have changed
+
+### After Pulling
+
+List the synced notes:
+
+```sh
+noteleaf pub list
+```
+
+View synced notes interactively:
+
+```sh
+noteleaf pub list --interactive
+```
+
+## Publishing Local Notes
+
+### Publish a Note
+
+Create a new document on leaflet from a local note:
+
+```sh
+noteleaf pub post 123
+```
+
+### Publish as Draft
+
+Create as draft instead of publishing immediately:
+
+```sh
+noteleaf pub post 123 --draft
+```
+
+### Preview Before Publishing
+
+See what would be posted without actually posting:
+
+```sh
+noteleaf pub post 123 --preview
+```
+
+### Validate Conversion
+
+Check if markdown conversion will work:
+
+```sh
+noteleaf pub post 123 --validate
+```
+
+## Updating Published Documents
+
+### Update an Existing Document
+
+Update a previously published note:
+
+```sh
+noteleaf pub patch 123
+```
+
+### Preview Update
+
+See what would be updated:
+
+```sh
+noteleaf pub patch 123 --preview
+```
+
+### Validate Update
+
+Check conversion before updating:
+
+```sh
+noteleaf pub patch 123 --validate
+```
+
+## Batch Operations
+
+### Publish Multiple Notes
+
+Create or update multiple documents at once:
+
+```sh
+noteleaf pub push 1 2 3 4 5
+```
+
+This will:
+- Create new documents for notes never published
+- Update existing documents for notes already on leaflet
+
+### Batch Publish as Drafts
+
+```sh
+noteleaf pub push 10 11 12 --draft
+```
+
+## Viewing Publications
+
+### List All Synced Notes
+
+```sh
+noteleaf pub list
+```
+
+Aliases:
+```sh
+noteleaf pub ls
+```
+
+### Filter by Status
+
+Published documents only:
+```sh
+noteleaf pub list --published
+```
+
+Drafts only:
+```sh
+noteleaf pub list --draft
+```
+
+All documents:
+```sh
+noteleaf pub list --all
+```
+
+### Interactive Browser
+
+Browse with TUI interface:
+
+```sh
+noteleaf pub list --interactive
+noteleaf pub list -i
+```
+
+With filters:
+```sh
+noteleaf pub list --published --interactive
+noteleaf pub list --draft -i
+```
+
+## Common Workflows
+
+### Initial Setup and Pull
+
+Set up leaflet integration and pull existing documents:
+
+```sh
+# Authenticate
+noteleaf pub auth username.bsky.social
+
+# Check status
+noteleaf pub status
+
+# Pull all documents
+noteleaf pub pull
+
+# View synced notes
+noteleaf pub list --interactive
+```
+
+### Publishing Workflow
+
+Write locally, then publish to leaflet:
+
+```sh
+# Create a note
+noteleaf note create "My Blog Post" --interactive
+
+# List notes to get ID
+noteleaf note list
+
+# Publish as draft first
+noteleaf pub post 42 --draft
+
+# Review draft on leaflet.pub
+# Make edits locally
+noteleaf note edit 42
+
+# Update the draft
+noteleaf pub patch 42
+
+# When ready, republish without --draft flag
+noteleaf pub post 42
+```
+
+### Sync Workflow
+
+Keep local notes in sync with leaflet:
+
+```sh
+# Pull latest changes from leaflet
+noteleaf pub pull
+
+# Make local edits
+noteleaf note edit 123
+
+# Push changes back
+noteleaf pub patch 123
+
+# Check sync status
+noteleaf pub list --published
+```
+
+### Draft Management
+
+Work with drafts before publishing:
+
+```sh
+# Create drafts
+noteleaf pub post 10 --draft
+noteleaf pub post 11 --draft
+noteleaf pub post 12 --draft
+
+# View all drafts
+noteleaf pub list --draft
+
+# Edit a draft locally
+noteleaf note edit 10
+
+# Update on leaflet
+noteleaf pub patch 10
+
+# Promote draft to published (re-post without --draft)
+noteleaf pub post 10
+```
+
+### Batch Publishing
+
+Publish multiple notes at once:
+
+```sh
+# Create several notes
+noteleaf note create "Post 1" "Content 1"
+noteleaf note create "Post 2" "Content 2"
+noteleaf note create "Post 3" "Content 3"
+
+# Get note IDs
+noteleaf note list --static
+
+# Publish all at once
+noteleaf pub push 50 51 52
+
+# Or as drafts
+noteleaf pub push 50 51 52 --draft
+```
+
+### Review Before Publishing
+
+Always preview and validate before publishing:
+
+```sh
+# Validate markdown conversion
+noteleaf pub post 99 --validate
+
+# Preview the output
+noteleaf pub post 99 --preview
+
+# If everything looks good, publish
+noteleaf pub post 99
+```
+
+### Cross-Platform Editing
+
+Edit on leaflet.pub, sync to local:
+
+```sh
+# Pull changes from leaflet
+noteleaf pub pull
+
+# View what changed
+noteleaf pub list --interactive
+
+# Make additional edits locally
+noteleaf note edit 123
+
+# Push updates back
+noteleaf pub patch 123
+```
+
+### Status Monitoring
+
+Check authentication and publication status:
+
+```sh
+# Check auth status
+noteleaf pub status
+
+# List published documents
+noteleaf pub list --published
+
+# Count publications
+noteleaf pub list --published --static | wc -l
+```
+
+## Troubleshooting
+
+### Re-authenticate
+
+If authentication expires:
+
+```sh
+noteleaf pub auth username.bsky.social
+```
+
+### Check Status
+
+Verify connection:
+
+```sh
+noteleaf pub status
+```
+
+### Force Pull
+
+Re-sync all documents:
+
+```sh
+noteleaf pub pull
+```
+
+### Validate Before Publishing
+
+If publishing fails, validate first:
+
+```sh
+noteleaf pub post 123 --validate
+```
+
+Check for markdown formatting issues that might not convert properly.
+
+## Integration with Notes
+
+### Publishing Flow
+
+```sh
+# Create note locally
+noteleaf note create "Article Title" --interactive
+
+# Add tags for organization
+noteleaf note tag 1 --add published,blog
+
+# Publish to leaflet
+noteleaf pub post 1
+
+# Continue editing locally
+noteleaf note edit 1
+
+# Sync updates
+noteleaf pub patch 1
+```
+
+### Import from Leaflet
+
+```sh
+# Pull from leaflet
+noteleaf pub pull
+
+# View imported notes
+noteleaf pub list
+
+# Edit locally
+noteleaf note edit 123
+
+# Continue working with standard note commands
+noteleaf note read 123
+noteleaf note tag 123 --add imported
+```
+
+## Advanced Usage
+
+### Selective Publishing
+
+Publish only specific notes with a tag:
+
+```sh
+# Tag notes for publication
+noteleaf note tag 10 --add ready-to-publish
+noteleaf note tag 11 --add ready-to-publish
+
+# List tagged notes
+noteleaf note list --tags ready-to-publish
+
+# Publish those notes
+noteleaf pub push 10 11
+```
+
+### Draft Review Cycle
+
+```sh
+# Publish drafts
+noteleaf pub push 1 2 3 --draft
+
+# Review on leaflet.pub in browser
+# Make edits locally based on feedback
+
+# Update drafts
+noteleaf pub push 1 2 3
+
+# When ready, publish (create as non-drafts)
+noteleaf pub post 1
+noteleaf pub post 2
+noteleaf pub post 3
+```
+
+### Publication Archive
+
+Keep track of published work:
+
+```sh
+# Tag published notes
+noteleaf note tag 123 --add published,2024,blog
+
+# List all published notes
+noteleaf note list --tags published
+
+# Archive old publications
+noteleaf note archive 123
+```
+
+## Notes
+
+- Authentication tokens are stored in the configuration file
+- Notes are matched by their leaflet record key (rkey)
+- The `push` command intelligently chooses between `post` and `patch`
+- Draft status is preserved when patching existing documents
+- Use `--preview` and `--validate` flags to test before publishing
+- Pull regularly to stay synced with changes made on leaflet.pub

website/docs/examples/tasks.md

···
+# Task Examples
+
+Examples of common task management workflows using Noteleaf.
+
+## Basic Task Management
+
+### Create a Simple Task
+
+```sh
+noteleaf task add "Buy groceries"
+```
+
+### Create Task with Priority
+
+```sh
+noteleaf task add "Fix critical bug" --priority urgent
+noteleaf task add "Update documentation" --priority low
+```
+
+### Create Task with Project
+
+```sh
+noteleaf task add "Design new homepage" --project website
+noteleaf task add "Refactor auth service" --project backend
+```
+
+### Create Task with Due Date
+
+```sh
+noteleaf task add "Submit report" --due 2024-12-31
+noteleaf task add "Review PRs" --due tomorrow
+```
+
+### Create Task with Tags
+
+```sh
+noteleaf task add "Write blog post" --tags writing,blog
+noteleaf task add "Server maintenance" --tags ops,backend,infra
+```
+
+### Create Task with Context
+
+```sh
+noteleaf task add "Call client" --context phone
+noteleaf task add "Deploy to production" --context office
+```
+
+### Create Task with All Attributes
+
+```sh
+noteleaf task add "Launch marketing campaign" \
+  --project marketing \
+  --priority high \
+  --due 2024-06-15 \
+  --tags campaign,social \
+  --context office
+```
+
+## Viewing Tasks
+
+### List All Tasks
+
+Interactive mode:
+
+```sh
+noteleaf task list
+```
+
+Static output:
+
+```sh
+noteleaf task list --static
+```
+
+### Filter by Status
+
+```sh
+noteleaf task list --status pending
+noteleaf task list --status completed
+```
+
+### Filter by Priority
+
+```sh
+noteleaf task list --priority high
+noteleaf task list --priority urgent
+```
+
+### Filter by Project
+
+```sh
+noteleaf task list --project website
+noteleaf task list --project backend
+```
+
+### Filter by Tags
+
+```sh
+noteleaf task list --tags urgent,bug
+```
+
+### View Task Details
+
+```sh
+noteleaf task view 1
+```
+
+## Updating Tasks
+
+### Mark Task as Done
+
+```sh
+noteleaf task done 1
+```
+
+### Update Task Priority
+
+```sh
+noteleaf task update 1 --priority high
+```
+
+### Update Task Project
+
+```sh
+noteleaf task update 1 --project website
+```
+
+### Add Tags to Task
+
+```sh
+noteleaf task update 1 --add-tags backend,api
+```
+
+### Remove Tags from Task
+
+```sh
+noteleaf task update 1 --remove-tags urgent
+```
+
+### Edit Task Interactively
+
+Opens task in your editor:
+
+```sh
+noteleaf task edit 1
+```
+
+## Time Tracking
+
+### Start Time Tracking
+
+```sh
+noteleaf task start 1
+```
+
+### Stop Time Tracking
+
+```sh
+noteleaf task stop 1
+```
+
+### View Timesheet
+
+All entries:
+
+```sh
+noteleaf task timesheet
+```
+
+Filtered by date:
+
+```sh
+noteleaf task timesheet --from 2024-01-01 --to 2024-01-31
+```
+
+Filtered by project:
+
+```sh
+noteleaf task timesheet --project website
+```
+
+## Project Management
+
+### List All Projects
+
+```sh
+noteleaf task projects
+```
+
+### View Tasks in Project
+
+```sh
+noteleaf task list --project website
+```
+
+## Tag Management
+
+### List All Tags
+
+```sh
+noteleaf task tags
+```
+
+### View Tasks with Tag
+
+```sh
+noteleaf task list --tags urgent
+```
+
+## Context Management
+
+### List All Contexts
+
+```sh
+noteleaf task contexts
+```
+
+### View Tasks in Context
+
+```sh
+noteleaf task list --context office
+```
+
+## Advanced Workflows
+
+### Daily Planning
+
+View today's tasks:
+
+```sh
+noteleaf task list --due today
+```
+
+View overdue tasks:
+
+```sh
+noteleaf task list --due overdue
+```
+
+### Weekly Review
+
+View completed tasks this week:
+
+```sh
+noteleaf task list --status completed --from monday
+```
+
+View pending high-priority tasks:
+
+```sh
+noteleaf task list --status pending --priority high
+```
+
+### Project Focus
+
+List all tasks for a project, sorted by priority:
+
+```sh
+noteleaf task list --project website --sort priority
+```
+
+### Bulk Operations
+
+Mark multiple tasks as done:
+
+```sh
+noteleaf task done 1 2 3 4
+```
+
+Delete multiple tasks:
+
+```sh
+noteleaf task delete 5 6 7
+```
+
+## Task Deletion
+
+### Delete a Task
+
+```sh
+noteleaf task delete 1
+```
+
+### Delete with Confirmation
+
+```sh
+noteleaf task delete 1 --confirm
+```