StarPunk/docs/projectplan/v1.X.X-indieweb-options.md

# StarPunk v1.X.X IndieWeb-Focused Release Options

*Created: 2025-11-28*
*Status: Options for architect review*

Based on analysis of current implementation gaps and IndieWeb specifications, here are three genuinely different paths forward for full IndieWeb protocol support.

---

## Option A: v1.2.0 "Conversation" - Webmention & Reply Context

**Focus:** Enable two-way conversations between IndieWeb sites

**What's Missing Now:**
- Zero Webmention support (no sending, no receiving)
- No reply context display (when replying to others)
- No backlinks/responses display
- No notification system for mentions

**What You'll Get:**
- **Webmention Sending** (W3C Webmention spec)
  - Automatic endpoint discovery via HTTP headers/HTML links
  - Send notifications when mentioning/replying to other sites
  - Queue system for reliable delivery with retries
- **Webmention Receiving** (W3C Webmention spec)
  - Advertise endpoint in HTML and HTTP headers
  - Verify source mentions target
  - Store and display incoming mentions (likes, replies, reposts)
- **Reply Context** (IndieWeb reply-context spec)
  - Fetch and display content you're replying to
  - Parse microformats2 from source
  - Cache reply contexts locally
- **Response Display** (facepile pattern)
  - Show likes/reposts as compact avatars
  - Display full replies with author info
  - Separate responses by type

**IndieWeb Specs:**
- W3C Webmention: https://www.w3.org/TR/webmention/
- Reply-context: https://indieweb.org/reply-context
- Response display: https://indieweb.org/responses
- Facepile: https://indieweb.org/facepile

**Completion Criteria:**
- Pass webmention.rocks test suite (21 tests)
- Successfully send/receive with 3+ IndieWeb sites
- Display reply contexts with proper h-cite markup
- Show incoming responses grouped by type

**User Value:**
Transform StarPunk from broadcast-only to conversational. Users can reply to other IndieWeb posts and see who's engaging with their content. Creates a decentralized comment system.

**Scope:** 8-10 weeks

---

## Option B: v1.3.0 "Studio" - Complete Micropub Media & Post Types

**Focus:** Full Micropub spec compliance with rich media and diverse post types

**What's Missing Now:**
- No media endpoint (can't upload images/audio/video)
- No update/delete via Micropub (create-only)
- No syndication targets
- Only supports notes (no articles, photos, bookmarks, etc.)
- No query support beyond basic config

**What You'll Get:**
- **Micropub Media Endpoint** (W3C Micropub spec section 3.7)
  - Accept multipart uploads for images/audio/video
  - Generate URLs for uploaded media
  - Return media URL to client for embedding
  - Basic image resizing/optimization
- **Micropub Updates/Deletes** (W3C Micropub spec sections 3.3-3.4)
  - Replace/add/delete specific properties
  - Full post deletion support
  - JSON syntax for complex updates
- **Post Type Discovery** (IndieWeb post-type-discovery)
  - Articles (with titles)
  - Photos (image-centric posts)
  - Bookmarks (link saving)
  - Likes (marking favorites)
  - Reposts (sharing others' content)
  - Audio/Video posts
- **Syndication Targets** (Micropub syndicate-to)
  - Configure external targets (Mastodon, Twitter bridges)
  - POSSE implementation
  - Return syndication URLs

**IndieWeb Specs:**
- W3C Micropub (complete): https://www.w3.org/TR/micropub/
- Post Type Discovery: https://indieweb.org/post-type-discovery
- POSSE: https://indieweb.org/POSSE

**Completion Criteria:**
- Pass micropub.rocks full test suite (not just create)
- Support all major post types with proper templates
- Successfully syndicate to 2+ external services
- Handle media uploads from mobile apps

**User Value:**
Use any Micropub client (Indigenous, Quill, etc.) with full features. Post photos from your phone, save bookmarks, like posts, all through standard clients. Syndicate to social media automatically.

**Scope:** 10-12 weeks

---

## Option C: v1.4.0 "Identity" - Complete Microformats2 & IndieAuth Provider

**Focus:** Become a full IndieWeb identity provider and improve content markup

**What's Missing Now:**
- Minimal h-entry markup (missing author, location, syndication)
- No h-card on pages (no author identity)
- No h-feed markup enhancements
- No rel=me verification
- Using external IndieAuth (not self-hosted)
- No authorization endpoint
- No token endpoint

**What You'll Get:**
- **Complete h-entry Microformats2** (microformats2 spec)
  - Author h-card embedded in each post
  - Location (p-location with h-geo/h-adr)
  - Syndication links (u-syndication)
  - In-reply-to markup (u-in-reply-to)
  - Categories/tags (p-category)
- **Author h-card** (microformats2 h-card)
  - Full profile page with h-card
  - Representative h-card on homepage
  - Contact info, bio, social links
  - rel=me links for verification
- **Enhanced h-feed** (microformats2 h-feed)
  - Feed name and author
  - Pagination with rel=prev/next
  - Feed photo/summary
- **IndieAuth Provider** (IndieAuth spec)
  - Authorization endpoint (login to other sites with your domain)
  - Token endpoint (issue access tokens)
  - Client registration support
  - Scope management
  - Token revocation interface

**IndieWeb Specs:**
- Microformats2: http://microformats.org/wiki/microformats2
- h-card: http://microformats.org/wiki/h-card
- h-entry: http://microformats.org/wiki/h-entry
- IndieAuth: https://indieauth.spec.indieweb.org/
- rel=me: https://indieweb.org/rel-me

**Completion Criteria:**
- Pass IndieWebify.me full validation
- Successfully authenticate to 5+ IndieWeb services
- Parse correctly in all major microformats2 parsers
- Provide IndieAuth to other sites (eat your own dogfood)

**User Value:**
Your site becomes your identity across the web. Log into any IndieWeb service with your domain. Rich markup makes your content parse perfectly everywhere. No dependency on external auth services.

**Scope:** 6-8 weeks

---

## Recommendation Rationale

Each option represents a fundamentally different IndieWeb capability:

- **Option A (Conversation)**: Makes StarPunk social and interactive
- **Option B (Studio)**: Makes StarPunk a complete publishing platform
- **Option C (Identity)**: Makes StarPunk an identity provider

All three are essential for "full IndieWeb support" but focus on different protocols:

- A focuses on **Webmention** (W3C Recommendation)
- B focuses on **Micropub** completion (W3C Recommendation)
- C focuses on **Microformats2** & **IndieAuth** (IndieWeb specs)

## Current Implementation Gaps Summary

Based on code analysis:

### Micropub (`starpunk/micropub.py`)
✅ Create notes (basic)
✅ Query config
✅ Query source
❌ Media endpoint
❌ Updates (replace/add/delete)
❌ Deletes
❌ Syndication targets
❌ Query for syndicate-to

### Microformats (templates)
✅ Basic h-entry (content, published date, URL)
✅ Basic h-feed wrapper
❌ Author h-card
❌ Complete h-entry properties
❌ rel=me links
❌ h-feed metadata

### Webmention
❌ No implementation at all

### IndieAuth
✅ Client (using indielogin.com)
❌ No provider capability

### Post Types
✅ Notes
❌ Articles, photos, bookmarks, likes, reposts, etc.

---

## Decision Factors

Consider these when choosing:

1. **User Demand**: What are users asking for most?
2. **Ecosystem Value**: Which adds most value to IndieWeb network?
3. **Technical Dependencies**: Option C (Identity) might benefit A & B
4. **Market Differentiation**: Which makes StarPunk unique?

All three options are genuinely different approaches to "full IndieWeb support" - the choice depends on priorities.