STOP if you catch yourself thinking:
- “Let me quickly search Readwise...”
- “I’ll just check the highlights...”
- “The MCP tool is right here in my tool list...”

These thoughts in MAIN CHAT = VIOLATION. Delegate instead.

User: “Search my Readwise for proxy advisor articles”

MAIN CHAT RESPONSE:
Task(subagent_type=”workflows:librarian”, prompt=”Search Readwise for proxy advisor articles and summarize findings”)

NEVER IN MAIN CHAT:
mcp__readwise__search_readwise_highlights(...)

User mentions tagged items or NLM content
              │
              ▼
    ┌─────────────────────┐
    │ 1. CHECK NLM FIRST  │ ← MANDATORY
    │    nlm list         │
    │    nlm chat <id>    │
    └─────────────────────┘
              │
       Not in NLM?
              ▼
    ┌─────────────────────┐
    │ 2. USE READER API   │ ← For tagged items
    │    --tag "X"        │
    │    NOT MCP search!  │
    └─────────────────────┘

STOP if user mentions tagged items AND you're about to:
- Call mcp__readwise__search_readwise_highlights
- Do "semantic search" for tagged content
- Skip checking NLM first

These are WORKFLOW VIOLATIONS. The content is already curated by tag.

User: "I thought we added the Egan-Jones letters to NLM? They were tagged proxy advisors."

CORRECT:
1. Task(librarian) → Check NLM for proxy advisors notebook
2. If not found: Use Reader API with --tag "proxy advisors"
3. NEVER: mcp__readwise__search_readwise_highlights("Egan-Jones...")

WRONG:
- Immediately calling MCP search
- Skipping NLM check
- Using semantic search for tagged content

┌─────────────────────────────────────────────────────────────┐
│ 1. CHECK NLM FIRST (always)                                  │
│    Is the content already in a NotebookLM notebook?          │
│    → nlm list && nlm chat <id> "query"                       │
└─────────────────────────────────────────────────────────────┘
                          │
                    Not in NLM?
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Do you know the exact tag(s)?                             │
│                                                              │
│ YES → Reader API (tag-based fetch)                           │
│       Fast, gets full documents, no semantic search needed   │
│       → python3 skills/readwise/scripts/readwise_to_nlm.py \ │
│           --tag "tag" --notebook <id>                        │
│                                                              │
│ NO → MCP (semantic search) - LAST RESORT                     │
│      Find highlights by meaning/keywords                     │
│      → mcp__readwise__search_readwise_highlights             │
└─────────────────────────────────────────────────────────────┘

mcp__readwise__search_readwise_highlights

{
  “vector_search_term”: “proxy advisors ISS Glass Lewis shareholder voting”,
  “full_text_queries”: [
    {“field_name”: “highlight_plaintext”, “search_term”: “proxy”}
  ]
}

{
  “id”: 123456789,
  “score”: 0.025,
  “attributes”: {
    “document_author”: “Author Name”,
    “document_category”: “books|articles”,
    “document_tags”: [“tag1”, “tag2”],
    “document_title”: “Document Title”,
    “highlight_note”: “User’s annotation”,
    “highlight_plaintext”: “The highlighted text...”,
    “highlight_tags”: [“htag1”]
  }
}

# Readwise Highlights: [Topic]

Generated: [date]
Search: vector=”[query]” + full_text=”[filter]”

---

## From “[Document Title]” by [Author]
**Tags:** tag1, tag2

> “[Highlight text...]”

**Note:** [User’s annotation if present]

---

[Repeat for each source document]

cat <<'EOF' | /Users/vwh7mb/projects/nlm/nlm add <notebook-id> -
[formatted markdown]
EOF

/Users/vwh7mb/projects/nlm/nlm rename-source <source-id> “Readwise: [Topic] Highlights”

from reader import ReaderClient

# Token from agenix
import os
token = open(“/var/folders/01/wzs3mqmn3jx2b81f0dcq9w8h0000gq/T/agenix/readwise-token”).read().strip()
client = ReaderClient(token)

# All documents
docs = client.list_documents()

# Filter by location: new, later, shortlist, archive, feed
docs = client.list_documents(location=”archive”)

# Filter by category: article, email, rss, highlight, note, pdf, epub, tweet, video
docs = client.list_documents(category=”article”)

# Get document with full HTML content
doc = client.get_document(document_id, with_html_content=True)

# Access the content
html = doc.get(“html_content”)  # Full HTML
title = doc.get(“title”)
author = doc.get(“author”)
source_url = doc.get(“source_url”)

doc = client.find_by_url(“https://example.com/article”)

result = client.add_article(
    url=”https://example.com/article”,
    html=”<html>...</html>”,  # Optional: for paywall bypass
    title=”Article Title”,
    author=”Author Name”,
    tags=[“research”, “topic”]
)

# Dry run - see what would be added
python3 skills/readwise/scripts/readwise_to_nlm.py \
  --tag “proxy advisors” \
  --notebook 1457a61e-02ff-4ef0-a0de-deeb0e931972 \
  --dry-run

# Add all documents with tag to notebook
python3 skills/readwise/scripts/readwise_to_nlm.py \
  --tag “proxy advisors” \
  --notebook 1457a61e-02ff-4ef0-a0de-deeb0e931972

# Verbose output
python3 skills/readwise/scripts/readwise_to_nlm.py \
  --tag “Corps” \
  --notebook abc123 \
  --verbose

pip install requests html2text

# Simple task (list, single add)
opencode run -m github-copilot/gpt-5-mini \
  “Add documents tagged ‘Corps’ to notebook abc123”

# Long context (many docs, research)
opencode run -m google/antigravity-gemini-3-flash \
  “Search readwise for highlights on activism and add to notebook xyz”