provozni zaloha

skills/bookmark/SKILL.md

@@ -35,29 +35,40 @@ bookmark.py add "https://example.com/rust-async" "Async Rust patterns" --tags ru
 bookmark.py list [--tag <tag>]
 ```
 
-Shows ID, URL, tags, description, and date added for each unread bookmark. Use `--tag` to filter.
+Shows display ID, URL, tags, description, and date added for each unread bookmark. Use `--tag` to filter (display IDs stay global, so a filtered list may show gaps).
+
+### Display IDs
+
+The `#1`, `#2`, … shown by `list` and `history` are **display IDs** — sequential positions, computed on the fly, never the internal DB id. They renumber whenever the set changes, so run `list`/`history` first if unsure.
+
+- `read <n>` and `show <n>` take the display ID from **`list`** (the unread set).
+- `unread <n>` takes the display ID from **`history`** (the read set).
+
+A freshly added bookmark is always display `#1` in `list` (newest first).
 
 ### Mark as read
 
 ```bash
-bookmark.py read <id>
+bookmark.py read <display-id>
 ```
 
-Marks bookmark as read (stores `read_at` timestamp). Does **not** delete — entry stays in DB.
+`<display-id>` is the number from `list`. Marks bookmark as read (stores `read_at` timestamp). Does **not** delete — entry stays in DB.
 
 ### Unmark (mark as unread again)
 
 ```bash
-bookmark.py unread <id>
+bookmark.py unread <display-id>
 ```
 
+`<display-id>` is the number from `history`.
+
 ### Show bookmark details
 
 ```bash
-bookmark.py show <id>
+bookmark.py show <display-id>
 ```
 
-Shows full URL, description, tags, status (read/unread), and dates. Does **not** change any state.
+`<display-id>` is the number from `list`. Shows full URL, description, tags, status, and dates. Does **not** change any state.
 
 ### List read bookmarks (history)
 
@@ -65,7 +76,7 @@ Shows full URL, description, tags, status (read/unread), and dates. Does **not**
 bookmark.py history
 ```
 
-Shows all bookmarks marked as read, with both `added` and `read` dates.
+Shows all bookmarks marked as read, with both `added` and `read` dates, numbered with their own display IDs.
 
 ## Output formatting
 
@@ -75,7 +86,7 @@ When presenting bookmark lists or details to the user, **always use markdown lin
 #3 [hackaday.com](https://hackaday.com/2026/06/02/linux-fu-taming-strace/) [linux, strace] — lepší strace
 ```
 
-Format: `#<id> [<domain>](<url>) [<tags>] — <description>`
+Format: `#<display-id> [<domain>](<url>) [<tags>] — <description>`
 
 - Domain is clickable, pointing to the full URL
 - Tags in brackets, comma-separated
@@ -86,6 +97,6 @@ Format: `#<id> [<domain>](<url>) [<tags>] — <description>`
 
 1. User shares a URL → `add` with description and optional tags
 2. User wants to see what to read → `list`
-3. User wants to see details of a bookmark → `show <id>`
-4. User finishes an article → `read <id>`
-5. User wants to revisit → `unread <id>` or `history`
+3. User wants to see details of a bookmark → `show <display-id>` (from `list`)
+4. User finishes an article → `read <display-id>` (from `list`)
+5. User wants to revisit → `unread <display-id>` (from `history`) or `history`