Tag Sync

Tag Sync

Fetch tags from Raindrop, curate the top N by usage, characterize each with a one-line description, and write or sync the vocabulary file. Follows the vendor-sync pattern: registry (vocabulary file) -> fetch from external (Raindrop API) -> diff against local -> preview -> apply after approval.

The output file at ~/.claude/references/raindrop-tags.md is consumed by /session-bookmarks when selecting tags for new bookmarks.

Arguments

• /tag-sync — sync existing vocabulary (or create if no file exists)
• /tag-sync 100 — set tag count to 100, then sync/create
• /tag-sync --reset — force full recreation (re-characterize + re-cluster all)

Edge Cases

• Raindrop MCP unavailable — report error and exit. Do not write a partial file.
• find_tags returns fewer than tag_count — use all available tags. Store the actual count in frontmatter so the next sync has a realistic target.
• ai-bookmarked not in top N — always inject it regardless of rank. It is listed in mandatory_tags frontmatter.
• No bookmarks found for a tag (characterization step) — infer from tag name alone. Flag with * in preview: *auto-inferred from name.
• ~/.claude/references/ directory missing — create it before writing.
• Vocabulary fetched today, no explicit args — warn: "Vocabulary was already synced today. Pass a count or --reset to force." Do not re-fetch.
• User declines all changes — report "No changes made" and exit.

Workflow

Step 1: Parse arguments

Accept an optional integer argument or --reset flag.

• Integer sets tag_count (how many tags to include).
• --reset forces creation mode even if the file exists.
• No argument: use tag_count from existing file, or default 75.

Step 2: Load existing vocabulary

Read(file_path="~/.claude/references/raindrop-tags.md")

• File exists — enter sync mode. Extract tag_count, fetched_at, and existing tag entries (tag name, count, characterization, cluster). Also extract optional config fields from frontmatter: blocklist, context_tags, conventions. Preserve these unchanged through the sync cycle — they are user-authored config, not Raindrop-derived data. Record which of the three are absent from frontmatter — Step 8 will backfill them from the seed values defined below. Check staleness: if fetched_at matches today's date and no explicit arguments were passed, warn "Vocabulary was already synced today. Pass a count or --reset to force." and Stop. Do not proceed to Step 3.
• File missing (or --reset) — enter creation mode. Seed default config fields: blocklist: ["5", "4", "3", "2", "imported", "toread", "unread", "for:*"], context_tags: [], conventions: [].

Step 3: Fetch tags from Raindrop

mcp__raindrop__find_tags()

Returns tags with usage counts. Paginate if has_more=true. Sort by count descending. Take the top tag_count entries. Always include ai-bookmarked in the target set regardless of rank.

Step 4: Diff (sync mode only)

Compare target set against existing vocabulary:

If no new tags and no dropped tags (only count changes), report "Tag vocabulary is in sync — only usage counts updated" and offer to apply count updates in place.

Step 5: Characterize new tags

For each new tag (creation mode: all tags; sync mode: only new arrivals), sample 2-3 bookmarks to ground the description:

mcp__raindrop__find_bookmarks(has_tags=["<tag-name>"], limit=3, sort="random")

From bookmark titles and excerpts, write a concise one-line characterization (10-15 words max). If find_bookmarks returns empty, infer from the tag name (e.g., conways-law -> "Org structure effects on system architecture").

Do NOT call find_bookmarks for tags that already have characterizations in the existing file (sync mode).

Step 6: Assign clusters

Four groups:

• Retained tags keep their existing cluster (stability across syncs).
• New tags are auto-assigned from name + sample bookmark content.
• --reset forces re-assignment of all clusters.

Step 7: Preview

Show the proposed state before writing.

Creation mode — full vocabulary table grouped by cluster.

Sync mode — diff summary first, then full table:

## Tag Vocabulary Preview

**Mode:** Sync | **Count:** 75 | **Fetched:** 2026-04-06

### New tags to add (3)

| Tag | Count | Cluster | Characterization |
|-----|-------|---------|-----------------|
| `basis-ecosystem` | 12 | Architecture | Foundational stack choices and tradeoffs |

### Tags to remove (1)

| Tag | Count | Cluster | Characterization |
|-----|-------|---------|-----------------|
| `old-unused-tag` | 2 | Other | Below threshold |

### Count updates (silent, no approval needed)

- `javascript`: 398 -> 412
- `nodejs`: 280 -> 287

### Summary after changes

75 tags: 31 Ecosystem | 24 Architecture | 12 Content Type | 8 Other

Approve all, or specify adjustments (e.g. "keep old-unused-tag",
"move basis-ecosystem to Content Type", "change characterization for X").

Wait for user response before writing.

Step 8: Write

After approval, build the complete file and write atomically:

Write(file_path="~/.claude/references/raindrop-tags.md", content="...")

Full-file overwrite (not incremental edit). Create ~/.claude/references/ directory if it does not exist.

Reincorporate preserved config fields into the written file's YAML frontmatter. Do not overwrite or strip blocklist, context_tags, or conventions — these are user-authored and must survive the sync cycle.

Additively heal pre-seeding vocab files. If sync mode encountered a file that pre-dates the Step 2 seeding behavior, one or more of blocklist, context_tags, or conventions will be absent from the frontmatter extracted in Step 2. For each of these three fields, apply this rule when building the written frontmatter:

• Field present (even if empty — blocklist: [] or blocklist: with no value) — preserve as-is. Treat presence as an intentional user choice.
• Field absent (key not in the frontmatter at all) — backfill with the Step 2 creation-mode seed value (the same defaults applied when seeding a new file: blocklist: ["5", "4", "3", "2", "imported", "toread", "unread", "for:*"], context_tags: [], conventions: []).

Healing is additive only — never replace, merge, or augment an existing field's contents. The three fields are evaluated independently (a file may have context_tags set but be missing blocklist). Mention any healed fields in the Step 9 report so the user sees what was backfilled.

Step 9: Report

## Tag Vocabulary Synced

File: ~/.claude/references/raindrop-tags.md
Tags: 75 (31 Ecosystem | 24 Architecture | 12 Content Type | 8 Other)
Mandatory: ai-bookmarked (always applied)

Changes: added 3, removed 1, updated 18 counts

Next: `/session-bookmarks` will use this vocabulary when creating bookmarks.

Output File Format

The vocabulary file uses YAML frontmatter for machine-readable metadata and markdown tables for human-readable content:

---
tag_count: 75
fetched_at: 2026-04-06
mandatory_tags:
  - ai-bookmarked
blocklist:
  - "5"
  - "4"
  - "3"
  - "2"
  - imported
  - toread
  - unread
  - "for:*"
context_tags: []
conventions: []
---

# Raindrop Tag Vocabulary

Always include `ai-bookmarked`. Choose 2-5 additional tags per bookmark.

## Ecosystem

| Tag | Count | Characterization |
|-----|-------|-----------------|
| `javascript` | 412 | Core JS language, runtime, ecosystem |
| `nodejs` | 287 | Node.js server-side runtime and tooling |

## Architecture

| Tag | Count | Characterization |
|-----|-------|-----------------|
| `protocol-design` | 156 | Specs, RFCs, protocol architecture |

## Content Type

| Tag | Count | Characterization |
|-----|-------|-----------------|
| `foundational-text` | 89 | Seminal papers, essays, reference works |

## Other

| Tag | Count | Characterization |
|-----|-------|-----------------|
| `indieweb` | 67 | IndieWeb movement, ownership, POSSE |