Bookmark — URL Knowledge Capture

Fetches a URL, generates a concise summary, checks for duplicates, and stores the result as a bookmark entry.

When to Use

/bookmark <url> [#tags]
"bookmark this", "save this link", "store this URL", "remember this page"

Process

Step 1: Check MCP

See CONVENTIONS.md — skip if already confirmed this conversation.

Step 2: Parse Arguments

First argument: URL (required). If missing, ask the user.
#tag tokens: explicit tags to apply

Example: /bookmark https://example.com/article #caching #architecture

Step 3: Fetch URL Content

Use WebFetch to retrieve content at the URL.

If WebFetch fails, prompt for a manual summary:

Could not fetch URL: <url>
Error: <error message>

Please provide a manual summary of the page content:
>

Continue to Step 4 with the manual summary.

Step 4: Generate Summary

Synthesize content into a summary: 2-4 sentences on main topic and takeaways, followed by 3-5 bullet points.

Show preview before storing:

## Bookmark Summary (preview)

<summary text>

Key points:
- <point 1>
- <point 2>
- <point 3>

Ready to store? (yes / edit / skip)

If the user edits, accept their revision. If they skip, confirm "Skipped. No entry was stored."

Step 5: Check for Duplicates

Call distillery_find_similar(content="<url> <summary>", dedup_action=true). Handle by action field:

"create": No similar entries. Proceed to Step 6.

"skip": Near-exact duplicate. Show similarity table and offer: (1) Store anyway, (2) Skip.

"merge" or "link": Related entry exists. Show similarity table and offer: (1) Store anyway, (2) Skip.

Similar entries found:

| Entry ID | Similarity | URL | Preview |
|----------|-----------|-----|---------|
| <id>     | 92%       | <url> | <first 80 chars> |

1. Store anyway  2. Skip

On skip, confirm "Skipped. No new entry was stored." and stop.

Step 6: Determine Author & Project

See CONVENTIONS.md for resolution order. Cache for the session.

Step 7: Extract Tags

Combine explicit #tag arguments with 2-5 auto-extracted keywords from the summary. Tag format rules:

Lowercase, hyphen-separated within segments
source/bookmark/{domain} — derived from URL domain (drop www., dots to hyphens)
domain/{topic} — subject-area tags
project/{repo-name}/references — if project is known
Repo/domain name normalization: lowercase, drop www., replace non-[a-z0-9-] with hyphens, collapse consecutive hyphens, trim leading/trailing hyphens. Must match [a-z0-9][a-z0-9\-]*.
Strip leading # from user-provided tags

Step 8: Store Entry

distillery_store(
  content="<summary>\n\nKey points:\n- ...",
  entry_type="bookmark",
  author="<author>",
  project="<project>",
  tags=[...],
  metadata={"url": "<the-url>", "summary": "<2-4 sentence summary>"}
)

Step 9: Confirm

[bookmark] Stored: <entry-id>
Project: <project> | Author: <author>
Summary: <first 200 chars>...
Tags: tag1, tag2, tag3

Output Format

Stored:

[bookmark] Stored: <entry-id>
Project: <project> | Author: <author>
Summary: <first 200 chars>...
Tags: tag1, tag2, tag3

Skipped:

Skipped. No new entry was stored.

Rules

Store only the summary, never raw HTML
Always use WebFetch (not curl) to retrieve URL content
Always show the summary preview before storing
Always check for duplicates before storing (threshold 0.8)
If URL is inaccessible, fall back to asking for a manual summary
Always store the original URL in metadata.url, even if content was manually provided
On MCP errors, see CONVENTIONS.md error handling — display and stop
No retry loops — if store fails after one attempt, report and stop