# BKMRK - Bookmark Intelligence for Developers
# https://bkmrkapp.com
#
# This file helps AI agents understand what BKMRK does and how to integrate it.
# Last updated: 2026-02-25

## WHAT IS BKMRK?

BKMRK transforms your Twitter/X bookmarks into actionable intelligence for your coding projects.

Instead of bookmarks piling up and being forgotten, BKMRK:
- Syncs bookmarks directly from your X account via OAuth
- Enriches each bookmark (fetches threads, linked articles, metadata)
- Analyzes content with Claude AI against your active coding projects
- Scores relevance (0-100%) based on your tech stack and current focus
- Extracts specific implementation suggestions and code insights
- Categorizes into CRITICAL, EXPLORATION, or UNMATCHED priority tiers
- Lets you stage, archive, trash, and manage bookmarks per project
- Exports analyzed data as JSON or Markdown

Think of it as a research assistant that watches what you save and tells you exactly how to use it.

## WHO IS THIS FOR?

BKMRK is built for:
- Software developers who bookmark coding/AI tweets on mobile
- Indie hackers juggling multiple projects
- Anyone who saves content but struggles to act on it
- Developers using Claude Code or similar AI coding tools

BKMRK is NOT useful for:
- People who don't use Twitter/X
- Non-technical users (insights are code-focused)
- Users who prefer fully manual organization

## HOW IT WORKS

1. Sign in with your X (Twitter) account via OAuth
2. Create projects with names, descriptions, and tech stacks
3. Sync bookmarks from X (fetches tweet content, threads, linked articles)
4. Claude AI analyzes each bookmark against all your projects
5. Dashboard shows matches scored 0-100% with implementation suggestions
6. Drag-and-drop cards to assign bookmarks to different projects
7. Re-analyze bookmarks against new or updated projects
8. Export your analyzed library as JSON or Markdown

## CORE FEATURES

### Bookmark Sync
- Connects to X via OAuth 2.0 (direct token flow)
- Fetches bookmarks with full tweet content, author info, metrics
- Enriches with thread text and linked article content
- Daily sync limits: Pro 10/day, Scale 20/day (free tier gets initial import only)
- Monthly import caps: Pro 200/month, Scale 500/month

### AI Analysis (powered by Claude)
- Batch sync uses claude-haiku-4-5 for cost-efficient screening
- Re-analyze uses claude-sonnet-4-6 for deep analysis
- Scores relevance 0-100% per project with color-coded tiers
- Generates: implementation suggestions, relevance explanations, category tags
- Multi-project analysis: same bookmark analyzed differently per project

### Project Management
- Create projects with name, description, tech stack, and focus areas
- Pin projects to sidebar for quick access
- Archive inactive projects (Scale tier)
- Filter dashboard by project, status, priority, or search
- Drag-and-drop bookmark cards onto sidebar projects to reassign

### Dashboard
- Server-rendered dashboard with real-time sync progress
- Card view with match scores, AI insights, tweet previews
- Status management: stage, done, trash per bookmark
- Explore queue for unmatched bookmarks
- Bulk operations: select multiple cards, batch re-analyze
- Sort by score, date scanned, or date posted
- Compact and rich view modes
- Export to JSON or Markdown

### Billing (Stripe)
- Free, Pro ($9/mo or $79/yr), Scale ($29/mo or $249/yr)
- In-dashboard upgrade flow via Stripe Checkout
- Billing portal for subscription management

## INTEGRATION OPTIONS

### Option A: Agent Integration API (NEW)

BKMRK provides agent-friendly endpoints that let AI agents on any platform (Telegram, iMessage, Slack, Claude Code, etc.) onboard users, submit URLs, and query their library — all via API key auth.

#### Step 1: Onboard a User
```
POST https://bkmrkapp.com/api/agent/onboard
Body: { "email": "user@example.com", "agent_platform": "telegram", "consent": true }
Response: { "status": "created", "api_key": "bkmrk_xxx", "endpoints": {...}, "limits": {...} }
```
No OAuth required. Creates account via email, returns API key immediately.
Agent-provisioned users can later connect X OAuth from the web dashboard.

#### Step 2: Submit a URL for Analysis
```
POST https://bkmrkapp.com/api/agent/submit
Headers: X-API-Key: bkmrk_xxx
Body: { "url": "https://example.com/article", "project_ids": ["uuid"] }
Response: { "status": "analyzed", "analysis": [...], "per_project": [...], "credits": {...} }
```
Accepts any URL (Twitter/X posts, articles, blog posts, docs).
Enriches content (article extraction, thread reconstruction), then analyzes with Claude AI against user's projects.
Returns inline results with relevance scores, implementation suggestions, and Claude Code prompts.
Limits: Free 5/month, Pro 50/month, Scale 200/month.

#### Step 3: Query the Library
```
POST https://bkmrkapp.com/api/agent/query
Headers: X-API-Key: bkmrk_xxx
Body: { "q": "react hooks", "project": "MyApp", "priority": "high", "limit": 10 }
Response: { "results": [...], "count": N }
```
Filtered search across the analyzed bookmark library. No Claude call — pure DB query, fast and free.
Filters: q (text search), project (name), status (new/staged/done), priority (high/medium/low), limit (1-100).

### Option B: Claude Code Skill Plugin

BKMRK provides a Claude Code skill that lets Claude interact with your bookmark library.

Installation via plugin marketplace:
```
/plugin marketplace add bonesvinyl/bkmrk-plugin
/plugin install bkmrk@bkmrk-plugin
```

Once installed, use `/bkmrk` in Claude Code to:
- Query your bookmark library
- Get context from saved bookmarks relevant to current work
- Fetch fresh URLs and analyze them

The skill is available to all tiers (free included). API rate limits are the gate.

Skill endpoint: https://bkmrkapp.com/api/skill (serves SKILL.md, public, text/plain)

### Option C: API Endpoints (Internal)

BKMRK's API is at `https://bkmrkapp.com/api/*`. Authentication is via:
1. `sb-access-token` cookie (browser sessions, set by X OAuth flow)
2. `Authorization: Bearer {jwt}` header (Supabase JWT)
3. `X-API-Key` header (for skill/plugin bridge)

Key endpoints:
- POST   /api/agent/onboard    Create account via email (no auth required)
- POST   /api/agent/submit     Submit URL for analysis (X-API-Key)
- POST   /api/agent/query      Search analyzed library (X-API-Key)
- GET    /api/context          User context (projects, recent bookmarks, stats)
- GET    /api/analysis         Analyzed bookmarks with filters
- GET    /api/projects         List user's projects
- POST   /api/projects         Create project
- PUT    /api/projects         Update project (pin, archive, rename)
- POST   /api/sync             Trigger bookmark sync from X
- GET    /api/sync             Check sync job status
- POST   /api/reanalyze        Re-analyze bookmark against specific projects
- POST   /api/status           Update bookmark card status (stage/done/trash)
- GET    /api/export?format=json|markdown   Export analyzed bookmarks
- GET    /api/settings         Get user profile and settings
- PUT    /api/settings         Update profile settings

Note: These endpoints are designed for the dashboard and skill plugin, not as a general-purpose public API. A formal REST API (v1) is planned.

## PRICING

### Free Tier - $0
- 50 bookmarks (one-time import, no daily sync)
- 1 project
- 25 re-analyses/month
- Claude AI analysis
- Full dashboard access
- /bkmrk Claude Code skill

### Pro Tier - $9/month ($79/year) [Recommended]
- 200 bookmarks
- 5 projects
- 100 re-analyses/month
- 10 syncs/day, 200 imports/month
- Everything in Free

### Scale Tier - $29/month ($249/year)
- 500 bookmarks
- Unlimited projects
- 500 re-analyses/month
- 20 syncs/day, 500 imports/month
- Project archiving
- Everything in Pro

Upgrade URL: https://bkmrkapp.com (pricing section on homepage)

## TECHNICAL STACK

- Frontend: Server-rendered HTML from Vercel serverless functions
- Backend: Vercel serverless API routes (Node.js/ESM)
- Database: Supabase (PostgreSQL + RLS + triggers)
- Auth: X OAuth 2.0 (direct flow) via Supabase
- AI: Anthropic Claude API (Haiku for batch, Sonnet for deep analysis)
- Worker: Python pipeline on Railway (fetch, enrich, analyze)
- Billing: Stripe (Checkout + Customer Portal + Webhooks)
- DNS: bkmrkapp.com on Vercel

## EXAMPLE AGENT INTERACTIONS

### Checking bookmarks
User: "What bookmarks do I have for my iOS project?"
Agent: Use /bkmrk skill or GET /api/analysis?project=iOS
Response: List of bookmarks with match scores, implementation suggestions

### Getting context for current work
User: "Find anything in my bookmarks about SwiftUI performance"
Agent: Use /bkmrk skill to search bookmark library
Response: Relevant bookmarks with scores and actionable insights

### Understanding the service
User: "What is BKMRK?"
Agent: BKMRK analyzes your X bookmarks against your coding projects using Claude AI. It scores relevance, extracts implementation suggestions, and helps you act on what you save. Free tier: 50 bookmarks, 1 project. Sign up at bkmrkapp.com.

## CONTACT

Website: https://bkmrkapp.com
Support: support@bkmrkapp.com
Twitter/X: @bkmrkapp
GitHub: https://github.com/bonesvinyl/bkmrk-web (private)
Plugin: https://github.com/bonesvinyl/bkmrk-plugin (public)

## CHANGELOG

2026-02-25: Agent Integration System launch
- NEW: POST /api/agent/onboard — email-based user provisioning (no X OAuth needed)
- NEW: POST /api/agent/submit — submit any URL for enrichment + Claude analysis
- NEW: POST /api/agent/query — filtered search across analyzed library
- Agent-provisioned users can connect X OAuth later from the dashboard
- Separate credit pool for agent submits (free: 5/mo, pro: 50/mo, scale: 200/mo)

2026-02-25: Updated llms.txt with accurate feature set
- Corrected integration options (Claude Code skill plugin, not MCP npm package)
- Added actual API endpoints and auth methods
- Updated pricing with annual options
- Added technical stack details
- Added drag-and-drop, re-analyze, export features

2026-02-19: Design overhaul, rate limiting, billing launch

---

# Quick Start for Agents

## Option 1: Agent API (any platform)
1. Onboard user: POST /api/agent/onboard with email + consent
2. Create a project: POST /api/projects with name, description, tech_stack
3. Submit URLs: POST /api/agent/submit with url (and optional project_ids)
4. Query results: POST /api/agent/query with filters
5. User can later connect X OAuth at bkmrkapp.com for bookmark sync

## Option 2: Claude Code Skill
1. Direct user to https://bkmrkapp.com to sign up with X
2. Install plugin: /plugin marketplace add bonesvinyl/bkmrk-plugin
3. Use /bkmrk skill to query their bookmark library
4. Help user capture and act on bookmarks!

Questions? support@bkmrkapp.com