# Tags

Unifyl integrates deeply with macOS native tags, providing a rich tagging workflow for organizing, searching, and filtering files. Tags in Unifyl go beyond simple labels — they connect to Advanced Search, Smart Folders, and the file list display for a cohesive organizational system.

---

## Table of Contents

- [Overview](#overview)
- [macOS Native Tags](#macos-native-tags)
- [Viewing Tags in the File List](#viewing-tags-in-the-file-list)
  - [Color Dot Display](#color-dot-display)
  - [Tag Column](#tag-column)
  - [Tag Badges](#tag-badges)
- [Assigning Tags](#assigning-tags)
  - [Right-Click Context Menu](#right-click-context-menu)
  - [Keyboard Shortcut](#keyboard-shortcut)
  - [Tag Editor Panel](#tag-editor-panel)
  - [Drag and Drop](#drag-and-drop)
  - [Batch Tagging](#batch-tagging)
  - [Get Info Window](#get-info-window)
- [Removing Tags](#removing-tags)
- [Tag Colors](#tag-colors)
  - [Standard macOS Colors](#standard-macos-colors)
  - [Custom Tag Colors](#custom-tag-colors)
  - [Color Display Modes](#color-display-modes)
- [Searching by Tag](#searching-by-tag)
  - [Quick Filter by Tag](#quick-filter-by-tag)
  - [Advanced Search Tag Criterion](#advanced-search-tag-criterion)
  - [Combining Tag Search with Other Criteria](#combining-tag-search-with-other-criteria)
- [Tag Filtering](#tag-filtering)
  - [Filter Bar Tag Chips](#filter-bar-tag-chips)
  - [Sidebar Tag List](#sidebar-tag-list)
  - [Multiple Tag Filtering](#multiple-tag-filtering)
- [Smart Folder Integration](#smart-folder-integration)
  - [Creating a Tag-Based Smart Folder](#creating-a-tag-based-smart-folder)
  - [Dynamic Tag Smart Folders](#dynamic-tag-smart-folders)
  - [Smart Folder with Tags + Other Criteria](#smart-folder-with-tags--other-criteria)
- [AI Smart Tagging](#ai-smart-tagging)
  - [How AI Tagging Works](#how-ai-tagging-works)
  - [Reviewing AI Tag Suggestions](#reviewing-ai-tag-suggestions)
  - [Configuring AI Tagging](#configuring-ai-tagging)
- [Tag Management](#tag-management)
  - [Creating New Tags](#creating-new-tags)
  - [Renaming Tags](#renaming-tags)
  - [Deleting Tags](#deleting-tags)
  - [Tag Statistics](#tag-statistics)
- [Tag Sync and Compatibility](#tag-sync-and-compatibility)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Tips and Best Practices](#tips-and-best-practices)

---

## Overview

Tags in macOS are extended attributes (xattrs) stored directly in the filesystem. This means:

- Tags persist when files are moved within the same volume
- Tags are visible in Finder and any macOS application that supports them
- Tags survive across Unifyl sessions — they are not stored in a separate database
- Tags sync via iCloud Drive (if the file is in an iCloud-synced directory)

Unifyl reads and writes the standard `com.apple.metadata:_kMDItemUserTags` extended attribute, ensuring full compatibility with Finder and Spotlight.

---

## macOS Native Tags

macOS provides 7 standard tag colors plus the ability to create unlimited custom named tags:

| Color | Name | System Tag |
|-------|------|------------|
| None | (Custom name only) | Text-only tag |
| Red | Red | `Red` |
| Orange | Orange | `Orange` |
| Yellow | Yellow | `Yellow` |
| Green | Green | `Green` |
| Blue | Blue | `Blue` |
| Purple | Purple | `Purple` |
| Gray | Gray | `Gray` |

**Custom tags** can have any name and optionally be assigned one of the 7 colors. A tag without a color assignment appears as a text label without a colored dot.

**Tag storage format:**

Tags are stored as a plist array in the file's extended attributes:

```
com.apple.metadata:_kMDItemUserTags = (
    "Red\n6",
    "Important",
    "Project Alpha\n4"
)
```

Each entry is the tag name, optionally followed by `\n` and a color index (0=None, 1=Gray, 2=Green, 3=Purple, 4=Blue, 5=Yellow, 6=Red, 7=Orange).

---

## Viewing Tags in the File List

Tags are displayed in the file list in three ways:

### Color Dot Display

The default and most compact display mode. A small colored dot (or multiple dots) appears next to the filename for each color tag assigned to the file.

**Example:**

```
📁 Documents                    
📄 report.pdf          🔴 🔵    ← Red + Blue tags
📄 notes.txt           🟢       ← Green tag
📄 budget.xlsx         🟡 🟠    ← Yellow + Orange tags
📄 readme.md                    ← No tags
```

Multiple dots are shown left to right in the order the tags were assigned. If a file has more than 4 color tags, the remaining count is shown as "+N".

**Dot placement:** The color dots appear between the file icon and the filename by default. This matches Finder's behavior.

### Tag Column

Enable a dedicated "Tags" column in the file list to see all tag names (not just colors):

1. Right-click the column header bar
2. Check **Tags** to add the column
3. The column shows comma-separated tag names

**Example with Tags column:**

```
Name              │ Size    │ Tags
──────────────────┼─────────┼──────────────────────
report.pdf        │ 2.4 MB  │ Red, Project Alpha
notes.txt         │ 12 KB   │ Green, Meeting Notes
budget.xlsx       │ 45 KB   │ Yellow, Orange, Q3
readme.md         │ 3 KB    │ (none)
```

The Tags column is sortable — click the header to sort files by their first tag alphabetically.

### Tag Badges

In icon/thumbnail view modes (grid layout), tags appear as colored bars below the filename, similar to Finder's grid view.

---

## Assigning Tags

### Right-Click Context Menu

1. Select one or more files
2. Right-click to open the context menu
3. Hover over **Tags** to see the tag submenu
4. Click a tag to toggle it (assign or remove)

The tag submenu shows:

```
Tags  ►  ● Red
         ● Orange
         ● Yellow
         ● Green
         ● Blue
         ● Purple
         ● Gray
         ─────────────
         ✓ Important        ← currently assigned
           Project Alpha
           Meeting Notes
         ─────────────
         New Tag...
```

A checkmark indicates tags already assigned to the selected file(s). For multiple selection, a dash indicates the tag is assigned to some but not all selected files.

### Keyboard Shortcut

Unifyl provides quick keyboard shortcuts for the 7 color tags:

| Shortcut | Tag |
|----------|-----|
| **Ctrl+1** | Red |
| **Ctrl+2** | Orange |
| **Ctrl+3** | Yellow |
| **Ctrl+4** | Green |
| **Ctrl+5** | Blue |
| **Ctrl+6** | Purple |
| **Ctrl+7** | Gray |
| **Ctrl+0** | Remove all tags |

These shortcuts toggle the tag — press once to add, press again to remove.

**Custom tag shortcuts:** You can assign keyboard shortcuts to custom (named) tags via **Settings > Keyboard Shortcuts**. Search for "Tag:" to find all tag-related commands.

### Tag Editor Panel

For more detailed tag management on a specific file:

1. Select a file
2. Press **Cmd+Shift+T** or choose **Edit > Tags...**
3. The Tag Editor panel appears:

```
┌─ Tags: report.pdf ───────────────────────────┐
│                                                │
│  Current tags:                                 │
│  [🔴 Red  ✕] [🔵 Project Alpha  ✕]           │
│                                                │
│  Add tag: [_________________________]  [Add]   │
│                                                │
│  Suggestions:                                  │
│  Important   Q3 Report   Finance   2024        │
│                                                │
│  Recent tags:                                  │
│  Meeting Notes   Code Review   Urgent          │
│                                                │
└────────────────────────────────────────────────┘
```

**Features:**
- View all currently assigned tags as removable chips
- Type to add a new tag (auto-complete from existing tags)
- Click the X on any chip to remove that tag
- AI suggestions (when enabled) based on file content
- Recent tags list for quick re-use

### Drag and Drop

Drag a tag from the sidebar tag list and drop it onto a file or selection to assign that tag.

### Batch Tagging

To tag multiple files at once:

1. Select all target files (Cmd+click, Shift+click, or Cmd+A)
2. Use any tagging method (keyboard shortcut, right-click, or Tag Editor)
3. The tag is applied to all selected files simultaneously

**Batch tagging in Multi-Rename:** The Multi-Rename tool does not modify tags directly, but you can use macros to batch-tag files as part of an automated workflow.

### Get Info Window

The Get Info window (Cmd+I) includes a Tags section where you can view and modify tags for the selected file.

---

## Removing Tags

| Method | Action |
|--------|--------|
| **Keyboard** | Ctrl+0 removes all tags from selected files |
| **Right-click** | Tags submenu > click a checkmarked tag to remove it |
| **Tag Editor** | Click the X button on the tag chip |
| **Get Info** | Remove tags in the Tags section |
| **Bulk remove** | Select files > right-click > Tags > Remove All Tags |

---

## Tag Colors

### Standard macOS Colors

The 7 standard tag colors are defined by macOS and are consistent across all applications:

| Color | Hex (Dark) | Hex (Light) | Color Index |
|-------|-----------|-------------|-------------|
| Red | `#FF3B30` | `#FF3B30` | 6 |
| Orange | `#FF9500` | `#FF9500` | 7 |
| Yellow | `#FFCC00` | `#FFCC00` | 5 |
| Green | `#34C759` | `#28A745` | 2 |
| Blue | `#007AFF` | `#007AFF` | 4 |
| Purple | `#AF52DE` | `#AF52DE` | 3 |
| Gray | `#8E8E93` | `#8E8E93` | 1 |

### Custom Tag Colors

Custom-named tags can be assigned one of the 7 standard colors, or left uncolored:

- **Colored custom tag:** Displays both the color dot and the tag name
- **Uncolored custom tag:** Displays only the tag name text (no dot)

To assign a color to a custom tag:

1. Open **Settings > Tags** (or right-click tag submenu > Manage Tags)
2. Select the custom tag
3. Choose a color from the color picker
4. The color is updated everywhere the tag appears

### Color Display Modes

Unifyl offers three display modes for tag colors in the file list:

| Mode | Appearance | Setting Location |
|------|-----------|-----------------|
| **Dot** (default) | Small colored circle before filename | Settings > General > Tag Display |
| **Background** | Subtle colored tint on the entire row | Settings > General > Tag Display |
| **Dot + Name** | Colored dot followed by tag text | Settings > General > Tag Display |

In **Background** mode, if a file has multiple colored tags, the leftmost (primary) tag's color is used as the row tint.

---

## Searching by Tag

### Quick Filter by Tag

The fastest way to filter the current directory by tag:

1. Press **Cmd+F** to activate the filter bar
2. Type `tag:` followed by the tag name
3. Only files with the matching tag are shown

**Examples:**

| Filter | Result |
|--------|--------|
| `tag:Red` | Show only files tagged Red |
| `tag:Important` | Show only files tagged "Important" |
| `tag:Red,Blue` | Show files tagged Red OR Blue |

### Advanced Search Tag Criterion

The Advanced Search panel (**Cmd+Shift+F**) includes a dedicated Tag criterion for building complex tag-based searches.

**Adding a tag criterion:**

1. Open Advanced Search
2. Click **Add Criterion**
3. Select **Tag** from the attribute dropdown
4. Configure the condition:

| Condition | Description | Example |
|-----------|-------------|---------|
| **is** | File has this exact tag | Tag is "Red" |
| **is not** | File does not have this tag | Tag is not "Red" |
| **contains** | Tag name contains text | Tag contains "project" |
| **starts with** | Tag name starts with text | Tag starts with "Q3" |
| **is any of** | File has any of the listed tags | Tag is any of: Red, Blue, Green |
| **is all of** | File has all of the listed tags | Tag is all of: Important, Urgent |
| **is empty** | File has no tags | Tag is empty |
| **is not empty** | File has at least one tag | Tag is not empty |

### Combining Tag Search with Other Criteria

Tag criteria can be combined with other Advanced Search criteria using AND/OR logic:

**Example: Find large important files**
```
Tag is "Important"
AND Size > 100 MB
AND Date Modified > "Last 30 days"
```

**Example: Find untagged images**
```
Tag is empty
AND Extension is any of: jpg, png, heic, gif
```

**Example: Find project files by tag + content**
```
Tag contains "Project"
AND Name contains ".swift"
OR Tag contains "Project"
AND Name contains ".md"
```

---

## Tag Filtering

### Filter Bar Tag Chips

When a tag filter is active, it appears as a colored chip in the filter bar:

```
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 Filter: [🔴 Red ✕] [🔵 Important ✕]  │  Showing 12 of 347  │
└──────────────────────────────────────────────────────────────────┘
```

Click the X on any chip to remove that tag filter. Click the chip itself to toggle between include (show only tagged) and exclude (hide tagged) modes.

### Sidebar Tag List

The sidebar (when visible) includes a Tags section listing all tags used in the current directory tree:

```
TAGS
─────────────
🔴 Red           (14)
🟠 Orange         (3)
🟡 Yellow         (7)
🟢 Green         (23)
🔵 Blue           (5)
🟣 Purple         (2)
⚪ Gray           (1)
─────────────
Important        (12)
Project Alpha     (8)
Meeting Notes     (4)
```

Click any tag in the sidebar to instantly filter the file list to show only files with that tag. The count in parentheses shows how many files in the current directory tree have that tag.

**Multi-select:** Cmd+click multiple tags in the sidebar to filter by multiple tags (OR logic).

### Multiple Tag Filtering

When filtering by multiple tags, you can choose the logic:

| Mode | Behavior | Example |
|------|----------|---------|
| **Any (OR)** | Show files with ANY of the selected tags | Red OR Blue = show if Red or Blue |
| **All (AND)** | Show files with ALL of the selected tags | Red AND Blue = show only if both |
| **None (NOT)** | Show files with NONE of the selected tags | NOT Red = hide all Red-tagged files |

Toggle between modes using the dropdown next to the tag filter chips.

---

## Smart Folder Integration

Smart Folders in Unifyl are virtual file collections that can be populated from Advanced Search results. Tags are a primary criterion for building Smart Folders.

### Creating a Tag-Based Smart Folder

1. Open Advanced Search (Cmd+Shift+F)
2. Add a Tag criterion (e.g., Tag is "Important")
3. Optionally add additional criteria
4. Click the **Save as Smart Folder** button
5. Name the Smart Folder (e.g., "Important Files")
6. The Smart Folder appears in the sidebar under Smart Folders

The Smart Folder dynamically updates — any file you tag as "Important" in the future will automatically appear in this Smart Folder.

### Dynamic Tag Smart Folders

Unifyl can automatically create Smart Folders for your most-used tags:

1. Open **Settings > Smart Folders**
2. Enable **Auto-create tag Smart Folders**
3. Select which tags should have automatic Smart Folders
4. Smart Folders named "Tag: Red", "Tag: Important", etc. appear in the sidebar

### Smart Folder with Tags + Other Criteria

Combine tags with other criteria for powerful Smart Folders:

**Example Smart Folders:**

| Smart Folder Name | Criteria |
|-------------------|----------|
| "Urgent Large Files" | Tag is "Urgent" AND Size > 50 MB |
| "Recent Project Files" | Tag contains "Project" AND Modified in last 7 days |
| "Untagged Downloads" | Tag is empty AND Path starts with ~/Downloads |
| "Code to Review" | Tag is "Review" AND Extension is any of: swift, py, js |

Smart Folder contents are displayed in the same FileTableView as regular directories, with full support for sorting, filtering, selection, and file operations (copy, move, delete, rename, tag).

---

## AI Smart Tagging

When AI features are enabled (Settings > AI > Smart Tagging), Unifyl can suggest tags for files based on their content.

### How AI Tagging Works

1. When you open a directory, AI analyzes file contents in the background
2. For **images:** Vision model identifies subjects, scenes, and objects
3. For **documents:** NLP model extracts key topics and themes
4. For **code:** Analysis of imports, class names, and project structure
5. Suggested tags appear as dimmed/dotted chips below the filename or in the Tag Editor

All processing runs locally on your Mac using CoreML — no data is sent to any server.

### Reviewing AI Tag Suggestions

AI suggestions are never applied automatically. They appear as recommendations that you can accept or dismiss:

**In the file list:**
- AI-suggested tags appear as faded/dotted indicators (distinct from applied tags)
- Click a suggestion to accept it (applies the tag)
- Right-click > Dismiss to hide the suggestion

**In the Tag Editor:**
- AI suggestions appear in the "Suggestions" section
- Click a suggestion to apply it
- Hover for a confidence score (e.g., "85% confidence")

### Configuring AI Tagging

Settings > AI > Smart Tagging:

| Setting | Description | Default |
|---------|-------------|---------|
| **Enable Smart Tagging** | Turn AI tag suggestions on/off | On |
| **Suggestion threshold** | Minimum confidence to show a suggestion (0-100%) | 70% |
| **Max suggestions per file** | Maximum number of tag suggestions | 5 |
| **Tag vocabulary** | Use only existing tags / Allow new tag names | Existing tags only |
| **Auto-analyze** | Analyze files when entering a directory | On |
| **File types** | Which file types to analyze | Images, Documents, Code |

---

## Tag Management

### Creating New Tags

Create a new tag in several ways:

1. **Tag Editor:** Type a new name in the "Add tag" field and press Return
2. **Right-click submenu:** Tags > New Tag...
3. **Settings:** Settings > Tags > Create New Tag
4. **Finder (compatible):** Tags created in Finder are recognized by Unifyl

### Renaming Tags

1. Open **Settings > Tags** (or right-click a tag > Manage Tags)
2. Double-click the tag name
3. Type the new name
4. Press Return

**Important:** Renaming a tag updates it on all files that use it. This operation scans all indexed files and may take a moment for tags used on many files.

### Deleting Tags

1. Open **Settings > Tags**
2. Select the tag to delete
3. Click **Delete** or press the Delete key
4. Confirm: "Remove tag 'TagName' from all 23 files?"

Deleting a tag removes it from all files. The files themselves are not affected — only the tag is removed.

### Tag Statistics

The Tag Management panel in Settings shows statistics:

| Stat | Description |
|------|-------------|
| **Total tags** | Number of unique tags in use |
| **Total tagged files** | Number of files with at least one tag |
| **Most used tag** | Tag assigned to the most files |
| **Uncolored tags** | Tags without a color assignment |
| **Orphaned tags** | Tags not assigned to any file (can be cleaned up) |

---

## Tag Sync and Compatibility

### iCloud Drive

Tags on files stored in iCloud Drive sync automatically across all your Macs and iOS devices. Tags assigned in Unifyl appear in Finder on other Macs and in the Files app on iPhone/iPad.

### Finder Compatibility

Tags assigned in Unifyl are fully compatible with Finder:
- Finder sees all tags assigned by Unifyl
- Unifyl sees all tags assigned by Finder
- Tag colors are consistent between both applications
- Spotlight indexes tags from both sources

### Volume Compatibility

| Volume Type | Tag Support |
|-------------|-------------|
| **APFS** | Full support |
| **HFS+** | Full support |
| **FAT32 / ExFAT** | No support (extended attributes not available) |
| **NTFS (read-only)** | No support |
| **Network (SMB/AFP)** | Depends on server configuration |
| **External SSD/HDD (APFS/HFS+)** | Full support |

**Important:** When copying tagged files to a volume that does not support extended attributes (e.g., FAT32 USB drive), tags are silently lost. Unifyl warns you about this in the copy confirmation dialog.

---

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| **Ctrl+1** | Toggle Red tag |
| **Ctrl+2** | Toggle Orange tag |
| **Ctrl+3** | Toggle Yellow tag |
| **Ctrl+4** | Toggle Green tag |
| **Ctrl+5** | Toggle Blue tag |
| **Ctrl+6** | Toggle Purple tag |
| **Ctrl+7** | Toggle Gray tag |
| **Ctrl+0** | Remove all tags |
| **Cmd+Shift+T** | Open Tag Editor for selected file |

Additional tag shortcuts can be configured in **Settings > Keyboard Shortcuts**.

---

## Tips and Best Practices

### Use tags for cross-folder organization
Tags let you create virtual groupings that span multiple directories. Tag related files in different locations, then use Smart Folders or tag filters to view them together.

### Establish a tagging convention
Create a consistent tagging system for your workflow. For example:
- **Color tags** for priority/status (Red=Urgent, Yellow=In Progress, Green=Complete)
- **Named tags** for projects ("Project Alpha", "Client Beta")
- **Type tags** for categories ("Invoice", "Receipt", "Contract")

### Combine with Smart Folders
Tags become most powerful when combined with Smart Folders. Create Smart Folders for your most common tag-based views so they are always one click away in the sidebar.

### Clean up unused tags periodically
Over time, tags can accumulate. Use Settings > Tags to view tag statistics and delete orphaned tags that are no longer assigned to any files.

### AI suggestions save time
Enable AI Smart Tagging for large photo libraries or document collections. The AI suggestions can dramatically speed up initial organization of untagged files.

---

*See also: [Settings > File Colors](Settings.md#file-colors) for tag-related color display, [Command Palette](Command-Palette.md) for tag commands, [Multi-Rename](Multi-Rename.md) for renaming tagged files, [Compare and Sync](Compare-and-Sync.md) for syncing tagged files.*