@prmichaelsen/reddit-mcp 0.1.0

package/agent/tasks/milestone-1-foundation-listings-mvp/task-1-project-scaffolding.md

@@ -0,0 +1,75 @@
+# Task 1: Project Scaffolding
+
+**Milestone**: [M1 - Foundation + Listings MVP](../../milestones/milestone-1-foundation-listings-mvp.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: None
+**Status**: Not Started
+
+---
+
+## Objective
+
+Set up the project directory structure, package.json, TypeScript config, build system, test config, and install all dependencies. Following the youtube-mcp pattern.
+
+---
+
+## Context
+
+This task creates the foundation that all subsequent development builds upon. The structure follows the youtube-mcp reference project pattern — ESM TypeScript with esbuild bundling, Jest for tests, and MCP SDK for the server.
+
+---
+
+## Steps
+
+### 1. Create package.json
+- Name: `@prmichaelsen/reddit-mcp`
+- Type: `module` (ESM)
+- Exports: `.` → `dist/server.js`, `./factory` → `dist/factory.js`
+- Scripts: build, dev, test, typecheck
+- Dependencies: `@modelcontextprotocol/sdk`, `zod`
+- Dev deps: `typescript`, `jest`, `ts-jest`, `esbuild`, `tsx`
+
+### 2. Create tsconfig.json
+- Target: ES2022, Module: Node16
+- Strict mode, declaration generation, source maps
+- Include src/, exclude node_modules, dist, tests
+
+### 3. Create esbuild.build.js
+- Entry points: src/index.ts, src/server.ts, src/factory.ts
+- Bundle: true, target: node20, format: esm
+- Generate .d.ts via tsc
+
+### 4. Create jest.config.js
+- Preset: ts-jest/presets/default-esm
+- Coverage threshold: 70%
+- Test pattern: tests/**/*.test.ts
+
+### 5. Create directory structure
+```
+src/auth/, src/client/, src/tools/, src/transport/, src/types/
+tests/unit/, tests/fixtures/, tests/helpers/
+```
+
+### 6. Create .env.example
+Document all required environment variables.
+
+### 7. Create .gitignore
+Add dist/, node_modules/, .env*, .tokens/, coverage/
+
+### 8. Install dependencies
+Run `npm install`
+
+---
+
+## Verification
+
+- [ ] `npm install` completes without errors
+- [ ] `npm run build` completes without errors
+- [ ] `npm run typecheck` passes
+- [ ] Directory structure matches specification
+- [ ] package.json has correct exports configuration
+
+---
+
+**Next Task**: [Task 2: Reddit OAuth 2.0](task-2-reddit-oauth.md)

package/agent/tasks/milestone-1-foundation-listings-mvp/task-2-reddit-oauth.md

@@ -0,0 +1,71 @@
+# Task 2: Reddit OAuth 2.0
+
+**Milestone**: [M1 - Foundation + Listings MVP](../../milestones/milestone-1-foundation-listings-mvp.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Task 1
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement Reddit OAuth 2.0 authentication with authorization code flow, token storage, and automatic token refresh.
+
+---
+
+## Context
+
+Reddit requires OAuth 2.0 for API access. Unlike YouTube which uses the googleapis library, Reddit has no official Node.js SDK — we implement OAuth directly with fetch. The auth module must support both direct user auth (for stdio) and raw access token injection (for mcp-auth factory pattern).
+
+---
+
+## Steps
+
+### 1. Create RedditAuth class (src/auth/oauth.ts)
+
+```typescript
+export class RedditAuth {
+  constructor(config: RedditAuthConfig)
+  getAuthUrl(scopes: string[]): string
+  exchangeCode(code: string): Promise<TokenData>
+  getAccessToken(): Promise<string>  // auto-refresh
+  hasStoredCredentials(): boolean
+}
+```
+
+Key behaviors:
+- Authorization URL generation with state parameter
+- Code exchange via POST to `https://www.reddit.com/api/v1/access_token`
+- Basic auth header with client_id:client_secret
+- Token refresh 5 minutes before expiry
+- File-based token storage with 0o600 permissions
+
+### 2. Create factory function
+
+```typescript
+export function createAuthFromEnv(): RedditAuth
+```
+Reads REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_REDIRECT_URI, REDDIT_USER_AGENT, TOKEN_STORAGE_PATH from environment.
+
+### 3. Reddit-specific OAuth details
+- Token endpoint: `https://www.reddit.com/api/v1/access_token`
+- Authorization endpoint: `https://www.reddit.com/api/v1/authorize`
+- Use `duration=permanent` for refresh tokens
+- Basic auth header (not body params) for client credentials
+- Reddit returns `expires_in` in seconds (typically 3600)
+
+---
+
+## Verification
+
+- [ ] RedditAuth class created with all methods
+- [ ] Token exchange works with Reddit OAuth endpoint
+- [ ] Token refresh works before expiry
+- [ ] Tokens stored securely (0o600 file permissions)
+- [ ] Factory function reads from environment correctly
+- [ ] Unit tests cover auth flow, refresh, and error cases
+
+---
+
+**Next Task**: [Task 3: Reddit API Client Wrapper](task-3-reddit-api-client.md)

package/agent/tasks/milestone-1-foundation-listings-mvp/task-3-reddit-api-client.md

@@ -0,0 +1,71 @@
+# Task 3: Reddit API Client Wrapper
+
+**Milestone**: [M1 - Foundation + Listings MVP](../../milestones/milestone-1-foundation-listings-mvp.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Task 2
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a Reddit API HTTP client wrapper with proper headers, rate limit handling, error mapping, and retry logic.
+
+---
+
+## Context
+
+Reddit has no official Node.js SDK, so we build a thin HTTP client using fetch. The client must handle Reddit-specific concerns: User-Agent header, OAuth bearer tokens, rate limit headers, and Reddit's JSON response format.
+
+---
+
+## Steps
+
+### 1. Create RedditClient class (src/client/reddit.ts)
+
+```typescript
+export class RedditClient {
+  constructor(auth: RedditAuth | string)  // auth object or raw access token
+  async get<T>(path: string, params?: Record<string, string>): Promise<T>
+  async post<T>(path: string, body: Record<string, string>): Promise<T>
+}
+```
+
+### 2. Base URL and Headers
+- Base URL: `https://oauth.reddit.com`
+- Headers: `Authorization: Bearer {token}`, `User-Agent: {configured agent}`
+- Accept: `application/json`
+
+### 3. Rate Limit Handling
+- Parse response headers: `X-Ratelimit-Remaining`, `X-Ratelimit-Reset`, `X-Ratelimit-Used`
+- If remaining < 5, delay before next request
+- On 429 response, wait for reset period
+
+### 4. Error Mapping
+- 400 → RedditApiError (bad request, include Reddit's error message)
+- 401 → RedditApiError (unauthorized, token expired)
+- 403 → RedditApiError (forbidden, scope missing or banned)
+- 404 → RedditApiError (not found)
+- 429 → RedditApiError (rate limited, include reset time)
+- 5xx → RedditApiError (server error, retryable)
+
+### 5. Retry Logic
+- Max 3 retries for 5xx errors and network failures
+- Exponential backoff: 1s, 2s, 4s
+- No retry for 4xx errors (except 429)
+
+---
+
+## Verification
+
+- [ ] RedditClient created with get/post methods
+- [ ] Proper Authorization and User-Agent headers sent
+- [ ] Rate limit headers parsed and respected
+- [ ] Error mapping works for all status codes
+- [ ] Retry logic works for 5xx errors
+- [ ] Unit tests cover client, errors, and retry
+
+---
+
+**Next Task**: [Task 4: Listing Tools](task-4-listing-tools.md)

package/agent/tasks/milestone-1-foundation-listings-mvp/task-4-listing-tools.md

@@ -0,0 +1,65 @@
+# Task 4: Listing Tools
+
+**Milestone**: [M1 - Foundation + Listings MVP](../../milestones/milestone-1-foundation-listings-mvp.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Task 3
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement the core listing tools that allow browsing Reddit — hot, new, top, rising, controversial, best posts, comment threads, duplicates, and info lookup.
+
+---
+
+## Steps
+
+### 1. Create MCP server factory (src/server.ts)
+
+```typescript
+export function createServer(auth?: RedditAuth): McpServer
+export function createServerWithToken(accessToken: string): McpServer
+```
+
+### 2. Create src/tools/listings.ts
+
+Register 9 tools:
+
+| Tool | Endpoint | Parameters |
+|------|----------|------------|
+| `reddit_listings_best` | GET /best | limit, after, before |
+| `reddit_listings_hot` | GET /r/{subreddit}/hot or /hot | subreddit?, limit, after, before |
+| `reddit_listings_new` | GET /r/{subreddit}/new or /new | subreddit?, limit, after, before |
+| `reddit_listings_rising` | GET /r/{subreddit}/rising or /rising | subreddit?, limit, after, before |
+| `reddit_listings_top` | GET /r/{subreddit}/top or /top | subreddit?, t (hour/day/week/month/year/all), limit, after, before |
+| `reddit_listings_controversial` | GET /r/{subreddit}/controversial | subreddit?, t, limit, after, before |
+| `reddit_comments_thread` | GET /r/{subreddit}/comments/{article} | subreddit, article, sort?, limit?, depth? |
+| `reddit_duplicates` | GET /duplicates/{article} | article, limit, after, before |
+| `reddit_info` | GET /api/info | id (fullname, e.g. t3_abc123) |
+
+### 3. Tool pattern
+Each tool:
+- Define zod schema for input validation
+- Register via `server.tool(name, description, schema, handler)`
+- Include scope requirement in description
+- Return JSON-serialized API response
+
+### 4. Create src/index.ts
+Transport selector: parse --transport flag, default to stdio.
+
+---
+
+## Verification
+
+- [ ] All 9 listing tools registered on MCP server
+- [ ] Each tool validates input with zod
+- [ ] Tools correctly build Reddit API URLs
+- [ ] Subreddit parameter is optional for frontpage listings
+- [ ] Comment thread tool supports sort and depth
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 5: Search Tools](task-5-search-tools.md)

package/agent/tasks/milestone-1-foundation-listings-mvp/task-5-search-tools.md

@@ -0,0 +1,43 @@
+# Task 5: Search Tools
+
+**Milestone**: [M1 - Foundation + Listings MVP](../../milestones/milestone-1-foundation-listings-mvp.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 1.5 hours
+**Dependencies**: Task 4
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement search tools for searching across all of Reddit and within specific subreddits.
+
+---
+
+## Steps
+
+### 1. Create src/tools/search.ts
+
+Register 2 tools:
+
+| Tool | Endpoint | Parameters |
+|------|----------|------------|
+| `reddit_search` | GET /search | q, sort (relevance/hot/top/new/comments), t (time filter), type (link/sr/user), limit, after, before |
+| `reddit_search_subreddit` | GET /r/{subreddit}/search | subreddit, q, restrict_sr=true, sort, t, limit, after, before |
+
+### 2. Register in server.ts
+Add search tool registration to the MCP server factory.
+
+---
+
+## Verification
+
+- [ ] Both search tools registered
+- [ ] Query parameter (q) is required
+- [ ] Sort and time filter parameters validated
+- [ ] restrict_sr automatically set for subreddit search
+- [ ] Unit tests for search tools
+
+---
+
+**Next Task**: [Task 6: Testing & Verification](task-6-testing-verification.md)

package/agent/tasks/milestone-1-foundation-listings-mvp/task-6-testing-verification.md

@@ -0,0 +1,49 @@
+# Task 6: Testing & Verification
+
+**Milestone**: [M1 - Foundation + Listings MVP](../../milestones/milestone-1-foundation-listings-mvp.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Tasks 1-5
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create comprehensive unit tests, mock client, response fixtures, and verify MVP end-to-end.
+
+---
+
+## Steps
+
+### 1. Create test helpers (tests/helpers/mock-client.ts)
+Mock RedditClient that returns fixture data without hitting the API.
+
+### 2. Create response fixtures (tests/fixtures/reddit-responses.ts)
+Sample Reddit API responses for listings, search, comments, errors.
+
+### 3. Create unit test suites
+- tests/unit/auth.test.ts — OAuth flow, token refresh, error cases
+- tests/unit/client.test.ts — HTTP client, error mapping, retry, rate limits
+- tests/unit/server.test.ts — Server creation, tool registration count
+- tests/unit/listings.test.ts — All listing tool definitions and handlers
+- tests/unit/search.test.ts — Search tool definitions and handlers
+
+### 4. Verify end-to-end
+- Server creates successfully
+- All 11 tools registered
+- stdio transport starts without errors
+
+---
+
+## Verification
+
+- [ ] All test suites pass
+- [ ] Coverage >= 70% (branches, functions, lines, statements)
+- [ ] Mock client properly simulates Reddit API responses
+- [ ] Error cases tested (401, 403, 429, 5xx)
+- [ ] `npm test` runs cleanly
+
+---
+
+**Next Task**: [Task 7: Post Tools](../milestone-2-content-interaction/task-7-post-tools.md)

package/agent/tasks/milestone-2-content-interaction/task-7-post-tools.md

@@ -0,0 +1,56 @@
+# Task 7: Post Tools
+
+**Milestone**: [M2 - Content Interaction](../../milestones/milestone-2-content-interaction.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for creating, editing, deleting, and managing posts — including hide/unhide, NSFW marking, and spoiler marking.
+
+---
+
+## Steps
+
+### 1. Create src/tools/posts.ts
+
+Register 9 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_submit` | POST /api/submit | sr, title, kind (self/link), text/url, nsfw?, spoiler?, flair_id? | submit |
+| `reddit_edit` | POST /api/editusertext | thing_id, text | edit |
+| `reddit_delete` | POST /api/del | id | edit |
+| `reddit_hide` | POST /api/hide | id | report |
+| `reddit_unhide` | POST /api/unhide | id | report |
+| `reddit_mark_nsfw` | POST /api/marknsfw | id | modposts |
+| `reddit_unmark_nsfw` | POST /api/unmarknsfw | id | modposts |
+| `reddit_spoiler` | POST /api/spoiler | id | modposts |
+| `reddit_unspoiler` | POST /api/unspoiler | id | modposts |
+
+### 2. Submit tool details
+- Support both self-posts (text) and link posts (url)
+- `kind` parameter: "self" or "link"
+- Optional flair_id for post flair
+- Return the created post's fullname
+
+### 3. Register in server.ts
+
+---
+
+## Verification
+
+- [ ] `reddit_submit` creates both self and link posts
+- [ ] `reddit_edit` updates post/comment text
+- [ ] `reddit_delete` removes content
+- [ ] Hide/unhide, NSFW, spoiler toggles work
+- [ ] All tools validate required parameters
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 8: Comment Tools](task-8-comment-tools.md)

package/agent/tasks/milestone-2-content-interaction/task-8-comment-tools.md

@@ -0,0 +1,49 @@
+# Task 8: Comment Tools
+
+**Milestone**: [M2 - Content Interaction](../../milestones/milestone-2-content-interaction.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 7
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for posting comments/replies and loading collapsed comment threads.
+
+---
+
+## Steps
+
+### 1. Create src/tools/comments.ts
+
+Register 2 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_comment` | POST /api/comment | parent (fullname t1_ or t3_), text | submit |
+| `reddit_more_children` | GET /api/morechildren | link_id, children (comma-separated IDs), sort? | read |
+
+### 2. Comment tool details
+- `parent` is a fullname: t3_ for posts, t1_ for comments (replies)
+- `text` is markdown-formatted
+- Returns the created comment data
+
+### 3. More children details
+- Used to expand "load more comments" stubs
+- `children` is a comma-separated list of comment IDs from the "more" object
+- `link_id` is the parent post's fullname
+
+---
+
+## Verification
+
+- [ ] `reddit_comment` posts top-level comments (parent=t3_)
+- [ ] `reddit_comment` posts replies (parent=t1_)
+- [ ] `reddit_more_children` loads expanded comments
+- [ ] Unit tests cover both tools
+
+---
+
+**Next Task**: [Task 9: Vote, Save & Report Tools](task-9-vote-save-report-tools.md)

package/agent/tasks/milestone-2-content-interaction/task-9-vote-save-report-tools.md

@@ -0,0 +1,50 @@
+# Task 9: Vote, Save & Report Tools
+
+**Milestone**: [M2 - Content Interaction](../../milestones/milestone-2-content-interaction.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 1.5 hours
+**Dependencies**: Task 7
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement voting, save/unsave, and report tools.
+
+---
+
+## Steps
+
+### 1. Create src/tools/voting.ts
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_vote` | POST /api/vote | id (fullname), dir (1=up, 0=unvote, -1=down) | vote |
+
+### 2. Create src/tools/save.ts
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_save` | POST /api/save | id, category? | save |
+| `reddit_unsave` | POST /api/unsave | id | save |
+
+### 3. Create src/tools/report.ts
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_report` | POST /api/report | thing_id, reason, other_reason? | report |
+
+---
+
+## Verification
+
+- [ ] `reddit_vote` handles upvote (1), downvote (-1), unvote (0)
+- [ ] `reddit_save` and `reddit_unsave` toggle save state
+- [ ] `reddit_report` sends report with reason
+- [ ] All parameters validated with zod
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 10: Account Tools](../milestone-3-users-and-messaging/task-10-account-tools.md)

package/agent/tasks/milestone-3-users-and-messaging/task-10-account-tools.md

@@ -0,0 +1,44 @@
+# Task 10: Account Tools
+
+**Milestone**: [M3 - Users & Messaging](../../milestones/milestone-3-users-and-messaging.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for viewing and managing the authenticated user's account — info, karma, preferences, trophies, friends, and blocked users.
+
+---
+
+## Steps
+
+### 1. Create src/tools/account.ts
+
+Register 7 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_me` | GET /api/v1/me | — | identity |
+| `reddit_me_karma` | GET /api/v1/me/karma | — | mysubreddits |
+| `reddit_me_prefs` | GET /api/v1/me/prefs | — | identity |
+| `reddit_me_prefs_update` | PATCH /api/v1/me/prefs | prefs (JSON object) | account |
+| `reddit_me_trophies` | GET /api/v1/me/trophies | — | identity |
+| `reddit_me_friends` | GET /prefs/friends | — | mysubreddits |
+| `reddit_me_blocked` | GET /prefs/blocked | — | mysubreddits |
+
+---
+
+## Verification
+
+- [ ] `reddit_me` returns user profile data
+- [ ] `reddit_me_karma` returns subreddit karma breakdown
+- [ ] `reddit_me_prefs_update` accepts and applies preference changes
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 11: User Profile Tools](task-11-user-profile-tools.md)

package/agent/tasks/milestone-3-users-and-messaging/task-11-user-profile-tools.md

@@ -0,0 +1,50 @@
+# Task 11: User Profile Tools
+
+**Milestone**: [M3 - Users & Messaging](../../milestones/milestone-3-users-and-messaging.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2.5 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for viewing other users' profiles, post/comment history, saved items, votes, trophies, and blocking users.
+
+---
+
+## Steps
+
+### 1. Create src/tools/users.ts
+
+Register 9 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_user_about` | GET /user/{username}/about | username | read |
+| `reddit_user_overview` | GET /user/{username}/overview | username, sort?, t?, limit, after, before | history |
+| `reddit_user_submitted` | GET /user/{username}/submitted | username, sort?, t?, limit, after, before | history |
+| `reddit_user_comments` | GET /user/{username}/comments | username, sort?, t?, limit, after, before | history |
+| `reddit_user_saved` | GET /user/{username}/saved | username, sort?, t?, limit, after, before | history |
+| `reddit_user_upvoted` | GET /user/{username}/upvoted | username, sort?, t?, limit, after, before | history |
+| `reddit_user_downvoted` | GET /user/{username}/downvoted | username, sort?, t?, limit, after, before | history |
+| `reddit_user_trophies` | GET /api/v1/user/{username}/trophies | username | read |
+| `reddit_block_user` | POST /api/block_user | name | account |
+
+### 2. Listing parameters pattern
+All user listing endpoints share: sort (hot/new/top/controversial), t (time filter), limit, after, before. Create a shared zod schema for these.
+
+---
+
+## Verification
+
+- [ ] `reddit_user_about` returns public profile info
+- [ ] User listing tools return paginated results
+- [ ] `reddit_block_user` blocks a user
+- [ ] Shared listing parameters work correctly
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 12: Private Message Tools](task-12-private-message-tools.md)

package/agent/tasks/milestone-3-users-and-messaging/task-12-private-message-tools.md

@@ -0,0 +1,50 @@
+# Task 12: Private Message Tools
+
+**Milestone**: [M3 - Users & Messaging](../../milestones/milestone-3-users-and-messaging.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for reading, sending, and managing private messages.
+
+---
+
+## Steps
+
+### 1. Create src/tools/messages.ts
+
+Register 7 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_inbox` | GET /message/inbox | limit, after, before | privatemessages |
+| `reddit_unread` | GET /message/unread | limit, after, before | privatemessages |
+| `reddit_sent` | GET /message/sent | limit, after, before | privatemessages |
+| `reddit_compose` | POST /api/compose | to, subject, text | privatemessages |
+| `reddit_read_message` | POST /api/read_message | id | privatemessages |
+| `reddit_unread_message` | POST /api/unread_message | id | privatemessages |
+| `reddit_del_msg` | POST /api/del_msg | id | privatemessages |
+
+### 2. Compose details
+- `to` is a username (without /u/ prefix)
+- `subject` is required
+- `text` is markdown-formatted body
+
+---
+
+## Verification
+
+- [ ] `reddit_inbox` returns inbox messages
+- [ ] `reddit_compose` sends a private message
+- [ ] `reddit_read_message` marks message as read
+- [ ] `reddit_del_msg` deletes a message
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 13: Subreddit Tools](../milestone-4-subreddits-and-flair/task-13-subreddit-tools.md)