From d24f1d6c34c93c04d828d47bee55adbce326f073 Mon Sep 17 00:00:00 2001
From: Elmar Kresse <elmar.kresse@stud.htwk-leipzig.de>
Date: Tue, 20 Jan 2026 00:59:20 +0100
Subject: [PATCH] docs: Add detailed explanation of how the extension works,
 including URL fragment identification, navigation interception, and the
 `webNavigation` permission.

---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 49 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 0eab0c8..156d91a 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,41 @@ A Firefox extension that associates bookmarks with containers. When you click a
 
 - **Right-click context menu**: Assign containers to any bookmark
 - **Automatic container opening**: Bookmarks open directly in their assigned container
+- **Multiple bookmarks, same URL**: Supports different containers for bookmarks pointing to the same site (e.g., personal vs work YouTube)
 - **Popup overview**: View and manage all container-assigned bookmarks
 - **Auto-cleanup**: Mappings are removed when bookmarks or containers are deleted
 
+## How It Works
+
+### URL Fragment Identification
+
+When you assign a container to a bookmark, the extension adds a unique identifier fragment to the bookmark URL:
+
+```
+https://www.youtube.com → https://www.youtube.com#cb-abc123
+```
+
+The `#cb-<bookmarkId>` fragment allows the extension to:
+1. **Identify which bookmark was clicked** - Even if multiple bookmarks point to the same URL
+2. **Look up the correct container** - Each bookmark can have its own container assignment
+3. **Open the clean URL** - The fragment is stripped when opening the page
+
+### Navigation Interception
+
+When you click a bookmark:
+1. The extension detects the `#cb-` fragment in the URL
+2. Extracts the bookmark ID from the fragment
+3. Looks up the container assignment for that bookmark
+4. Opens the **clean URL** (without fragment) in the assigned container
+
+> **Note**: Typing a URL directly in the address bar is not intercepted - only bookmark clicks with the container fragment are redirected.
+
+### Example: Multiple YouTube Accounts
+
+You can have two YouTube bookmarks open in different containers:
+- **Personal YouTube** (`youtube.com#cb-personal123`) → Opens in "Personal" container
+- **Work YouTube** (`youtube.com#cb-work456`) → Opens in "Work" container
+
 ## Installation
 
 ### Temporary Installation (for development)
@@ -16,7 +48,6 @@ A Firefox extension that associates bookmarks with containers. When you click a
 1. Open Firefox and navigate to `about:debugging#/runtime/this-firefox`
 2. Click **"Load Temporary Add-on..."**
 3. Navigate to this folder and select `manifest.json`
-4. The extension icon will appear in your toolbar
 
 ### Permanent Installation
 
@@ -29,12 +60,19 @@ Package the extension as a `.xpi` file and submit to [addons.mozilla.org](https:
 1. Right-click on any bookmark (in bookmark toolbar, menu, or sidebar)
 2. Click **"Set Container"**
 3. Select the container you want
+4. The bookmark URL will be updated with a unique identifier
+
+### Removing a Container Assignment
+
+1. Right-click on the bookmark
+2. Click **"Set Container"** → **"Remove Container Assignment"**
+3. The bookmark URL will be restored to its original form
 
 ### Opening a Bookmark in a Specific Container (One-time)
 
 1. Right-click on any bookmark
 2. Click **"Open in Container"**
-3. Select the container
+3. Select the container (opens without changing the bookmark's assignment)
 
 ### Viewing Assigned Bookmarks
 
@@ -44,12 +82,15 @@ Package the extension as a `.xpi` file and submit to [addons.mozilla.org](https:
 
 ## Permissions
 
-- `bookmarks`: Read and manage bookmarks
-- `contextualIdentities`: Access container information
-- `cookies`: Required for container support
-- `storage`: Persist bookmark-container mappings
-- `tabs`: Open tabs in specific containers
-- `menus`: Add context menu items
+| Permission | Purpose |
+|------------|---------|
+| `bookmarks` | Read and modify bookmark URLs |
+| `contextualIdentities` | Access container information |
+| `cookies` | Required for container support |
+| `storage` | Persist bookmark-container mappings |
+| `tabs` | Open tabs in specific containers |
+| `menus` | Add context menu items |
+| `webNavigation` | Detect bookmark navigation and redirect |
 
 ## Development