- Docker configuration (Dockerfile, docker-compose.prod.yml)
- Caddy reverse proxy with HSTS, CSP, wildcard SSL
- Deployment scripts (deploy.sh, setup-production.sh, backup.sh)
- DID key generation script
- OAuth callback with XSS protection
- Environment template (.env.prod.example)

Align social.coves.community.list endpoint to lexicon specification
with comprehensive testing and atProto compliance.

**Summary:**
- ✅ Lexicon-compliant parameter handling
- ✅ atProto-standard pagination (cursor-based)
- ✅ Input validation for all parameters
- ✅ Performance optimization (removed COUNT query)
- ✅ Comprehensive test coverage (8 new test cases)
- ✅ All tests passing

**Changes:**
- Add visibility parameter to lexicon
- Implement sort enum (popular/active/new/alphabetical)
- Fix cursor type (string vs int)
- Remove undocumented "total" field
- Add input validation for visibility and sort
- Update test suite with comprehensive coverage

Ready for alpha deployment 🚀

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add comprehensive test coverage for social.coves.community.list
endpoint with all parameter combinations.

**New Test Cases:**
- List with sort=popular (default)
- List with sort=active
- List with sort=new
- List with sort=alphabetical (validates actual ordering)
- List with invalid sort value (expects 400)
- List with visibility filter
- List with default sort (no parameter)
- List with limit bounds validation

**Test Cleanup:**
- Remove deprecated "total" field from response structs
- Add "cursor" field to all list response structs
- Update repository tests for new List() signature

All tests passing ✅

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Align social.coves.community.list handler to lexicon specification
following atProto standards.

**Changes:**
- Add visibility parameter (public/unlisted/private) to lexicon
- Implement sort enum mapping (popular→subscriber_count,
active→post_count, new→created_at, alphabetical→name)
- Add input validation for sort and visibility parameters
- Enforce limit bounds (1-100, default 50)
- Update ListCommunitiesRequest struct with new parameters
- Remove deprecated hostedBy parameter

**atProto Compliance:**
- Use string cursor type (not int)
- Remove undocumented "total" field (follows Bluesky patterns)
- Eliminate COUNT query for better performance
- Return empty cursor when pagination complete

**Performance:**
- Single query instead of COUNT + SELECT
- Proper cursor-based pagination

**Code Quality:**
- Fix magic number in GetDisplayHandle (11 → len(".community."))
- Add TODO comments for future category/language filters

Addresses lexicon contract violations and follows atProto design
patterns from bluesky-social/atproto#4245.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add bd (beads) issue tracking section to project instructions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add comprehensive documentation for AI agents on using bd (beads)
for issue tracking, including workflow, priorities, and best practices
for managing planning documents in history/ directory.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Create starter issues for tracking Coves development:
- Complete post creation and moderation features [P1]
- Implement aggregator feed federation [P1]
- Add comprehensive API documentation [P2, blocked by features]

Issues tracked in .beads/issues.jsonl with dependency graph.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Set up Beads dependency-aware issue tracker to provide persistent
memory and task tracking across agent sessions. Issues will use
prefix 'Coves-1, Coves-2, etc.' and sync via JSONL in git.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update project guidelines and best practices.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add complete Docker configuration for containerized deployment.

Files added:
- Dockerfile: Multi-stage Python 3.11 image with cron scheduler
- docker-compose.yml: Simple deployment configuration
- docker-entrypoint.sh: Startup script with validation
- .dockerignore: Build optimization

Features:
- Automated cron scheduling (daily at 1 PM UTC)
- Health checks (verifies cron is running)
- Log rotation (10MB max, 3 files)
- Auto-restart on failure
- Environment-based configuration
- Single command deployment: docker compose up -d

The container runs cron internally and streams logs to stdout,
making it production-ready and easy to monitor.

Updated README with comprehensive Docker deployment documentation
including quick start, configuration, testing, and production
deployment best practices.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add Kagi-specific automated registration script and update README.

Changes:
- Move setup-kagi-aggregator.sh to kagi-news/scripts/setup.sh
- Add comprehensive Registration section to README
- Document automated vs manual setup options
- Explain registration workflow and requirements
- Update project structure to reflect new scripts

The setup script automates all 4 registration steps:
1. PDS account creation
2. .well-known file generation
3. Coves registration via XRPC
4. Service declaration creation

This makes the Kagi aggregator self-contained and ready to be
split into its own repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add comprehensive setup scripts and documentation for aggregator registration.

Scripts:
- 1-create-pds-account.sh: Create PDS account for aggregator
- 2-setup-wellknown.sh: Generate .well-known/atproto-did file
- 3-register-with-coves.sh: Register with Coves instance via XRPC
- 4-create-service-declaration.sh: Create service declaration record

Documentation:
- Detailed README with step-by-step instructions
- Troubleshooting guide
- Configuration examples (nginx/Apache)
- Security best practices

These scripts automate the 4-step process of:
1. Creating a DID for the aggregator
2. Proving domain ownership
3. Registering with Coves
4. Publishing service metadata

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Implement social.coves.aggregator.register endpoint for aggregator registration.

Features:
- Lexicon schema for registration request/response
- Domain verification via .well-known/atproto-did
- DID resolution and validation
- User table insertion for aggregators
- Comprehensive integration tests

The endpoint allows aggregators to register with a Coves instance by:
1. Providing their DID and domain
2. Verifying domain ownership via .well-known file
3. Getting indexed into the users table

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Implements mandatory bidirectional did:web verification matching Bluesky's
security model. This prevents domain impersonation attacks by requiring
DID documents to claim the handle domain in their alsoKnownAs field.

Security Improvements:
- MANDATORY bidirectional verification (hard-fail, not soft-fail)
- Verifies domain matching (handle domain == hostedBy domain)
- Fetches DID document from https://domain/.well-known/did.json
- Verifies DID document ID matches claimed DID
- NEW: Verifies DID document claims handle in alsoKnownAs field
- Rejects communities that fail verification (was: log warning only)
- Cache TTL increased from 1h to 24h (matches Bluesky recommendations)

Implementation:
- Location: internal/atproto/jetstream/community_consumer.go
- Verification runs in AppView Jetstream consumer (not creation API)
- Impact: Controls AppView indexing and federation trust
- Performance: Bounded LRU cache (1000 entries), rate limiting (10 req/s)

Attack Prevention:
✓ Domain impersonation (can't claim did:web:nintendo.com without owning it)
✓ DNS hijacking (bidirectional check fails even with DNS control)
✓ Reputation hijacking (can't point your domain to someone else's DID)
✓ AppView pollution (only legitimate communities indexed)
✓ Federation trust (other instances can verify instance identity)

Tests:
- Updated existing tests to handle mandatory verification
- Added comprehensive bidirectional verification tests with mock HTTP server
- All tests passing ✅

Documentation:
- PRD_BACKLOG.md: Marked did:web verification as COMPLETE
- PRD_ALPHA_GO_LIVE.md: Added production deployment requirements
- Clarified architecture: AppView (coves.social) + PDS (coves.me)
- Added PDS deployment checklist (separate domain required)
- Updated production environment checklist
- Added Jetstream configuration (Bluesky production firehose)

Production Requirements:
- Deploy .well-known/did.json to coves.social with alsoKnownAs field
- Set SKIP_DID_WEB_VERIFICATION=false (production)
- PDS must be on separate domain (coves.me, not coves.social)
- Jetstream connects to wss://jetstream2.us-east.bsky.network/subscribe

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Added comprehensive PRD for implementing Lemmy-style federation in Beta:

**Overview:**
- Enable users on any Coves instance to post to communities on other instances
- Maintain community ownership (posts live in community repos)
- Use atProto-native service authentication pattern

**Key Features:**
- Cross-instance posting: user@instance-a posts to !community@instance-b
- atProto service auth via com.atproto.server.getServiceAuth
- Community moderation control maintained
- Allowlist-based federation (manual for Beta)

**Technical Approach:**
- Service-to-service JWT authentication
- Community credentials delegation to user's instance
- Proper record ownership in community repos
- Security: signature verification, rate limiting, moderation

**Deferred to Future:**
- Automatic instance discovery (Beta uses manual allowlist)
- Cross-instance moderation delegation
- Content mirroring/replication
- User migration between instances

**Target:** Beta Release

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Updated PRD to show all 6 E2E test suites are complete:

**Status Change:**
- From: "Pre-Alpha"
- To: "Pre-Alpha → **E2E Testing Complete** 🎉"

**Updates:**
- Added major progress update section at top
- Marked all E2E test sections (lines 211-312) as ✅ COMPLETE
- Added actual implementation times and test file locations
- Updated timeline estimate: 65-80 hours → 50-65 hours remaining
- Updated success criteria to show E2E test milestones achieved
- Updated next steps to show E2E tests moved to completed status
- Added celebration message for major milestone

**Test Suite Completion:**
✅ Full User Journey (40 min)
✅ Blob Upload (35 min)
✅ Multi-Community Timeline (30 min)
✅ Concurrent Scenarios (45 min - with race detection)
✅ Rate Limiting (25 min)
✅ Error Recovery (30 min)

Total: ~3 hours of E2E test implementation

**Next Phase:** P0 blockers (JWT verification, DPoP fix, did:web verification)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Implemented all 6 critical E2E test suites required for Alpha launch:

1. **User Journey E2E Test** (user_journey_e2e_test.go)
- Tests complete user flow: signup → create community → post → comment → vote
- Uses real PDS accounts and Jetstream WebSocket subscription
- Validates full atProto write-forward architecture
- Fixed silent fallback: now fails by default if Jetstream times out
- Use ALLOW_SIMULATION_FALLBACK=true env var to enable fallback in CI

2. **Blob Upload E2E Test** (blob_upload_e2e_test.go)
- Tests image upload to PDS via com.atproto.repo.uploadBlob
- Fixed to use REAL PDS credentials instead of fake tokens
- Tests PNG, JPEG, and WebP (MIME only) format validation
- Validates blob references in post records
- Tests multiple images and external embed thumbnails

3. **Concurrent Scenarios Test** (concurrent_scenarios_test.go)
- Tests race conditions with 20-30 simultaneous users
- Added database record verification to detect duplicates/lost records
- Uses COUNT(*) and COUNT(DISTINCT) queries to catch race conditions
- Tests concurrent: voting, mixed voting, commenting, subscriptions

4. **Multi-Community Timeline Test** (timeline_test.go)
- Tests feed aggregation across multiple communities
- Validates sorting (hot, new, top) and pagination
- Tests cross-community post interleaving

5. **Rate Limiting E2E Test** (ratelimit_e2e_test.go)
- Tests 100 req/min general limit
- Tests 20 req/min comment endpoint limit
- Tests 10 posts/hour aggregator limit
- Removed fake summary test, converted to documentation

6. **Error Recovery Test** (error_recovery_test.go)
- Tests Jetstream connection retry logic
- Tests PDS unavailability handling
- Tests malformed event handling
- Renamed reconnection test to be honest about scope
- Improved SQL cleanup patterns to be more specific

**Architecture Validated:**
- atProto write-forward: writes to PDS, AppView indexes from Jetstream
- Real Docker infrastructure: PDS (port 3001), Jetstream (6008), PostgreSQL (5434)
- Graceful degradation: tests skip if infrastructure unavailable (CI-friendly)

**Security Tested:**
- Input validation at handler level
- Parameterized queries (no SQL injection)
- Authorization checks before operations
- Rate limiting enforcement

**Time Saved:** ~7-12 hours through parallel sub-agent implementation
**Test Quality:** Enhanced with database verification to catch race conditions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add comprehensive Alpha launch readiness documentation and production
JWT verification testing infrastructure.

**Alpha Go-Live PRD** (docs/PRD_ALPHA_GO_LIVE.md):
- Track remaining work for alpha launch with real users
- P0 blockers: DPoP architecture fix, JWT verification (2 items)
- ✅ Validated handle resolution already implemented
- ✅ Validated comment_count reconciliation already implemented
- P1 infrastructure: Monitoring, logging, backups, load testing
- E2E testing recommendations (7 critical gaps identified)
- Timeline: 65-80 hours (~2-3 weeks)
- Go/no-go decision criteria and risk assessment

**JWT Verification Test** (tests/integration/jwt_verification_test.go):
- E2E test for JWT signature verification with real PDS
- Tests JWT parsing, JWKS fetching, and auth middleware
- Validates AUTH_SKIP_VERIFY=false production mode
- Handles both dev PDS (symmetric) and production PDS (JWKS)
- Tests tampered token rejection

Changes support alpha launch planning and production security validation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Fixes two backlog issues:
1. Post comment_count reconciliation - Added tests proving it works
2. Handle resolution for block/unblock endpoints - Full implementation

Changes include:
- 15 new integration tests (all passing)
- Handle resolution with proper error handling (400/404/500)
- Updated documentation in PRD_BACKLOG.md
- Code formatting compliance with gofumpt

Auto-formatting comment blocks to comply with gofumpt standards.
No functional changes.

Mark the following backlog items as complete:
1. Post comment_count reconciliation (2025-11-16)
- Added comprehensive test coverage (4 test cases)
- Updated misleading FIXME comment to accurate documentation
- Verified existing reconciliation logic works correctly

2. Handle resolution for block endpoints (2025-11-16)
- Phase 3: Block/unblock endpoints now accept handles
- Added 11 test cases covering all identifier formats
- Proper error handling (400 for validation, 404 for not found)
- Phase 1 (post creation) was already complete

Both issues estimated at 2-3 hours each, completed with full test
coverage and documentation updates.

Update block and unblock handlers to accept at-identifiers (handles)
in addition to DIDs, resolving them via ResolveCommunityIdentifier().

Changes:
- Remove DID-only validation in HandleBlock and HandleUnblock
- Add ResolveCommunityIdentifier() call with proper error handling
- Map validation errors (malformed identifiers) to 400 Bad Request
- Map not-found errors to 404
- Map other errors to 500 Internal Server Error

Supported formats:
- DIDs: did:plc:xxx, did:web:xxx
- Canonical handles: gaming.community.coves.social
- @-prefixed handles: @gaming.community.coves.social
- Scoped format: !gaming@coves.social

Test coverage (11 test cases):
- Block with canonical handle
- Block with @-prefixed handle
- Block with scoped format
- Block with DID (backwards compatibility)
- Block with malformed identifiers (4 cases - returns 400)
- Block with invalid/nonexistent handle (returns 404)
- Unblock with handle
- Unblock with invalid handle

Addresses PR feedback: Validation errors now return 400 instead of 500

Fixes issue: Handle Resolution Missing
Affected: Post creation, blocking endpoints

Add comprehensive integration tests verifying that post comment_count
is correctly reconciled when comments arrive before their parent post
due to out-of-order Jetstream event delivery.

Test coverage:
- Single comment arrives before post - count reconciled to 1
- Multiple comments arrive before post - count reconciled correctly
- Mixed ordering (comments before and after post) - count accurate
- Idempotent post indexing preserves comment_count

Also update misleading FIXME comment in comment_consumer.go to accurate
NOTE explaining that reconciliation IS implemented in post_consumer.go
at lines 210-226.

Fixes issue: Post comment_count Never Reconciles
File: internal/atproto/jetstream/comment_consumer.go:362

Complete migration of comment namespace from social.coves.feed.comment
to social.coves.community.comment.

This migration aligns the comment system with the community-focused
architecture and ensures all comment records use the correct namespace.

Summary:
- ✅ Lexicon migrated to community/comment.json
- ✅ Database migration 018 applied successfully
- ✅ All backend code updated (consumer, service, validation)
- ✅ Server configuration updated for Jetstream
- ✅ All 22 integration tests passing
- ✅ Test scripts and data updated
- ✅ Documentation updated

Migration verified with:
- Unit tests: ✅ PASSING
- Integration tests: ✅ 22/22 PASSING
- Build: ✅ SUCCESS
- Database: ✅ Migration 018 applied

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update COMMENT_SYSTEM_IMPLEMENTATION.md to reflect the completed
migration from social.coves.feed.comment to
social.coves.community.comment.

Changes:
- Mark Phase 4 (Namespace Migration) as COMPLETED (2025-11-16)
- Update all namespace references throughout the document
- Add migration completion details and scope

Documentation now accurately reflects the current implementation
using the community.comment namespace for all comment records.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update all test comment generation scripts to use
social.coves.community.comment namespace in URI construction.

Scripts updated:
- generate_deep_thread.go: Creates nested comment threads
- generate_nba_comments.go: Generates NBA discussion comments
- generate_test_comments.go: Creates general test comments

All scripts now generate comment URIs with the correct namespace
pattern: at://did/social.coves.community.comment/rkey

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update all comment integration tests to use the new
social.coves.community.comment namespace.

Files updated:
- comment_consumer_test.go: 18 tests covering create/update/delete
- comment_query_test.go: 11 tests covering queries and pagination
- comment_vote_test.go: 6 tests covering voting on comments

All test data now uses the correct namespace for URI construction,
$type fields, and collection names. Tests verify that the new
namespace works correctly throughout the entire comment lifecycle.

All 22 integration tests passing ✅

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update Jetstream comment consumer configuration to subscribe to
social.coves.community.comment collection instead of
social.coves.feed.comment.

Changes:
- Update COMMENT_JETSTREAM_URL wantedCollections parameter
- Update log message to reflect new collection name

The consumer will now listen for CREATE/UPDATE/DELETE operations
on the community.comment collection from the Jetstream firehose.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update all backend code to use social.coves.community.comment
namespace instead of social.coves.feed.comment.

Changes:
- comment_consumer.go: Update collection constant and URI construction
- vote_consumer.go: Update comment collection matching for votes
- comment.go: Update lexicon reference in documentation
- comment_service.go: Update record type in buildCommentRecord
- view_models.go: Update lexicon references in comments
- lexicon.go: Update ValidateComment to use new namespace
- record_utils.go: Update example documentation

All URI construction now uses social.coves.community.comment
for new comment records and collection filtering in Jetstream
consumers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add migration 018 to update all comment URIs from
social.coves.feed.comment to social.coves.community.comment.

Migration updates:
- comments.uri (main comment URIs)
- comments.root_uri (when root is a comment)
- comments.parent_uri (when parent is a comment)

Includes rollback support via -- +goose Down section for safe
reversibility. Since we're pre-production, only the comments table
is updated (votes table not affected).

Migration file: 018_migrate_comment_namespace.sql

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Migrate comment record lexicon from social.coves.feed.comment to
social.coves.community.comment to align with community-focused
architecture.

Changes:
- Move lexicon from feed/comment.json to community/comment.json
- Update lexicon ID: social.coves.community.comment
- Update test data lexicons (3 files) to use new namespace

This is part of the broader namespace migration to organize all
community-related records under the community namespace.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add two new scripts for generating realistic test data:

- generate_deep_thread.go: Creates deeply nested comment threads (100 levels)
for testing threading logic, depth limits, and performance

- generate_nba_comments.go: Generates NBA-themed comments with realistic
basketball discussion content for UX testing and demos

Both scripts:
- Insert directly into PostgreSQL (bypassing Jetstream for speed)
- Create realistic comment trees with varied content
- Useful for stress testing, performance validation, and demos

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Remove deprecated 'version' field from docker-compose.dev.yml.
Docker Compose v2 ignores this field and it's no longer needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

- Add source_name field to Perspective model for better attribution
- Extract source name from HTML anchor tags in parser
- Display source name in rich text (e.g., "The Straits Times" vs generic "Source")
- Improve spacing in highlights, perspectives, and sources lists (double newlines)
- Better visual separation between list items

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Streamable and other providers return protocol-relative URLs (//cdn.example.com)
in their oEmbed thumbnail_url field. These fail when passed to the blob service
because http.NewRequest requires a full URL with scheme.

Fix:
- Add normalizeURL() helper to convert // → https://
- Apply to both oEmbed and OpenGraph thumbnail URLs
- Add comprehensive tests (6 test cases)

Example transformation:
//cdn-cf-east.streamable.com/image/abc.jpg
→ https://cdn-cf-east.streamable.com/image/abc.jpg

This ensures Streamable video thumbnails are properly downloaded and uploaded
as blobs, fixing missing thumbnails in video embeds.

Affects: All users posting Streamable/YouTube/Reddit links (not Kagi-specific)
Tested: Unit tests pass, build successful

Update Kagi News aggregator client for nested external embed structure,
add unfurling roadmap items, and include utility scripts for testing.

**Kagi News Aggregator Updates:**
- Update client to use nested "external" structure (social.coves.embed.external)
- Update tests for new embed format
- Update README with latest API requirements
- Fix E2E tests for lexicon schema changes

**PRD Backlog Additions:**
60 new lines documenting unfurling feature:
- URL metadata enrichment via oEmbed/OpenGraph
- Blob upload for thumbnails
- Cache strategy (24h TTL)
- Circuit breaker for provider failures
- Supported providers (Streamable, YouTube, Reddit, Kagi)

**.env.dev Updates:**
- Add unfurl service configuration
- Add blob upload settings
- Update PDS URLs for testing

**Development Scripts:**
- generate_test_comments.go: Generate test comment data
- post_streamable.py: Test Streamable unfurling E2E

**Summary:**
- Aggregator client: Updated for nested embed structure
- Documentation: Added unfurling feature to backlog
- Scripts: Testing utilities for development

All aggregator tests updated to match new lexicon schema.
Ready for deployment with backward-compatible migration path.

Add extensive test coverage for external embed thumb validation and blob
reference transformation in feed responses.

**Thumb Validation Tests** (post_thumb_validation_test.go):
7 test cases covering strict blob reference validation:
1. ❌ Reject thumb as URL string (must be blob ref)
2. ❌ Reject thumb missing $type field
3. ❌ Reject thumb missing ref field
4. ❌ Reject thumb missing mimeType field
5. ✅ Accept valid blob reference
6. ✅ Accept missing thumb (unfurl will handle)
7. Security: Prevents URL injection attacks via thumb field

**Feed Blob Transform Tests** (feed_test.go):
6 test cases for GetCommunityFeed blob URL transformation:
1. Transforms blob refs to PDS URLs
2. Preserves community PDSURL in PostView
3. Generates correct getBlob endpoint URLs
4. Handles posts without embeds
5. Handles posts without thumbs
6. End-to-end feed query validation

**Integration Test Updates:**
- Update post creation tests for content length validation
- Update post handler tests with proper context setup
- Update E2E tests for nested external embed structure
- Add helper for creating communities with PDS credentials
- Add createTestUser helper for unique test isolation

**Test Isolation:**
- Use unique DIDs per test (via t.Name() suffix)
- Prevent cross-test data contamination
- Proper cleanup with defer db.Close()

**Example Validation:**
```go
// ❌ This should fail validation:
"thumb": "https://example.com/thumb.jpg" // URL string

// ✅ This should pass validation:
"thumb": {
"$type": "blob",
"ref": {"$link": "bafyrei..."},
"mimeType": "image/jpeg",
"size": 52813
}
```

**Coverage:**
- Blob validation: 7 test cases
- Blob transformation: 6 test cases
- Feed integration: 99 added lines in feed_test.go
- Total: 13 new test scenarios

This ensures security (no URL injection), correctness (proper blob format),
and functionality (URLs work in API responses).

Update external embed lexicon to use proper nested structure with dedicated
external object, aligning with atproto conventions and enabling better validation.

**Schema Changes:**
1. Main object now requires "external" property (was flat structure)
2. Add dedicated "external" definition with link metadata
3. Update embedType known values:
- OLD: ["article", "image", "video-stream"]
- NEW: ["article", "image", "video", "website"]
- Removed "video-stream" (use "video" instead)
- Added "website" for generic pages

**Before (flat structure):**
```json
{
"$type": "social.coves.embed.external",
"uri": "https://example.com",
"title": "Example",
"thumb": {...}
}
```

**After (nested structure):**
```json
{
"$type": "social.coves.embed.external",
"external": {
"uri": "https://example.com",
"title": "Example",
"thumb": {...}
}
}
```

**Rationale:**
- Follows atproto pattern (app.bsky.embed.external uses same structure)
- Enables future extensibility (can add external-level metadata)
- Clearer separation between embed type and embedded content
- Better validation with required "external" property

**embedType Values:**
- "article": Blog posts, news articles (rich text content)
- "image": Image galleries, photos (visual content)
- "video": Video embeds from Streamable, YouTube, etc.
- "website": Generic web pages without specific type

This aligns our lexicon with atproto best practices and prepares for
potential federation with other atproto implementations.

Breaking change: Clients must update to use nested structure.

Transform blob references to direct PDS URLs in feed responses, enabling
clients to fetch thumbnails without complex blob resolution logic.

**Blob Transform Module:**
- TransformBlobRefsToURLs: Convert blob refs → PDS URLs in-place
- transformThumbToURL: Extract CID and build getBlob URL
- Handles external embeds only (social.coves.embed.external)
- Graceful handling of missing/malformed data

**Transform Logic:**
```go
// Before (blob ref in database):
"thumb": {
"$type": "blob",
"ref": {"$link": "bafyrei..."},
"mimeType": "image/jpeg",
"size": 52813
}

// After (URL string in API response):
"thumb": "http://pds.example.com/xrpc/com.atproto.sync.getBlob?did=did:plc:community&cid=bafyrei..."
```

**Repository Updates:**
- Add community_pds_url to all feed queries (feed_repo_base.go)
- Include PDSURL in PostView.Community for transformation
- Apply to: GetCommunityFeed, GetTimeline, GetDiscover

**Handler Updates:**
- Call TransformBlobRefsToURLs before returning posts
- Applies to: social.coves.feed.getCommunityFeed
- Applies to: social.coves.feed.getTimeline
- Applies to: social.coves.feed.getDiscover

**Comprehensive Tests** (13 test cases):
- Valid blob ref → URL transformation
- Missing thumb (no-op)
- Already-transformed URL (no-op)
- Nil post/community (no-op)
- Missing/empty PDS URL (no-op)
- Malformed blob refs (graceful)
- Non-external embed types (ignored)

**Why This Matters:**
Clients receive ready-to-use image URLs instead of blob references,
simplifying rendering and eliminating need for CID resolution logic.
Works seamlessly with federated communities (each has own PDS URL).

Fixes client-side rendering for external embeds with thumbnails.

Wire unfurl and blob services into the post creation pipeline, enabling
automatic enhancement of external embeds with rich metadata and thumbnails.

**Post Service Integration:**
- Add optional BlobService and UnfurlService dependencies
- Update constructor to accept blob/unfurl services (nil-safe)
- Add ThumbnailURL field to CreatePostRequest for client-provided URLs
- Add PDSURL to CommunityRef for blob URL transformation (internal only)

**Server Main Changes:**
- Initialize unfurl repository with PostgreSQL
- Initialize blob service with default PDS URL
- Initialize unfurl service with:
- 10s timeout for HTTP fetches
- 24h cache TTL
- CovesBot/1.0 user agent
- Pass blob and unfurl services to post service constructor

**Flow:**
```
Client POST → CreateHandler
↓
PostService.Create() [external embed detected]
↓ (if no thumb provided)
UnfurlService.UnfurlURL() [fetch oEmbed/OpenGraph]
↓ (cache miss)
HTTP fetch → oEmbed provider / HTML parser
↓ (thumbnail URL found)
BlobService.UploadBlobFromURL() [download & upload to PDS]
↓
com.atproto.repo.uploadBlob → PDS
↓ (returns BlobRef with CID)
Embed enriched with thumb blob → Write to PDS
```

**Interface Documentation:**
- Added comments explaining optional blob/unfurl service injection
- Unfurl service auto-enriches external embeds when provided
- Blob service uploads thumbnails from unfurled URLs

This is the core integration that enables the full unfurling feature.
The actual unfurl logic in posts/service.go will be implemented separately.

Implement blob upload service to fetch images from URLs and upload them to
PDS as atproto blobs, enabling proper thumbnail storage for external embeds.

**Service Features:**
- UploadBlobFromURL: Fetch image from URL → validate → upload to PDS
- UploadBlob: Upload raw binary data to PDS with authentication
- Size limit: 1MB per image (atproto recommendation)
- Supported MIME types: image/jpeg, image/png, image/webp
- MIME type normalization (image/jpg → image/jpeg)
- Timeout handling (10s for fetch, 30s for upload)

**Security & Validation:**
- Input validation (empty checks, nil guards)
- Size validation before network calls
- MIME type validation before reading data
- HTTP status code checking with sanitized error logs
- Proper error wrapping for debugging

**Federated Support:**
- Uses community's PDS URL when available
- Fallback to service default PDS
- Community authentication via PDSAccessToken

**Flow:**
1. Client posts external embed with URI (no thumb)
2. Unfurl service fetches metadata from oEmbed/OpenGraph
3. Blob service downloads thumbnail from metadata.thumbnailURL
4. Upload to community's PDS via com.atproto.repo.uploadBlob
5. Return BlobRef with CID for inclusion in post record

**BlobRef Type:**
```go
type BlobRef struct {
Type string `json:"$type"` // "blob"
Ref map[string]string `json:"ref"` // {"$link": "bafyrei..."}
MimeType string `json:"mimeType"` // "image/jpeg"
Size int `json:"size"` // bytes
}
```

This enables automatic thumbnail upload when users post links to
Streamable, YouTube, Reddit, Kagi Kite, or any URL with OpenGraph metadata.

Add PostgreSQL-backed cache for oEmbed and OpenGraph unfurl results to reduce
external API calls and improve performance.

**Database Layer:**
- Migration 017: Create unfurl_cache table with JSONB metadata storage
- Index on expires_at for efficient TTL-based cleanup
- Store provider, metadata, and thumbnail_url with expiration

**Repository Layer:**
- Repository interface with Get/Set operations
- PostgreSQL implementation with JSON marshaling
- Automatic TTL handling via PostgreSQL intervals
- Returns nil on cache miss (not an error)

**Error Types:**
- ErrNotFound: Cache miss or expired entry
- ErrInvalidURL: Invalid URL format
- ErrInvalidTTL: Non-positive TTL value

Design decisions:
- JSONB metadata column for flexible schema evolution
- Separate thumbnail_url for potential query optimization
- ON CONFLICT for upsert behavior (update on re-fetch)
- TTL-based expiration (default: 24 hours)

Part of URL unfurling feature to auto-populate external embeds with rich
metadata from supported providers (Streamable, YouTube, Reddit, Kagi, etc.).

Related: Circuit breaker pattern prevents cascading failures when providers
go down (already implemented in previous commits).

Update integration tests to reflect new validation order and circuit
breaker integration in unfurl service.

Changes in post_creation_test.go:
- Fix content length validation test expectations
- Update validation order: basic input before DID authentication
- Adjust test assertions to match new error flow

Changes in post_unfurl_test.go:
- Update Kagi provider test to expect circuit breaker wrapper
- Fix provider name expectations in unfurl tests
- Ensure tests align with circuit breaker integration

These changes ensure all integration tests pass with the new validation
flow and circuit breaker implementation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Restore full aggregator authorization checks while maintaining the
special case for Kagi aggregator's thumbnail URL handling.

Changes:
- Restore aggregator DID validation in post creation flow
- Add distinction between Kagi (trusted) and other aggregators
- Map aggregator authorization errors to 403 Forbidden
- Maintain validation order: basic input -> DID auth -> aggregator check
- Keep Kagi special case for thumbnail URL transformation

Security improvements:
- All aggregator posts now require valid aggregator DID registration
- Kagi aggregator identified via KAGI_AGGREGATOR_DID environment variable
- Non-Kagi aggregators must follow standard thumbnail validation rules
- Unauthorized aggregator attempts return 403 with clear error message

This ensures only authorized aggregators can create posts while allowing
Kagi's existing thumbnail URL workflow to continue working.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Implement circuit breaker pattern to handle external provider failures
gracefully and prevent cascading failures when unfurl services are down.

Changes:
- Add circuit_breaker.go with state management (Closed, Open, HalfOpen)
- Implement automatic recovery with exponential backoff
- Add comprehensive circuit breaker unit tests
- Integrate circuit breaker into unfurl service
- Fix defer response.Body.Close() errors in providers
- Fix linting issues in kagi_test.go and opengraph_test.go

The circuit breaker tracks failures per provider and automatically opens
when failure threshold is reached, preventing wasted requests to failing
services. After a cooldown period, it transitions to half-open to test
if the service has recovered.

Configuration:
- Failure threshold: 5 consecutive failures
- Timeout: 10 seconds
- Reset timeout: 60 seconds (before attempting recovery)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add community handles to all feed responses and refactor feed repositories

Features:
- Add handle field to communityRef lexicon and struct
- Select community handle in all feed SQL queries (community, timeline, discover)
- Populate handle in comment service post views
- Refactor feed_repo.go to use feedRepoBase (68% code reduction)
- Add HMAC-signed cursors for security

Improvements:
- Improved error handling for missing communities (ERROR log + fallback)
- Moved nullStringPtr helper to correct location
- Apply gofumpt formatting to entire codebase

All tests passing, linter checks pass, production-ready.

- Run gofumpt -l -w on all Go files
- Fix import statement formatting (blank lines between groups)
- Auto-fix via make lint-fix
- All linter checks now pass

No functional changes, formatting only

- Add cursorSecret parameter to all NewCommunityFeedRepository calls
- Use 'test-cursor-secret' for test environments
- Add assertions to verify community handle is present in responses
- All 10 feed integration tests pass with HMAC-signed cursors

- Capture community.Handle when fetching community data
- Set Handle field in CommunityRef struct
- Improve error handling for missing communities:
- Log as ERROR (not warning) for data integrity issues
- Use DID as fallback for handle/name to prevent API breakage
- Surfaces orphaned post issues in logs while maintaining resilience

Fixes: Community handle field empty in post views from comment service

- Update NewCommunityFeedRepository to accept cursorSecret parameter
- Enables HMAC-signed cursors for security
- Consistent with timeline and discover feed repos
- Prevents cursor tampering and pagination attacks

- Update SELECT clauses to include c.handle as community_handle
- Update scanFeedPost to scan and populate handle field
- Changes apply to:
- Community feed (feed_repo.go)
- Timeline feed (timeline_repo.go)
- Discover feed (discover_repo.go)
- Shared base scanner (feed_repo_base.go)

All feed endpoints now return community handles in responses

- Update communityRef lexicon definition to include handle field
- Add Handle field to CommunityRef struct
- Follows atProto pattern of including both DID and handle
- Consistent with authorView which requires both fields

Fixes: Backend missing community handle in feed responses

Applied gofumpt strict formatting across entire codebase for consistency.

Changes:
- Import statement formatting (stdlib, external, internal order)
- Blank line grouping in imports
- Fix errcheck issue in user_repo.go (properly check rows.Close() error)
- Add log import for error logging

All tests pass after formatting changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Addresses P0 PR review test coverage requirements:

Unit Tests (comment_service_test.go):
- Fix mockUserRepo to implement GetByDIDs method (compilation blocker)
- Update all buildCommentView calls to 4-parameter signature
- Add 5 tests for GetByDIDs mock (empty, single, multiple, missing, fields)
- Add 5 tests for JSON deserialization (facets, embeds, labels, malformed, nil/empty)
- Total: 10 new unit tests covering Phase 2C functionality

Integration Tests (user_test.go):
- Add TestUserRepository_GetByDIDs with 7 comprehensive test cases
- Test empty array, single/multiple DIDs, missing users, field preservation
- Test validation: batch size limit (>1000), invalid DID format
- All tests use real PostgreSQL database with migrations

Test Fixes (comment_query_test.go):
- Fix TestCommentQuery_InvalidInputs failing tests
- Create real test post/community for validation tests
- Tests now verify normalization works (negative depth, excessive limits)
- All 6 test cases now pass

Test Results:
- Unit tests: 43 total (33 existing + 10 new) - ALL PASS
- Integration tests: 26 total (19 comment + 7 user) - ALL PASS
- Zero compilation errors, zero test failures

Coverage validates:
- Batch user loading prevents N+1 queries
- Input validation rejects oversized/malformed inputs
- JSON deserialization handles errors gracefully
- Security validation prevents injection attacks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Addresses critical P0 PR review issues for Phase 2C metadata hydration:

Input Validation (user_repo.go):
- Add MaxBatchSize constant (1000 DIDs) to prevent excessive queries
- Validate batch size before database operations
- Validate DID format (must start with "did:")
- Prevents SQL injection and malformed queries

Security Hardening (comment_service.go):
- Add HTTPS validation for community avatar URLs
- Validate CID format (must start with "baf" for IPFS CIDv1)
- Add URL escaping with url.QueryEscape() for DID and CID parameters
- Import "net/url" for proper URL handling
- Prevents mixed content warnings, MitM attacks, and injection attacks

API Documentation (interfaces.go):
- Add comprehensive godoc for GetByDIDs method
- Document parameters, return values, and behavior
- Include usage examples for developers

All changes maintain backward compatibility while adding critical
security and validation layers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Update COMMENT_SYSTEM_IMPLEMENTATION.md to reflect completion of Phase 2C
metadata hydration work.

Changes:
- Updated overview status: Phase 1, 2A, 2B & 2C Complete
- Updated last updated date with Phase 2C details
- Added comprehensive Phase 2C implementation section (165+ lines)
- Updated conclusion with Phase 2C achievements
- Added Phase 2C features to key features list:
- Full author metadata (handles from users table)
- Community metadata (names, avatars with blob URLs)
- Rich text facets (mentions, links, formatting)
- Embedded content (images, quoted posts)
- Content labels (NSFW, spoilers)
- Updated scalability section with user batch loading stats
- Added Rich Content checkmark to production readiness

Documentation includes:
- Batch user loading implementation details
- Community name/avatar hydration with priority selection
- Rich text deserialization patterns
- Error handling strategies
- Performance impact analysis
- Lexicon compliance validation

All Phase 2C work is now fully documented with technical details,
implementation patterns, and production considerations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add full user, community, and record metadata to comment query API responses.
Completes lexicon compliance for rich comment content including facets, embeds, and labels.

Changes to comment service:

1. **Batch User Hydration**
- Integrate GetByDIDs() for efficient author loading
- Collect all unique author DIDs from comment tree
- Single batch query prevents N+1 problem
- Populate AuthorView.Handle from users table

2. **Community Metadata Hydration**
- Fetch community for each post in response
- Populate community name with priority: DisplayName > Name > Handle > DID
- Construct avatar blob URL: {pds}/xrpc/com.atproto.sync.getBlob?did={did}&cid={cid}
- Graceful fallback if community not found

3. **Rich Text Deserialization**
- Deserialize contentFacets from JSONB (mentions, links, formatting)
- Deserialize embed from JSONB (images, quoted posts)
- Deserialize labels from JSONB (NSFW, spoilers, warnings)
- Populate both CommentView fields and complete record
- Graceful error handling (log warnings, don't fail requests)

4. **Complete Record Population**
- buildCommentRecord() now fully populates all fields
- Record includes: facets, embed, labels per lexicon
- Verbatim atProto record for full compatibility

API Response Enhancements:
- CommentView.ContentFacets: Rich text annotations
- CommentView.Embed: Embedded images or quoted posts
- CommentView.Record: Complete atProto record with all nested fields
- CommunityRef.Name: User-friendly community name
- CommunityRef.Avatar: Full blob URL for avatar image
- AuthorView.Handle: Correct handle from users table

Error Handling:
- All JSON parsing errors logged as warnings
- Requests succeed even if rich content parsing fails
- Missing users/communities handled gracefully
- Maintains API reliability with graceful degradation

Performance:
- Batch user loading prevents N+1 queries
- Single community query per response (acceptable for alpha)
- JSON deserialization happens in-memory (fast)
- No additional database queries for rich content

Lexicon Compliance:
- ✅ social.coves.community.comment.defs#commentView
- ✅ social.coves.community.post.get#authorView
- ✅ social.coves.community.post.get#communityRef
- ✅ All required fields populated, optional fields handled correctly

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Add GetByDIDs repository method to fetch multiple users in a single query,
preventing N+1 performance issues when hydrating comment authors in threads.

Changes:
- Add GetByDIDs() method to UserRepository interface
- Implement batch query using PostgreSQL ANY() with pq.Array type conversion
- Returns map[string]*User for O(1) lookups by DID
- Gracefully handles missing users (no error, just excluded from result map)

Performance impact:
- Before: N separate queries (1 per comment author)
- After: 1 batch query for all authors in thread
- ~10-100x faster for threads with many unique authors

Implementation uses parameterized query with PostgreSQL array support:
```sql
SELECT did, handle, pds_url, created_at, updated_at
FROM users WHERE did = ANY($1)
```

This is a foundational optimization for Phase 2C metadata hydration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>