Doc: Organizing bills with tags

Author: sergeyklay

docs/features/003-organizing-bills-with-tags.md

@@ -0,0 +1,82 @@
+# Organizing bills with tags
+
+- **Status:** Draft
+- **Last Updated:** 2025-12-12
+- **Related:**
+
+## Overview
+
+Tags let you organize and filter your bills by category. You can create any tags you want and assign multiple tags to each bill. When you select a tag from the toolbar, the entire interface updates to show only bills matching your selection.
+
+## Adding tags to bills
+
+When you add or edit a bill, you'll find a Tags section in the form. Type a tag name to search existing tags or create new ones on the fly. You can assign as many tags as you need to a single bill.
+
+Tags you create persist across all your bills. Once you create a tag like "Business," it appears in the dropdown for every bill.
+
+## Filtering by tag
+
+Your tags appear in a dropdown menu on the top toolbar. The button shows "All Bills" when no tag is selected. Click it to see your available tags.
+
+When you select a tag, three changes happen:
+
+- The bill list filters to show only bills with your selected tag
+- Reports and totals update to reflect only those filtered bills
+- A badge appears next to the dropdown showing which tag is active
+
+To clear the filter, click the X on the active tag badge or select a different tag.
+
+## Viewing tags on a bill
+
+Tags don't appear in the standard bill list. To see a bill's tags:
+
+1. Click on any bill in the list
+2. The right sidebar opens, replacing the calendar view
+3. Scroll to the bottom of the bill detail to see all assigned tags
+
+To close the bill detail, click the same bill again or click the X button in the detail panel. The calendar view returns when you deselect the bill.
+
+## Common uses for tags
+
+**Separating personal and business expenses.** Create "Personal" and "Business" tags. Assign each bill to the appropriate category. Select "Business" to see your total business expenses when tax season arrives.
+
+**Tracking bills for different people.** If you manage bills for a spouse, parent, or roommate, create a tag for each person's name. Assign their bills accordingly. For shared bills, add both tags. Filter by a person's name to see their share.
+
+**Grouping by payment source.** Create tags like "Bank Account" and "Credit Card" to track where money comes from. This helps you understand how much flows from each account without mixing credit card charges with direct bank payments.
+
+**Organizing by category.** Tags like "Utilities," "Subscriptions," or "Insurance" help you see spending patterns within specific expense types.
+
+## Edge cases
+
+**Empty tag name.** You can't create a tag without a name. The system requires at least one character.
+
+**Duplicate tags.** Tag names are unique. If you type a name that already exists, the system selects the existing tag instead of creating a duplicate.
+
+**Deleting a bill with tags.** When you delete a bill, its tag associations disappear. The tags themselves remain available for other bills.
+
+**Filtering with no matches.** If no bills have your selected tag, you see an empty list with a message explaining no bills match.
+
+**Special characters.** Tag names support letters, numbers, spaces, and common punctuation. The system creates a URL-safe version for filtering.
+
+## Verification
+
+To confirm tags work as expected:
+
+1. Create a new bill and add a tag called "Test"
+2. The "All Bills" dropdown should now include "Test"
+3. Select "Test" from the dropdown
+4. Only your tagged bill appears in the list
+5. Click the bill to open its detail
+6. Scroll down; your "Test" tag appears at the bottom
+7. Clear the filter; all bills return
+
+## Future scope
+
+The following features aren't included in this version:
+
+- Tag colors or icons for visual distinction
+- Tag management screen (edit, rename, or delete tags)
+- Multi-tag filtering with AND/OR logic
+- Tag-based reports and analytics
+- Drag-and-drop tag assignment
+