# Quickstart: Tag Browser

## Verifying the feature end-to-end

### Prerequisites

- Docker stack running (`docker compose up`)
- At least 3 images uploaded with different tags (e.g., `cat`, `funny`, `reaction`)
- At least one image with two tags (e.g., both `cat` and `funny`)

### Scenario 1 — Tag browser shows all tags with correct counts

1. Open the app (not logged in).
2. Navigate to `/tags`.
3. **Expected**: A list of tags is shown. Each tag displays the number of images with that tag. Tags are ordered from most images to fewest.
4. Verify: Count next to `cat` matches the number of images actually tagged `cat`.
5. Verify: Tags with zero images are not shown.

### Scenario 2 — Clicking a tag navigates to the filtered library

1. On the `/tags` page, click the `cat` tag.
2. **Expected**: Navigated to the library (`/`) showing only images tagged `cat`.
3. Verify: The active filter chip shows `cat` in the library.

### Scenario 3 — Library page links to tag browser

1. Navigate to `/` (library, logged in or out).
2. **Expected**: A link or button labelled "Browse by tag" (or similar) is visible.
3. Click it.
4. **Expected**: The tag browser page loads.

### Scenario 4 — Empty state

1. If the library has no images at all, navigate to `/tags`.
2. **Expected**: An empty state message is shown rather than a blank page or error.

### API verification

```bash
# Sorted by count, zero-count tags excluded
curl http://localhost:8000/api/v1/tags?sort=count_desc&min_count=1

# Existing autocomplete behaviour unchanged
curl http://localhost:8000/api/v1/tags?q=ca&limit=10
```