feat(feeds): add feed reader extension and API documentation

Extensions:
- extensions/feeds/ - Simple RSS/Atom feed reader demonstrating the feeds API
- Subscribe to feeds, poll for entries, view in UI
- Option+F shortcut to open reader
- Commands: feeds, feeds:subscribe, feeds:refresh

Documentation:
- docs/feeds-api.md - Comprehensive API reference with examples for:
- Stock price tracking (numeric series)
- Mood tracking (text series)
- Habit streaks with calculations
- Ticket availability triggers
- RSS feed reading
- System action logging
- Spotify listening history

docs/feeds-api.md

···
+# Feeds & Series API
+
+This document covers the APIs for time-series data and external feeds in Peek.
+
+## Overview
+
+Peek uses two item types for temporal data:
+
+- **`series`** - Scalar values over time (numeric or text)
+- **`feed`** - Entries from external sources (RSS, APIs, logs)
+
+Both store their data in the `item_events` table. The item defines *what* you're tracking; events record *when* things happened.
+
+## Core Concepts
+
+### Items = Definitions
+
+Items with `type: 'series'` or `type: 'feed'` define what you're tracking:
+
+```javascript
+// A series tracks scalar values
+const series = await api.datastore.addItem('series', {
+  content: 'AAPL Stock Price',
+  metadata: JSON.stringify({ unit: 'USD', source: 'yahoo-finance' })
+});
+
+// A feed tracks entries from a source
+const feed = await api.datastore.addItem('feed', {
+  content: 'https://example.com/rss',
+  metadata: JSON.stringify({ name: 'Example Blog', format: 'rss' })
+});
+```
+
+### Events = Facts
+
+Events are append-only records of what happened:
+
+```javascript
+// Record a series observation
+await api.datastore.addItemEvent(series.data.id, {
+  value: 156.32,        // numeric value
+  occurredAt: Date.now()
+});
+
+// Record a feed entry
+await api.datastore.addItemEvent(feed.data.id, {
+  content: 'https://example.com/article-123',  // entry URL
+  occurredAt: pubDate,
+  metadata: JSON.stringify({ title: 'Article Title', author: 'Jane' })
+});
+```
+
+## API Reference
+
+### Item Operations
+
+Standard item CRUD works for series and feeds:
+
+```javascript
+// Create
+const result = await api.datastore.addItem('series', { content: 'Mood', metadata: '{}' });
+
+// Read
+const item = await api.datastore.getItem(itemId);
+
+// Update
+await api.datastore.updateItem(itemId, { metadata: '{"unit":"points"}' });
+
+// Delete (also delete events first)
+await api.datastore.deleteItemEvents(itemId);
+await api.datastore.deleteItem(itemId);
+
+// Query all series
+const series = await api.datastore.queryItems({ type: 'series' });
+
+// Query all feeds
+const feeds = await api.datastore.queryItems({ type: 'feed' });
+```
+
+### Event Operations
+
+#### `addItemEvent(itemId, options)`
+
+Add an event to a series or feed.
+
+```javascript
+await api.datastore.addItemEvent(itemId, {
+  content: 'text value or URL',      // optional
+  value: 42,                          // optional, for numeric data
+  occurredAt: Date.now(),             // optional, defaults to now
+  metadata: JSON.stringify({...})     // optional, JSON string
+});
+```
+
+#### `getItemEvent(eventId)`
+
+Get a single event by ID.
+
+```javascript
+const event = await api.datastore.getItemEvent(eventId);
+// { id, itemId, content, value, occurredAt, metadata, createdAt }
+```
+
+#### `queryItemEvents(filter)`
+
+Query events with filters.
+
+```javascript
+const events = await api.datastore.queryItemEvents({
+  itemId: 'item_123',           // single item
+  // OR
+  itemIds: ['item_1', 'item_2'], // multiple items
+  since: Date.now() - 86400000,  // after timestamp
+  until: Date.now(),             // before timestamp
+  limit: 50,                     // max results
+  offset: 0,                     // skip first N
+  order: 'desc'                  // 'asc' or 'desc' by occurredAt
+});
+```
+
+#### `deleteItemEvent(eventId)`
+
+Delete a single event.
+
+```javascript
+await api.datastore.deleteItemEvent(eventId);
+```
+
+#### `deleteItemEvents(itemId)`
+
+Delete all events for an item.
+
+```javascript
+const count = await api.datastore.deleteItemEvents(itemId);
+```
+
+#### `getLatestItemEvent(itemId)`
+
+Get the most recent event.
+
+```javascript
+const latest = await api.datastore.getLatestItemEvent(itemId);
+```
+
+#### `countItemEvents(itemId, filter)`
+
+Count events for an item.
+
+```javascript
+const count = await api.datastore.countItemEvents(itemId, {
+  since: Date.now() - 86400000  // last 24 hours
+});
+```
+
+## Use-Case Examples
+
+### 1. Stock Price Tracking
+
+Track numeric values over time from a web source.
+
+```javascript
+// Create the series
+const stock = await api.datastore.addItem('series', {
+  content: 'AAPL',
+  metadata: JSON.stringify({
+    name: 'Apple Stock Price',
+    unit: 'USD',
+    source_url: 'https://finance.yahoo.com/quote/AAPL'
+  })
+});
+const stockId = stock.data.id;
+
+// Record observations (from polling job)
+async function recordPrice(price) {
+  await api.datastore.addItemEvent(stockId, {
+    value: price,
+    occurredAt: Date.now()
+  });
+}
+
+// Query last 7 days
+const prices = await api.datastore.queryItemEvents({
+  itemId: stockId,
+  since: Date.now() - 7 * 24 * 60 * 60 * 1000,
+  order: 'asc'
+});
+
+// Calculate average
+const avg = prices.data.reduce((sum, e) => sum + e.value, 0) / prices.data.length;
+
+// Get latest price
+const latest = await api.datastore.getLatestItemEvent(stockId);
+console.log(`Current: $${latest.data.value}, 7-day avg: $${avg.toFixed(2)}`);
+```
+
+### 2. Mood Tracking (Text Values)
+
+Track non-numeric values like mood or status.
+
+```javascript
+// Create the series
+const mood = await api.datastore.addItem('series', {
+  content: 'Mood',
+  metadata: JSON.stringify({ input: 'tag-board' })
+});
+const moodId = mood.data.id;
+
+// Record mood (from tag button board)
+async function recordMood(moodValue) {
+  await api.datastore.addItemEvent(moodId, {
+    content: moodValue,  // 'great', 'good', 'meh', 'bad'
+    occurredAt: Date.now()
+  });
+}
+
+// Usage
+await recordMood('great');
+await recordMood('meh');
+
+// Query this week's moods
+const moods = await api.datastore.queryItemEvents({
+  itemId: moodId,
+  since: Date.now() - 7 * 24 * 60 * 60 * 1000
+});
+
+// Count by mood
+const counts = {};
+for (const event of moods.data) {
+  counts[event.content] = (counts[event.content] || 0) + 1;
+}
+console.log('Mood distribution:', counts);
+```
+
+### 3. Habit Tracking with Streaks
+
+Track daily habits and calculate streaks.
+
+```javascript
+// Create the series
+const pushups = await api.datastore.addItem('series', {
+  content: 'Pushups',
+  metadata: JSON.stringify({ frequency: 'daily', tag: 'pushups' })
+});
+const pushupId = pushups.data.id;
+
+// Record daily check-in
+async function logPushups(count) {
+  const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+  await api.datastore.addItemEvent(pushupId, {
+    value: count,
+    occurredAt: Date.now(),
+    metadata: JSON.stringify({ date: today })
+  });
+}
+
+// Calculate current streak
+async function getStreak() {
+  const events = await api.datastore.queryItemEvents({
+    itemId: pushupId,
+    limit: 365,
+    order: 'desc'
+  });
+
+  if (!events.success || events.data.length === 0) return 0;
+
+  let streak = 0;
+  let expectedDate = new Date();
+  expectedDate.setHours(0, 0, 0, 0);
+
+  for (const event of events.data) {
+    const meta = JSON.parse(event.metadata || '{}');
+    const eventDate = new Date(meta.date);
+    eventDate.setHours(0, 0, 0, 0);
+
+    // Check if this is the expected date (consecutive day)
+    const diffDays = Math.round((expectedDate - eventDate) / 86400000);
+
+    if (diffDays === 0) {
+      streak++;
+      expectedDate.setDate(expectedDate.getDate() - 1);
+    } else if (diffDays === 1) {
+      // Skip today if not logged yet
+      expectedDate.setDate(expectedDate.getDate() - 1);
+      if (expectedDate.getTime() === eventDate.getTime()) {
+        streak++;
+        expectedDate.setDate(expectedDate.getDate() - 1);
+      } else {
+        break;
+      }
+    } else {
+      break;
+    }
+  }
+
+  return streak;
+}
+
+// Usage
+await logPushups(20);
+const streak = await getStreak();
+console.log(`Current streak: ${streak} days`);
+
+// Get personal best
+const allEvents = await api.datastore.queryItemEvents({ itemId: pushupId });
+const max = Math.max(...allEvents.data.map(e => e.value || 0));
+console.log(`Personal best: ${max} pushups`);
+```
+
+### 4. Ticket Availability Trigger
+
+Poll a page and notify when condition is met.
+
+```javascript
+// Create the series (acts as trigger definition)
+const tickets = await api.datastore.addItem('series', {
+  content: 'Taylor Swift Tickets',
+  metadata: JSON.stringify({
+    source_url: 'https://ticketmaster.com/event/123',
+    selector: '.buy-button',
+    condition: 'exists',
+    notified: false
+  })
+});
+const ticketId = tickets.data.id;
+
+// Polling function (run periodically)
+async function checkTickets() {
+  const item = await api.datastore.getItem(ticketId);
+  const meta = JSON.parse(item.data.metadata || '{}');
+
+  if (meta.notified) return; // Already notified
+
+  // In a real extension, you'd load the page in a hidden window
+  // and run document.querySelector(meta.selector)
+  const available = await checkPageForElement(meta.source_url, meta.selector);
+
+  // Record the check
+  await api.datastore.addItemEvent(ticketId, {
+    value: available ? 1 : 0,
+    content: available ? 'Available!' : 'Not available',
+    occurredAt: Date.now()
+  });
+
+  // Trigger notification
+  if (available) {
+    meta.notified = true;
+    await api.datastore.updateItem(ticketId, {
+      metadata: JSON.stringify(meta)
+    });
+
+    // Show notification
+    new Notification('Tickets Available!', {
+      body: 'Taylor Swift tickets are now on sale!'
+    });
+  }
+}
+```
+
+### 5. RSS Feed Reader
+
+Subscribe to and poll RSS feeds.
+
+```javascript
+// Subscribe to a feed
+async function subscribe(url) {
+  const response = await fetch(url);
+  const xml = await response.text();
+  const title = parseFeedTitle(xml); // Your XML parsing function
+
+  const feed = await api.datastore.addItem('feed', {
+    content: url,
+    metadata: JSON.stringify({
+      name: title,
+      format: 'rss',
+      lastPolledAt: 0
+    })
+  });
+
+  return feed.data.id;
+}
+
+// Poll a feed for new entries
+async function pollFeed(feedId) {
+  const item = await api.datastore.getItem(feedId);
+  const feedUrl = item.data.content;
+
+  const response = await fetch(feedUrl);
+  const xml = await response.text();
+  const entries = parseFeedEntries(xml); // Your XML parsing function
+
+  // Get existing entries to dedupe
+  const existing = await api.datastore.queryItemEvents({ itemId: feedId, limit: 100 });
+  const existingGuids = new Set(
+    existing.data.map(e => JSON.parse(e.metadata || '{}').guid)
+  );
+
+  // Add new entries
+  for (const entry of entries) {
+    if (existingGuids.has(entry.guid)) continue;
+
+    await api.datastore.addItemEvent(feedId, {
+      content: entry.link,
+      occurredAt: entry.pubDate,
+      metadata: JSON.stringify({
+        guid: entry.guid,
+        title: entry.title,
+        author: entry.author
+      })
+    });
+  }
+
+  // Update last polled
+  const meta = JSON.parse(item.data.metadata || '{}');
+  meta.lastPolledAt = Date.now();
+  await api.datastore.updateItem(feedId, { metadata: JSON.stringify(meta) });
+}
+
+// Get all entries across feeds
+async function getAllEntries(limit = 50) {
+  const feeds = await api.datastore.queryItems({ type: 'feed' });
+  const feedIds = feeds.data.map(f => f.id);
+
+  const entries = await api.datastore.queryItemEvents({
+    itemIds: feedIds,
+    limit: limit,
+    order: 'desc'
+  });
+
+  return entries.data.map(e => ({
+    ...e,
+    meta: JSON.parse(e.metadata || '{}')
+  }));
+}
+```
+
+### 6. System Metrics / Action Log
+
+Track internal application events.
+
+```javascript
+// Create a log feed
+const actionLog = await api.datastore.addItem('feed', {
+  content: 'peek:system:actions',
+  metadata: JSON.stringify({ format: 'internal' })
+});
+const logId = actionLog.data.id;
+
+// Log an action
+async function logAction(action, details = {}) {
+  await api.datastore.addItemEvent(logId, {
+    content: action,
+    occurredAt: Date.now(),
+    metadata: JSON.stringify(details)
+  });
+}
+
+// Usage
+await logAction('page_open', { url: 'https://example.com', source: 'bookmark' });
+await logAction('settings_changed', { key: 'theme', value: 'dark' });
+await logAction('extension_loaded', { id: 'feeds', version: '1.0.0' });
+
+// Query recent actions
+const recent = await api.datastore.queryItemEvents({
+  itemId: logId,
+  since: Date.now() - 3600000, // last hour
+  order: 'desc'
+});
+
+// Count actions by type
+const counts = {};
+for (const event of recent.data) {
+  counts[event.content] = (counts[event.content] || 0) + 1;
+}
+console.log('Action counts:', counts);
+```
+
+### 7. Spotify Listening History
+
+Pull data from external APIs.
+
+```javascript
+// Create the feed
+const spotify = await api.datastore.addItem('feed', {
+  content: 'spotify:me:recently-played',
+  metadata: JSON.stringify({
+    format: 'api',
+    service: 'spotify',
+    lastSyncedAt: 0
+  })
+});
+const spotifyId = spotify.data.id;
+
+// Sync from Spotify API (requires OAuth token)
+async function syncSpotify(accessToken) {
+  const response = await fetch('https://api.spotify.com/v1/me/player/recently-played?limit=50', {
+    headers: { 'Authorization': `Bearer ${accessToken}` }
+  });
+  const data = await response.json();
+
+  // Get existing to dedupe
+  const existing = await api.datastore.queryItemEvents({ itemId: spotifyId, limit: 100 });
+  const existingIds = new Set(
+    existing.data.map(e => JSON.parse(e.metadata || '{}').playedAt)
+  );
+
+  // Add new plays
+  for (const item of data.items) {
+    const playedAt = new Date(item.played_at).getTime();
+    if (existingIds.has(item.played_at)) continue;
+
+    await api.datastore.addItemEvent(spotifyId, {
+      content: item.track.uri,
+      occurredAt: playedAt,
+      metadata: JSON.stringify({
+        playedAt: item.played_at,
+        trackName: item.track.name,
+        artistName: item.track.artists[0]?.name,
+        albumName: item.track.album?.name,
+        durationMs: item.track.duration_ms
+      })
+    });
+  }
+
+  // Update sync time
+  const meta = JSON.parse((await api.datastore.getItem(spotifyId)).data.metadata || '{}');
+  meta.lastSyncedAt = Date.now();
+  await api.datastore.updateItem(spotifyId, { metadata: JSON.stringify(meta) });
+}
+
+// Get top artists from listening history
+async function getTopArtists(days = 30) {
+  const plays = await api.datastore.queryItemEvents({
+    itemId: spotifyId,
+    since: Date.now() - days * 24 * 60 * 60 * 1000
+  });
+
+  const artistCounts = {};
+  for (const play of plays.data) {
+    const meta = JSON.parse(play.metadata || '{}');
+    const artist = meta.artistName || 'Unknown';
+    artistCounts[artist] = (artistCounts[artist] || 0) + 1;
+  }
+
+  return Object.entries(artistCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+}
+```
+
+## Schema Reference
+
+### items table (existing, extended)
+
+```sql
+items (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,  -- 'url', 'text', 'tagset', 'image', 'series', 'feed'
+  content TEXT,        -- identifier, URL, or name
+  metadata TEXT,       -- JSON with type-specific data
+  ...
+)
+```
+
+### item_events table (new)
+
+```sql
+item_events (
+  id TEXT PRIMARY KEY,
+  itemId TEXT NOT NULL,     -- FK to series or feed
+  content TEXT,             -- text value, URL, or message
+  value REAL,               -- numeric value (optional)
+  occurredAt INTEGER,       -- when it happened (Unix ms)
+  metadata TEXT,            -- JSON extras
+  createdAt INTEGER         -- when recorded
+)
+
+-- Indexes
+CREATE INDEX idx_item_events_item_time ON item_events(itemId, occurredAt DESC);
+CREATE INDEX idx_item_events_occurred ON item_events(occurredAt DESC);
+```
+
+## Best Practices
+
+1. **Use `value` for numbers, `content` for text/URLs** - Makes queries and aggregations simpler.
+
+2. **Store dedup keys in metadata** - For feeds, store `guid` to avoid duplicate entries.
+
+3. **Set `occurredAt` to event time, not record time** - For RSS entries, use `pubDate`; for API data, use the original timestamp.
+
+4. **Keep metadata lightweight** - Truncate descriptions, store only what you need for display.
+
+5. **Delete events when deleting items** - Always call `deleteItemEvents(itemId)` before `deleteItem(itemId)`.
+
+6. **Use `order: 'desc'` for recent-first** - Most UIs want newest first.
+
+7. **Batch queries with `itemIds`** - When showing entries from multiple feeds, query once with all IDs.

extensions/feeds/background.html

···
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Feeds Extension</title>
+</head>
+<body>
+  <script type="module" src="background.js"></script>
+</body>
+</html>

extensions/feeds/background.js

···
+/**
+ * Feeds Extension - Simple RSS/Atom Feed Reader
+ *
+ * Demonstrates:
+ * - Using the 'feed' item type for subscriptions
+ * - Using item_events for feed entries
+ * - Polling feeds and parsing RSS/Atom
+ * - Commands for subscribing and viewing feeds
+ */
+
+const api = window.app;
+const POLL_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
+
+let pollTimer = null;
+
+// ==================== Feed Parsing ====================
+
+/**
+ * Parse RSS or Atom feed XML into normalized entries
+ */
+function parseFeed(xml, feedUrl) {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(xml, 'text/xml');
+
+  // Check for parse errors
+  const parseError = doc.querySelector('parsererror');
+  if (parseError) {
+    throw new Error('Invalid XML: ' + parseError.textContent);
+  }
+
+  // Detect feed type and parse accordingly
+  const rssChannel = doc.querySelector('channel');
+  const atomFeed = doc.querySelector('feed');
+
+  if (rssChannel) {
+    return parseRSS(rssChannel, feedUrl);
+  } else if (atomFeed) {
+    return parseAtom(atomFeed, feedUrl);
+  } else {
+    throw new Error('Unknown feed format');
+  }
+}
+
+/**
+ * Parse RSS 2.0 feed
+ */
+function parseRSS(channel, feedUrl) {
+  const title = channel.querySelector('title')?.textContent || feedUrl;
+  const items = channel.querySelectorAll('item');
+
+  const entries = [];
+  for (const item of items) {
+    const link = item.querySelector('link')?.textContent;
+    const guid = item.querySelector('guid')?.textContent || link;
+    const pubDate = item.querySelector('pubDate')?.textContent;
+
+    entries.push({
+      guid: guid || link || `${feedUrl}#${entries.length}`,
+      title: item.querySelector('title')?.textContent || 'Untitled',
+      link: link || '',
+      author: item.querySelector('author')?.textContent ||
+              item.querySelector('dc\\:creator')?.textContent || '',
+      description: item.querySelector('description')?.textContent || '',
+      pubDate: pubDate ? new Date(pubDate).getTime() : Date.now()
+    });
+  }
+
+  return { title, entries };
+}
+
+/**
+ * Parse Atom feed
+ */
+function parseAtom(feed, feedUrl) {
+  const title = feed.querySelector('title')?.textContent || feedUrl;
+  const items = feed.querySelectorAll('entry');
+
+  const entries = [];
+  for (const item of items) {
+    const link = item.querySelector('link[rel="alternate"]')?.getAttribute('href') ||
+                 item.querySelector('link')?.getAttribute('href');
+    const id = item.querySelector('id')?.textContent || link;
+    const published = item.querySelector('published')?.textContent ||
+                      item.querySelector('updated')?.textContent;
+
+    entries.push({
+      guid: id || link || `${feedUrl}#${entries.length}`,
+      title: item.querySelector('title')?.textContent || 'Untitled',
+      link: link || '',
+      author: item.querySelector('author name')?.textContent || '',
+      description: item.querySelector('summary')?.textContent ||
+                   item.querySelector('content')?.textContent || '',
+      pubDate: published ? new Date(published).getTime() : Date.now()
+    });
+  }
+
+  return { title, entries };
+}
+
+// ==================== Feed Operations ====================
+
+/**
+ * Subscribe to a new feed
+ */
+async function subscribeFeed(url) {
+  // Check if already subscribed
+  const existing = await api.datastore.queryItems({ type: 'feed' });
+  if (existing.success) {
+    const alreadySubscribed = existing.data.find(f => f.content === url);
+    if (alreadySubscribed) {
+      console.log('[feeds] Already subscribed to:', url);
+      return { success: false, error: 'Already subscribed to this feed' };
+    }
+  }
+
+  // Fetch and parse to validate and get title
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const xml = await response.text();
+    const { title } = parseFeed(xml, url);
+
+    // Create feed item
+    const result = await api.datastore.addItem('feed', {
+      content: url,
+      metadata: JSON.stringify({
+        name: title,
+        format: 'rss',
+        lastPolledAt: 0,
+        errorCount: 0
+      })
+    });
+
+    if (result.success) {
+      console.log('[feeds] Subscribed to:', title);
+      // Poll immediately
+      await pollFeed(result.data.id, url);
+      return { success: true, data: { id: result.data.id, title, url } };
+    }
+    return result;
+  } catch (error) {
+    console.error('[feeds] Subscribe error:', error);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Unsubscribe from a feed
+ */
+async function unsubscribeFeed(feedId) {
+  // Delete all entries first
+  await api.datastore.deleteItemEvents(feedId);
+  // Delete the feed item
+  return await api.datastore.deleteItem(feedId);
+}
+
+/**
+ * Get all subscribed feeds
+ */
+async function getFeeds() {
+  const result = await api.datastore.queryItems({ type: 'feed' });
+  if (!result.success) return [];
+
+  return result.data.map(item => {
+    let metadata = {};
+    try {
+      metadata = JSON.parse(item.metadata || '{}');
+    } catch {}
+    return {
+      id: item.id,
+      url: item.content,
+      name: metadata.name || item.content,
+      lastPolledAt: metadata.lastPolledAt || 0,
+      errorCount: metadata.errorCount || 0
+    };
+  });
+}
+
+/**
+ * Poll a single feed for new entries
+ */
+async function pollFeed(feedId, feedUrl) {
+  console.log('[feeds] Polling:', feedUrl);
+
+  try {
+    const response = await fetch(feedUrl);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const xml = await response.text();
+    const { title, entries } = parseFeed(xml, feedUrl);
+
+    // Get existing entries to avoid duplicates
+    const existingEvents = await api.datastore.queryItemEvents({ itemId: feedId, limit: 100 });
+    const existingGuids = new Set();
+    if (existingEvents.success) {
+      for (const event of existingEvents.data) {
+        try {
+          const meta = JSON.parse(event.metadata || '{}');
+          if (meta.guid) existingGuids.add(meta.guid);
+        } catch {}
+      }
+    }
+
+    // Add new entries
+    let newCount = 0;
+    for (const entry of entries) {
+      if (existingGuids.has(entry.guid)) continue;
+
+      await api.datastore.addItemEvent(feedId, {
+        content: entry.link,
+        occurredAt: entry.pubDate,
+        metadata: JSON.stringify({
+          guid: entry.guid,
+          title: entry.title,
+          author: entry.author,
+          description: entry.description?.slice(0, 500) // Truncate long descriptions
+        })
+      });
+      newCount++;
+    }
+
+    // Update feed metadata
+    await api.datastore.updateItem(feedId, {
+      metadata: JSON.stringify({
+        name: title,
+        format: 'rss',
+        lastPolledAt: Date.now(),
+        errorCount: 0
+      })
+    });
+
+    console.log(`[feeds] Polled ${feedUrl}: ${newCount} new entries`);
+    return { success: true, newCount };
+  } catch (error) {
+    console.error('[feeds] Poll error:', feedUrl, error);
+
+    // Increment error count
+    const item = await api.datastore.getItem(feedId);
+    if (item.success && item.data) {
+      let metadata = {};
+      try { metadata = JSON.parse(item.data.metadata || '{}'); } catch {}
+      metadata.errorCount = (metadata.errorCount || 0) + 1;
+      metadata.lastError = error.message;
+      await api.datastore.updateItem(feedId, {
+        metadata: JSON.stringify(metadata)
+      });
+    }
+
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Poll all feeds
+ */
+async function pollAllFeeds() {
+  const feeds = await getFeeds();
+  console.log(`[feeds] Polling ${feeds.length} feeds...`);
+
+  for (const feed of feeds) {
+    await pollFeed(feed.id, feed.url);
+  }
+}
+
+/**
+ * Get entries for a feed or all feeds
+ */
+async function getEntries(feedId = null, limit = 50) {
+  const filter = { limit, order: 'desc' };
+
+  if (feedId) {
+    filter.itemId = feedId;
+  } else {
+    // Get all feeds to query their entries
+    const feeds = await getFeeds();
+    if (feeds.length === 0) return [];
+    filter.itemIds = feeds.map(f => f.id);
+  }
+
+  const result = await api.datastore.queryItemEvents(filter);
+  if (!result.success) return [];
+
+  return result.data.map(event => {
+    let metadata = {};
+    try { metadata = JSON.parse(event.metadata || '{}'); } catch {}
+    return {
+      id: event.id,
+      feedId: event.itemId,
+      url: event.content,
+      title: metadata.title || event.content,
+      author: metadata.author || '',
+      description: metadata.description || '',
+      pubDate: event.occurredAt
+    };
+  });
+}
+
+// ==================== UI ====================
+
+function openFeedsUI() {
+  api.window.open('peek://ext/feeds/feeds.html', {
+    key: 'feeds-reader',
+    width: 900,
+    height: 700,
+    title: 'Feed Reader'
+  });
+}
+
+// ==================== Extension ====================
+
+const extension = {
+  id: 'feeds',
+  labels: {
+    name: 'Feed Reader'
+  },
+
+  registerCommands() {
+    api.commands.register({
+      name: 'feeds',
+      description: 'Open feed reader',
+      execute: openFeedsUI
+    });
+
+    api.commands.register({
+      name: 'feeds:subscribe',
+      description: 'Subscribe to an RSS/Atom feed',
+      execute: async (ctx) => {
+        const url = ctx?.input?.text || ctx?.input;
+        if (url && typeof url === 'string' && url.startsWith('http')) {
+          const result = await subscribeFeed(url);
+          if (result.success) {
+            openFeedsUI();
+          }
+        } else {
+          // Open UI with subscribe prompt
+          openFeedsUI();
+        }
+      }
+    });
+
+    api.commands.register({
+      name: 'feeds:refresh',
+      description: 'Refresh all feeds',
+      execute: pollAllFeeds
+    });
+
+    console.log('[feeds] Commands registered');
+  },
+
+  init() {
+    console.log('[feeds] Initializing...');
+
+    // Wait for cmd:ready before registering commands
+    api.subscribe('cmd:ready', () => {
+      this.registerCommands();
+    }, api.scopes.GLOBAL);
+
+    api.publish('cmd:query', {}, api.scopes.GLOBAL);
+
+    // Register global shortcut
+    api.shortcuts.register('Option+f', openFeedsUI, { global: true });
+
+    // Start polling timer
+    pollTimer = setInterval(pollAllFeeds, POLL_INTERVAL_MS);
+
+    // Initial poll after short delay
+    setTimeout(pollAllFeeds, 5000);
+
+    console.log('[feeds] Extension loaded');
+  },
+
+  uninit() {
+    console.log('[feeds] Cleaning up...');
+
+    if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+
+    api.shortcuts.unregister('Option+f', { global: true });
+    api.commands.unregister('feeds');
+    api.commands.unregister('feeds:subscribe');
+    api.commands.unregister('feeds:refresh');
+  }
+};
+
+export default extension;
+
+// Export for UI
+export { getFeeds, getEntries, subscribeFeed, unsubscribeFeed, pollFeed, pollAllFeeds };

extensions/feeds/feeds.html

···
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Feed Reader</title>
+  <style>
+    * {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: var(--bg-primary, #1a1a1a);
+      color: var(--text-primary, #e0e0e0);
+      height: 100vh;
+      display: flex;
+      flex-direction: column;
+    }
+
+    header {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      padding: 12px 16px;
+      background: var(--bg-secondary, #252525);
+      border-bottom: 1px solid var(--border, #333);
+    }
+
+    header h1 {
+      font-size: 16px;
+      font-weight: 500;
+      flex: 1;
+    }
+
+    .btn {
+      background: var(--bg-tertiary, #333);
+      border: 1px solid var(--border, #444);
+      color: var(--text-primary, #e0e0e0);
+      padding: 6px 12px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 13px;
+    }
+
+    .btn:hover {
+      background: var(--bg-hover, #3a3a3a);
+    }
+
+    .btn-primary {
+      background: var(--accent, #4a9eff);
+      border-color: var(--accent, #4a9eff);
+      color: white;
+    }
+
+    .btn-primary:hover {
+      background: var(--accent-hover, #3a8eef);
+    }
+
+    .container {
+      display: flex;
+      flex: 1;
+      overflow: hidden;
+    }
+
+    .sidebar {
+      width: 240px;
+      background: var(--bg-secondary, #252525);
+      border-right: 1px solid var(--border, #333);
+      display: flex;
+      flex-direction: column;
+    }
+
+    .sidebar-header {
+      padding: 12px;
+      border-bottom: 1px solid var(--border, #333);
+      font-size: 12px;
+      font-weight: 600;
+      text-transform: uppercase;
+      color: var(--text-secondary, #888);
+    }
+
+    .feed-list {
+      flex: 1;
+      overflow-y: auto;
+    }
+
+    .feed-item {
+      padding: 10px 12px;
+      cursor: pointer;
+      border-bottom: 1px solid var(--border, #2a2a2a);
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .feed-item:hover {
+      background: var(--bg-hover, #2a2a2a);
+    }
+
+    .feed-item.active {
+      background: var(--bg-active, #333);
+    }
+
+    .feed-item .name {
+      flex: 1;
+      font-size: 13px;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .feed-item .delete {
+      opacity: 0;
+      color: var(--text-secondary, #888);
+      font-size: 16px;
+    }
+
+    .feed-item:hover .delete {
+      opacity: 1;
+    }
+
+    .all-feeds {
+      font-weight: 500;
+    }
+
+    .main {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      overflow: hidden;
+    }
+
+    .entries {
+      flex: 1;
+      overflow-y: auto;
+      padding: 12px;
+    }
+
+    .entry {
+      padding: 12px;
+      margin-bottom: 8px;
+      background: var(--bg-secondary, #252525);
+      border-radius: 6px;
+      border: 1px solid var(--border, #333);
+    }
+
+    .entry:hover {
+      border-color: var(--border-hover, #444);
+    }
+
+    .entry-title {
+      font-size: 14px;
+      font-weight: 500;
+      margin-bottom: 4px;
+    }
+
+    .entry-title a {
+      color: var(--text-primary, #e0e0e0);
+      text-decoration: none;
+    }
+
+    .entry-title a:hover {
+      color: var(--accent, #4a9eff);
+    }
+
+    .entry-meta {
+      font-size: 12px;
+      color: var(--text-secondary, #888);
+      margin-bottom: 6px;
+    }
+
+    .entry-description {
+      font-size: 13px;
+      color: var(--text-secondary, #aaa);
+      line-height: 1.4;
+      max-height: 60px;
+      overflow: hidden;
+    }
+
+    .empty-state {
+      text-align: center;
+      padding: 60px 20px;
+      color: var(--text-secondary, #888);
+    }
+
+    .empty-state h2 {
+      font-size: 18px;
+      font-weight: 500;
+      margin-bottom: 8px;
+    }
+
+    .empty-state p {
+      font-size: 14px;
+      margin-bottom: 16px;
+    }
+
+    .subscribe-form {
+      padding: 12px;
+      border-top: 1px solid var(--border, #333);
+    }
+
+    .subscribe-form input {
+      width: 100%;
+      padding: 8px 10px;
+      background: var(--bg-primary, #1a1a1a);
+      border: 1px solid var(--border, #444);
+      border-radius: 4px;
+      color: var(--text-primary, #e0e0e0);
+      font-size: 13px;
+    }
+
+    .subscribe-form input:focus {
+      outline: none;
+      border-color: var(--accent, #4a9eff);
+    }
+
+    .loading {
+      text-align: center;
+      padding: 20px;
+      color: var(--text-secondary, #888);
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Feed Reader</h1>
+    <button class="btn" id="refreshBtn">Refresh All</button>
+  </header>
+
+  <div class="container">
+    <div class="sidebar">
+      <div class="sidebar-header">Feeds</div>
+      <div class="feed-list" id="feedList">
+        <div class="feed-item all-feeds active" data-feed-id="">
+          <span class="name">All Feeds</span>
+        </div>
+      </div>
+      <div class="subscribe-form">
+        <input type="url" id="subscribeInput" placeholder="Enter feed URL..." />
+      </div>
+    </div>
+
+    <div class="main">
+      <div class="entries" id="entries">
+        <div class="loading">Loading...</div>
+      </div>
+    </div>
+  </div>
+
+  <script type="module">
+    import { getFeeds, getEntries, subscribeFeed, unsubscribeFeed, pollAllFeeds } from './background.js';
+
+    const api = window.app;
+    let currentFeedId = null;
+
+    // ==================== Rendering ====================
+
+    async function renderFeeds() {
+      const feeds = await getFeeds();
+      const feedList = document.getElementById('feedList');
+
+      // Keep the "All Feeds" item
+      const allFeedsItem = feedList.querySelector('.all-feeds');
+
+      feedList.innerHTML = '';
+      feedList.appendChild(allFeedsItem);
+
+      for (const feed of feeds) {
+        const item = document.createElement('div');
+        item.className = 'feed-item' + (currentFeedId === feed.id ? ' active' : '');
+        item.dataset.feedId = feed.id;
+        item.innerHTML = `
+          <span class="name" title="${feed.url}">${feed.name}</span>
+          <span class="delete" title="Unsubscribe">&times;</span>
+        `;
+        feedList.appendChild(item);
+      }
+    }
+
+    async function renderEntries() {
+      const entries = await getEntries(currentFeedId, 100);
+      const container = document.getElementById('entries');
+
+      if (entries.length === 0) {
+        container.innerHTML = `
+          <div class="empty-state">
+            <h2>No entries yet</h2>
+            <p>${currentFeedId ? 'This feed has no entries.' : 'Subscribe to a feed to get started.'}</p>
+          </div>
+        `;
+        return;
+      }
+
+      container.innerHTML = entries.map(entry => `
+        <div class="entry">
+          <div class="entry-title">
+            <a href="${escapeHtml(entry.url)}" target="_blank">${escapeHtml(entry.title)}</a>
+          </div>
+          <div class="entry-meta">
+            ${entry.author ? escapeHtml(entry.author) + ' · ' : ''}${formatDate(entry.pubDate)}
+          </div>
+          ${entry.description ? `<div class="entry-description">${escapeHtml(stripHtml(entry.description))}</div>` : ''}
+        </div>
+      `).join('');
+    }
+
+    function escapeHtml(str) {
+      if (!str) return '';
+      return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    }
+
+    function stripHtml(str) {
+      if (!str) return '';
+      return str.replace(/<[^>]*>/g, '').trim();
+    }
+
+    function formatDate(timestamp) {
+      if (!timestamp) return '';
+      const date = new Date(timestamp);
+      const now = new Date();
+      const diff = now - date;
+
+      if (diff < 60000) return 'Just now';
+      if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
+      if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
+      if (diff < 604800000) return `${Math.floor(diff / 86400000)}d ago`;
+
+      return date.toLocaleDateString();
+    }
+
+    // ==================== Event Handlers ====================
+
+    document.getElementById('feedList').addEventListener('click', async (e) => {
+      const feedItem = e.target.closest('.feed-item');
+      if (!feedItem) return;
+
+      // Handle delete button
+      if (e.target.classList.contains('delete')) {
+        const feedId = feedItem.dataset.feedId;
+        if (feedId && confirm('Unsubscribe from this feed?')) {
+          await unsubscribeFeed(feedId);
+          if (currentFeedId === feedId) {
+            currentFeedId = null;
+          }
+          await renderFeeds();
+          await renderEntries();
+        }
+        return;
+      }
+
+      // Select feed
+      document.querySelectorAll('.feed-item').forEach(el => el.classList.remove('active'));
+      feedItem.classList.add('active');
+      currentFeedId = feedItem.dataset.feedId || null;
+      await renderEntries();
+    });
+
+    document.getElementById('subscribeInput').addEventListener('keypress', async (e) => {
+      if (e.key === 'Enter') {
+        const input = e.target;
+        const url = input.value.trim();
+        if (!url) return;
+
+        input.disabled = true;
+        const result = await subscribeFeed(url);
+        input.disabled = false;
+
+        if (result.success) {
+          input.value = '';
+          await renderFeeds();
+          await renderEntries();
+        } else {
+          alert('Failed to subscribe: ' + result.error);
+        }
+      }
+    });
+
+    document.getElementById('refreshBtn').addEventListener('click', async () => {
+      const btn = document.getElementById('refreshBtn');
+      btn.disabled = true;
+      btn.textContent = 'Refreshing...';
+
+      await pollAllFeeds();
+      await renderEntries();
+
+      btn.disabled = false;
+      btn.textContent = 'Refresh All';
+    });
+
+    // Handle entry link clicks
+    document.getElementById('entries').addEventListener('click', (e) => {
+      const link = e.target.closest('a');
+      if (link && link.href) {
+        e.preventDefault();
+        api.window.open(link.href);
+      }
+    });
+
+    // ==================== Init ====================
+
+    async function init() {
+      await renderFeeds();
+      await renderEntries();
+    }
+
+    init();
+  </script>
+</body>
+</html>

extensions/feeds/manifest.json

···
+{
+  "id": "feeds",
+  "shortname": "feeds",
+  "name": "Feed Reader",
+  "description": "Simple RSS/Atom feed reader demonstrating the series and feeds APIs",
+  "version": "1.0.0",
+  "background": "background.html",
+  "settingsSchema": "./settings-schema.json"
+}

extensions/feeds/settings-schema.json

···
+{
+  "pollInterval": {
+    "type": "select",
+    "label": "Poll Interval",
+    "description": "How often to check feeds for new entries",
+    "options": [
+      { "value": "5", "label": "5 minutes" },
+      { "value": "15", "label": "15 minutes" },
+      { "value": "30", "label": "30 minutes" },
+      { "value": "60", "label": "1 hour" }
+    ],
+    "default": "15"
+  }
+}