release: Bump version to 1.3.0

Promoting v1.3.0-rc.1 to stable release. Changes: - Updated version in starpunk/__init__.py to 1.3.0 - Updated CHANGELOG.md header to v1.3.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Merge feature/v1.3.0-tags-microformats into main
2025-12-10 12:19:11 -07:00 · 2025-12-10 12:01:09 -07:00 · 2025-12-10 12:00:56 -07:00 · 2025-12-10 11:58:45 -07:00 · 2025-12-10 11:58:10 -07:00 · 2025-12-10 11:51:39 -07:00
298 changed files with 38054 additions and 626 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,507 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [1.3.0] - 2025-12-10
+
+### Added
+
+- **Tag/Category System** - Complete tag support with hierarchical organization
+  - Tag creation and management via web UI and Micropub
+  - Support for Micropub `category` property in JSON and form-encoded requests
+  - Tag archive pages at `/tags/{tag}` with all tagged notes
+  - Tag cloud display on homepage showing all used tags
+  - Tag filtering in database queries (list_notes_by_tag)
+  - Reserved tag validation (prevents tags like 'api', 'admin', etc.)
+  - Comprehensive tag management in admin dashboard
+  - Database schema: tags table with slug and name fields
+  - Many-to-many relationship between notes and tags
+  - Automatic tag cleanup (removes orphaned tags)
+
+- **Strict Microformats2 Compliance** - Enhanced h-entry markup for parsers
+  - p-category property for each tag in note markup
+  - dt-updated property displays when note is modified
+  - dt-published always shown for temporal context
+  - u-uid property matches u-url for permalink stability
+  - Proper h-feed structure on homepage and tag archives
+  - p-name property only when note has explicit title (# heading)
+  - e-content wraps full note content
+  - Nested h-card for author within each h-entry
+  - Homepage displays as complete h-feed with feed properties
+
+- **h-feed Properties** - Proper feed markup on collection pages
+  - Homepage marked as h-feed with p-name "Recent Notes"
+  - Tag archive pages marked as h-feed with descriptive p-name
+  - Each feed contains multiple h-entry items
+  - Feed structure validates with Microformats2 parsers
+  - Supports feed readers and IndieWeb aggregators
+
+### Changed
+
+- **Template Structure** - Reorganized for better Microformats2 compliance
+  - Homepage template now wraps entries in proper h-feed
+  - Note display templates use semantic h-entry markup
+  - Tag display integrated throughout note views
+  - Consistent Microformats2 patterns across all pages
+
+### Technical Details
+
+- Migration 006: Add tags table and note_tags junction table
+- New module: `starpunk/tags.py` with tag CRUD operations
+- Enhanced: `starpunk/notes.py` with tag relationship handling
+- Enhanced: `starpunk/micropub.py` with category property support
+- Enhanced: Templates with p-category and h-feed markup
+- All tests passing (580+ tests)
+- 100% backward compatible with existing notes
+
+## [1.2.0] - 2025-12-09
+
+### Added
+- **Feed Media Enhancement** - Media RSS and JSON Feed image support for improved feed reader compatibility
+  - RSS feeds now include Media RSS namespace (xmlns:media) for structured media metadata
+  - RSS enclosure element added for first image (per RSS 2.0 spec)
+  - Media RSS media:content elements for all images with type, medium, and fileSize attributes
+  - Media RSS media:thumbnail element for first image preview
+  - JSON Feed items include "image" field with first image URL (per JSON Feed 1.1 spec)
+  - Image field absent (not null) when no media attached
+  - Both feed formats maintain existing HTML embedding for universal reader support
+  - Provides enhanced display in modern feed readers (Feedly, Inoreader, NetNewsWire)
+
+- **Custom Slug Input Field** - Web UI now supports custom slugs (v1.2.0 Phase 1)
+  - Added optional custom slug field to note creation form
+  - Slugs are read-only after creation to preserve permalinks
+  - Auto-validates and sanitizes slug format (lowercase, numbers, hyphens only)
+  - Shows helpful placeholder text and validation guidance
+  - Matches Micropub `mp-slug` behavior for consistency
+  - Falls back to auto-generation when field is left blank
+
+- **Author Profile Discovery** - Automatic h-card discovery from IndieAuth identity (v1.2.0 Phase 2)
+  - Discovers author information from user's IndieAuth profile URL on login
+  - Caches author h-card data (name, photo, bio, rel-me links) for 24 hours
+  - Uses mf2py library for reliable Microformats2 parsing
+  - Graceful fallback to domain name if discovery fails
+  - Never blocks login functionality (per ADR-061)
+  - Eliminates need for manual author configuration
+
+- **Complete Microformats2 Support** - Full IndieWeb h-entry, h-card, h-feed markup (v1.2.0 Phase 2)
+  - All notes display as proper h-entry with required properties (u-url, dt-published, e-content, p-author)
+  - Author h-card nested within each h-entry (not standalone)
+  - p-name property only added when note has explicit title (starts with # heading)
+  - u-uid and u-url match for notes (permalink stability)
+  - Homepage displays as h-feed with proper structure
+  - rel-me links from discovered profile added to HTML head
+  - dt-updated property shown when note is modified
+  - Passes Microformats2 validation (indiewebify.me compatible)
+
+- **Media Upload Support** - Image upload and display for notes (v1.2.0 Phase 3)
+  - Upload up to 4 images per note via web UI (JPEG, PNG, GIF, WebP)
+  - Automatic image optimization with Pillow library
+  - Rejects files over 10MB or dimensions over 4096x4096 pixels
+  - Auto-resizes images over 2048px (longest edge) to improve performance
+  - EXIF orientation correction ensures proper display
+  - Social media style layout: media displays at top, text content below
+  - Optional captions for accessibility (used as alt text)
+  - Media stored in date-organized folders (data/media/YYYY/MM/)
+  - UUID-based filenames prevent collisions
+  - Media included in all syndication feeds (RSS, ATOM, JSON Feed)
+  - RSS: HTML embedding in description
+  - ATOM: Both enclosures and HTML content
+  - JSON Feed: Native attachments array
+  - Multiple u-photo properties in Microformats2 markup
+  - Media files cached immutably (1 year) for performance
+
+### Fixed
+- **Media Display on Homepage** - Images now display correctly on homepage, not just individual note pages
+- **Responsive Image Sizing** - Images constrained to container width with proper CSS
+- **Caption Display** - Captions now used as alt text only, not displayed as visible text
+- **Logging Correlation ID** - Fixed crash in non-request contexts (app init, memory monitor)
+
+## [1.1.2] - 2025-11-28
+
+### Fixed
+- **CRITICAL**: Static files now load correctly - fixed HTTP middleware streaming response handling
+  - HTTP metrics middleware was accessing `.data` on streaming responses (Flask's `send_from_directory`)
+  - This caused RuntimeError: "Attempted implicit sequence conversion but the response object is in direct passthrough mode"
+  - Now checks `direct_passthrough` attribute before accessing response data
+  - Gracefully falls back to `content_length` for streaming responses
+  - Fixes complete site failure (no CSS/JS loading)
+
+- **HIGH**: Database metrics now display correctly - fixed configuration key mismatch
+  - Config sets `METRICS_SAMPLING_RATE` (singular), metrics read `METRICS_SAMPLING_RATES` (plural)
+  - Mismatch caused fallback to hardcoded 10% sampling regardless of config
+  - Fixed key to use `METRICS_SAMPLING_RATE` (singular) consistently
+  - MetricsBuffer now accepts both float (global rate) and dict (per-type rates)
+  - Increased default sampling rate from 10% to 100% for low-traffic sites
+
+### Changed
+- Default metrics sampling rate increased from 10% to 100%
+  - Better visibility for low-traffic single-user deployments
+  - Configurable via `METRICS_SAMPLING_RATE` environment variable (0.0-1.0)
+  - Minimal overhead at typical usage levels
+  - Power users can reduce if needed
+
+## [1.1.2-dev] - 2025-11-27
+
+### Added - Phase 3: Feed Statistics Dashboard & OPML Export (Complete)
+
+**Feed statistics dashboard and OPML 2.0 subscription list**
+
+- **Feed Statistics Dashboard** - Real-time feed performance monitoring
+  - Added "Feed Statistics" section to `/admin/metrics-dashboard`
+  - Tracks requests by format (RSS, ATOM, JSON Feed)
+  - Cache hit/miss rates and efficiency metrics
+  - Feed generation performance by format
+  - Format popularity breakdown (pie chart)
+  - Cache efficiency visualization (doughnut chart)
+  - Auto-refresh every 10 seconds via htmx
+  - Progressive enhancement (works without JavaScript)
+
+- **Feed Statistics API** - Business metrics aggregation
+  - New `get_feed_statistics()` function in `starpunk.monitoring.business`
+  - Aggregates metrics from MetricsBuffer and FeedCache
+  - Provides format-specific statistics (generated vs cached)
+  - Calculates cache hit rates and format percentages
+  - Integrated with `/admin/metrics` endpoint
+  - Comprehensive test coverage (6 unit tests + 5 integration tests)
+
+- **OPML 2.0 Export** - Feed subscription list for feed readers
+  - New `/opml.xml` endpoint for OPML 2.0 subscription list
+  - Lists all three feed formats (RSS, ATOM, JSON Feed)
+  - RFC-compliant OPML 2.0 structure
+  - Public access (no authentication required)
+  - Feed discovery link in HTML `<head>`
+  - Supports easy multi-feed subscription
+  - Cache headers (same TTL as feeds)
+  - Comprehensive test coverage (7 unit tests + 8 integration tests)
+
+- **Phase 3 Test Coverage** - 26 new tests
+  - 7 tests for OPML generation
+  - 8 tests for OPML route and discovery
+  - 6 tests for feed statistics functions
+  - 5 tests for feed statistics dashboard integration
+
+## [1.1.2-dev] - 2025-11-26
+
+### Added - Phase 2: Feed Formats (Complete - RSS Fix, ATOM, JSON Feed, Content Negotiation)
+
+**Multi-format feed support with ATOM, JSON Feed, and content negotiation**
+
+- **Content Negotiation** - Smart feed format selection via HTTP Accept header
+  - New `/feed` endpoint with HTTP content negotiation
+  - Supports Accept header quality factors (e.g., `q=0.9`)
+  - MIME type mapping:
+    - `application/rss+xml` → RSS 2.0
+    - `application/atom+xml` → ATOM 1.0
+    - `application/feed+json` or `application/json` → JSON Feed 1.1
+    - `*/*` → RSS 2.0 (default)
+  - Returns 406 Not Acceptable with helpful error message for unsupported formats
+  - Simple implementation (StarPunk philosophy) - not full RFC 7231 compliance
+  - Comprehensive test coverage (63 tests for negotiation + integration)
+
+- **Explicit Format Endpoints** - Direct access to specific feed formats
+  - `/feed.rss` - Explicit RSS 2.0 feed
+  - `/feed.atom` - Explicit ATOM 1.0 feed
+  - `/feed.json` - Explicit JSON Feed 1.1
+  - `/feed.xml` - Backward compatibility (redirects to `/feed.rss`)
+  - All endpoints support streaming and caching
+
+- **ATOM 1.0 Feed Support** - RFC 4287 compliant ATOM feeds
+  - Full ATOM 1.0 specification compliance with proper XML namespacing
+  - RFC 3339 date format for published and updated timestamps
+  - Streaming and non-streaming generation methods
+  - XML escaping using standard library (xml.etree.ElementTree approach)
+  - Business metrics integration for feed generation tracking
+  - Comprehensive test coverage (11 tests)
+
+- **JSON Feed 1.1 Support** - Modern JSON-based syndication format
+  - JSON Feed 1.1 specification compliance
+  - RFC 3339 date format for date_published
+  - Streaming and non-streaming generation methods
+  - UTF-8 JSON output with pretty-printing
+  - Custom _starpunk extension with permalink_path and word_count
+  - Business metrics integration
+  - Comprehensive test coverage (13 tests)
+
+- **Feed Module Restructuring** - Organized feed code for multiple formats
+  - New `starpunk/feeds/` module with format-specific files
+  - `feeds/rss.py` - RSS 2.0 generation (moved from feed.py)
+  - `feeds/atom.py` - ATOM 1.0 generation (new)
+  - `feeds/json_feed.py` - JSON Feed 1.1 generation (new)
+  - `feeds/negotiation.py` - Content negotiation logic (new)
+  - Backward compatible `feed.py` shim for existing imports
+  - All formats support both streaming and non-streaming generation
+  - Business metrics integrated into all feed generators
+
+### Fixed - Phase 2: RSS Ordering
+
+**CRITICAL: Fixed RSS feed ordering bug**
+
+- **RSS Feed Ordering** - Corrected feed entry ordering
+  - Fixed streaming RSS generation (removed incorrect reversed() at line 198)
+  - Feedgen-based RSS correctly uses reversed() to compensate for library behavior
+  - RSS feeds now properly show newest entries first (DESC order)
+  - Created shared test helper `tests/helpers/feed_ordering.py` for all formats
+  - All feed formats verified to maintain newest-first ordering
+
+### Added - Phase 1: Metrics Instrumentation
+
+**Complete metrics instrumentation foundation for production monitoring**
+
+- **Database Operation Monitoring** - Comprehensive database performance tracking
+  - MonitoredConnection wrapper times all database operations
+  - Extracts query type (SELECT, INSERT, UPDATE, DELETE, etc.)
+  - Identifies table names using regex (simple queries) or "unknown" for complex queries
+  - Detects slow queries (configurable threshold, default 1.0s)
+  - Slow queries and errors always recorded regardless of sampling
+  - Integrated at connection pool level for transparent operation
+  - See developer Q&A CQ1, IQ1, IQ3 for design rationale
+
+- **HTTP Request/Response Metrics** - Full request lifecycle tracking
+  - Automatic request timing for all HTTP requests
+  - UUID request ID generation for correlation (X-Request-ID header)
+  - Request IDs included in ALL responses, not just debug mode
+  - Tracks status codes, methods, endpoints, request/response sizes
+  - Errors always recorded for debugging
+  - Flask middleware integration for zero-overhead when disabled
+  - See developer Q&A IQ2 for request ID strategy
+
+- **Memory Monitoring** - Continuous background memory tracking
+  - Daemon thread monitors RSS and VMS memory usage
+  - 5-second baseline period after app initialization
+  - Detects memory growth (warns at >10MB growth from baseline)
+  - Tracks garbage collection statistics
+  - Graceful shutdown handling
+  - Automatically skipped in test mode to avoid thread pollution
+  - Uses psutil for cross-platform memory monitoring
+  - See developer Q&A CQ5, IQ8 for thread lifecycle design
+
+- **Business Metrics** - Application-specific event tracking
+  - Note operations: create, update, delete
+  - Feed generation: timing, format, item count, cache hits/misses
+  - All business metrics forced (always recorded)
+  - Ready for integration into notes.py and feed.py
+  - See implementation guide for integration examples
+
+- **Metrics Configuration** - Flexible runtime configuration
+  - `METRICS_ENABLED` - Master toggle (default: true)
+  - `METRICS_SLOW_QUERY_THRESHOLD` - Slow query detection (default: 1.0s)
+  - `METRICS_SAMPLING_RATE` - Sampling rate 0.0-1.0 (default: 1.0 = 100%)
+  - `METRICS_BUFFER_SIZE` - Circular buffer size (default: 1000)
+  - `METRICS_MEMORY_INTERVAL` - Memory check interval in seconds (default: 30)
+  - All configuration via environment variables or .env file
+
+### Changed
+
+- **Database Connection Pool** - Enhanced with metrics integration
+  - Connections now wrapped with MonitoredConnection when metrics enabled
+  - Passes slow query threshold from configuration
+  - Logs metrics status on initialization
+  - Zero overhead when metrics disabled
+
+- **Flask Application Factory** - Metrics middleware integration
+  - HTTP metrics middleware registered when metrics enabled
+  - Memory monitor thread started (skipped in test mode)
+  - Graceful cleanup handlers for memory monitor
+  - Maintains backward compatibility
+
+- **Package Version** - Bumped to 1.1.2-dev
+  - Follows semantic versioning
+  - Development version indicates work in progress
+  - See docs/standards/versioning-strategy.md
+
+### Dependencies
+
+- **Added**: `psutil==5.9.*` - Cross-platform system monitoring for memory tracking
+
+### Testing
+
+- **Added**: Comprehensive monitoring test suite (tests/test_monitoring.py)
+  - 28 tests covering all monitoring components
+  - 100% test pass rate
+  - Tests for database monitoring, HTTP metrics, memory monitoring, business metrics
+  - Configuration validation tests
+  - Thread lifecycle tests with proper cleanup
+
+### Documentation
+
+- **Added**: Phase 1 implementation report (docs/reports/v1.1.2-phase1-metrics-implementation.md)
+  - Complete implementation details
+  - Q&A compliance verification
+  - Test results and metrics demonstration
+  - Integration guide for Phase 2
+
+### Notes
+
+- This is Phase 1 of 3 for v1.1.2 "Syndicate" release
+- All architect Q&A guidance followed exactly (zero deviations)
+- Ready for Phase 2: Feed Formats (ATOM, JSON Feed)
+- Business metrics functions available but not yet integrated into notes/feed modules
+
+## [1.1.1-rc.2] - 2025-11-25
+
+### Fixed
+- **CRITICAL**: Resolved template/data mismatch causing 500 error on metrics dashboard
+  - Fixed Jinja2 UndefinedError: `'dict object' has no attribute 'database'`
+  - Added `transform_metrics_for_template()` function to map data structure
+  - Transforms `metrics.by_type.database` → `metrics.database` for template compatibility
+  - Maps field names: `avg_duration_ms` → `avg`, `min_duration_ms` → `min`, etc.
+  - Provides safe defaults for missing/empty metrics data
+  - Renamed metrics dashboard route from `/admin/dashboard` to `/admin/metrics-dashboard`
+  - Added defensive imports to handle missing monitoring module gracefully
+  - All existing `url_for("admin.dashboard")` calls continue to work correctly
+  - Notes dashboard at `/admin/` remains unchanged and functional
+  - See ADR-022 and ADR-060 for design rationale
+
+## [1.1.1] - 2025-11-25
+
+### Added
+- **Structured Logging** - Enhanced logging system for production readiness
+  - RotatingFileHandler with 10MB files, keeping 10 backups
+  - Correlation IDs for request tracing across the entire request lifecycle
+  - Separate log files in `data/logs/starpunk.log`
+  - All print statements replaced with proper logging
+  - See ADR-054 for architecture details
+
+- **Database Connection Pooling** - Improved database performance
+  - Connection pool with configurable size (default: 5 connections)
+  - Request-scoped connections via Flask's g object
+  - Pool statistics available for monitoring via `/admin/metrics`
+  - Transparent to calling code (maintains same interface)
+  - See ADR-053 for implementation details
+
+- **Enhanced Configuration Validation** - Fail-fast startup validation
+  - Validates both presence and type of all required configuration values
+  - Clear, detailed error messages with specific fixes
+  - Validates LOG_LEVEL against allowed values
+  - Type checking for strings, integers, and Path objects
+  - Non-zero exit status on configuration errors
+  - See ADR-052 for configuration strategy
+
+### Changed
+- **Centralized Error Handling** - Consistent error responses
+  - Moved error handlers from inline decorators to `starpunk/errors.py`
+  - Micropub endpoints return spec-compliant JSON errors
+  - HTML error pages for browser requests
+  - All errors logged with correlation IDs
+  - MicropubError exception class for spec compliance
+  - See ADR-055 for error handling strategy
+
+- **Database Module Reorganization** - Better structure
+  - Moved from single `database.py` to `database/` package
+  - Separated concerns: `init.py`, `pool.py`, `schema.py`
+  - Maintains backward compatibility with existing imports
+  - Cleaner separation of initialization and connection management
+
+- **Performance Monitoring Infrastructure** - Track system performance
+  - MetricsBuffer class with circular buffer (deque-based)
+  - Per-process metrics with process ID tracking
+  - Configurable sampling rates per operation type
+  - Database pool statistics endpoint (`/admin/metrics`)
+  - See Phase 2 implementation report for details
+
+- **Three-Tier Health Checks** - Comprehensive health monitoring
+  - Basic `/health` endpoint (public, load balancer-friendly)
+  - Detailed `/health?detailed=true` (authenticated, comprehensive)
+  - Full `/admin/health` diagnostics (authenticated, with metrics)
+  - Progressive detail levels for different use cases
+  - See developer Q&A Q10 for architecture
+
+- **Admin Metrics Dashboard** - Visual performance monitoring (Phase 3)
+  - Server-side rendering with Jinja2 templates
+  - Auto-refresh with htmx (10-second interval)
+  - Charts powered by Chart.js from CDN
+  - Progressive enhancement (works without JavaScript)
+  - Database pool statistics, performance metrics, system health
+  - Access at `/admin/dashboard`
+  - See developer Q&A Q19 for design decisions
+
+### Changed
+
+- **RSS Feed Streaming Optimization** - Memory-efficient feed generation (Phase 3)
+  - Generator-based streaming with `yield` (Q9)
+  - Memory usage reduced from O(n) to O(1) for feed size
+  - Yields XML in semantic chunks (channel metadata, items, closing tags)
+  - Lower time-to-first-byte (TTFB) for large feeds
+  - Note list caching still prevents repeated DB queries
+  - No ETags (incompatible with streaming), but Cache-Control headers maintained
+  - Recommended for feeds with 100+ items
+  - Backward compatible - transparent to RSS clients
+
+- **Search Enhancements** - Improved search robustness
+  - FTS5 availability detection at startup with caching
+  - Graceful fallback to LIKE queries when FTS5 unavailable
+  - Search result highlighting with XSS prevention (markupsafe.escape())
+  - Whitelist-only `<mark>` tags for highlighting
+  - See Phase 2 implementation for details
+
+- **Unicode Slug Generation** - International character support
+  - Unicode normalization (NFKD) before slug generation
+  - Timestamp-based fallback (YYYYMMDD-HHMMSS) for untranslatable text
+  - Warning logs with original text for debugging
+  - Never fails Micropub requests due to slug issues
+  - See Phase 2 implementation for details
+
+### Fixed
+
+- **Migration Race Condition Tests** - Fixed flaky tests (Phase 3, Q15)
+  - Corrected off-by-one error in retry count expectations
+  - Fixed mock time.time() call count in timeout tests
+  - 10 retries = 9 sleep calls (not 10)
+  - Tests now stable and reliable
+
+### Technical Details
+- Phase 1, 2, and 3 of v1.1.1 "Polish" release completed
+- Core infrastructure improvements for production readiness
+- 600 tests passing (all tests stable, no flaky tests)
+- No breaking changes to public API
+- Complete operational documentation added
+
+## [1.1.0] - 2025-11-25
+
+### Added
+- **Full-Text Search** - SQLite FTS5 implementation for searching note content
+  - FTS5 virtual table with Porter stemming and Unicode normalization
+  - Automatic index updates on note create/update/delete
+  - Graceful degradation if FTS5 unavailable
+  - Helper function to rebuild index from existing notes
+  - See ADR-034 for architecture details
+  - **Note**: Search UI (/api/search endpoint and templates) to be completed in follow-up
+
+- **Custom Slugs** - User-specified URLs via Micropub
+  - Support for `mp-slug` property in Micropub requests
+  - Automatic slug sanitization (lowercase, hyphens only)
+  - Reserved slug protection (api, admin, auth, feed, etc.)
+  - Sequential conflict resolution with suffixes (-2, -3, etc.)
+  - Hierarchical slugs (/) rejected (deferred to v1.2.0)
+  - Maintains backward compatibility with auto-generation
+  - See ADR-035 for implementation details
+
+### Fixed
+- **RSS Feed Ordering** - Feed now correctly displays newest posts first
+  - Added `reversed()` wrapper to compensate for feedgen internal ordering
+  - Regression test ensures feed matches database DESC order
+
+- **Custom Slug Extraction** - Fixed bug where mp-slug was ignored in Micropub requests
+  - Root cause: mp-slug was extracted after normalize_properties() filtered it out
+  - Solution: Extract mp-slug from raw request data before normalization
+  - Affects both form-encoded and JSON Micropub requests
+  - See docs/reports/custom-slug-bug-diagnosis.md for detailed analysis
+
+### Changed
+- **Database Migration System** - Renamed for clarity
+  - `SCHEMA_SQL` renamed to `INITIAL_SCHEMA_SQL`
+  - Documentation clarifies this represents frozen v1.0.0 baseline
+  - All schema changes after v1.0.0 must go in migration files
+  - See ADR-033 for redesign rationale
+
+### Technical Details
+- Migration 005: FTS5 virtual table with DELETE trigger
+- New modules: `starpunk/search.py`, `starpunk/slug_utils.py`
+- Modified: `starpunk/notes.py` (custom_slug param, FTS integration)
+- Modified: `starpunk/micropub.py` (mp-slug extraction)
+- Modified: `starpunk/feed.py` (reversed() fix)
+- 100% backward compatible, no breaking changes
+- All tests pass (557 tests)
+
 ## [1.0.1] - 2025-11-25

 ### Fixed
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,94 +8,50 @@ This file contains operational instructions for Claude agents working on this pr
 - All Python commands must be run with `uv run` prefix
 - Example: `uv run pytest`, `uv run flask run`

+## Agent Protocol (All Agents)
+
+**IMPORTANT**: All agents must review `docs/DOCUMENTATION.md` before starting work. This file is the authoritative source for documentation organization and supersedes any other instructions.
+
 ## Agent-Architect Protocol

 When invoking the agent-architect, always remind it to:

-1. Review documentation in docs/ before working on the task it is given 
-   - docs/architecture, docs/decisions, docs/standards are of particular interest 
+1. Review `docs/DOCUMENTATION.md` for documentation organization standards

-2. Give it the map of the documentation folder as described in the "Understanding the docs/ Structure" section below
+2. Review documentation in docs/ before working on the task it is given
+   - docs/architecture, docs/decisions, docs/standards are of particular interest

 3. Search for authoritative documentation for any web standard it is implementing on https://www.w3.org/

-4. If it is reviewing a developers implementation report and it is accepts the completed work it should go back and update the project plan to reflect the completed work
+4. If it is reviewing a developers implementation report and it accepts the completed work it should go back and update the project plan to reflect the completed work

 ## Agent-Developer Protocol

 When invoking the agent-developer, always remind it to:

-1. **Document work in reports**
-   - Create implementation reports in `docs/reports/`
-   - Include date in filename: `YYYY-MM-DD-description.md`
+1. Review `docs/DOCUMENTATION.md` for documentation organization standards

-2. **Update the changelog**
+2. **Document work in design folder**
+   - Create implementation reports in `docs/design/{version}/`
+   - Include date in filename: `YYYY-MM-DD-description.md`
+   - All developer interaction (questions, responses, reports, reviews) goes in design/{version}/
+
+3. **Update the changelog**
   - Add entries to `CHANGELOG.md` for user-facing changes
   - Follow existing format

-3. **Version number management**
+4. **Version number management**
   - Increment version numbers according to `docs/standards/versioning-strategy.md`
   - Update version in `starpunk/__init__.py`

-4. **Follow git protocol**
+5. **Follow git protocol**
   - Adhere to git branching strategy in `docs/standards/git-branching-strategy.md`
   - Create feature branches for non-trivial changes
   - Write clear commit messages

-## Documentation Navigation
+## Documentation

-### Understanding the docs/ Structure
-
-The `docs/` folder is organized by document type and purpose:
-
- **`docs/architecture/`** - System design overviews, component diagrams, architectural patterns
- **`docs/decisions/`** - Architecture Decision Records (ADRs), numbered sequentially (ADR-001, ADR-002, etc.)
- **`docs/deployment/`** - Deployment guides, infrastructure setup, operations documentation
- **`docs/design/`** - Detailed design documents, feature specifications, phase plans
- **`docs/examples/`** - Example implementations, code samples, usage patterns
- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions
- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives
- **`docs/standards/`** - Coding standards, conventions, processes, workflows
-
-### Where to Find Documentation
-
- **Before implementing a feature**: Check `docs/decisions/` for relevant ADRs and `docs/design/` for specifications
- **Understanding system architecture**: Start with `docs/architecture/overview.md`
- **Coding guidelines**: See `docs/standards/` for language-specific standards and best practices
- **Past implementation context**: Review `docs/reports/` for similar work (sorted by date)
- **Project roadmap and scope**: Refer to `docs/projectplan/`
-
-### Where to Create New Documentation
-
-**Create an ADR (`docs/decisions/`)** when:
- Making architectural decisions that affect system design
- Choosing between competing technical approaches
- Establishing patterns that others should follow
- Format: `ADR-NNN-brief-title.md` (find next number sequentially)
-
-**Create a design doc (`docs/design/`)** when:
- Planning a complex feature implementation
- Detailing technical specifications
- Documenting multi-phase development plans
-
-**Create an implementation report (`docs/reports/`)** when:
- Completing significant development work
- Documenting implementation details for architect review
- Format: `YYYY-MM-DD-brief-description.md`
-
-**Update standards (`docs/standards/`)** when:
- Establishing new coding conventions
- Documenting processes or workflows
- Creating checklists or guidelines
-
-### Key Documentation References
-
- **Architecture**: See `docs/architecture/overview.md`
- **Implementation Plan**: See `docs/projectplan/v1/implementation-plan.md`
- **Feature Scope**: See `docs/projectplan/v1/feature-scope.md`
- **Coding Standards**: See `docs/standards/python-coding-standards.md`
- **Testing**: See `docs/standards/testing-checklist.md`
+See `docs/DOCUMENTATION.md` for the authoritative documentation structure, navigation guidance, and key references.

 ## Project Philosophy

--- a/README.md
+++ b/README.md
@@ -2,16 +2,13 @@

 A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.

-**Current Version**: 1.0.0
+**Current Version**: 1.2.0

 ## Versioning

 StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/):
 - Version format: `MAJOR.MINOR.PATCH`
- Current: `1.0.0` (stable release)
-
-**Version Information**:
- Current: `1.0.0` (stable release)
+- Current: `1.2.0` (stable release)
 - Check version: `python -c "from starpunk import __version__; print(__version__)"`
 - See changes: [CHANGELOG.md](CHANGELOG.md)
 - Versioning strategy: [docs/standards/versioning-strategy.md](docs/standards/versioning-strategy.md)
@@ -32,10 +29,14 @@ StarPunk is designed for a single user who wants to:
 - **File-based storage**: Notes are markdown files, owned by you
 - **IndieAuth authentication**: Use your own website as identity
 - **Micropub support**: Full W3C Micropub specification compliance
- **RSS feed**: Automatic syndication
+- **Media attachments**: Upload and display images with your notes
+- **Microformats2**: Full h-entry, h-card, and h-feed markup for IndieWeb compatibility
+- **Author discovery**: Automatic profile discovery from your IndieWeb identity
+- **RSS, ATOM, JSON Feed**: Multiple syndication formats with Media RSS support
+- **Custom slugs**: Control your note permalinks
 - **No database lock-in**: SQLite for metadata, files for content
 - **Self-hostable**: Run on your own server
- **Minimal dependencies**: 6 core dependencies, no build tools
+- **Minimal dependencies**: Core dependencies, no build tools

 ## Requirements

@@ -157,8 +158,10 @@ See [docs/architecture/](docs/architecture/) for complete documentation.
 StarPunk implements:
 - [Micropub](https://micropub.spec.indieweb.org/) - Publishing API
 - [IndieAuth](https://www.w3.org/TR/indieauth/) - Authentication
- [Microformats2](http://microformats.org/) - Semantic HTML markup
- [RSS 2.0](https://www.rssboard.org/rss-specification) - Feed syndication
+- [Microformats2](http://microformats.org/) - h-entry, h-card, h-feed markup
+- [RSS 2.0](https://www.rssboard.org/rss-specification) with Media RSS extensions
+- [ATOM 1.0](https://validator.w3.org/feed/docs/atom.html) - Syndication format
+- [JSON Feed 1.1](https://jsonfeed.org/version/1.1) - Modern feed format

 ## Deployment

--- a/docs/DOCUMENTATION.md
+++ b/docs/DOCUMENTATION.md
@@ -0,0 +1,57 @@
+# PURPOSE
+
+This document describes how documentation in this folder should be organized and supersedes any other instructions.
+
+# FOLDERS
+
+## ARCHITECTURE
+
+The architecture folder should contain documentation reflecting the current design of the system and should be updated at the end of each release to ensure it is current.
+
+## DECISIONS
+
+This folder contains any architectural decisions, documented as ADRs.
+
+- Format: `ADR-NNN-brief-title.md` (numbered sequentially)
+- Create an ADR when making architectural decisions, choosing between technical approaches, or establishing patterns
+
+## DESIGN
+
+This folder is used by the architect to document implementation designs to be handed off to the developer. These designs should be sorted into subfolders reflecting the semantic version number of the release in question (e.g., `v1.0.0/`, `v1.1.1/`).
+
+All developer interaction belongs in the appropriate version subfolder:
+- Implementation designs and specifications
+- Developer questions to the architect
+- Architect responses
+- Implementation reports (format: `YYYY-MM-DD-description.md`)
+- Implementation reviews
+
+## PROJECTPLAN
+
+This folder contains documents relating to the future state of the project. There should be a single BACKLOG.md file that lists future features by priority as well as bugs (which are assumed to be high priority). Items in this file can have one of the following priorities:
+
+- Critical - Items that break existing functionality
+- High
+- Medium
+- Low
+
+In addition to the backlog file each version should have a folder named for its semantic version with a RELEASE.md file which lists the features and bugs to be addressed in that release.
+
+## STANDARDS
+
+Includes any standards written by the architect that the developer needs to reference during development. Any deprecated standards should be moved to the DEPRECATED subfolder when appropriate.
+
+# WHERE TO FIND DOCUMENTATION
+
+- **Before implementing a feature**: Check `decisions/` for relevant ADRs and `design/{version}/` for specifications
+- **Understanding system architecture**: Start with `architecture/`
+- **Coding guidelines**: See `standards/`
+- **Past implementation context**: Review `design/{version}/` for similar work
+- **Project roadmap and scope**: Refer to `projectplan/`
+
+# KEY REFERENCES
+
+- **Architecture**: `architecture/`
+- **Coding Standards**: `standards/python-coding-standards.md`
+- **Testing**: `standards/testing-checklist.md`
+- **Project Backlog**: `projectplan/BACKLOG.md`
--- a/docs/architecture/INDEX.md
+++ b/docs/architecture/INDEX.md
@@ -0,0 +1,82 @@
+# Architecture Documentation Index
+
+This directory contains architectural documentation, system design overviews, component diagrams, and architectural patterns for StarPunk CMS.
+
+## Core Architecture
+
+### System Overview
+- **[overview.md](overview.md)** - Complete system architecture and design principles
+- **[technology-stack.md](technology-stack.md)** - Current technology stack and dependencies
+- **[technology-stack-legacy.md](technology-stack-legacy.md)** - Historical technology decisions
+
+### Feature-Specific Architecture
+
+#### IndieAuth & Authentication
+- **[indieauth-assessment.md](indieauth-assessment.md)** - Assessment of IndieAuth implementation
+- **[indieauth-client-diagnosis.md](indieauth-client-diagnosis.md)** - IndieAuth client diagnostic analysis
+- **[indieauth-endpoint-discovery.md](indieauth-endpoint-discovery.md)** - Endpoint discovery architecture
+- **[indieauth-identity-page.md](indieauth-identity-page.md)** - Identity page architecture
+- **[indieauth-questions-answered.md](indieauth-questions-answered.md)** - Architectural Q&A for IndieAuth
+- **[indieauth-removal-architectural-review.md](indieauth-removal-architectural-review.md)** - Review of custom IndieAuth removal
+- **[indieauth-removal-implementation-guide.md](indieauth-removal-implementation-guide.md)** - Implementation guide for removal
+- **[indieauth-removal-phases.md](indieauth-removal-phases.md)** - Phased removal approach
+- **[indieauth-removal-plan.md](indieauth-removal-plan.md)** - Overall removal plan
+- **[indieauth-token-verification-diagnosis.md](indieauth-token-verification-diagnosis.md)** - Token verification diagnostic analysis
+- **[simplified-auth-architecture.md](simplified-auth-architecture.md)** - Simplified authentication architecture
+- **[endpoint-discovery-answers.md](endpoint-discovery-answers.md)** - Endpoint discovery implementation Q&A
+
+#### Database & Migrations
+- **[database-migration-architecture.md](database-migration-architecture.md)** - Database migration system architecture
+- **[migration-fix-quick-reference.md](migration-fix-quick-reference.md)** - Quick reference for migration fixes
+- **[migration-race-condition-answers.md](migration-race-condition-answers.md)** - Race condition resolution Q&A
+
+#### Syndication
+- **[syndication-architecture.md](syndication-architecture.md)** - RSS feed and syndication architecture
+
+## Version-Specific Architecture
+
+### v1.0.0
+- **[v1.0.0-release-validation.md](v1.0.0-release-validation.md)** - Release validation architecture
+
+### v1.1.0
+- **[v1.1.0-feature-architecture.md](v1.1.0-feature-architecture.md)** - Feature architecture for v1.1.0
+- **[v1.1.0-implementation-decisions.md](v1.1.0-implementation-decisions.md)** - Implementation decisions
+- **[v1.1.0-search-ui-validation.md](v1.1.0-search-ui-validation.md)** - Search UI validation
+- **[v1.1.0-validation-report.md](v1.1.0-validation-report.md)** - Overall validation report
+
+### v1.1.1
+- **[v1.1.1-architecture-overview.md](v1.1.1-architecture-overview.md)** - Architecture overview for v1.1.1
+
+## Phase Documentation
+- **[phase1-completion-guide.md](phase1-completion-guide.md)** - Phase 1 completion guide
+- **[phase-5-validation-report.md](phase-5-validation-report.md)** - Phase 5 validation report
+
+## Review Documentation
+- **[review-v1.0.0-rc.5.md](review-v1.0.0-rc.5.md)** - Architectural review of v1.0.0-rc.5
+
+## How to Use This Documentation
+
+### For New Developers
+1. Start with **overview.md** to understand the system
+2. Review **technology-stack.md** for current technologies
+3. Read feature-specific architecture docs relevant to your work
+
+### For Architects
+1. Review version-specific architecture for historical context
+2. Consult feature-specific docs when making changes
+3. Update relevant docs when architecture changes
+
+### For Contributors
+1. Read **overview.md** for system understanding
+2. Consult specific architecture docs for areas you're working on
+3. Follow patterns documented in architecture files
+
+## Related Documentation
+- **[../decisions/](../decisions/)** - Architectural Decision Records (ADRs)
+- **[../design/](../design/)** - Detailed design documents
+- **[../standards/](../standards/)** - Coding standards and conventions
+
+---
+
+**Last Updated**: 2025-11-25
+**Maintained By**: Documentation Manager Agent
--- a/docs/architecture/syndication-architecture.md
+++ b/docs/architecture/syndication-architecture.md
@@ -0,0 +1,233 @@
+# Syndication Architecture
+
+## Overview
+StarPunk's syndication architecture provides multiple feed formats for content distribution, ensuring broad compatibility with feed readers and IndieWeb tools while maintaining simplicity.
+
+## Current State (v1.1.0)
+```
+┌─────────────┐
+│   Database  │
+│   (Notes)   │
+└──────┬──────┘
+       │
+┌──────▼──────┐
+│  feed.py    │
+│  (RSS 2.0)  │
+└──────┬──────┘
+       │
+┌──────▼──────┐
+│ /feed.xml   │
+│  endpoint   │
+└─────────────┘
+```
+
+## Target Architecture (v1.1.2+)
+```
+┌─────────────┐
+│   Database  │
+│   (Notes)   │
+└──────┬──────┘
+       │
+┌──────▼──────────────────┐
+│   Feed Generation Layer  │
+├──────────┬───────────────┤
+│  feed.py │  json_feed.py │
+│  RSS/ATOM│     JSON      │
+└──────────┴───────────────┘
+       │
+┌──────▼──────────────────┐
+│      Feed Endpoints     │
+├─────────┬───────────────┤
+│/feed.xml│  /feed.atom   │
+│  (RSS)  │    (ATOM)     │
+├─────────┼───────────────┤
+│     /feed.json          │
+│    (JSON Feed)          │
+└─────────────────────────┘
+```
+
+## Design Principles
+
+### 1. Format Independence
+Each syndication format operates independently:
+- No shared state between formats
+- Failures in one don't affect others
+- Can be enabled/disabled individually
+
+### 2. Shared Data Access
+All formats read from the same data source:
+- Single query pattern for notes
+- Consistent ordering (newest first)
+- Same publication status filtering
+
+### 3. Library Leverage
+Maximize use of existing libraries:
+- `feedgen` for RSS and ATOM
+- Native Python `json` for JSON Feed
+- No custom XML generation
+
+## Component Design
+
+### Feed Generation Module (`feed.py`)
+**Current Responsibility**: RSS 2.0 generation
+**Future Enhancement**: Add ATOM generation function
+
+```python
+# Pseudocode structure
+def generate_rss_feed(notes, config) -> str
+def generate_atom_feed(notes, config) -> str  # New
+```
+
+### JSON Feed Module (`json_feed.py`)
+**New Component**: Dedicated JSON Feed generation
+
+```python
+# Pseudocode structure
+def generate_json_feed(notes, config) -> str
+def format_json_item(note) -> dict
+```
+
+### Route Handlers
+Simple pass-through to generation functions:
+```python
+@app.route('/feed.xml')  # Existing
+@app.route('/feed.atom') # New
+@app.route('/feed.json') # New
+```
+
+## Data Flow
+
+1. **Request**: Client requests feed at endpoint
+2. **Query**: Fetch published notes from database
+3. **Transform**: Convert notes to format-specific structure
+4. **Serialize**: Generate final output (XML/JSON)
+5. **Response**: Return with appropriate Content-Type
+
+## Microformats2 Architecture
+
+### Template Layer Enhancement
+Microformats2 operates at the HTML template layer:
+
+```
+┌──────────────┐
+│  Data Model  │
+│   (Notes)    │
+└──────┬───────┘
+       │
+┌──────▼───────┐
+│  Templates   │
+│  + mf2 markup│
+└──────┬───────┘
+       │
+┌──────▼───────┐
+│  HTML Output │
+│  (Semantic)  │
+└──────────────┘
+```
+
+### Markup Strategy
+- **Progressive Enhancement**: Add classes without changing structure
+- **CSS Independence**: Use mf2-specific classes, not styling classes
+- **Validation First**: Test with parsers during development
+
+## Configuration Requirements
+
+### New Configuration Variables
+```ini
+# Author information for h-card
+AUTHOR_NAME = "Site Author"
+AUTHOR_URL = "https://example.com"
+AUTHOR_PHOTO = "/static/avatar.jpg"  # Optional
+
+# Feed settings
+FEED_LIMIT = 50
+FEED_FORMATS = "rss,atom,json"  # Comma-separated
+```
+
+## Performance Considerations
+
+### Caching Strategy
+- Feed generation is read-heavy, write-light
+- Consider caching generated feeds (5-minute TTL)
+- Invalidate cache on note creation/update
+
+### Resource Usage
+- RSS/ATOM: ~O(n) memory for n notes
+- JSON Feed: Similar memory profile
+- Microformats2: No additional server resources
+
+## Security Considerations
+
+### Content Sanitization
+- HTML in feeds must be properly escaped
+- CDATA wrapping for RSS/ATOM
+- JSON string encoding for JSON Feed
+- No script injection vectors
+
+### Rate Limiting
+- Apply same limits as HTML endpoints
+- Consider aggressive caching for feeds
+- Monitor for feed polling abuse
+
+## Testing Architecture
+
+### Unit Tests
+```
+tests/
+├── test_feed.py          # Enhanced for ATOM
+├── test_json_feed.py     # New test module
+└── test_microformats.py  # Template parsing tests
+```
+
+### Integration Tests
+- Validate against external validators
+- Test feed reader compatibility
+- Verify IndieWeb tool parsing
+
+## Backwards Compatibility
+
+### URL Structure
+- `/feed.xml` remains RSS 2.0 (no breaking change)
+- New endpoints are additive only
+- Auto-discovery links updated in templates
+
+### Database
+- No schema changes required
+- All features use existing Note model
+- No migration needed
+
+## Future Extensibility
+
+### Potential Enhancements
+1. Content negotiation on `/feed`
+2. WebSub (PubSubHubbub) support
+3. Custom feed filtering (by tag, date)
+4. Feed pagination for large sites
+
+### Format Support Matrix
+| Format | v1.1.0 | v1.1.2 | v1.2.0 |
+|--------|--------|--------|--------|
+| RSS 2.0 | ✅ | ✅ | ✅ |
+| ATOM | ❌ | ✅ | ✅ |
+| JSON Feed | ❌ | ✅ | ✅ |
+| Microformats2 | Partial | Partial | ✅ |
+
+## Decision Rationale
+
+### Why Multiple Formats?
+1. **No Universal Standard**: Different ecosystems prefer different formats
+2. **Low Maintenance**: Feed formats are stable, rarely change
+3. **User Choice**: Let users pick their preferred format
+4. **IndieWeb Philosophy**: Embrace plurality and interoperability
+
+### Why This Architecture?
+1. **Simplicity**: Each component has single responsibility
+2. **Testability**: Isolated components are easier to test
+3. **Maintainability**: Changes to one format don't affect others
+4. **Performance**: Can optimize each format independently
+
+## References
+- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
+- [ATOM RFC 4287](https://tools.ietf.org/html/rfc4287)
+- [JSON Feed Specification](https://www.jsonfeed.org/)
+- [Microformats2](https://microformats.org/wiki/microformats2)
--- a/docs/decisions/ADR-033-database-migration-redesign.md
+++ b/docs/decisions/ADR-033-database-migration-redesign.md
@@ -0,0 +1,98 @@
+# ADR-033: Database Migration System Redesign
+
+## Status
+Proposed
+
+## Context
+The current migration system has a critical flaw: duplicate schema definitions exist between SCHEMA_SQL (used for fresh installs) and individual migration files. This violates the DRY principle and creates maintenance burden. When schema changes are made, developers must remember to update both locations, leading to potential inconsistencies.
+
+Current problems:
+1. Duplicate schema definitions in SCHEMA_SQL and migration files
+2. Risk of schema drift between fresh installs and upgraded databases
+3. Maintenance overhead of keeping two schema sources in sync
+4. Confusion about which schema definition is authoritative
+
+## Decision
+Implement an INITIAL_SCHEMA_SQL approach where:
+
+1. **Single Source of Truth**: The initial schema (v1.0.0 state) is defined once in INITIAL_SCHEMA_SQL
+2. **Migration-Only Changes**: All schema changes after v1.0.0 are defined only in migration files
+3. **Fresh Install Path**: New installations run INITIAL_SCHEMA_SQL + all migrations in sequence
+4. **Upgrade Path**: Existing installations only run new migrations from their current version
+5. **Version Tracking**: The migrations table continues to track applied migrations
+6. **Lightweight System**: Maintain custom migration system without heavyweight ORMs
+
+Implementation approach:
+```python
+# Conceptual flow (not actual code)
+def initialize_database():
+    if is_fresh_install():
+        execute(INITIAL_SCHEMA_SQL)  # v1.0.0 schema
+        mark_initial_version()
+    apply_pending_migrations()  # Apply any migrations after v1.0.0
+```
+
+## Rationale
+This approach provides several benefits:
+
+1. **DRY Compliance**: Schema for any version is defined exactly once
+2. **Clear History**: Migration files form a clear changelog of schema evolution
+3. **Reduced Errors**: No risk of forgetting to update duplicate definitions
+4. **Maintainability**: Easier to understand what changed when
+5. **Simplicity**: Still lightweight, no heavy dependencies
+6. **Compatibility**: Works with existing migration infrastructure
+
+Alternative approaches considered:
+- **SQLAlchemy/Alembic**: Too heavyweight for a minimal CMS
+- **Django-style migrations**: Requires ORM, adds complexity
+- **Status quo**: Maintaining duplicate schemas is error-prone
+- **Single evolving schema file**: Loses history of changes
+
+## Consequences
+### Positive
+- Single source of truth for each schema state
+- Clear separation between initial schema and evolution
+- Easier onboarding for new developers
+- Reduced maintenance burden
+- Better documentation of schema evolution
+
+### Negative
+- One-time migration to new system required
+- Must carefully preserve v1.0.0 schema state in INITIAL_SCHEMA_SQL
+- Fresh installs run more SQL statements (initial + migrations)
+
+### Implementation Requirements
+1. Extract current v1.0.0 schema to INITIAL_SCHEMA_SQL
+2. Remove schema definitions from existing migration files
+3. Update migration runner to handle initial schema
+4. Test both fresh install and upgrade paths thoroughly
+5. Document the new approach clearly
+
+## Alternatives Considered
+
+### Alternative 1: SQLAlchemy/Alembic
+- **Pros**: Industry standard, automatic migration generation
+- **Cons**: Heavy dependency, requires ORM adoption, against minimal philosophy
+- **Rejected because**: Overkill for single-table schema
+
+### Alternative 2: Single Evolving Schema File
+- **Pros**: Simple, one file to maintain
+- **Cons**: No history, can't track changes, upgrade path unclear
+- **Rejected because**: Loses important schema evolution history
+
+### Alternative 3: Status Quo (Duplicate Schemas)
+- **Pros**: Already implemented, works currently
+- **Cons**: DRY violation, error-prone, maintenance burden
+- **Rejected because**: Technical debt will compound over time
+
+## Migration Plan
+1. **Phase 1**: Document exact v1.0.0 schema state
+2. **Phase 2**: Create INITIAL_SCHEMA_SQL from current state
+3. **Phase 3**: Refactor migration system to use new approach
+4. **Phase 4**: Test extensively with both paths
+5. **Phase 5**: Deploy in v1.1.0 with clear upgrade instructions
+
+## References
+- ADR-032: Migration Requirements (parent decision)
+- Issue: Database schema duplication
+- Similar approach: Rails migrations with schema.rb
--- a/docs/decisions/ADR-034-full-text-search.md
+++ b/docs/decisions/ADR-034-full-text-search.md
@@ -0,0 +1,186 @@
+# ADR-034: Full-Text Search with SQLite FTS5
+
+## Status
+Proposed
+
+## Context
+Users need the ability to search through their notes efficiently. Currently, finding specific content requires manually browsing through notes or using external tools. A built-in search capability is essential for any content management system, especially as the number of notes grows.
+
+Requirements:
+- Fast search across all note content
+- Support for phrase searching and boolean operators
+- Ranking by relevance
+- Minimal performance impact on write operations
+- No external dependencies (Elasticsearch, Solr, etc.)
+- Works with existing SQLite database
+
+## Decision
+Implement full-text search using SQLite's FTS5 (Full-Text Search version 5) extension:
+
+1. **FTS5 Virtual Table**: Create a shadow FTS table that indexes note content
+2. **Synchronized Updates**: Keep FTS index in sync with note operations
+3. **Search Endpoint**: New `/api/search` endpoint for queries
+4. **Search UI**: Simple search interface in the web UI
+5. **Advanced Operators**: Support FTS5's query syntax for power users
+
+Database schema:
+```sql
+-- FTS5 virtual table for note content
+CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+    slug UNINDEXED,  -- For result retrieval, not searchable
+    title,           -- Note title (first line)
+    content,         -- Full markdown content
+    tokenize='porter unicode61'  -- Stem words, handle unicode
+);
+
+-- Trigger to keep FTS in sync with notes table
+CREATE TRIGGER notes_fts_insert AFTER INSERT ON notes
+BEGIN
+    INSERT INTO notes_fts (rowid, slug, title, content)
+    SELECT id, slug, title_from_content(content), content
+    FROM notes WHERE id = NEW.id;
+END;
+
+-- Similar triggers for UPDATE and DELETE
+```
+
+## Rationale
+SQLite FTS5 is the optimal choice because:
+
+1. **Native Integration**: Built into SQLite, no external dependencies
+2. **Performance**: Highly optimized C implementation
+3. **Features**: Rich query syntax (phrases, NEAR, boolean, wildcards)
+4. **Ranking**: Built-in BM25 ranking algorithm
+5. **Simplicity**: Just another table in our existing database
+6. **Maintenance-free**: No separate search service to manage
+7. **Size**: Minimal storage overhead (~30% of original text)
+
+Query capabilities:
+- Simple terms: `indieweb`
+- Phrases: `"static site"`
+- Wildcards: `micro*`
+- Boolean: `micropub OR websub`
+- Exclusions: `indieweb NOT wordpress`
+- Field-specific: `title:announcement`
+
+## Consequences
+### Positive
+- Powerful search with zero external dependencies
+- Fast queries even with thousands of notes
+- Rich query syntax for power users
+- Automatic stemming (search "running" finds "run", "runs")
+- Unicode support for international content
+- Integrates seamlessly with existing SQLite database
+
+### Negative
+- FTS index increases database size by ~30%
+- Initial indexing of existing notes required
+- Must maintain sync triggers for consistency
+- FTS5 requires SQLite 3.9.0+ (2015, widely available)
+- Cannot search in encrypted/binary content
+
+### Performance Characteristics
+- Index build: ~1ms per note
+- Search query: <10ms for 10,000 notes
+- Index size: ~30% of indexed text
+- Write overhead: ~5% increase in note creation time
+
+## Alternatives Considered
+
+### Alternative 1: Simple LIKE Queries
+```sql
+SELECT * FROM notes WHERE content LIKE '%search term%'
+```
+- **Pros**: No setup, works today
+- **Cons**: Extremely slow on large datasets, no ranking, no advanced features
+- **Rejected because**: Performance degrades quickly with scale
+
+### Alternative 2: External Search Service (Elasticsearch/Meilisearch)
+- **Pros**: More features, dedicated search infrastructure
+- **Cons**: External dependency, complex setup, overkill for single-user CMS
+- **Rejected because**: Violates minimal philosophy, adds operational complexity
+
+### Alternative 3: Client-Side Search (Lunr.js)
+- **Pros**: No server changes needed
+- **Cons**: Must download all content to browser, doesn't scale
+- **Rejected because**: Impractical beyond a few hundred notes
+
+### Alternative 4: Regex/Grep-based Search
+- **Pros**: Powerful pattern matching
+- **Cons**: Slow, no ranking, must read all files from disk
+- **Rejected because**: Poor performance, no relevance ranking
+
+## Implementation Plan
+
+### Phase 1: Database Schema (2 hours)
+1. Add FTS5 table creation to migrations
+2. Create sync triggers for INSERT/UPDATE/DELETE
+3. Build initial index from existing notes
+4. Test sync on note operations
+
+### Phase 2: Search API (2 hours)
+1. Create `/api/search` endpoint
+2. Implement query parser and validation
+3. Add result ranking and pagination
+4. Return structured results with snippets
+
+### Phase 3: Search UI (1 hour)
+1. Add search box to navigation
+2. Create search results page
+3. Highlight matching terms in results
+4. Add search query syntax help
+
+### Phase 4: Testing (1 hour)
+1. Test with various query types
+2. Benchmark with large datasets
+3. Verify sync triggers work correctly
+4. Test Unicode and special characters
+
+## API Design
+
+### Search Endpoint
+```
+GET /api/search?q={query}&limit=20&offset=0
+
+Response:
+{
+    "query": "indieweb micropub",
+    "total": 15,
+    "results": [
+        {
+            "slug": "implementing-micropub",
+            "title": "Implementing Micropub",
+            "snippet": "...the <mark>IndieWeb</mark> <mark>Micropub</mark> specification...",
+            "rank": 2.4,
+            "published": true,
+            "created_at": "2024-01-15T10:00:00Z"
+        }
+    ]
+}
+```
+
+### Query Syntax Examples
+- `indieweb` - Find notes containing "indieweb"
+- `"static site"` - Exact phrase
+- `micro*` - Prefix search
+- `title:announcement` - Search in title only
+- `micropub OR websub` - Boolean operators
+- `indieweb -wordpress` - Exclusion
+
+## Security Considerations
+1. Sanitize queries to prevent SQL injection (FTS5 handles this)
+2. Rate limit search endpoint to prevent abuse
+3. Only search published notes for anonymous users
+4. Escape HTML in snippets to prevent XSS
+
+## Migration Strategy
+1. Check SQLite version supports FTS5 (3.9.0+)
+2. Create FTS table and triggers in migration
+3. Build initial index from existing notes
+4. Monitor index size and performance
+5. Document search syntax for users
+
+## References
+- SQLite FTS5 Documentation: https://www.sqlite.org/fts5.html
+- BM25 Ranking: https://en.wikipedia.org/wiki/Okapi_BM25
+- FTS5 Performance: https://www.sqlite.org/fts5.html#performance
--- a/docs/decisions/ADR-035-custom-slugs.md
+++ b/docs/decisions/ADR-035-custom-slugs.md
@@ -0,0 +1,204 @@
+# ADR-035: Custom Slugs in Micropub
+
+## Status
+Proposed
+
+## Context
+Currently, StarPunk auto-generates slugs from note content (first 5 words). While this works well for most cases, users may want to specify custom slugs for:
+- SEO-friendly URLs
+- Memorable short links
+- Maintaining URL structure from migrated content
+- Creating hierarchical paths (e.g., `2024/11/my-note`)
+- Personal preference and control
+
+The Micropub specification supports custom slugs via the `mp-slug` property, which we should honor.
+
+## Decision
+Implement custom slug support through the Micropub endpoint:
+
+1. **Accept mp-slug**: Process the `mp-slug` property in Micropub requests
+2. **Validation**: Ensure slugs are URL-safe and unique
+3. **Fallback**: Auto-generate if no slug provided or if invalid
+4. **Conflict Resolution**: Handle duplicate slugs gracefully
+5. **Character Restrictions**: Allow only URL-safe characters
+
+Implementation approach:
+```python
+def process_micropub_request(request_data):
+    # Extract custom slug if provided
+    custom_slug = request_data.get('properties', {}).get('mp-slug', [None])[0]
+
+    if custom_slug:
+        # Validate and sanitize
+        slug = sanitize_slug(custom_slug)
+
+        # Ensure uniqueness
+        if slug_exists(slug):
+            # Add suffix or reject based on configuration
+            slug = make_unique(slug)
+    else:
+        # Fall back to auto-generation
+        slug = generate_slug(content)
+
+    return create_note(content, slug=slug)
+```
+
+## Rationale
+Supporting custom slugs provides:
+
+1. **User Control**: Authors can define meaningful URLs
+2. **Standards Compliance**: Follows Micropub specification
+3. **Migration Support**: Easier to preserve URLs when migrating
+4. **SEO Benefits**: Human-readable URLs improve discoverability
+5. **Flexibility**: Accommodates different URL strategies
+6. **Backward Compatible**: Existing auto-generation continues working
+
+Validation rules:
+- Maximum length: 200 characters
+- Allowed characters: `a-z0-9-_/`
+- No consecutive slashes or dashes
+- No leading/trailing special characters
+- Case-insensitive uniqueness check
+
+## Consequences
+### Positive
+- Full Micropub compliance for slug handling
+- Better user experience and control
+- SEO-friendly URLs when desired
+- Easier content migration from other platforms
+- Maintains backward compatibility
+
+### Negative
+- Additional validation complexity
+- Potential for user confusion with conflicts
+- Must handle edge cases (empty, invalid, duplicate)
+- Slightly more complex note creation logic
+
+### Security Considerations
+1. **Path Traversal**: Reject slugs containing `..` or absolute paths
+2. **Reserved Names**: Block system routes (`api`, `admin`, `feed`, etc.)
+3. **Length Limits**: Enforce maximum slug length
+4. **Character Filtering**: Strip or reject dangerous characters
+5. **Case Sensitivity**: Normalize to lowercase for consistency
+
+## Alternatives Considered
+
+### Alternative 1: No Custom Slugs
+- **Pros**: Simpler, no validation needed
+- **Cons**: Poor user experience, non-compliant with Micropub
+- **Rejected because**: Users expect URL control in modern CMS
+
+### Alternative 2: Separate Slug Field in UI
+- **Pros**: More discoverable for web users
+- **Cons**: Doesn't help API users, not Micropub standard
+- **Rejected because**: Should follow established standards
+
+### Alternative 3: Slugs Only via Direct API
+- **Pros**: Advanced feature for power users only
+- **Cons**: Inconsistent experience, limits adoption
+- **Rejected because**: Micropub clients expect this feature
+
+### Alternative 4: Hierarchical Slugs (`/2024/11/25/my-note`)
+- **Pros**: Organized structure, date-based archives
+- **Cons**: Complex routing, harder to implement
+- **Rejected because**: Can add later if needed, start simple
+
+## Implementation Plan
+
+### Phase 1: Core Logic (2 hours)
+1. Modify note creation to accept optional slug parameter
+2. Implement slug validation and sanitization
+3. Add uniqueness checking with conflict resolution
+4. Update database schema if needed (no changes expected)
+
+### Phase 2: Micropub Integration (1 hour)
+1. Extract `mp-slug` from Micropub requests
+2. Pass to note creation function
+3. Handle validation errors appropriately
+4. Return proper Micropub responses
+
+### Phase 3: Testing (1 hour)
+1. Test valid custom slugs
+2. Test invalid characters and patterns
+3. Test duplicate slug handling
+4. Test with Micropub clients
+5. Test auto-generation fallback
+
+## Validation Specification
+
+### Allowed Slug Format
+```regex
+^[a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*$
+```
+
+Examples:
+- ✅ `my-awesome-post`
+- ✅ `2024/11/25/daily-note`
+- ✅ `projects/starpunk/update-1`
+- ❌ `My-Post` (uppercase)
+- ❌ `my--post` (consecutive dashes)
+- ❌ `-my-post` (leading dash)
+- ❌ `my_post` (underscore not allowed)
+- ❌ `../../../etc/passwd` (path traversal)
+
+### Reserved Slugs
+The following slugs are reserved and cannot be used:
+- System routes: `api`, `admin`, `auth`, `feed`, `static`
+- Special pages: `login`, `logout`, `settings`
+- File extensions: Slugs ending in `.xml`, `.json`, `.html`
+
+### Conflict Resolution Strategy
+When a duplicate slug is detected:
+1. Append `-2`, `-3`, etc. to make unique
+2. Check up to `-99` before failing
+3. Return error if no unique slug found in 99 attempts
+
+Example:
+- Request: `mp-slug=my-note`
+- Exists: `my-note`
+- Created: `my-note-2`
+
+## API Examples
+
+### Micropub Request with Custom Slug
+```http
+POST /micropub
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+    "type": ["h-entry"],
+    "properties": {
+        "content": ["My awesome post content"],
+        "mp-slug": ["my-awesome-post"]
+    }
+}
+```
+
+### Response
+```http
+HTTP/1.1 201 Created
+Location: https://example.com/note/my-awesome-post
+```
+
+### Invalid Slug Handling
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+```
+
+## Migration Notes
+1. Existing notes keep their auto-generated slugs
+2. No database migration required (slug field exists)
+3. No breaking changes to API
+4. Existing clients continue working without modification
+
+## References
+- Micropub Specification: https://www.w3.org/TR/micropub/#mp-slug
+- URL Slug Best Practices: https://stackoverflow.com/questions/695438/safe-characters-for-friendly-url
+- IndieWeb Slug Examples: https://indieweb.org/slug
+## References
+- Micropub Specification: https://www.w3.org/TR/micropub/#mp-slug
+- URL Slug Best Practices: https://stackoverflow.com/questions/695438/safe-characters-for-friendly-url
+- IndieWeb Slug Examples: https://indieweb.org/slug
--- a/docs/decisions/ADR-036-indieauth-token-verification-method.md
+++ b/docs/decisions/ADR-036-indieauth-token-verification-method.md
@@ -0,0 +1,114 @@
+# ADR-036: IndieAuth Token Verification Method Diagnosis
+
+## Status
+Accepted
+
+## Context
+StarPunk is experiencing HTTP 405 Method Not Allowed errors when verifying tokens with the external IndieAuth provider (gondulf.thesatelliteoflove.com). The user questioned "why are we making GET requests to these endpoints?"
+
+Error from logs:
+```
+[2025-11-25 03:29:50] WARNING: Token verification failed:
+  Verification failed: Unexpected response: HTTP 405
+```
+
+## Investigation Results
+
+### What the IndieAuth Spec Says
+According to the W3C IndieAuth specification (Section 6.3.4 - Token Verification):
+- Token verification MUST use a **GET request** to the token endpoint
+- The request must include an Authorization header with Bearer token format
+- This is explicitly different from token issuance, which uses POST
+
+### What Our Code Does
+Our implementation in `starpunk/auth_external.py` (line 425):
+- **Correctly** uses GET for token verification
+- **Correctly** sends Authorization: Bearer header
+- **Correctly** follows the IndieAuth specification
+
+### Why the 405 Error Occurs
+HTTP 405 Method Not Allowed means the server doesn't support the HTTP method (GET) for the requested resource. This indicates that the gondulf IndieAuth provider is **not implementing the IndieAuth specification correctly**.
+
+## Decision
+Our implementation is correct. We are making GET requests because:
+1. The IndieAuth spec explicitly requires GET for token verification
+2. This distinguishes verification (GET) from token issuance (POST)
+3. This is a standard pattern in OAuth-like protocols
+
+## Rationale
+
+### Why GET for Verification?
+The IndieAuth spec uses different HTTP methods for different operations:
+- **POST** for state-changing operations (issuing tokens, revoking tokens)
+- **GET** for read-only operations (verifying tokens)
+
+This follows RESTful principles where:
+- GET is idempotent and safe (doesn't modify server state)
+- POST creates or modifies resources
+
+### The Problem
+The gondulf IndieAuth provider appears to only support POST on its token endpoint, not implementing the full IndieAuth specification which requires both:
+- POST for token issuance (Section 6.3)
+- GET for token verification (Section 6.3.4)
+
+## Consequences
+
+### Immediate Impact
+- StarPunk cannot verify tokens with gondulf.thesatelliteoflove.com
+- The provider needs to be fixed to support GET requests for verification
+- Our code is correct and should NOT be changed
+
+### Potential Solutions
+1. **Provider Fix** (Recommended): The gondulf IndieAuth provider should implement GET support for token verification per spec
+2. **Provider Switch**: Use a compliant IndieAuth provider that fully implements the specification
+3. **Non-Compliant Mode** (Not Recommended): Add a workaround to use POST for verification with non-compliant providers
+
+## Alternatives Considered
+
+### Alternative 1: Use POST for Verification
+- **Rejected**: Violates IndieAuth specification
+- Would make StarPunk non-compliant
+- Would create confusion about proper IndieAuth implementation
+
+### Alternative 2: Support Both GET and POST
+- **Rejected**: Adds complexity without benefit
+- The spec is clear: GET is required
+- Supporting non-standard behavior encourages poor implementations
+
+### Alternative 3: Document Provider Requirements
+- **Accepted as Additional Action**: We should clearly document that StarPunk requires IndieAuth providers that fully implement the W3C specification
+
+## Technical Details
+
+### Correct Token Verification Flow
+```
+Client → GET /token
+         Authorization: Bearer {token}
+
+Server → 200 OK
+         {
+           "me": "https://user.example.net/",
+           "client_id": "https://app.example.com/",
+           "scope": "create update"
+         }
+```
+
+### What Gondulf Is Doing Wrong
+```
+Client → GET /token
+         Authorization: Bearer {token}
+
+Server → 405 Method Not Allowed
+         (Server only accepts POST)
+```
+
+## References
+- [W3C IndieAuth Specification - Token Verification](https://www.w3.org/TR/indieauth/#token-verification)
+- [W3C IndieAuth Specification - Token Endpoint](https://www.w3.org/TR/indieauth/#token-endpoint)
+- StarPunk Implementation: `/home/phil/Projects/starpunk/starpunk/auth_external.py`
+
+## Recommendation
+1. Contact the gondulf IndieAuth provider maintainer and inform them their implementation is non-compliant
+2. Provide them with the W3C spec reference showing GET is required for verification
+3. Do NOT modify StarPunk's code - it is correct
+4. Consider adding a note in our documentation about provider compliance requirements
--- a/docs/decisions/ADR-037-migration-race-condition-fix.md
+++ b/docs/decisions/ADR-037-migration-race-condition-fix.md
--- a/docs/decisions/ADR-038-syndication-formats.md
+++ b/docs/decisions/ADR-038-syndication-formats.md
@@ -0,0 +1,50 @@
+# ADR-022: Multiple Syndication Format Support
+
+## Status
+Proposed
+
+## Context
+StarPunk currently provides RSS 2.0 feed generation using the feedgen library. The IndieWeb community and modern feed readers increasingly support additional syndication formats:
+- ATOM feeds (RFC 4287) - W3C/IETF standard XML format
+- JSON Feed (v1.1) - Modern JSON-based format gaining adoption
+- Microformats2 - Already partially implemented for IndieWeb parsing
+
+Multiple syndication formats increase content reach and client compatibility.
+
+## Decision
+Implement ATOM and JSON Feed support alongside existing RSS 2.0, maintaining all three formats in parallel.
+
+## Rationale
+1. **Low Implementation Complexity**: The feedgen library already supports ATOM generation with minimal code changes
+2. **JSON Feed Simplicity**: JSON structure maps directly to our Note model, easier than XML
+3. **Standards Alignment**: Both formats are well-specified and stable
+4. **User Choice**: Different clients prefer different formats
+5. **Minimal Maintenance**: Once implemented, feed formats rarely change
+
+## Consequences
+### Positive
+- Broader client compatibility
+- Better IndieWeb ecosystem integration
+- Leverages existing feedgen dependency for ATOM
+- JSON Feed provides modern alternative to XML
+
+### Negative
+- Three feed endpoints to maintain
+- Slightly increased test surface
+- Additional routes in API
+
+## Alternatives Considered
+1. **Single Universal Format**: Rejected - different clients have different preferences
+2. **Content Negotiation**: Too complex for minimal benefit
+3. **Plugin System**: Over-engineering for 3 stable formats
+
+## Implementation Approach
+1. ATOM: Use feedgen's built-in ATOM support (5-10 lines different from RSS)
+2. JSON Feed: Direct serialization from Note models (~50 lines)
+3. Routes: `/feed.xml` (RSS), `/feed.atom` (ATOM), `/feed.json` (JSON)
+
+## Effort Estimate
+- ATOM Feed: 2-4 hours (mostly testing)
+- JSON Feed: 4-6 hours (new serialization logic)
+- Tests & Documentation: 2-3 hours
+- Total: 8-13 hours
--- a/docs/decisions/ADR-039-micropub-url-construction-fix.md
+++ b/docs/decisions/ADR-039-micropub-url-construction-fix.md
@@ -0,0 +1,144 @@
+# ADR-039: Micropub URL Construction Fix
+
+## Status
+Accepted
+
+## Context
+After the v1.0.0 release, a bug was discovered in the Micropub implementation where the Location header returned after creating a post contains a double slash:
+
+- **Expected**: `https://starpunk.thesatelliteoflove.com/notes/so-starpunk-v100-is-complete`
+- **Actual**: `https://starpunk.thesatelliteoflove.com//notes/so-starpunk-v100-is-complete`
+
+### Root Cause Analysis
+The issue occurs due to a mismatch between how SITE_URL is stored and used:
+
+1. **Configuration Storage** (`starpunk/config.py`):
+   - SITE_URL is normalized to always end with a trailing slash (lines 26, 92)
+   - This is required for IndieAuth/OAuth specs where root URLs must have trailing slashes
+   - Example: `https://starpunk.thesatelliteoflove.com/`
+
+2. **URL Construction** (`starpunk/micropub.py`):
+   - Constructs URLs using: `f"{site_url}/notes/{note.slug}"` (lines 311, 381)
+   - This adds a leading slash to the path segment
+   - Results in: `https://starpunk.thesatelliteoflove.com/` + `/notes/...` = double slash
+
+3. **Inconsistent Handling**:
+   - RSS feed module (`starpunk/feed.py`) correctly strips trailing slash before use (line 77)
+   - Micropub module doesn't handle this, causing the bug
+
+## Decision
+Fix the URL construction in the Micropub module by removing the leading slash from the path segment. This maintains the trailing slash convention in SITE_URL while ensuring correct URL construction.
+
+### Implementation Approach
+Change the URL construction pattern from:
+```python
+permalink = f"{site_url}/notes/{note.slug}"
+```
+
+To:
+```python
+permalink = f"{site_url}notes/{note.slug}"
+```
+
+This works because SITE_URL is guaranteed to have a trailing slash.
+
+### Affected Code Locations
+1. `starpunk/micropub.py` line 311 - Location header in `handle_create`
+2. `starpunk/micropub.py` line 381 - URL in Microformats2 response in `handle_query`
+
+## Rationale
+
+### Why Not Strip the Trailing Slash?
+We could follow the RSS feed approach and strip the trailing slash:
+```python
+site_url = site_url.rstrip("/")
+permalink = f"{site_url}/notes/{note.slug}"
+```
+
+However, this approach has downsides:
+- Adds unnecessary processing to every request
+- Creates inconsistency with how SITE_URL is used elsewhere
+- The trailing slash is intentionally added for IndieAuth compliance
+
+### Why This Solution?
+- **Minimal change**: Only modifies the string literal, not the logic
+- **Consistent**: SITE_URL remains normalized with trailing slash throughout
+- **Efficient**: No runtime string manipulation needed
+- **Clear intent**: The code explicitly shows we expect SITE_URL to end with `/`
+
+## Consequences
+
+### Positive
+- Fixes the immediate bug with minimal code changes
+- No configuration changes required
+- No database migrations needed
+- Backward compatible - doesn't break existing data
+- Fast to implement and test
+
+### Negative
+- Developers must remember that SITE_URL has a trailing slash
+- Could be confusing without documentation
+- Potential for similar bugs if pattern isn't followed elsewhere
+
+### Mitigation
+- Add a comment at each URL construction site explaining the trailing slash convention
+- Consider adding a utility function in future versions for URL construction
+- Document the SITE_URL trailing slash convention clearly
+
+## Alternatives Considered
+
+### 1. Strip Trailing Slash at Usage Site
+```python
+site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip("/")
+permalink = f"{site_url}/notes/{note.slug}"
+```
+- **Pros**: More explicit, follows RSS feed pattern
+- **Cons**: Extra processing, inconsistent with config intention
+
+### 2. Remove Trailing Slash from Configuration
+Modify `config.py` to not add trailing slashes to SITE_URL.
+- **Pros**: Simpler URL construction
+- **Cons**: Breaks IndieAuth spec compliance, requires migration for existing deployments
+
+### 3. Create URL Builder Utility
+```python
+def build_url(base, *segments):
+    """Build URL from base and path segments"""
+    return "/".join([base.rstrip("/")] + list(segments))
+```
+- **Pros**: Centralized URL construction, prevents future bugs
+- **Cons**: Over-engineering for a simple fix, adds unnecessary abstraction for v1.0.1
+
+### 4. Use urllib.parse.urljoin
+```python
+from urllib.parse import urljoin
+permalink = urljoin(site_url, f"notes/{note.slug}")
+```
+- **Pros**: Standard library solution, handles edge cases
+- **Cons**: Adds import, slightly less readable, overkill for this use case
+
+## Implementation Notes
+
+### Version Impact
+- Current version: v1.0.0
+- Fix version: v1.0.1 (PATCH increment - backward-compatible bug fix)
+
+### Testing Requirements
+1. Verify Location header has single slash
+2. Test with various SITE_URL configurations (with/without trailing slash)
+3. Ensure RSS feed still works correctly
+4. Check all other URL constructions in the codebase
+
+### Release Type
+This qualifies as a **hotfix** because:
+- It fixes a bug in production (v1.0.0)
+- The fix is isolated and low-risk
+- No new features or breaking changes
+- Critical for proper Micropub client operation
+
+## References
+- [Issue Report]: Malformed redirect URL in Micropub implementation
+- [W3C Micropub Spec](https://www.w3.org/TR/micropub/): Location header requirements
+- [IndieAuth Spec](https://indieauth.spec.indieweb.org/): Client ID URL requirements
+- ADR-028: Micropub Implementation Strategy
+- docs/standards/versioning-strategy.md: Version increment guidelines
--- a/docs/decisions/ADR-040-microformats2-compliance.md
+++ b/docs/decisions/ADR-040-microformats2-compliance.md
@@ -0,0 +1,72 @@
+# ADR-023: Strict Microformats2 Compliance
+
+## Status
+Proposed
+
+## Context
+StarPunk currently implements basic microformats2 markup:
+- h-entry on note articles
+- e-content for note content
+- dt-published for timestamps
+- u-url for permalinks
+
+"Strict" microformats2 compliance would add comprehensive markup for full IndieWeb interoperability, enabling better parsing by readers, Webmention receivers, and IndieWeb tools.
+
+## Decision
+Enhance existing templates with complete microformats2 vocabulary, focusing on h-entry, h-card, and h-feed structures.
+
+## Rationale
+1. **Core IndieWeb Requirement**: Microformats2 is fundamental to IndieWeb data exchange
+2. **Template-Only Changes**: No backend modifications required
+3. **Progressive Enhancement**: Adds semantic value without breaking existing functionality
+4. **Standards Maturity**: Microformats2 spec is stable and well-documented
+5. **Testing Tools Available**: Validators exist for compliance verification
+
+## Consequences
+### Positive
+- Full IndieWeb parser compatibility
+- Better social reader integration
+- Improved SEO through semantic markup
+- Enables future Webmention support (v1.3.0)
+
+### Negative
+- More complex HTML templates
+- Careful CSS selector management needed
+- Testing requires microformats2 parser
+
+## Alternatives Considered
+1. **Minimal Compliance**: Current state - rejected as incomplete for IndieWeb tools
+2. **Microdata/RDFa**: Not IndieWeb standard, adds complexity
+3. **JSON-LD**: Additional complexity, not IndieWeb native
+
+## Implementation Scope
+### Required Markup
+1. **h-entry** (complete):
+   - p-name (title extraction)
+   - p-summary (excerpt)
+   - p-category (when tags added)
+   - p-author with embedded h-card
+
+2. **h-card** (author):
+   - p-name (author name)
+   - u-url (author URL)
+   - u-photo (avatar, optional)
+
+3. **h-feed** (index pages):
+   - p-name (feed title)
+   - p-author (feed author)
+   - Nested h-entry items
+
+### Template Updates Required
+- `/templates/base.html` - Add h-card in header
+- `/templates/index.html` - Add h-feed wrapper
+- `/templates/note.html` - Complete h-entry properties
+- `/templates/partials/note_summary.html` - Create for consistent h-entry
+
+## Effort Estimate
+- Template Analysis: 2-3 hours
+- Markup Implementation: 4-6 hours
+- CSS Compatibility Check: 1-2 hours
+- Testing with mf2 parser: 2-3 hours
+- Documentation: 1-2 hours
+- Total: 10-16 hours
--- a/docs/decisions/ADR-042-versioning-strategy-for-authorization-removal.md
+++ b/docs/decisions/ADR-042-versioning-strategy-for-authorization-removal.md
--- a/docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md
+++ b/docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md
@@ -1,7 +1,7 @@
-# ADR-030-CORRECTED: IndieAuth Endpoint Discovery Architecture
+# ADR-043-CORRECTED: IndieAuth Endpoint Discovery Architecture

 ## Status
-Accepted (Replaces incorrect understanding in ADR-030)
+Accepted (Replaces incorrect understanding in previous ADR-030)

 ## Context

--- a/docs/decisions/ADR-044-endpoint-discovery-implementation.md
+++ b/docs/decisions/ADR-044-endpoint-discovery-implementation.md
@@ -112,5 +112,5 @@ Security principle: when in doubt, deny access. We use cached endpoints as a gra
 ## References

 - W3C IndieAuth Specification Section 4.2 (Discovery)
- ADR-030-CORRECTED (Original design)
+- ADR-043-CORRECTED (Original design)
 - Developer analysis report (2025-11-24)
--- a/docs/decisions/ADR-052-configuration-system-architecture.md
+++ b/docs/decisions/ADR-052-configuration-system-architecture.md
@@ -0,0 +1,223 @@
+# ADR-052: Configuration System Architecture
+
+## Status
+Accepted
+
+## Context
+StarPunk v1.1.1 "Polish" introduces several configurable features to improve production readiness and user experience. Currently, configuration values are hardcoded throughout the application, making customization difficult. We need a consistent, simple approach to configuration management that:
+
+1. Maintains backward compatibility
+2. Provides sensible defaults
+3. Follows Python best practices
+4. Minimizes complexity
+5. Supports environment-based configuration
+
+## Decision
+We will implement a centralized configuration system using environment variables with fallback defaults, managed through a single configuration module.
+
+### Configuration Architecture
+
+```
+Environment Variables (highest priority)
+    ↓
+Configuration File (optional, .env)
+    ↓
+Default Values (in code)
+```
+
+### Configuration Module Structure
+
+Location: `starpunk/config.py`
+
+Categories:
+1. **Search Configuration**
+   - `SEARCH_ENABLED`: bool (default: True)
+   - `SEARCH_TITLE_LENGTH`: int (default: 100)
+   - `SEARCH_HIGHLIGHT_CLASS`: str (default: "highlight")
+   - `SEARCH_MIN_SCORE`: float (default: 0.0)
+
+2. **Performance Configuration**
+   - `PERF_MONITORING_ENABLED`: bool (default: False)
+   - `PERF_SLOW_QUERY_THRESHOLD`: float (default: 1.0 seconds)
+   - `PERF_LOG_QUERIES`: bool (default: False)
+   - `PERF_MEMORY_TRACKING`: bool (default: False)
+
+3. **Database Configuration**
+   - `DB_CONNECTION_POOL_SIZE`: int (default: 5)
+   - `DB_CONNECTION_TIMEOUT`: float (default: 10.0)
+   - `DB_WAL_MODE`: bool (default: True)
+   - `DB_BUSY_TIMEOUT`: int (default: 5000 ms)
+
+4. **Logging Configuration**
+   - `LOG_LEVEL`: str (default: "INFO")
+   - `LOG_FORMAT`: str (default: structured JSON)
+   - `LOG_FILE_PATH`: str (default: None)
+   - `LOG_ROTATION`: bool (default: False)
+
+5. **Production Configuration**
+   - `SESSION_TIMEOUT`: int (default: 86400 seconds)
+   - `HEALTH_CHECK_DETAILED`: bool (default: False)
+   - `ERROR_DETAILS_IN_RESPONSE`: bool (default: False)
+
+### Implementation Pattern
+
+```python
+# starpunk/config.py
+import os
+from typing import Any, Optional
+
+class Config:
+    """Centralized configuration management"""
+
+    @staticmethod
+    def get_bool(key: str, default: bool = False) -> bool:
+        """Get boolean configuration value"""
+        value = os.environ.get(key, "").lower()
+        if value in ("true", "1", "yes", "on"):
+            return True
+        elif value in ("false", "0", "no", "off"):
+            return False
+        return default
+
+    @staticmethod
+    def get_int(key: str, default: int) -> int:
+        """Get integer configuration value"""
+        try:
+            return int(os.environ.get(key, default))
+        except (ValueError, TypeError):
+            return default
+
+    @staticmethod
+    def get_float(key: str, default: float) -> float:
+        """Get float configuration value"""
+        try:
+            return float(os.environ.get(key, default))
+        except (ValueError, TypeError):
+            return default
+
+    @staticmethod
+    def get_str(key: str, default: str = "") -> str:
+        """Get string configuration value"""
+        return os.environ.get(key, default)
+
+# Configuration instances
+SEARCH_ENABLED = Config.get_bool("STARPUNK_SEARCH_ENABLED", True)
+SEARCH_TITLE_LENGTH = Config.get_int("STARPUNK_SEARCH_TITLE_LENGTH", 100)
+# ... etc
+```
+
+### Environment Variable Naming Convention
+
+All StarPunk environment variables are prefixed with `STARPUNK_` to avoid conflicts:
+- `STARPUNK_SEARCH_ENABLED`
+- `STARPUNK_PERF_MONITORING_ENABLED`
+- `STARPUNK_DB_CONNECTION_POOL_SIZE`
+- etc.
+
+## Rationale
+
+### Why Environment Variables?
+1. **Standard Practice**: Follows 12-factor app methodology
+2. **Container Friendly**: Works well with Docker/Kubernetes
+3. **No Dependencies**: Built into Python stdlib
+4. **Security**: Sensitive values not in code
+5. **Simple**: No complex configuration parsing
+
+### Why Not Alternative Approaches?
+
+**YAML/TOML/INI Files**:
+- Adds parsing complexity
+- Requires file management
+- Not as container-friendly
+- Additional dependency
+
+**Database Configuration**:
+- Circular dependency (need config to connect to DB)
+- Makes deployment more complex
+- Not suitable for bootstrap configuration
+
+**Python Config Files**:
+- Security risk if user-editable
+- Import complexity
+- Not standard practice
+
+### Why Centralized Module?
+1. **Single Source**: All configuration in one place
+2. **Type Safety**: Helper methods ensure correct types
+3. **Documentation**: Self-documenting defaults
+4. **Testing**: Easy to mock for tests
+5. **Validation**: Can add validation logic centrally
+
+## Consequences
+
+### Positive
+1. **Backward Compatible**: All existing deployments continue working with defaults
+2. **Production Ready**: Ops teams can configure without code changes
+3. **Simple Implementation**: ~100 lines of code
+4. **Testable**: Easy to test different configurations
+5. **Documented**: Configuration options clear in one file
+6. **Flexible**: Can override any setting via environment
+
+### Negative
+1. **Environment Pollution**: Many environment variables in production
+2. **No Validation**: Invalid values fall back to defaults silently
+3. **No Hot Reload**: Requires restart to apply changes
+4. **Limited Types**: Only primitive types supported
+
+### Mitigations
+1. Use `.env` files for local development
+2. Add startup configuration validation
+3. Log configuration values at startup (non-sensitive only)
+4. Document all configuration options clearly
+
+## Alternatives Considered
+
+### 1. Pydantic Settings
+**Pros**: Type validation, .env support, modern
+**Cons**: New dependency, overengineered for our needs
+**Decision**: Too complex for v1.1.1 patch release
+
+### 2. Click Configuration
+**Pros**: Already using Click, integrated CLI options
+**Cons**: CLI args not suitable for all config, complex precedence
+**Decision**: Keep CLI and config separate
+
+### 3. ConfigParser (INI files)
+**Pros**: Python stdlib, familiar format
+**Cons**: File management complexity, not container-native
+**Decision**: Environment variables are simpler
+
+### 4. No Configuration System
+**Pros**: Simplest possible
+**Cons**: No production flexibility, poor UX
+**Decision**: v1.1.1 specifically targets production readiness
+
+## Implementation Notes
+
+1. Configuration module loads at import time
+2. Values are immutable after startup
+3. Invalid values log warnings but use defaults
+4. Sensitive values (tokens, keys) never logged
+5. Configuration documented in deployment guide
+6. Example `.env.example` file provided
+
+## Testing Strategy
+
+1. Unit tests mock environment variables
+2. Integration tests verify default behavior
+3. Configuration validation tests
+4. Performance impact tests (configuration overhead)
+
+## Migration Path
+
+No migration required - all configuration has sensible defaults that match current behavior.
+
+## References
+
+- [The Twelve-Factor App - Config](https://12factor.net/config)
+- [Python os.environ](https://docs.python.org/3/library/os.html#os.environ)
+- [Docker Environment Variables](https://docs.docker.com/compose/environment-variables/)
+
+## Document History
+
+- 2025-11-25: Initial draft for v1.1.1 release planning
--- a/docs/decisions/ADR-053-performance-monitoring-strategy.md
+++ b/docs/decisions/ADR-053-performance-monitoring-strategy.md
@@ -0,0 +1,304 @@
+# ADR-053: Performance Monitoring Strategy
+
+## Status
+Accepted
+
+## Context
+StarPunk v1.1.1 introduces performance monitoring to help operators understand system behavior in production. Currently, we have no visibility into:
+- Database query performance
+- Memory usage patterns
+- Request processing times
+- Bottlenecks and slow operations
+
+We need a lightweight, zero-dependency monitoring solution that provides actionable insights without impacting performance.
+
+## Decision
+Implement a built-in performance monitoring system using Python's standard library, with optional detailed tracking controlled by configuration.
+
+### Architecture Overview
+
+```
+Request → Middleware (timing) → Handler
+              ↓                    ↓
+         Context Manager      Decorators
+              ↓                    ↓
+         Metrics Store ← Database Hooks
+              ↓
+        Admin Dashboard
+```
+
+### Core Components
+
+#### 1. Metrics Collector
+Location: `starpunk/monitoring/collector.py`
+
+Responsibilities:
+- Collect timing data
+- Track memory usage
+- Store recent metrics in memory
+- Provide aggregation functions
+
+Data Structure:
+```python
+@dataclass
+class Metric:
+    timestamp: float
+    category: str  # "db", "http", "function"
+    operation: str  # specific operation name
+    duration: float  # in seconds
+    metadata: dict  # additional context
+```
+
+#### 2. Database Performance Tracking
+Location: `starpunk/monitoring/db_monitor.py`
+
+Features:
+- Query execution timing
+- Slow query detection
+- Query pattern analysis
+- Connection pool monitoring
+
+Implementation via SQLite callbacks:
+```python
+# Wrap database operations
+with monitor.track_query("SELECT", "notes"):
+    cursor.execute(query)
+```
+
+#### 3. Memory Tracking
+Location: `starpunk/monitoring/memory.py`
+
+Track:
+- Process memory (RSS)
+- Memory growth over time
+- Per-request memory delta
+- Memory high water mark
+
+Uses `resource` module (stdlib).
+
+#### 4. Request Performance
+Location: `starpunk/monitoring/http.py`
+
+Track:
+- Request processing time
+- Response size
+- Status code distribution
+- Slowest endpoints
+
+#### 5. Admin Dashboard
+Location: `/admin/performance`
+
+Display:
+- Real-time metrics (last 15 minutes)
+- Slow query log
+- Memory usage graph
+- Endpoint performance table
+- Database statistics
+
+### Data Retention
+
+In-memory circular buffer approach:
+- Last 1000 metrics retained
+- Automatic old data eviction
+- No persistent storage (privacy/simplicity)
+- Reset on restart
+
+### Performance Overhead
+
+Target: <1% overhead when enabled
+
+Strategies:
+- Sampling for high-frequency operations
+- Lazy computation of aggregates
+- Minimal memory footprint (1MB max)
+- Conditional compilation via config
+
+## Rationale
+
+### Why Built-in Monitoring?
+1. **Zero Dependencies**: Uses only Python stdlib
+2. **Privacy**: No external services
+3. **Simplicity**: No complex setup
+4. **Integrated**: Direct access to internals
+5. **Lightweight**: Minimal overhead
+
+### Why Not External Tools?
+
+**Prometheus/Grafana**:
+- Requires external services
+- Complex setup
+- Overkill for single-user system
+
+**APM Services** (New Relic, DataDog):
+- Privacy concerns
+- Subscription costs
+- Network dependency
+- Too heavy for our needs
+
+**OpenTelemetry**:
+- Large dependency
+- Complex configuration
+- Designed for distributed systems
+
+### Design Principles
+
+1. **Opt-in**: Disabled by default
+2. **Lightweight**: Minimal resource usage
+3. **Actionable**: Focus on useful metrics
+4. **Temporary**: No permanent storage
+5. **Private**: No external data transmission
+
+## Consequences
+
+### Positive
+1. **Production Visibility**: Understand behavior under load
+2. **Performance Debugging**: Identify bottlenecks quickly
+3. **No Dependencies**: Pure Python solution
+4. **Privacy Preserving**: Data stays local
+5. **Simple Deployment**: No additional services
+
+### Negative
+1. **Limited History**: Only recent data available
+2. **Memory Usage**: ~1MB for metrics buffer
+3. **No Alerting**: Manual monitoring required
+4. **Single Node**: No distributed tracing
+
+### Mitigations
+1. Export capability for external tools
+2. Configurable buffer size
+3. Webhook support for alerts (future)
+4. Focus on most valuable metrics
+
+## Alternatives Considered
+
+### 1. Logging-based Monitoring
+**Approach**: Parse performance data from logs
+**Pros**: Simple, no new code
+**Cons**: Log parsing complexity, no real-time view
+**Decision**: Dedicated monitoring is cleaner
+
+### 2. External Monitoring Service
+**Approach**: Use service like Sentry
+**Pros**: Full-featured, alerting included
+**Cons**: Privacy, cost, complexity
+**Decision**: Violates self-hosted principle
+
+### 3. Prometheus Exporter
+**Approach**: Expose /metrics endpoint
+**Pros**: Standard, good tooling
+**Cons**: Requires Prometheus setup
+**Decision**: Too complex for target users
+
+### 4. No Monitoring
+**Approach**: Rely on logs and external tools
+**Pros**: Simplest
+**Cons**: Poor production visibility
+**Decision**: v1.1.1 specifically targets production readiness
+
+## Implementation Details
+
+### Instrumentation Points
+
+1. **Database Layer**
+   - All queries automatically timed
+   - Connection acquisition/release
+   - Transaction duration
+   - Migration execution
+
+2. **HTTP Layer**
+   - Middleware wraps all requests
+   - Per-endpoint timing
+   - Static file serving
+   - Error handling
+
+3. **Core Functions**
+   - Note creation/update
+   - Search operations
+   - RSS generation
+   - Authentication flow
+
+### Performance Dashboard Layout
+
+```
+Performance Dashboard
+═══════════════════
+
+Overview
+--------
+Uptime: 5d 3h 15m
+Requests: 10,234
+Avg Response: 45ms
+Memory: 128MB
+
+Slow Queries (>1s)
+------------------
+[timestamp] SELECT ... FROM notes (1.2s)
+[timestamp] UPDATE ... SET ... (1.1s)
+
+Endpoint Performance
+-------------------
+GET /          : avg 23ms, p99 45ms
+GET /notes/:id : avg 35ms, p99 67ms
+POST /micropub : avg 125ms, p99 234ms
+
+Memory Usage
+-----------
+[ASCII graph showing last 15 minutes]
+
+Database Stats
+-------------
+Pool Size: 3/5
+Queries/sec: 4.2
+Cache Hit Rate: 87%
+```
+
+### Configuration Options
+
+```python
+# All under STARPUNK_PERF_* prefix
+MONITORING_ENABLED = False  # Master switch
+SLOW_QUERY_THRESHOLD = 1.0  # seconds
+LOG_QUERIES = False  # Log all queries
+MEMORY_TRACKING = False  # Track memory usage
+SAMPLE_RATE = 1.0  # 1.0 = all, 0.1 = 10%
+BUFFER_SIZE = 1000  # Number of metrics
+DASHBOARD_ENABLED = True  # Enable web UI
+```
+
+## Testing Strategy
+
+1. **Unit Tests**: Mock collectors, verify metrics
+2. **Integration Tests**: End-to-end monitoring flow
+3. **Performance Tests**: Verify low overhead
+4. **Load Tests**: Behavior under stress
+
+## Security Considerations
+
+1. Dashboard requires admin authentication
+2. No sensitive data in metrics
+3. No external data transmission
+4. Metrics cleared on logout
+5. Rate limiting on dashboard endpoint
+
+## Migration Path
+
+No migration required - monitoring is opt-in via configuration.
+
+## Future Enhancements
+
+v1.2.0 and beyond:
+- Metric export (CSV/JSON)
+- Alert thresholds
+- Historical trending
+- Custom metric points
+- Plugin architecture
+
+## References
+
+- [Python resource module](https://docs.python.org/3/library/resource.html)
+- [SQLite Query Performance](https://www.sqlite.org/queryplanner.html)
+- [Web Vitals](https://web.dev/vitals/)
+
+## Document History
+
+- 2025-11-25: Initial draft for v1.1.1 release planning
--- a/docs/decisions/ADR-054-structured-logging-architecture.md
+++ b/docs/decisions/ADR-054-structured-logging-architecture.md
@@ -0,0 +1,355 @@
+# ADR-054: Structured Logging Architecture
+
+## Status
+Accepted
+
+## Context
+StarPunk currently uses print statements and basic logging without structure. For production deployments, we need:
+- Consistent log formatting
+- Appropriate log levels
+- Structured data for parsing
+- Correlation IDs for request tracking
+- Performance-conscious logging
+
+We need a logging architecture that is simple, follows Python best practices, and provides production-grade observability.
+
+## Decision
+Implement structured logging using Python's built-in `logging` module with JSON formatting and contextual information.
+
+### Logging Architecture
+
+```
+Application Code
+      ↓
+Logger Interface → Filters → Formatters → Handlers → Output
+      ↑                                              ↓
+Context Injection                            (stdout/file)
+```
+
+### Log Levels
+
+Following standard Python/syslog levels:
+
+| Level | Value | Usage |
+|-------|-------|-------|
+| CRITICAL | 50 | System failures requiring immediate attention |
+| ERROR | 40 | Errors that need investigation |
+| WARNING | 30 | Unexpected conditions that might cause issues |
+| INFO | 20 | Normal operation events |
+| DEBUG | 10 | Detailed diagnostic information |
+
+### Log Structure
+
+JSON format for production, human-readable for development:
+
+```json
+{
+  "timestamp": "2025-11-25T10:30:45.123Z",
+  "level": "INFO",
+  "logger": "starpunk.micropub",
+  "message": "Note created",
+  "request_id": "a1b2c3d4",
+  "user": "alice@example.com",
+  "context": {
+    "note_id": 123,
+    "slug": "my-note",
+    "word_count": 42
+  },
+  "performance": {
+    "duration_ms": 45
+  }
+}
+```
+
+### Logger Hierarchy
+
+```
+starpunk (root logger)
+├── starpunk.auth        # Authentication/authorization
+├── starpunk.micropub    # Micropub endpoint
+├── starpunk.database    # Database operations
+├── starpunk.search      # Search functionality
+├── starpunk.web        # Web interface
+├── starpunk.rss        # RSS generation
+├── starpunk.monitoring # Performance monitoring
+└── starpunk.migration  # Database migrations
+```
+
+### Implementation Pattern
+
+```python
+# starpunk/logging.py
+import logging
+import json
+import sys
+from datetime import datetime
+from contextvars import ContextVar
+
+# Request context for correlation
+request_id: ContextVar[str] = ContextVar('request_id', default='')
+
+class StructuredFormatter(logging.Formatter):
+    """JSON formatter for structured logging"""
+
+    def format(self, record):
+        log_obj = {
+            'timestamp': datetime.utcnow().isoformat() + 'Z',
+            'level': record.levelname,
+            'logger': record.name,
+            'message': record.getMessage(),
+            'request_id': request_id.get()
+        }
+
+        # Add extra fields
+        if hasattr(record, 'context'):
+            log_obj['context'] = record.context
+
+        if hasattr(record, 'performance'):
+            log_obj['performance'] = record.performance
+
+        # Add exception info if present
+        if record.exc_info:
+            log_obj['exception'] = self.formatException(record.exc_info)
+
+        return json.dumps(log_obj)
+
+def setup_logging(level='INFO', format_type='json'):
+    """Configure logging for the application"""
+    root_logger = logging.getLogger('starpunk')
+    root_logger.setLevel(level)
+
+    handler = logging.StreamHandler(sys.stdout)
+
+    if format_type == 'json':
+        formatter = StructuredFormatter()
+    else:
+        # Human-readable for development
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+
+    handler.setFormatter(formatter)
+    root_logger.addHandler(handler)
+
+    return root_logger
+
+# Usage pattern
+logger = logging.getLogger('starpunk.micropub')
+
+def create_note(content, user):
+    logger.info(
+        "Creating note",
+        extra={
+            'context': {
+                'user': user,
+                'content_length': len(content)
+            }
+        }
+    )
+    # ... implementation
+```
+
+### What to Log
+
+#### Always Log (INFO+)
+- Authentication attempts (success/failure)
+- Note CRUD operations
+- Configuration changes
+- Startup/shutdown
+- External API calls
+- Migration execution
+- Search queries
+
+#### Error Conditions (ERROR)
+- Database connection failures
+- Invalid Micropub requests
+- Authentication failures
+- File system errors
+- Configuration errors
+
+#### Warnings (WARNING)
+- Slow queries
+- High memory usage
+- Deprecated feature usage
+- Missing optional configuration
+- FTS5 unavailability
+
+#### Debug Information (DEBUG)
+- SQL queries executed
+- Request/response bodies
+- Template rendering details
+- Cache operations
+- Detailed timing data
+
+### What NOT to Log
+- Passwords or tokens
+- Full note content (unless debug)
+- Personal information (PII)
+- Request headers with auth
+- Database connection strings
+
+### Performance Considerations
+
+1. **Lazy Evaluation**: Use lazy % formatting
+   ```python
+   logger.debug("Processing note %s", note_id)  # Good
+   logger.debug(f"Processing note {note_id}")   # Bad
+   ```
+
+2. **Level Checking**: Check before expensive operations
+   ```python
+   if logger.isEnabledFor(logging.DEBUG):
+       logger.debug("Data: %s", expensive_serialization())
+   ```
+
+3. **Async Logging**: For high-volume scenarios (future)
+
+4. **Sampling**: For very frequent operations
+   ```python
+   if random.random() < 0.1:  # Log 10%
+       logger.debug("High frequency operation")
+   ```
+
+## Rationale
+
+### Why Standard Logging Module?
+1. **No Dependencies**: Built into Python
+2. **Industry Standard**: Well understood
+3. **Flexible**: Handlers, formatters, filters
+4. **Battle-tested**: Proven in production
+5. **Integration**: Works with existing tools
+
+### Why JSON Format?
+1. **Parseable**: Easy for log aggregators
+2. **Structured**: Consistent field access
+3. **Flexible**: Can add fields without breaking
+4. **Standard**: Widely supported
+
+### Why Not Alternatives?
+
+**structlog**:
+- Additional dependency
+- More complex API
+- Overkill for our needs
+
+**loguru**:
+- Third-party dependency
+- Non-standard API
+- Not necessary for our scale
+
+**Print statements**:
+- No levels
+- No structure
+- No filtering
+- Not production-ready
+
+## Consequences
+
+### Positive
+1. **Production Ready**: Professional logging
+2. **Debuggable**: Rich context in logs
+3. **Parseable**: Integration with log tools
+4. **Performant**: Minimal overhead
+5. **Configurable**: Adjust without code changes
+6. **Correlatable**: Request tracking via IDs
+
+### Negative
+1. **Verbosity**: More code for logging
+2. **Learning**: Developers must understand levels
+3. **Size**: JSON logs are larger than plain text
+4. **Complexity**: More setup than prints
+
+### Mitigations
+1. Provide logging utilities/helpers
+2. Document logging guidelines
+3. Use log rotation for size management
+4. Create developer-friendly formatter option
+
+## Alternatives Considered
+
+### 1. Continue with Print Statements
+**Pros**: Simplest possible
+**Cons**: Not production-ready
+**Decision**: Inadequate for production
+
+### 2. Custom Logging Solution
+**Pros**: Exactly what we need
+**Cons**: Reinventing the wheel
+**Decision**: Standard library is sufficient
+
+### 3. External Logging Service
+**Pros**: No local storage needed
+**Cons**: Privacy, dependency, cost
+**Decision**: Conflicts with self-hosted philosophy
+
+### 4. Syslog Integration
+**Pros**: Standard Unix logging
+**Cons**: Platform-specific, complexity
+**Decision**: Can add as handler if needed
+
+## Implementation Notes
+
+### Bootstrap Logging
+```python
+# Application startup
+import logging
+from starpunk.logging import setup_logging
+
+# Configure based on environment
+if os.environ.get('STARPUNK_ENV') == 'production':
+    setup_logging(level='INFO', format_type='json')
+else:
+    setup_logging(level='DEBUG', format_type='human')
+```
+
+### Request Correlation
+```python
+# Middleware sets request ID
+from uuid import uuid4
+from contextvars import copy_context
+
+def middleware(request):
+    request_id.set(str(uuid4())[:8])
+    # Process request in context
+    return copy_context().run(handler, request)
+```
+
+### Migration Strategy
+1. Phase 1: Add logging module, keep prints
+2. Phase 2: Convert prints to logger calls
+3. Phase 3: Remove print statements
+4. Phase 4: Add structured context
+
+## Testing Strategy
+
+1. **Unit Tests**: Mock logger, verify calls
+2. **Integration Tests**: Verify log output format
+3. **Performance Tests**: Measure logging overhead
+4. **Configuration Tests**: Test different levels/formats
+
+## Configuration
+
+Environment variables:
+- `STARPUNK_LOG_LEVEL`: DEBUG|INFO|WARNING|ERROR|CRITICAL
+- `STARPUNK_LOG_FORMAT`: json|human
+- `STARPUNK_LOG_FILE`: Path to log file (optional)
+- `STARPUNK_LOG_ROTATION`: Enable rotation (optional)
+
+## Security Considerations
+
+1. Never log sensitive data
+2. Sanitize user input in logs
+3. Rate limit log output
+4. Monitor for log injection attacks
+5. Secure log file permissions
+
+## References
+
+- [Python Logging HOWTO](https://docs.python.org/3/howto/logging.html)
+- [The Twelve-Factor App - Logs](https://12factor.net/logs)
+- [OWASP Logging Guide](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
+- [JSON Logging Best Practices](https://www.loggly.com/use-cases/json-logging-best-practices/)
+
+## Document History
+
+- 2025-11-25: Initial draft for v1.1.1 release planning
--- a/docs/decisions/ADR-055-error-handling-philosophy.md
+++ b/docs/decisions/ADR-055-error-handling-philosophy.md
@@ -0,0 +1,415 @@
+# ADR-055: Error Handling Philosophy
+
+## Status
+Accepted
+
+## Context
+StarPunk v1.1.1 focuses on production readiness, including graceful error handling. Currently, error handling is inconsistent:
+- Some errors crash the application
+- Error messages vary in helpfulness
+- No distinction between user and system errors
+- Insufficient context for debugging
+
+We need a consistent philosophy for handling errors that balances user experience, security, and debuggability.
+
+## Decision
+Adopt a layered error handling strategy that provides graceful degradation, helpful user messages, and detailed logging for operators.
+
+### Error Handling Principles
+
+1. **Fail Gracefully**: Never crash when recovery is possible
+2. **Be Helpful**: Provide actionable error messages
+3. **Log Everything**: Detailed context for debugging
+4. **Secure by Default**: Don't leak sensitive information
+5. **User vs System**: Different handling for different audiences
+
+### Error Categories
+
+#### 1. User Errors (4xx class)
+Errors caused by user action or client issues.
+
+Examples:
+- Invalid Micropub request
+- Authentication failure
+- Missing required fields
+- Invalid slug format
+
+Handling:
+- Return helpful error message
+- Suggest corrective action
+- Log at INFO level
+- Don't expose internals
+
+#### 2. System Errors (5xx class)
+Errors in system operation.
+
+Examples:
+- Database connection failure
+- File system errors
+- Memory exhaustion
+- Template rendering errors
+
+Handling:
+- Generic user message
+- Detailed logging at ERROR level
+- Attempt recovery if possible
+- Alert operators (future)
+
+#### 3. Configuration Errors
+Errors due to misconfiguration.
+
+Examples:
+- Missing required config
+- Invalid configuration values
+- Incompatible settings
+- Permission issues
+
+Handling:
+- Fail fast at startup
+- Clear error messages
+- Suggest fixes
+- Document requirements
+
+#### 4. Transient Errors
+Temporary errors that may succeed on retry.
+
+Examples:
+- Database lock
+- Network timeout
+- Resource temporarily unavailable
+
+Handling:
+- Automatic retry with backoff
+- Log at WARNING level
+- Fail gracefully after retries
+- Track frequency
+
+### Error Response Format
+
+#### Development Mode
+```json
+{
+  "error": {
+    "type": "ValidationError",
+    "message": "Invalid slug format",
+    "details": {
+      "field": "slug",
+      "value": "my/bad/slug",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "suggestion": "Slugs can only contain lowercase letters, numbers, and hyphens",
+    "documentation": "/docs/api/micropub#slugs",
+    "trace_id": "abc123"
+  }
+}
+```
+
+#### Production Mode
+```json
+{
+  "error": {
+    "message": "Invalid request format",
+    "suggestion": "Please check your request and try again",
+    "documentation": "/docs/api/micropub",
+    "trace_id": "abc123"
+  }
+}
+```
+
+### Implementation Pattern
+
+```python
+# starpunk/errors.py
+from enum import Enum
+from typing import Optional, Dict, Any
+import logging
+
+logger = logging.getLogger('starpunk.errors')
+
+class ErrorCategory(Enum):
+    USER = "user"
+    SYSTEM = "system"
+    CONFIG = "config"
+    TRANSIENT = "transient"
+
+class StarPunkError(Exception):
+    """Base exception for all StarPunk errors"""
+
+    def __init__(
+        self,
+        message: str,
+        category: ErrorCategory = ErrorCategory.SYSTEM,
+        suggestion: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        status_code: int = 500,
+        recoverable: bool = False
+    ):
+        self.message = message
+        self.category = category
+        self.suggestion = suggestion
+        self.details = details or {}
+        self.status_code = status_code
+        self.recoverable = recoverable
+        super().__init__(message)
+
+    def to_user_dict(self, debug: bool = False) -> dict:
+        """Format error for user response"""
+        result = {
+            'error': {
+                'message': self.message,
+                'trace_id': self.trace_id
+            }
+        }
+
+        if self.suggestion:
+            result['error']['suggestion'] = self.suggestion
+
+        if debug and self.details:
+            result['error']['details'] = self.details
+            result['error']['type'] = self.__class__.__name__
+
+        return result
+
+    def log(self):
+        """Log error with appropriate level"""
+        if self.category == ErrorCategory.USER:
+            logger.info(
+                "User error: %s",
+                self.message,
+                extra={'context': self.details}
+            )
+        elif self.category == ErrorCategory.TRANSIENT:
+            logger.warning(
+                "Transient error: %s",
+                self.message,
+                extra={'context': self.details}
+            )
+        else:
+            logger.error(
+                "System error: %s",
+                self.message,
+                extra={'context': self.details},
+                exc_info=True
+            )
+
+# Specific error classes
+class ValidationError(StarPunkError):
+    """User input validation failed"""
+    def __init__(self, message: str, field: str = None, **kwargs):
+        super().__init__(
+            message,
+            category=ErrorCategory.USER,
+            status_code=400,
+            **kwargs
+        )
+        if field:
+            self.details['field'] = field
+
+class AuthenticationError(StarPunkError):
+    """Authentication failed"""
+    def __init__(self, message: str = "Authentication required", **kwargs):
+        super().__init__(
+            message,
+            category=ErrorCategory.USER,
+            status_code=401,
+            suggestion="Please authenticate and try again",
+            **kwargs
+        )
+
+class DatabaseError(StarPunkError):
+    """Database operation failed"""
+    def __init__(self, message: str, **kwargs):
+        super().__init__(
+            message,
+            category=ErrorCategory.SYSTEM,
+            status_code=500,
+            suggestion="Please try again later",
+            **kwargs
+        )
+
+class ConfigurationError(StarPunkError):
+    """Configuration is invalid"""
+    def __init__(self, message: str, setting: str = None, **kwargs):
+        super().__init__(
+            message,
+            category=ErrorCategory.CONFIG,
+            status_code=500,
+            **kwargs
+        )
+        if setting:
+            self.details['setting'] = setting
+```
+
+### Error Handling Middleware
+
+```python
+# starpunk/middleware/errors.py
+def error_handler(func):
+    """Decorator for consistent error handling"""
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except StarPunkError as e:
+            e.log()
+            return e.to_user_dict(debug=is_debug_mode())
+        except Exception as e:
+            # Unexpected error
+            error = StarPunkError(
+                message="An unexpected error occurred",
+                category=ErrorCategory.SYSTEM,
+                details={'original': str(e)}
+            )
+            error.log()
+            return error.to_user_dict(debug=is_debug_mode())
+    return wrapper
+```
+
+### Graceful Degradation Examples
+
+#### FTS5 Unavailable
+```python
+try:
+    # Attempt FTS5 search
+    results = search_with_fts5(query)
+except FTS5UnavailableError:
+    logger.warning("FTS5 unavailable, falling back to LIKE")
+    results = search_with_like(query)
+    flash("Search is running in compatibility mode")
+```
+
+#### Database Lock
+```python
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=0.5, max=2),
+    retry=retry_if_exception_type(sqlite3.OperationalError)
+)
+def execute_query(query):
+    """Execute with retry for transient errors"""
+    return db.execute(query)
+```
+
+#### Missing Optional Feature
+```python
+if not config.SEARCH_ENABLED:
+    # Return empty results instead of error
+    return {
+        'results': [],
+        'message': 'Search is disabled on this instance'
+    }
+```
+
+## Rationale
+
+### Why Graceful Degradation?
+1. **User Experience**: Don't break the whole app
+2. **Reliability**: Partial functionality better than none
+3. **Operations**: Easier to diagnose in production
+4. **Recovery**: System can self-heal from transients
+
+### Why Different Error Categories?
+1. **Appropriate Response**: Different errors need different handling
+2. **Security**: Don't expose internals for system errors
+3. **Debugging**: Operators need full context
+4. **User Experience**: Users need actionable messages
+
+### Why Structured Errors?
+1. **Consistency**: Predictable error format
+2. **Parsing**: Tools can process errors
+3. **Correlation**: Trace IDs link logs to responses
+4. **Documentation**: Self-documenting error details
+
+## Consequences
+
+### Positive
+1. **Better UX**: Helpful error messages
+2. **Easier Debugging**: Rich context in logs
+3. **More Reliable**: Graceful degradation
+4. **Secure**: No information leakage
+5. **Consistent**: Predictable error handling
+
+### Negative
+1. **More Code**: Error handling adds complexity
+2. **Testing Burden**: Many error paths to test
+3. **Performance**: Error handling overhead
+4. **Maintenance**: Error messages need updates
+
+### Mitigations
+1. Use error hierarchy to reduce duplication
+2. Generate tests for error paths
+3. Cache error messages
+4. Document error codes clearly
+
+## Alternatives Considered
+
+### 1. Let Exceptions Bubble
+**Pros**: Simple, Python default
+**Cons**: Poor UX, crashes, no context
+**Decision**: Not production-ready
+
+### 2. Generic Error Pages
+**Pros**: Simple to implement
+**Cons**: Not helpful, poor API experience
+**Decision**: Insufficient for Micropub API
+
+### 3. Error Codes System
+**Pros**: Precise, machine-readable
+**Cons**: Complex, needs documentation
+**Decision**: Over-engineered for our scale
+
+### 4. Sentry/Error Tracking Service
+**Pros**: Rich features, alerting
+**Cons**: External dependency, privacy
+**Decision**: Conflicts with self-hosted philosophy
+
+## Implementation Notes
+
+### Critical Path Protection
+Always protect critical paths:
+```python
+# Never let note creation completely fail
+try:
+    create_search_index(note)
+except Exception as e:
+    logger.error("Search indexing failed: %s", e)
+    # Continue without search - note still created
+```
+
+### Error Budget
+Track error rates for SLO monitoring:
+- User errors: Unlimited (not our fault)
+- System errors: <0.1% of requests
+- Configuration errors: 0 after startup
+- Transient errors: <1% of requests
+
+### Testing Strategy
+1. Unit tests for each error class
+2. Integration tests for error paths
+3. Chaos testing for transient errors
+4. User journey tests with errors
+
+## Security Considerations
+
+1. Never expose stack traces to users
+2. Sanitize error messages
+3. Rate limit error endpoints
+4. Don't leak existence via errors
+5. Log security errors specially
+
+## Migration Path
+
+1. Phase 1: Add error classes
+2. Phase 2: Wrap existing code
+3. Phase 3: Add graceful degradation
+4. Phase 4: Improve error messages
+
+## References
+
+- [Error Handling Best Practices](https://www.python.org/dev/peps/pep-0008/#programming-recommendations)
+- [HTTP Status Codes](https://httpstatuses.com/)
+- [OWASP Error Handling](https://owasp.org/www-community/Improper_Error_Handling)
+- [Google SRE Book - Handling Overload](https://sre.google/sre-book/handling-overload/)
+
+## Document History
+
+- 2025-11-25: Initial draft for v1.1.1 release planning
--- a/docs/decisions/ADR-056-no-selfhosted-indieauth.md
+++ b/docs/decisions/ADR-056-no-selfhosted-indieauth.md
@@ -0,0 +1,110 @@
+# ADR-056: Use External IndieAuth Provider (Never Self-Host)
+
+## Status
+**ACCEPTED** - This is a permanent, non-negotiable decision.
+
+## Context
+StarPunk is a minimal IndieWeb CMS focused on **content creation and syndication**, not identity infrastructure. The project philosophy demands that every line of code must justify its existence.
+
+The question of whether to implement self-hosted IndieAuth has been raised multiple times. This ADR documents the final, permanent decision on this matter.
+
+## Decision
+**StarPunk will NEVER implement self-hosted IndieAuth.**
+
+We will always rely on external IndieAuth providers such as:
+- indielogin.com (primary recommendation)
+- Other established IndieAuth providers
+
+This decision is **permanent and non-negotiable**.
+
+## Rationale
+
+### 1. Project Focus
+StarPunk's mission is to be a minimal CMS for publishing IndieWeb content. Our core competencies are:
+- Publishing notes with proper microformats
+- Generating RSS/Atom/JSON feeds
+- Implementing Micropub for content creation
+- Media management for content
+
+Identity infrastructure is explicitly **NOT** our focus.
+
+### 2. Complexity vs Value
+Implementing IndieAuth would require:
+- OAuth 2.0 implementation
+- Token management
+- Security considerations
+- Key storage and rotation
+- User profile management
+- Authorization code flows
+
+This represents hundreds or thousands of lines of code that don't serve our core mission of content publishing.
+
+### 3. Existing Solutions Work
+External IndieAuth providers like indielogin.com:
+- Are battle-tested
+- Handle security updates
+- Support multiple authentication methods
+- Are free to use
+- Align with IndieWeb principles of building on existing infrastructure
+
+### 4. Philosophy Alignment
+Our core philosophy states: "Every line of code must justify its existence. When in doubt, leave it out."
+
+Self-hosted IndieAuth cannot justify its existence in a minimal content-focused CMS.
+
+## Consequences
+
+### Positive
+- Dramatically reduced codebase complexity
+- No security burden for identity management
+- Faster development of content features
+- Clear project boundaries
+- User authentication "just works" via proven providers
+
+### Negative
+- Dependency on external service (indielogin.com)
+- Cannot function without internet connection to auth provider
+- No control over authentication user experience
+
+### Mitigations
+- Document clear setup instructions for using indielogin.com
+- Support multiple external providers for redundancy
+- Cache authentication tokens appropriately
+
+## Alternatives Considered
+
+### 1. Self-Hosted IndieAuth (REJECTED)
+**Why considered:** Full control over authentication
+**Why rejected:** Massive scope creep, violates project philosophy
+
+### 2. No Authentication (REJECTED)
+**Why considered:** Ultimate simplicity
+**Why rejected:** Single-user system still needs access control
+
+### 3. Basic Auth or Simple Password (REJECTED)
+**Why considered:** Very simple to implement
+**Why rejected:** Not IndieWeb compliant, poor user experience
+
+### 4. Hybrid Approach (REJECTED)
+**Why considered:** Optional self-hosted with external fallback
+**Why rejected:** Maintains complexity we're trying to avoid
+
+## Implementation Notes
+
+All authentication code should:
+1. Assume an external IndieAuth provider
+2. Never include hooks or abstractions for self-hosting
+3. Document indielogin.com as the recommended provider
+4. Include clear error messages when auth provider is unavailable
+
+## References
+- Project Philosophy: "Every line of code must justify its existence"
+- IndieAuth Specification: https://indieauth.spec.indieweb.org/
+- indielogin.com: https://indielogin.com/
+
+## Final Note
+This decision has been made after extensive consideration and multiple discussions. It is final.
+
+**Do not propose self-hosted IndieAuth in future architectural discussions.**
+
+The goal of StarPunk is **content**, not **identity**.
--- a/docs/decisions/ADR-057-media-attachment-model.md
+++ b/docs/decisions/ADR-057-media-attachment-model.md
@@ -0,0 +1,110 @@
+# ADR-057: Media Attachment Model
+
+## Status
+Accepted
+
+## Context
+The v1.2.0 media upload feature needed a clear model for how media relates to notes. Initial design assumed inline markdown image insertion (like a blog editor), but user feedback clarified that notes are more like social media posts (tweets, Mastodon toots) where media is attached rather than inline.
+
+Key insights from user:
+- "Notes are more like tweets, thread posts, mastodon posts etc. where the media is inserted is kind of irrelevant"
+- Media should appear at the TOP of notes when displayed
+- Text content should appear BELOW media
+- Multiple images per note should be supported
+
+## Decision
+We will implement a social media-style attachment model for media:
+
+1. **Database Design**: Use a junction table (`note_media`) to associate media files with notes, allowing:
+   - Multiple media per note (max 4)
+   - Explicit ordering via `display_order` column
+   - Per-attachment metadata (captions)
+   - Future reuse of media across notes
+
+2. **Display Model**: Media attachments appear at the TOP of notes:
+   - 1 image: Full width display
+   - 2 images: Side-by-side layout
+   - 3-4 images: Grid layout
+   - Text content always appears below media
+
+3. **Syndication Strategy**:
+   - RSS: Embed media as HTML in description (universal support)
+   - ATOM: Use both `<link rel="enclosure">` and HTML content
+   - JSON Feed: Use native `attachments` array (cleanest)
+
+4. **Microformats2**: Multiple `u-photo` properties for multi-photo posts
+
+## Rationale
+**Why attachment model over inline markdown?**
+- Matches user mental model (social media posts)
+- Simplifies UI/UX (no cursor tracking needed)
+- Better syndication support (especially JSON Feed)
+- Cleaner Microformats2 markup
+- Consistent display across all contexts
+
+**Why junction table over array column?**
+- Better query performance for feeds
+- Supports future media reuse
+- Per-attachment metadata
+- Explicit ordering control
+- Standard relational design
+
+**Why limit to 4 images?**
+- Twitter limit is 4 images
+- Mastodon limit is 4 images
+- Prevents performance issues
+- Maintains clean grid layouts
+- Sufficient for microblogging use case
+
+## Consequences
+
+### Positive
+- Clean separation of media and text content
+- Familiar social media UX pattern
+- Excellent syndication feed support
+- Future-proof for media galleries
+- Supports accessibility via captions
+- Efficient database queries
+
+### Negative
+- No inline images in markdown content
+- All media must appear at top
+- Cannot mix text and images
+- More complex database schema
+- Additional JOIN queries needed
+
+### Neutral
+- Different from traditional blog CMSs
+- Requires grid layout CSS
+- Media upload is separate from text editing
+
+## Alternatives Considered
+
+### Alternative 1: Inline Markdown Images
+Store media URLs in markdown content as `![alt](url)`.
+- **Pros**: Traditional blog approach, flexible positioning
+- **Cons**: Poor syndication, complex editing UX, inconsistent display
+
+### Alternative 2: JSON Array in Notes Table
+Store media IDs as JSON array column in notes table.
+- **Pros**: Simpler schema, fewer tables
+- **Cons**: Poor query performance, no per-media metadata, violates 1NF
+
+### Alternative 3: Single Media Per Note
+Restrict to one image per note.
+- **Pros**: Simplest implementation
+- **Cons**: Too limiting, doesn't match social media patterns
+
+## Implementation Notes
+
+1. Migration will create both `media` and `note_media` tables
+2. Feed generators must query media via JOIN
+3. Template must render media before content
+4. Upload UI shows thumbnails, not markdown insertion
+5. Consider lazy loading for performance
+
+## References
+- [IndieWeb multi-photo posts](https://indieweb.org/multi-photo)
+- [Microformats2 u-photo property](https://microformats.org/wiki/h-entry#u-photo)
+- [JSON Feed attachments](https://jsonfeed.org/version/1.1#attachments)
+- [Twitter photo upload limits](https://help.twitter.com/en/using-twitter/tweeting-gifs-and-pictures)
--- a/docs/decisions/ADR-058-image-optimization-strategy.md
+++ b/docs/decisions/ADR-058-image-optimization-strategy.md
@@ -0,0 +1,183 @@
+# ADR-058: Image Optimization Strategy
+
+## Status
+Accepted
+
+## Context
+The v1.2.0 media upload feature requires decisions about image size limits, optimization, and validation. Based on user requirements:
+- 4 images maximum per note (confirmed)
+- No drag-and-drop reordering needed (display order is upload order)
+- Image optimization desired
+- Optional caption field for each image (accessibility)
+
+Research was conducted on:
+- Web image best practices (2024)
+- IndieWeb implementation patterns
+- Python image processing libraries
+- Storage implications for single-user CMS
+
+## Decision
+
+### Image Limits
+We will enforce the following limits:
+
+1. **Count**: Maximum 4 images per note
+2. **File Size**: Maximum 10MB per image
+3. **Dimensions**: Maximum 4096x4096 pixels
+4. **Formats**: JPEG, PNG, GIF, WebP only
+
+### Optimization Strategy
+We will implement **automatic resizing on upload**:
+
+1. **Resize Policy**:
+   - Images larger than 2048 pixels (longest edge) will be resized
+   - Aspect ratio will be preserved
+   - Original quality will be maintained (no aggressive compression)
+   - EXIF orientation will be corrected
+
+2. **Rejection Policy**:
+   - Files over 10MB will be rejected (before optimization)
+   - Dimensions over 4096x4096 will be rejected
+   - Invalid formats will be rejected
+   - Corrupted files will be rejected
+
+3. **Processing Library**: Use **Pillow** for image processing
+
+### Database Schema Updates
+Add caption field to `note_media` table:
+```sql
+CREATE TABLE note_media (
+    id INTEGER PRIMARY KEY,
+    note_id INTEGER NOT NULL,
+    media_id INTEGER NOT NULL,
+    display_order INTEGER NOT NULL DEFAULT 0,
+    caption TEXT,  -- Optional caption for accessibility
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (note_id) REFERENCES notes(id) ON DELETE CASCADE,
+    FOREIGN KEY (media_id) REFERENCES media(id) ON DELETE CASCADE,
+    UNIQUE(note_id, media_id)
+);
+```
+
+## Rationale
+
+### Why 10MB file size limit?
+- Generous for high-quality photos from modern phones
+- Prevents storage abuse on single-user instance
+- Reasonable upload time even on slower connections
+- Matches or exceeds most social platforms
+
+### Why 4096x4096 max dimensions?
+- Covers 16-megapixel images (4000x4000)
+- Sufficient for 4K displays (3840x2160)
+- Prevents memory issues during processing
+- Larger than needed for web display
+
+### Why resize to 2048px?
+- Optimal balance between quality and performance
+- Retina-ready (2x scaling on 1024px display)
+- Significant file size reduction
+- Matches common social media limits
+- Preserves quality for most use cases
+
+### Why Pillow over alternatives?
+- De-facto standard for Python image processing
+- Fastest for basic resize operations
+- Minimal dependencies
+- Well-documented and stable
+- Sufficient for our needs (resize, format conversion, EXIF)
+
+### Why automatic optimization?
+- Better user experience (no manual intervention)
+- Consistent output quality
+- Storage efficiency
+- Faster page loads
+- Users still get good quality
+
+### Why no thumbnail generation?
+- Adds complexity for minimal benefit
+- Modern browsers handle image scaling well
+- Single-user CMS doesn't need CDN optimization
+- Can be added later if needed
+
+## Consequences
+
+### Positive
+- Automatic optimization improves performance
+- Generous limits support high-quality photography
+- Captions improve accessibility
+- Storage usage remains reasonable
+- Fast processing with Pillow
+
+### Negative
+- Users cannot upload raw/unprocessed images
+- Some quality loss for images over 2048px
+- No manual control over optimization
+- Additional processing time on upload
+
+### Neutral
+- Requires Pillow dependency
+- Images stored at single resolution
+- No progressive enhancement (thumbnails)
+
+## Alternatives Considered
+
+### Alternative 1: No Optimization
+Accept images as-is, no processing.
+- **Pros**: Simpler, preserves originals
+- **Cons**: Storage bloat, slow page loads, memory issues
+
+### Alternative 2: Strict Limits (1MB, 1920x1080)
+Match typical web recommendations.
+- **Pros**: Optimal performance, minimal storage
+- **Cons**: Too restrictive for photography, poor UX
+
+### Alternative 3: Generate Multiple Sizes
+Create thumbnail, medium, and full sizes.
+- **Pros**: Optimal delivery, responsive images
+- **Cons**: Complex implementation, 3x storage, overkill for single-user
+
+### Alternative 4: Client-side Resizing
+Resize in browser before upload.
+- **Pros**: Reduces server load
+- **Cons**: Inconsistent quality, browser limitations, poor UX
+
+## Implementation Notes
+
+1. **Validation Order**:
+   - Check file size (reject if >10MB)
+   - Check MIME type (accept only allowed formats)
+   - Load with Pillow (validates file integrity)
+   - Check dimensions (reject if >4096px)
+   - Resize if needed (>2048px)
+   - Save optimized version
+
+2. **Error Messages**:
+   - "File too large. Maximum size is 10MB"
+   - "Invalid image format. Accepted: JPEG, PNG, GIF, WebP"
+   - "Image dimensions too large. Maximum is 4096x4096"
+   - "Image appears to be corrupted"
+
+3. **Pillow Configuration**:
+   ```python
+   # Preserve quality during resize
+   image.thumbnail((2048, 2048), Image.Resampling.LANCZOS)
+
+   # Correct EXIF orientation
+   ImageOps.exif_transpose(image)
+
+   # Save with original quality
+   image.save(output, quality=95, optimize=True)
+   ```
+
+4. **Caption Implementation**:
+   - Add caption field to upload form
+   - Store in `note_media.caption`
+   - Use as alt text in HTML
+   - Include in Microformats markup
+
+## References
+- [MDN Web Performance: Images](https://developer.mozilla.org/en-US/docs/Web/Performance/images)
+- [Pillow Documentation](https://pillow.readthedocs.io/)
+- [Web.dev Image Optimization](https://web.dev/fast/#optimize-your-images)
+- [Twitter Image Specifications](https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/uploading-media/media-best-practices)
--- a/docs/decisions/ADR-059-full-feed-media-standardization.md
+++ b/docs/decisions/ADR-059-full-feed-media-standardization.md
@@ -0,0 +1,281 @@
+# ADR-059: Full Feed Media Standardization (Option 3)
+
+## Status
+Proposed (For v1.3.0 Backlog)
+
+## Context
+StarPunk v1.2.0 introduced media attachments for notes (images). The initial implementation embeds media as HTML in feed description fields. Option 2 (implemented in v1.2.x) adds Media RSS extension elements and JSON Feed image fields for better feed reader compatibility.
+
+This ADR documents Option 3: Full Standardization, which provides comprehensive media support across all syndication formats, including video, audio, and advanced features. This is planned for v1.3.0 or later.
+
+## Decision
+Document the scope of "Full Standardization" for feed media support to be implemented in a future release. This option goes beyond Option 2's basic Media RSS support to include:
+
+1. **Complete Media RSS Specification Support**
+2. **Podcast RSS Support (RSS 2.0 enclosures for audio)**
+3. **Video Support**
+4. **Multiple Image Sizes/Thumbnails**
+5. **Full JSON Feed 1.1 Media Compliance**
+
+## Scope of Full Standardization
+
+### 1. Complete Media RSS Implementation
+
+**Research Required**: Full Media RSS specification at https://www.rssboard.org/media-rss
+
+**Elements to Implement**:
+- `<media:content>` with full attribute support:
+  - `url` (required) - Direct URL to media file
+  - `fileSize` - Size in bytes
+  - `type` - MIME type
+  - `medium` - Type: "image", "audio", "video", "document", "executable"
+  - `isDefault` - Boolean for default rendition
+  - `expression` - "full", "sample", "nonstop"
+  - `bitrate` - Kilobits per second
+  - `framerate` - Frames per second (video)
+  - `samplingrate` - Samples per second (audio)
+  - `channels` - Audio channels
+  - `duration` - Seconds
+  - `height` / `width` - Dimensions in pixels
+  - `lang` - RFC-3066 language code
+
+- `<media:group>` - Container for multiple renditions of same content
+- `<media:thumbnail>` - Multiple sizes with url, width, height, time
+- `<media:title>` - Media title (type="plain" or "html")
+- `<media:description>` - Media description (type="plain" or "html")
+- `<media:keywords>` - Comma-separated keywords
+- `<media:category>` - Categorization with scheme attribute
+- `<media:credit>` - Credit attribution with role and scheme
+- `<media:copyright>` - Copyright information
+- `<media:rating>` - Content rating (scheme-based)
+- `<media:hash>` - MD5/SHA-1 hash for integrity
+- `<media:player>` - Embeddable player URL
+
+**Effort Estimate**: 8-12 hours
+
+### 2. Podcast RSS Support
+
+**Research Required**:
+- Apple Podcast RSS specification
+- Google Podcast RSS requirements
+- Podcast Index namespace (podcast:)
+
+**Elements to Implement**:
+- iTunes namespace (`xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"`):
+  - `<itunes:summary>` - Episode summary
+  - `<itunes:duration>` - Audio duration (HH:MM:SS)
+  - `<itunes:image>` - Episode artwork
+  - `<itunes:explicit>` - Content rating
+  - `<itunes:episode>` - Episode number
+  - `<itunes:season>` - Season number
+  - `<itunes:episodeType>` - "full", "trailer", "bonus"
+  - `<itunes:author>` - Author name
+  - `<itunes:owner>` - Owner contact
+
+- Standard RSS `<enclosure>` for audio:
+  - `url` - Direct audio file URL
+  - `length` - File size in bytes
+  - `type` - MIME type (audio/mpeg, audio/mp4, etc.)
+
+**Database Changes**:
+- Add `duration` column to `note_media` table
+- Add `media_type` enum (image, audio, video)
+- Consider `podcast_metadata` table for series-level data
+
+**Effort Estimate**: 10-16 hours
+
+### 3. Video Support
+
+**Research Required**:
+- Video hosting considerations (storage, bandwidth)
+- Supported formats (mp4, webm, ogg)
+- Transcoding requirements
+- Poster image generation
+
+**Implementation Scope**:
+- Accept video uploads via Micropub media endpoint
+- Generate poster thumbnails automatically
+- Include in Media RSS with proper video attributes:
+  - `medium="video"`
+  - `framerate`, `duration`, `bitrate`
+  - Associated `<media:thumbnail>` for poster
+
+- HTML5 `<video>` element in feed description
+- Consider video hosting limits (file size, duration)
+
+**Database Changes**:
+- Video-specific metadata in `media` table
+- Poster image path
+- Transcoding status (if needed)
+
+**Effort Estimate**: 16-24 hours (significant)
+
+### 4. Multiple Image Sizes (Thumbnails)
+
+**Research Required**:
+- Responsive image best practices
+- WebP generation
+- srcset/sizes patterns
+
+**Implementation Scope**:
+- Generate multiple sizes on upload:
+  - Thumbnail: 150x150 (square crop)
+  - Small: 320px width
+  - Medium: 640px width
+  - Large: 1280px width
+  - Original: preserved
+
+- Store all sizes in `media_variants` table
+- Include in Media RSS:
+  ```xml
+  <media:group>
+    <media:content url="large.jpg" isDefault="true" width="1280" />
+    <media:content url="medium.jpg" width="640" />
+    <media:content url="small.jpg" width="320" />
+  </media:group>
+  <media:thumbnail url="thumb.jpg" width="150" height="150" />
+  ```
+
+- JSON Feed: Use `image` for default, include variants in `_starpunk` extension
+
+**Database Changes**:
+- `media_variants` table: media_id, variant_type, path, width, height, size_bytes
+- Add `has_variants` boolean to `media` table
+
+**Effort Estimate**: 8-12 hours
+
+### 5. Full JSON Feed 1.1 Media Compliance
+
+**Research Required**: JSON Feed 1.1 specification for extensions
+
+**Implementation Scope**:
+- Top-level `image` field (URL of first image, per spec)
+- Top-level `banner_image` if applicable
+- Item-level `image` field (main/featured image)
+- Item-level `banner_image` for posts with banners
+- Complete `attachments` array:
+  ```json
+  {
+    "url": "https://example.com/media/image.jpg",
+    "mime_type": "image/jpeg",
+    "title": "Image caption",
+    "size_in_bytes": 245760,
+    "duration_in_seconds": null
+  }
+  ```
+- Audio attachments with `duration_in_seconds`
+- Video attachments (if supported)
+
+**Effort Estimate**: 4-6 hours
+
+### 6. ATOM Feed Media Extensions
+
+**Research Required**:
+- ATOM Media extension namespace
+- `<link rel="enclosure">` best practices
+
+**Implementation Scope**:
+- `<link rel="enclosure">` for each media item
+- `type` attribute with MIME type
+- `length` attribute with file size
+- `title` attribute with caption
+- Consider `<link rel="related">` for thumbnails
+
+**Effort Estimate**: 3-5 hours
+
+## Total Effort Estimate
+
+| Feature | Minimum | Maximum |
+|---------|---------|---------|
+| Complete Media RSS | 8 hours | 12 hours |
+| Podcast RSS Support | 10 hours | 16 hours |
+| Video Support | 16 hours | 24 hours |
+| Multiple Image Sizes | 8 hours | 12 hours |
+| JSON Feed Compliance | 4 hours | 6 hours |
+| ATOM Extensions | 3 hours | 5 hours |
+| **Total** | **49 hours** | **75 hours** |
+
+**Note**: Video support is the most complex feature and could be deferred to v1.4.0 "Media" release.
+
+## Prerequisites
+
+Before implementing Full Standardization:
+
+1. **Option 2 Complete**: Basic Media RSS and JSON Feed `image` field
+2. **Image Optimization**: ADR-058 image optimization strategy implemented
+3. **Media Storage Architecture**: Clear path for large file storage
+4. **Test Infrastructure**: Feed validation tests in place
+
+## Implementation Phases
+
+### Phase A: Enhanced Image Support (v1.3.0)
+- Multiple image sizes/thumbnails
+- Full Media RSS for images
+- Enhanced JSON Feed attachments
+- **Effort**: 12-18 hours
+
+### Phase B: Audio Support (v1.3.x or v1.4.0)
+- Podcast RSS implementation
+- Audio duration extraction
+- iTunes namespace
+- **Effort**: 10-16 hours
+
+### Phase C: Video Support (v1.4.0 "Media")
+- Video upload handling
+- Poster generation
+- Video in feeds
+- **Effort**: 16-24 hours
+
+## Consequences
+
+### Positive
+- Best-in-class feed reader compatibility
+- Podcast distribution capability
+- Video content support
+- Professional media syndication
+- Future-proof architecture
+
+### Negative
+- Significant implementation effort (50-75 hours total)
+- Increased storage requirements
+- More complex feed generation
+- Processing overhead for image variants
+- Larger codebase to maintain
+
+### Neutral
+- Aligns with media-focused v1.4.0 roadmap
+- Phased implementation possible
+- Optional features can be configuration-gated
+
+## Alternatives Considered
+
+### Alternative 1: Minimal Enhancement (Option 2 Only)
+Just implement basic Media RSS and JSON Feed image field.
+- **Pros**: Low effort, immediate benefit
+- **Cons**: Misses podcast/video opportunity
+
+### Alternative 2: Third-Party Media Service
+Use external service (Cloudinary, etc.) for media processing.
+- **Pros**: Offloads complexity
+- **Cons**: External dependency, cost, data ownership concerns
+
+### Alternative 3: Plugin Architecture
+Make media support pluggable for advanced features.
+- **Pros**: Keeps core simple
+- **Cons**: Added architectural complexity
+
+## References
+
+- [Media RSS Specification](https://www.rssboard.org/media-rss)
+- [JSON Feed 1.1 Specification](https://jsonfeed.org/version/1.1)
+- [Apple Podcast RSS Requirements](https://podcasters.apple.com/support/823-podcast-requirements)
+- [Podcast Index Namespace](https://github.com/Podcastindex-org/podcast-namespace)
+- [RSS 2.0 Enclosure Specification](https://www.rssboard.org/rss-specification#ltenclosuregtSubelementOfLtitemgt)
+- [ADR-057: Media Attachment Model](/home/phil/Projects/starpunk/docs/decisions/ADR-057-media-attachment-model.md)
+- [ADR-058: Image Optimization Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-058-image-optimization-strategy.md)
+
+## Decision
+This ADR documents the scope of Full Standardization (Option 3) for the project backlog. Implementation should be scheduled for v1.3.0 and v1.4.0 releases according to the phased approach outlined above.
+
+**Immediate Action**: Implement Option 2 (ADR-060) for v1.2.x release.
+**Future Action**: Review and refine this scope when scheduling v1.3.0 work.
--- a/docs/decisions/ADR-061-author-discovery.md
+++ b/docs/decisions/ADR-061-author-discovery.md
@@ -0,0 +1,111 @@
+# ADR-061: Author Profile Discovery from IndieAuth
+
+## Status
+Accepted
+
+## Context
+StarPunk v1.2.0 requires Microformats2 compliance, including proper h-card author information in h-entries. The original design assumed author information would be configured via environment variables (AUTHOR_NAME, AUTHOR_PHOTO, etc.).
+
+However, since StarPunk uses IndieAuth for authentication, and users authenticate with their domain/profile URL, we have an opportunity to discover author information directly from their IndieWeb profile rather than requiring manual configuration.
+
+The user explicitly stated: "These should be retrieved from the logged in profile domain (rel me etc.)" when asked about author configuration.
+
+## Decision
+Implement automatic author profile discovery from the IndieAuth 'me' URL:
+
+1. When a user logs in via IndieAuth, fetch their profile page
+2. Parse h-card microformats and rel-me links from the profile
+3. Cache this information in a new `author_profile` database table
+4. Use discovered information in templates for Microformats2 markup
+5. Provide fallback behavior when discovery fails
+
+## Rationale
+1. **IndieWeb Native**: Discovery from profile URLs is a core IndieWeb pattern
+2. **DRY Principle**: Author already maintains their profile; no need to duplicate
+3. **Dynamic Updates**: Profile changes are reflected on next login
+4. **Standards-Based**: Uses existing h-card and rel-me specifications
+5. **User Experience**: Zero configuration for author information
+6. **Consistency**: Author info always matches their IndieWeb identity
+
+## Consequences
+
+### Positive
+- No manual configuration of author information required
+- Automatically stays in sync with user's profile
+- Supports full IndieWeb identity model
+- Works with any IndieAuth provider
+- Discoverable rel-me links for identity verification
+
+### Negative
+- Requires network request during login (mitigated by caching)
+- Depends on proper markup on user's profile page
+- Additional database table required
+- More complex than static configuration
+- Parsing complexity for microformats
+
+### Implementation Details
+
+#### Database Schema
+```sql
+CREATE TABLE author_profile (
+    id INTEGER PRIMARY KEY,
+    me_url TEXT NOT NULL UNIQUE,
+    name TEXT,
+    photo TEXT,
+    bio TEXT,
+    rel_me_links TEXT,  -- JSON array
+    discovered_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+#### Discovery Flow
+1. User authenticates with IndieAuth
+2. On successful login, trigger discovery
+3. Fetch user's profile page (with timeout)
+4. Parse h-card for: name, photo, bio
+5. Parse rel-me links
+6. Store in database with timestamp
+7. Use cache for 7 days, refresh on login
+
+#### Fallback Strategy
+- If discovery fails during login, use cached data if available
+- If no cache exists, use minimal defaults (domain as name)
+- Never block login due to discovery failure
+- Log failures for monitoring
+
+## Alternatives Considered
+
+### 1. Environment Variables (Original Design)
+Static configuration via .env file
+- ✅ Simple, no network requests
+- ❌ Requires manual configuration
+- ❌ Duplicates information already on profile
+- ❌ Can become out of sync
+
+### 2. Hybrid Approach
+Environment variables with optional discovery
+- ✅ Flexibility for both approaches
+- ❌ More complex configuration
+- ❌ Unclear which takes precedence
+
+### 3. Discovery Only, No Cache
+Fetch profile on every request
+- ✅ Always up to date
+- ❌ Performance impact
+- ❌ Reliability issues
+
+### 4. Static Import Tool
+CLI command to import profile once
+- ✅ No runtime discovery needed
+- ❌ Manual process
+- ❌ Can become stale
+
+## Implementation Priority
+High - Required for v1.2.0 Microformats2 compliance
+
+## References
+- https://microformats.org/wiki/h-card
+- https://indieweb.org/rel-me
+- https://indieweb.org/discovery
+- W3C IndieAuth specification
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -0,0 +1,139 @@
+# Architectural Decision Records (ADRs) Index
+
+This directory contains all Architectural Decision Records for StarPunk CMS. ADRs document significant architectural decisions, their context, rationale, and consequences.
+
+## ADR Format
+
+Each ADR follows this structure:
+- **Title**: ADR-NNN-brief-descriptive-title.md
+- **Status**: Proposed, Accepted, Deprecated, Superseded
+- **Context**: Why we're making this decision
+- **Decision**: What we decided to do
+- **Consequences**: Impact of this decision
+
+## All ADRs (Chronological)
+
+### Foundation & Technology Stack (ADR-001 to ADR-009)
+- **[ADR-001](ADR-001-python-web-framework.md)** - Python Web Framework Selection
+- **[ADR-002](ADR-002-flask-extensions.md)** - Flask Extensions Strategy
+- **[ADR-003](ADR-003-frontend-technology.md)** - Frontend Technology Stack
+- **[ADR-004](ADR-004-file-based-note-storage.md)** - File-Based Note Storage
+- **[ADR-005](ADR-005-indielogin-authentication.md)** - IndieLogin Authentication
+- **[ADR-006](ADR-006-python-virtual-environment-uv.md)** - Python Virtual Environment with uv
+- **[ADR-007](ADR-007-slug-generation-algorithm.md)** - Slug Generation Algorithm
+- **[ADR-008](ADR-008-versioning-strategy.md)** - Versioning Strategy
+- **[ADR-009](ADR-009-git-branching-strategy.md)** - Git Branching Strategy
+
+### Authentication & Authorization (ADR-010 to ADR-027)
+- **[ADR-010](ADR-010-authentication-module-design.md)** - Authentication Module Design
+- **[ADR-011](ADR-011-development-authentication-mechanism.md)** - Development Authentication Mechanism
+- **[ADR-016](ADR-016-indieauth-client-discovery.md)** - IndieAuth Client Discovery
+- **[ADR-017](ADR-017-oauth-client-metadata-document.md)** - OAuth Client Metadata Document
+- **[ADR-018](ADR-018-indieauth-detailed-logging.md)** - IndieAuth Detailed Logging
+- **[ADR-019](ADR-019-indieauth-correct-implementation.md)** - IndieAuth Correct Implementation
+- **[ADR-021](ADR-021-indieauth-provider-strategy.md)** - IndieAuth Provider Strategy
+- **[ADR-022](ADR-022-auth-route-prefix-fix.md)** - Auth Route Prefix Fix
+- **[ADR-023](ADR-023-indieauth-client-identification.md)** - IndieAuth Client Identification
+- **[ADR-024](ADR-024-static-identity-page.md)** - Static Identity Page
+- **[ADR-025](ADR-025-indieauth-pkce-authentication.md)** - IndieAuth PKCE Authentication
+- **[ADR-026](ADR-026-indieauth-token-exchange-compliance.md)** - IndieAuth Token Exchange Compliance
+- **[ADR-027](ADR-027-indieauth-authentication-endpoint-correction.md)** - IndieAuth Authentication Endpoint Correction
+
+### Error Handling & Core Features (ADR-012 to ADR-015)
+- **[ADR-012](ADR-012-http-error-handling-policy.md)** - HTTP Error Handling Policy
+- **[ADR-013](ADR-013-expose-deleted-at-in-note-model.md)** - Expose Deleted-At in Note Model
+- **[ADR-014](ADR-014-rss-feed-implementation.md)** - RSS Feed Implementation
+- **[ADR-015](ADR-015-phase-5-implementation-approach.md)** - Phase 5 Implementation Approach
+
+### Micropub & API (ADR-028 to ADR-029)
+- **[ADR-028](ADR-028-micropub-implementation.md)** - Micropub Implementation
+- **[ADR-029](ADR-029-micropub-indieauth-integration.md)** - Micropub IndieAuth Integration
+
+### Database & Migrations (ADR-020, ADR-031 to ADR-037)
+- **[ADR-020](ADR-020-automatic-database-migrations.md)** - Automatic Database Migrations
+- **[ADR-031](ADR-031-database-migration-system-redesign.md)** - Database Migration System Redesign
+- **[ADR-032](ADR-032-initial-schema-sql-implementation.md)** - Initial Schema SQL Implementation
+- **[ADR-033](ADR-033-database-migration-redesign.md)** - Database Migration Redesign
+- **[ADR-037](ADR-037-migration-race-condition-fix.md)** - Migration Race Condition Fix
+- **[ADR-041](ADR-041-database-migration-conflict-resolution.md)** - Database Migration Conflict Resolution
+
+### Search & Advanced Features (ADR-034 to ADR-036, ADR-038 to ADR-040)
+- **[ADR-034](ADR-034-full-text-search.md)** - Full-Text Search
+- **[ADR-035](ADR-035-custom-slugs.md)** - Custom Slugs
+- **[ADR-036](ADR-036-indieauth-token-verification-method.md)** - IndieAuth Token Verification Method
+- **[ADR-038](ADR-038-syndication-formats.md)** - Syndication Formats (ATOM, JSON Feed)
+- **[ADR-039](ADR-039-micropub-url-construction-fix.md)** - Micropub URL Construction Fix
+- **[ADR-040](ADR-040-microformats2-compliance.md)** - Microformats2 Compliance
+
+### Architecture Refinements (ADR-042 to ADR-044)
+- **[ADR-042](ADR-042-versioning-strategy-for-authorization-removal.md)** - Versioning Strategy for Authorization Removal
+- **[ADR-043](ADR-043-CORRECTED-indieauth-endpoint-discovery.md)** - CORRECTED IndieAuth Endpoint Discovery
+- **[ADR-044](ADR-044-endpoint-discovery-implementation.md)** - Endpoint Discovery Implementation Details
+
+### Major Architectural Changes (ADR-050 to ADR-051)
+- **[ADR-050](ADR-050-remove-custom-indieauth-server.md)** - Remove Custom IndieAuth Server
+- **[ADR-051](ADR-051-phase1-test-strategy.md)** - Phase 1 Test Strategy
+
+### v1.1.1 Quality & Production Readiness (ADR-052 to ADR-055)
+- **[ADR-052](ADR-052-configuration-system-architecture.md)** - Configuration System Architecture
+- **[ADR-053](ADR-053-performance-monitoring-strategy.md)** - Performance Monitoring Strategy
+- **[ADR-054](ADR-054-structured-logging-architecture.md)** - Structured Logging Architecture
+- **[ADR-055](ADR-055-error-handling-philosophy.md)** - Error Handling Philosophy
+
+## ADRs by Topic
+
+### Authentication & IndieAuth
+ADR-005, ADR-010, ADR-011, ADR-016, ADR-017, ADR-018, ADR-019, ADR-021, ADR-022, ADR-023, ADR-024, ADR-025, ADR-026, ADR-027, ADR-036, ADR-043, ADR-044, ADR-050
+
+### Database & Migrations
+ADR-004, ADR-020, ADR-031, ADR-032, ADR-033, ADR-037, ADR-041
+
+### API & Micropub
+ADR-028, ADR-029, ADR-039
+
+### Content & Features
+ADR-007, ADR-013, ADR-014, ADR-034, ADR-035, ADR-038, ADR-040
+
+### Development & Operations
+ADR-001, ADR-002, ADR-003, ADR-006, ADR-008, ADR-009, ADR-012, ADR-015, ADR-042, ADR-051, ADR-052, ADR-053, ADR-054, ADR-055
+
+## Superseded ADRs
+
+These ADRs have been superseded by later decisions:
+- **ADR-030** (old) - Superseded by ADR-043 (CORRECTED IndieAuth Endpoint Discovery)
+
+## How to Create a New ADR
+
+1. **Find the next sequential number**: Check the highest existing ADR number
+2. **Use the naming format**: `ADR-NNN-brief-descriptive-title.md`
+3. **Follow the template**:
+   ```markdown
+   # ADR-NNN: Title
+
+   ## Status
+   Proposed | Accepted | Deprecated | Superseded
+
+   ## Context
+   Why are we making this decision?
+
+   ## Decision
+   What have we decided to do?
+
+   ## Consequences
+   What are the positive and negative consequences?
+
+   ## Alternatives Considered
+   What other options did we evaluate?
+   ```
+4. **Update this index** with the new ADR
+
+## Related Documentation
+- **[../architecture/](../architecture/)** - Architectural overviews and system design
+- **[../design/](../design/)** - Detailed design documents
+- **[../standards/](../standards/)** - Coding standards and conventions
+
+---
+
+**Last Updated**: 2025-11-25
+**Maintained By**: Documentation Manager Agent
+**Total ADRs**: 55
--- a/docs/design/INDEX.md
+++ b/docs/design/INDEX.md
@@ -0,0 +1,128 @@
+# Design Documentation Index
+
+This directory contains detailed design documents, feature specifications, and phase implementation plans for StarPunk CMS.
+
+## Project Structure
+- **[project-structure.md](project-structure.md)** - Overall project structure and organization
+- **[initial-files.md](initial-files.md)** - Initial file structure for the project
+
+## Phase Implementation Plans
+
+### Phase 1: Foundation
+- **[phase-1.1-core-utilities.md](phase-1.1-core-utilities.md)** - Core utility functions and helpers
+- **[phase-1.1-quick-reference.md](phase-1.1-quick-reference.md)** - Quick reference for Phase 1.1
+- **[phase-1.2-data-models.md](phase-1.2-data-models.md)** - Data models and database schema
+- **[phase-1.2-quick-reference.md](phase-1.2-quick-reference.md)** - Quick reference for Phase 1.2
+
+### Phase 2: Core Features
+- **[phase-2.1-notes-management.md](phase-2.1-notes-management.md)** - Notes CRUD functionality
+- **[phase-2.1-quick-reference.md](phase-2.1-quick-reference.md)** - Quick reference for Phase 2.1
+
+### Phase 3: Authentication
+- **[phase-3-authentication.md](phase-3-authentication.md)** - Authentication system design
+- **[phase-3-authentication-implementation.md](phase-3-authentication-implementation.md)** - Implementation details
+- **[indieauth-pkce-authentication.md](indieauth-pkce-authentication.md)** - IndieAuth PKCE authentication design
+
+### Phase 4: Web Interface
+- **[phase-4-web-interface.md](phase-4-web-interface.md)** - Web interface design
+- **[phase-4-quick-reference.md](phase-4-quick-reference.md)** - Quick reference for Phase 4
+- **[phase-4-error-handling-fix.md](phase-4-error-handling-fix.md)** - Error handling improvements
+
+### Phase 5: RSS & Deployment
+- **[phase-5-rss-and-container.md](phase-5-rss-and-container.md)** - RSS feed and container deployment
+- **[phase-5-executive-summary.md](phase-5-executive-summary.md)** - Executive summary of Phase 5
+- **[phase-5-quick-reference.md](phase-5-quick-reference.md)** - Quick reference for Phase 5
+
+## Feature-Specific Design
+
+### Micropub API
+- **[micropub-endpoint-design.md](micropub-endpoint-design.md)** - Micropub endpoint detailed design
+
+### Authentication Fixes
+- **[auth-redirect-loop-diagnosis.md](auth-redirect-loop-diagnosis.md)** - Diagnosis of redirect loop issues
+- **[auth-redirect-loop-diagram.md](auth-redirect-loop-diagram.md)** - Visual diagrams of the problem
+- **[auth-redirect-loop-executive-summary.md](auth-redirect-loop-executive-summary.md)** - Executive summary
+- **[auth-redirect-loop-fix-implementation.md](auth-redirect-loop-fix-implementation.md)** - Implementation guide
+
+### Database Schema
+- **[initial-schema-implementation-guide.md](initial-schema-implementation-guide.md)** - Schema implementation guide
+- **[initial-schema-quick-reference.md](initial-schema-quick-reference.md)** - Quick reference
+
+### Security
+- **[token-security-migration.md](token-security-migration.md)** - Token security improvements
+
+## Version-Specific Design
+
+### v1.1.1
+- **[v1.1.1/](v1.1.1/)** - v1.1.1 specific design documents
+
+## Quick Reference Documents
+
+Quick reference documents provide condensed, actionable information for developers:
+- **phase-1.1-quick-reference.md** - Core utilities quick ref
+- **phase-1.2-quick-reference.md** - Data models quick ref
+- **phase-2.1-quick-reference.md** - Notes management quick ref
+- **phase-4-quick-reference.md** - Web interface quick ref
+- **phase-5-quick-reference.md** - RSS and deployment quick ref
+- **initial-schema-quick-reference.md** - Database schema quick ref
+
+## How to Use This Documentation
+
+### For Developers Implementing Features
+1. Start with the relevant **phase** document (e.g., phase-2.1-notes-management.md)
+2. Consult the **quick reference** for that phase
+3. Check **feature-specific design** docs for details
+4. Reference **ADRs** in ../decisions/ for architectural decisions
+
+### For Planning New Features
+1. Review similar **phase documents** for patterns
+2. Check **project-structure.md** for organization guidelines
+3. Create new design doc following existing format
+4. Update this index with the new document
+
+### For Understanding Existing Code
+1. Find the **phase** that implemented the feature
+2. Read the design document for context
+3. Check **ADRs** for decision rationale
+4. Review implementation reports in ../reports/
+
+## Document Types
+
+### Phase Documents
+Comprehensive plans for each development phase, including:
+- Goals and scope
+- Implementation tasks
+- Dependencies
+- Testing requirements
+
+### Quick Reference Documents
+Condensed information for rapid development:
+- Key decisions
+- Code patterns
+- Common operations
+- Gotchas and notes
+
+### Feature Design Documents
+Detailed specifications for specific features:
+- Requirements
+- API design
+- Data models
+- UI/UX considerations
+
+### Diagnostic Documents
+Problem analysis and solutions:
+- Issue description
+- Root cause analysis
+- Solution design
+- Implementation plan
+
+## Related Documentation
+- **[../architecture/](../architecture/)** - System architecture and overviews
+- **[../decisions/](../decisions/)** - Architectural Decision Records (ADRs)
+- **[../reports/](../reports/)** - Implementation reports
+- **[../standards/](../standards/)** - Coding standards and conventions
+
+---
+
+**Last Updated**: 2025-11-25
+**Maintained By**: Documentation Manager Agent
--- a/docs/design/v1.0.0/2025-11-18-auth-redirect-loop-fix.md
+++ b/docs/design/v1.0.0/2025-11-18-auth-redirect-loop-fix.md
--- a/docs/design/v1.0.0/2025-11-18-quickfix-auth-loop.md
+++ b/docs/design/v1.0.0/2025-11-18-quickfix-auth-loop.md
--- a/docs/design/v1.0.0/2025-11-19-container-implementation-summary.md
+++ b/docs/design/v1.0.0/2025-11-19-container-implementation-summary.md
--- a/docs/design/v1.0.0/2025-11-19-migration-implementation-quick-reference.md
+++ b/docs/design/v1.0.0/2025-11-19-migration-implementation-quick-reference.md
--- a/docs/design/v1.0.0/2025-11-19-migration-system-implementation-guidance.md
+++ b/docs/design/v1.0.0/2025-11-19-migration-system-implementation-guidance.md
--- a/docs/design/v1.0.0/2025-11-19-migration-system-implementation-report.md
+++ b/docs/design/v1.0.0/2025-11-19-migration-system-implementation-report.md
--- a/docs/design/v1.0.0/2025-11-19-todo-test-updates.md
+++ b/docs/design/v1.0.0/2025-11-19-todo-test-updates.md
--- a/docs/design/v1.0.0/2025-11-22-auth-route-prefix-fix.md
+++ b/docs/design/v1.0.0/2025-11-22-auth-route-prefix-fix.md
--- a/docs/design/v1.0.0/2025-11-22-authorization-endpoint-fix.md
+++ b/docs/design/v1.0.0/2025-11-22-authorization-endpoint-fix.md
--- a/docs/design/v1.0.0/2025-11-22-grant-type-fix.md
+++ b/docs/design/v1.0.0/2025-11-22-grant-type-fix.md
--- a/docs/design/v1.0.0/2025-11-24-endpoint-discovery-analysis.md
+++ b/docs/design/v1.0.0/2025-11-24-endpoint-discovery-analysis.md
@@ -9,7 +9,7 @@

 ## Executive Summary

-I have reviewed the architect's corrected IndieAuth endpoint discovery design and the W3C IndieAuth specification. The design is fundamentally sound and correctly implements the IndieAuth specification. However, I have **critical questions** about implementation details, particularly around the "chicken-and-egg" problem of determining which endpoint to verify a token with when we don't know the user's identity beforehand.
+I have reviewed the architect's corrected IndieAuth endpoint discovery design (ADR-043) and the W3C IndieAuth specification. The design is fundamentally sound and correctly implements the IndieAuth specification. However, I have **critical questions** about implementation details, particularly around the "chicken-and-egg" problem of determining which endpoint to verify a token with when we don't know the user's identity beforehand.

 **Overall Assessment**: The design is architecturally correct, but needs clarification on practical implementation details before coding can begin.

@@ -148,7 +148,7 @@ The token is an opaque string like `"abc123xyz"`. We have no idea:
 - Which provider issued it
 - Which endpoint to verify it with

-**ADR-030-CORRECTED suggests (line 204-258)**:
+**ADR-043-CORRECTED suggests (line 204-258)**:
 ```
 4. Option A: If we have cached token info, use cached 'me' URL
 5. Option B: Try verification with last known endpoint for similar tokens
@@ -204,7 +204,7 @@ Please confirm this is correct or provide the proper approach.

 ### Question 2: Caching Strategy Details

-**ADR-030-CORRECTED suggests** (line 131-160):
+**ADR-043-CORRECTED suggests** (line 131-160):
 - Endpoint cache TTL: 3600s (1 hour)
 - Token verification cache TTL: 300s (5 minutes)

@@ -363,7 +363,7 @@ The W3C spec says "first HTTP Link header takes precedence", which suggests **Op

 ### Question 5: URL Resolution and Validation

-**From ADR-030-CORRECTED** line 217:
+**From ADR-043-CORRECTED** line 217:

 ```python
 from urllib.parse import urljoin
--- a/docs/design/v1.0.0/2025-11-24-indieauth-removal-complete.md
+++ b/docs/design/v1.0.0/2025-11-24-indieauth-removal-complete.md
--- a/docs/design/v1.0.0/2025-11-24-migration-detection-hotfix-rc3.md
+++ b/docs/design/v1.0.0/2025-11-24-migration-detection-hotfix-rc3.md
--- a/docs/design/v1.0.0/2025-11-24-migration-fix-v1.0.0-rc.2.md
+++ b/docs/design/v1.0.0/2025-11-24-migration-fix-v1.0.0-rc.2.md
--- a/docs/design/v1.0.0/2025-11-24-phase1-indieauth-server-removal.md
+++ b/docs/design/v1.0.0/2025-11-24-phase1-indieauth-server-removal.md
--- a/docs/design/v1.0.0/2025-11-24-v1.0.0-rc.5-implementation.md
+++ b/docs/design/v1.0.0/2025-11-24-v1.0.0-rc.5-implementation.md
--- a/docs/design/v1.0.0/ADR-025-implementation-report.md
+++ b/docs/design/v1.0.0/ADR-025-implementation-report.md
--- a/docs/design/v1.0.0/ADR-025-implementation-summary.md
+++ b/docs/design/v1.0.0/ADR-025-implementation-summary.md
--- a/docs/design/v1.0.0/ADR-025-versioning-guidance.md
+++ b/docs/design/v1.0.0/ADR-025-versioning-guidance.md
--- a/docs/design/v1.0.0/ARCHITECT-FINAL-ANALYSIS.md
+++ b/docs/design/v1.0.0/ARCHITECT-FINAL-ANALYSIS.md
--- a/docs/design/v1.0.0/container-deployment.md
+++ b/docs/design/v1.0.0/container-deployment.md
--- a/docs/design/v1.0.0/custom-slug-bug-diagnosis.md
+++ b/docs/design/v1.0.0/custom-slug-bug-diagnosis.md
@@ -0,0 +1,231 @@
+# Custom Slug Bug Diagnosis Report
+
+**Date**: 2025-11-25
+**Issue**: Custom slugs (mp-slug) not working in production
+**Architect**: StarPunk Architect Subagent
+
+## Executive Summary
+
+Custom slugs specified via the `mp-slug` property in Micropub requests are being completely ignored in production. The root cause is that `mp-slug` is being incorrectly extracted from the normalized properties dictionary instead of directly from the raw request data.
+
+## Problem Reproduction
+
+### Input
+- **Client**: Quill (Micropub client)
+- **Request Type**: Form-encoded POST to `/micropub`
+- **Content**: "This is a test for custom slugs. Only the best slugs to be found here"
+- **mp-slug**: "slug-test"
+
+### Expected Result
+- Note created with slug: `slug-test`
+
+### Actual Result
+- Note created with auto-generated slug: `this-is-a-test-for-f0x5`
+- Redirect URL: `https://starpunk.thesatelliteoflove.com/notes/this-is-a-test-for-f0x5`
+
+## Root Cause Analysis
+
+### The Bug Location
+
+**File**: `/home/phil/Projects/starpunk/starpunk/micropub.py`
+**Lines**: 299-304
+**Function**: `handle_create()`
+
+```python
+# Extract custom slug if provided (Micropub extension)
+custom_slug = None
+if 'mp-slug' in properties:
+    # mp-slug is an array in Micropub format
+    slug_values = properties.get('mp-slug', [])
+    if slug_values and len(slug_values) > 0:
+        custom_slug = slug_values[0]
+```
+
+### Why It's Broken
+
+The code is looking for `mp-slug` in the `properties` dictionary, but `mp-slug` is **NOT** a property—it's a Micropub server extension parameter. The `normalize_properties()` function explicitly **EXCLUDES** all parameters that start with `mp-` from the properties dictionary.
+
+Looking at line 139 in `micropub.py`:
+```python
+# Skip reserved Micropub parameters
+if key.startswith("mp-") or key in ["action", "url", "access_token", "h"]:
+    continue
+```
+
+This means `mp-slug` is being filtered out before it ever reaches the properties dictionary!
+
+## Data Flow Analysis
+
+### Current (Broken) Flow
+
+1. **Form-encoded request arrives** with `mp-slug=slug-test`
+2. **Raw data parsed** in `micropub_endpoint()` (lines 97-99):
+   ```python
+   data = request.form.to_dict(flat=False)
+   # data = {"content": ["..."], "mp-slug": ["slug-test"], ...}
+   ```
+
+3. **Data passed to `handle_create()`** (line 103)
+
+4. **Properties normalized** via `normalize_properties()` (line 292):
+   - Line 139 **SKIPS** `mp-slug` because it starts with "mp-"
+   - Result: `properties = {"content": ["..."]}`
+   - `mp-slug` is LOST!
+
+5. **Attempt to extract mp-slug** (lines 299-304):
+   - Looks for `mp-slug` in properties
+   - Never finds it (was filtered out)
+   - `custom_slug` remains `None`
+
+6. **Note created** with `custom_slug=None` (line 318)
+   - Falls back to auto-generated slug
+
+### Correct Flow (How It Should Work)
+
+1. Form-encoded request arrives with `mp-slug=slug-test`
+2. Raw data parsed
+3. Data passed to `handle_create()`
+4. Extract `mp-slug` **BEFORE** normalizing properties:
+   ```python
+   # Extract mp-slug from raw data (before normalization)
+   custom_slug = None
+   if isinstance(data, dict):
+       if 'mp-slug' in data:
+           slug_values = data.get('mp-slug', [])
+           if isinstance(slug_values, list) and slug_values:
+               custom_slug = slug_values[0]
+           elif isinstance(slug_values, str):
+               custom_slug = slug_values
+   ```
+5. Normalize properties (mp-slug gets filtered, which is correct)
+6. Pass `custom_slug` to `create_note()`
+
+## The Fix
+
+### Required Code Changes
+
+**File**: `/home/phil/Projects/starpunk/starpunk/micropub.py`
+**Function**: `handle_create()`
+**Lines to modify**: 289-305
+
+Replace the current implementation:
+```python
+# Normalize and extract properties
+try:
+    properties = normalize_properties(data)
+    content = extract_content(properties)
+    title = extract_title(properties)
+    tags = extract_tags(properties)
+    published_date = extract_published_date(properties)
+
+    # Extract custom slug if provided (Micropub extension)
+    custom_slug = None
+    if 'mp-slug' in properties:  # BUG: mp-slug is not in properties!
+        # mp-slug is an array in Micropub format
+        slug_values = properties.get('mp-slug', [])
+        if slug_values and len(slug_values) > 0:
+            custom_slug = slug_values[0]
+```
+
+With the corrected implementation:
+```python
+# Extract mp-slug BEFORE normalizing properties (it's not a property!)
+custom_slug = None
+if isinstance(data, dict) and 'mp-slug' in data:
+    # Handle both form-encoded (list) and JSON (could be string or list)
+    slug_value = data.get('mp-slug')
+    if isinstance(slug_value, list) and slug_value:
+        custom_slug = slug_value[0]
+    elif isinstance(slug_value, str):
+        custom_slug = slug_value
+
+# Normalize and extract properties
+try:
+    properties = normalize_properties(data)
+    content = extract_content(properties)
+    title = extract_title(properties)
+    tags = extract_tags(properties)
+    published_date = extract_published_date(properties)
+```
+
+### Why This Fix Works
+
+1. **Extracts mp-slug from raw data** before normalization filters it out
+2. **Handles both formats**:
+   - Form-encoded: `mp-slug` is a list `["slug-test"]`
+   - JSON: `mp-slug` could be string or list
+3. **Preserves the custom slug** through to `create_note()`
+4. **Maintains separation**: mp-slug is correctly treated as a server parameter, not a property
+
+## Validation Strategy
+
+### Test Cases
+
+1. **Form-encoded with mp-slug**:
+   ```
+   POST /micropub
+   Content-Type: application/x-www-form-urlencoded
+
+   content=Test+post&mp-slug=custom-slug
+   ```
+   Expected: Note created with slug "custom-slug"
+
+2. **JSON with mp-slug**:
+   ```json
+   {
+     "type": ["h-entry"],
+     "properties": {
+       "content": ["Test post"]
+     },
+     "mp-slug": "custom-slug"
+   }
+   ```
+   Expected: Note created with slug "custom-slug"
+
+3. **Without mp-slug**:
+   Should auto-generate slug from content
+
+4. **Reserved slug**:
+   mp-slug="api" should be rejected
+
+5. **Duplicate slug**:
+   Should make unique with suffix
+
+### Verification Steps
+
+1. Apply the fix to `micropub.py`
+2. Test with Quill client specifying custom slug
+3. Verify slug matches the specified value
+4. Check database to confirm correct slug storage
+5. Test all edge cases above
+
+## Architectural Considerations
+
+### Design Validation
+
+The current architecture is sound:
+- Separation between Micropub parameters and properties is correct
+- Slug validation pipeline in `slug_utils.py` is well-designed
+- `create_note()` correctly accepts `custom_slug` parameter
+
+The bug was purely an implementation error, not an architectural flaw.
+
+### Standards Compliance
+
+Per the Micropub specification:
+- `mp-slug` is a server extension, not a property
+- It should be extracted from the request, not from properties
+- The fix aligns with Micropub spec requirements
+
+## Recommendations
+
+1. **Immediate Action**: Apply the fix to `handle_create()` function
+2. **Add Tests**: Create unit tests for mp-slug extraction
+3. **Documentation**: Update implementation notes to clarify mp-slug handling
+4. **Code Review**: Check for similar parameter/property confusion elsewhere
+
+## Conclusion
+
+The custom slug feature is architecturally complete and correctly designed. The bug is a simple implementation error where `mp-slug` is being looked for in the wrong place. The fix is straightforward: extract `mp-slug` from the raw request data before it gets filtered out by the property normalization process.
+
+This is a classic case of correct design with incorrect implementation—the kind of bug that's invisible in code review but immediately apparent in production use.
--- a/docs/design/v1.0.0/custom-slug-bug-implementation.md
+++ b/docs/design/v1.0.0/custom-slug-bug-implementation.md
@@ -0,0 +1,205 @@
+# Custom Slug Bug Fix - Implementation Report
+
+**Date**: 2025-11-25
+**Developer**: StarPunk Developer Subagent
+**Branch**: bugfix/custom-slug-extraction
+**Status**: Complete - Ready for Testing
+
+## Executive Summary
+
+Successfully fixed the custom slug extraction bug in the Micropub handler. Custom slugs specified via `mp-slug` parameter are now correctly extracted and used when creating notes.
+
+## Problem Statement
+
+Custom slugs specified via the `mp-slug` property in Micropub requests were being completely ignored. The system was falling back to auto-generated slugs even when a custom slug was provided by the client (e.g., Quill).
+
+**Root Cause**: `mp-slug` was being extracted from normalized properties after it had already been filtered out by `normalize_properties()` which removes all `mp-*` parameters.
+
+## Implementation Details
+
+### Files Modified
+
+1. **starpunk/micropub.py** (lines 290-307)
+   - Moved `mp-slug` extraction to BEFORE property normalization
+   - Added support for both form-encoded and JSON request formats
+   - Added clear comments explaining the timing requirement
+
+2. **tests/test_micropub.py** (added lines 191-246)
+   - Added `test_micropub_create_with_custom_slug_form()` - tests form-encoded requests
+   - Added `test_micropub_create_with_custom_slug_json()` - tests JSON requests
+   - Both tests verify the custom slug is actually used in the created note
+
+### Code Changes
+
+#### Before (Broken)
+```python
+# Normalize and extract properties
+try:
+    properties = normalize_properties(data)  # mp-slug gets filtered here!
+    content = extract_content(properties)
+    title = extract_title(properties)
+    tags = extract_tags(properties)
+    published_date = extract_published_date(properties)
+
+    # Extract custom slug if provided (Micropub extension)
+    custom_slug = None
+    if 'mp-slug' in properties:  # BUG: mp-slug not in properties!
+        slug_values = properties.get('mp-slug', [])
+        if slug_values and len(slug_values) > 0:
+            custom_slug = slug_values[0]
+```
+
+#### After (Fixed)
+```python
+# Extract mp-slug BEFORE normalizing properties (it's not a property!)
+# mp-slug is a Micropub server extension parameter that gets filtered during normalization
+custom_slug = None
+if isinstance(data, dict) and 'mp-slug' in data:
+    # Handle both form-encoded (list) and JSON (could be string or list)
+    slug_value = data.get('mp-slug')
+    if isinstance(slug_value, list) and slug_value:
+        custom_slug = slug_value[0]
+    elif isinstance(slug_value, str):
+        custom_slug = slug_value
+
+# Normalize and extract properties
+try:
+    properties = normalize_properties(data)
+    content = extract_content(properties)
+    title = extract_title(properties)
+    tags = extract_tags(properties)
+    published_date = extract_published_date(properties)
+```
+
+### Why This Fix Works
+
+1. **Extracts before filtering**: Gets `mp-slug` from raw request data before `normalize_properties()` filters it out
+2. **Handles both formats**:
+   - Form-encoded: `mp-slug` is a list `["slug-value"]`
+   - JSON: `mp-slug` can be string `"slug-value"` or list `["slug-value"]`
+3. **Preserves existing flow**: The `custom_slug` variable was already being passed to `create_note()` correctly
+4. **Architecturally correct**: Treats `mp-slug` as a server parameter (not a property), which aligns with Micropub spec
+
+## Test Results
+
+### Micropub Test Suite
+All 13 Micropub tests passed:
+```
+tests/test_micropub.py::test_micropub_no_token PASSED
+tests/test_micropub.py::test_micropub_invalid_token PASSED
+tests/test_micropub.py::test_micropub_insufficient_scope PASSED
+tests/test_micropub.py::test_micropub_create_note_form PASSED
+tests/test_micropub.py::test_micropub_create_note_json PASSED
+tests/test_micropub.py::test_micropub_create_with_name PASSED
+tests/test_micropub.py::test_micropub_create_with_categories PASSED
+tests/test_micropub.py::test_micropub_create_with_custom_slug_form PASSED  # NEW
+tests/test_micropub.py::test_micropub_create_with_custom_slug_json PASSED  # NEW
+tests/test_micropub.py::test_micropub_query_config PASSED
+tests/test_micropub.py::test_micropub_query_source PASSED
+tests/test_micropub.py::test_micropub_missing_content PASSED
+tests/test_micropub.py::test_micropub_unsupported_action PASSED
+```
+
+### New Test Coverage
+
+**Test 1: Form-encoded with custom slug**
+- Request: `POST /micropub` with `content=...&mp-slug=my-custom-slug`
+- Verifies: Location header ends with `/notes/my-custom-slug`
+- Verifies: Note exists in database with correct slug
+
+**Test 2: JSON with custom slug**
+- Request: `POST /micropub` with JSON body including `"mp-slug": "json-custom-slug"`
+- Verifies: Location header ends with `/notes/json-custom-slug`
+- Verifies: Note exists in database with correct slug
+
+### Regression Testing
+
+All existing Micropub tests continue to pass, confirming:
+- Authentication still works correctly
+- Scope checking still works correctly
+- Auto-generated slugs still work when no `mp-slug` provided
+- Content extraction still works correctly
+- Title and category handling still works correctly
+
+## Validation Against Requirements
+
+Per the architect's bug report (`docs/reports/custom-slug-bug-diagnosis.md`):
+
+- [x] Extract `mp-slug` from raw request data
+- [x] Extract BEFORE calling `normalize_properties()`
+- [x] Handle both form-encoded (list) and JSON (string or list) formats
+- [x] Pass `custom_slug` to `create_note()`
+- [x] Add tests for both request formats
+- [x] Ensure existing tests still pass
+
+## Architecture Compliance
+
+The fix maintains architectural correctness:
+
+1. **Separation of Concerns**: `mp-slug` is correctly treated as a server extension parameter, not a Micropub property
+2. **Existing Validation Pipeline**: The slug still goes through all validation in `create_note()`:
+   - Reserved slug checking
+   - Uniqueness checking with suffix generation if needed
+   - Sanitization
+3. **No Breaking Changes**: All existing functionality preserved
+4. **Micropub Spec Compliance**: Aligns with how `mp-*` extensions should be handled
+
+## Deployment Notes
+
+### What to Test in Production
+
+1. **Create note with custom slug via Quill**:
+   - Use Quill client to create a note
+   - Specify a custom slug in the slug field
+   - Verify the created note uses your specified slug
+
+2. **Create note without custom slug**:
+   - Create a note without specifying a slug
+   - Verify auto-generation still works
+
+3. **Reserved slug handling**:
+   - Try to create a note with slug "api" or "admin"
+   - Should be rejected with validation error
+
+4. **Duplicate slug handling**:
+   - Create a note with slug "test-slug"
+   - Try to create another with the same slug
+   - Should get "test-slug-xxxx" with random suffix
+
+### Known Issues
+
+None. The fix is clean and complete.
+
+### Version Impact
+
+This fix will be included in **v1.1.0-rc.2** (or next release).
+
+## Git Information
+
+**Branch**: `bugfix/custom-slug-extraction`
+**Commit**: 894e5e3
+**Commit Message**: "fix: Extract mp-slug before property normalization"
+
+**Files Changed**:
+- `starpunk/micropub.py` (69 insertions, 8 deletions)
+- `tests/test_micropub.py` (added 2 comprehensive tests)
+
+## Next Steps
+
+1. Merge `bugfix/custom-slug-extraction` into `main`
+2. Deploy to production
+3. Test with Quill client in production environment
+4. Update CHANGELOG.md with fix details
+5. Close any related issue tickets
+
+## References
+
+- **Bug Diagnosis**: `/home/phil/Projects/starpunk/docs/reports/custom-slug-bug-diagnosis.md`
+- **Micropub Spec**: https://www.w3.org/TR/micropub/
+- **Related ADR**: ADR-029 (Micropub Property Mapping)
+
+## Conclusion
+
+The custom slug feature is now fully functional. The bug was a simple timing issue in the extraction logic - trying to get `mp-slug` after it had been filtered out. The fix is clean, well-tested, and maintains all existing functionality while enabling the custom slug feature as originally designed.
+
+The implementation follows the architect's design exactly and adds comprehensive test coverage for future regression prevention.
--- a/docs/design/v1.0.0/database-migration-architecture.md
+++ b/docs/design/v1.0.0/database-migration-architecture.md
--- a/docs/design/v1.0.0/database-migration-conflict-diagnosis.md
+++ b/docs/design/v1.0.0/database-migration-conflict-diagnosis.md
--- a/docs/design/v1.0.0/delete-nonexistent-note-error-analysis.md
+++ b/docs/design/v1.0.0/delete-nonexistent-note-error-analysis.md
--- a/docs/design/v1.0.0/delete-route-404-fix-implementation.md
+++ b/docs/design/v1.0.0/delete-route-404-fix-implementation.md
--- a/docs/design/v1.0.0/delete-route-fix-summary.md
+++ b/docs/design/v1.0.0/delete-route-fix-summary.md
--- a/docs/design/v1.0.0/delete-route-implementation-spec.md
+++ b/docs/design/v1.0.0/delete-route-implementation-spec.md
--- a/docs/projectplan/v1/dependencies-diagram.md
+++ b/docs/projectplan/v1/dependencies-diagram.md
--- a/docs/design/v1.0.0/endpoint-discovery-answers.md
+++ b/docs/design/v1.0.0/endpoint-discovery-answers.md
--- a/docs/design/v1.0.0/error-handling-rest-vs-web-patterns.md
+++ b/docs/design/v1.0.0/error-handling-rest-vs-web-patterns.md
--- a/docs/projectplan/v1/feature-scope.md
+++ b/docs/projectplan/v1/feature-scope.md
--- a/docs/design/v1.0.0/fix-hardcoded-endpoints.md
+++ b/docs/design/v1.0.0/fix-hardcoded-endpoints.md
--- a/docs/design/v1.0.0/identity-domain-validation-2025-11-19.md
+++ b/docs/design/v1.0.0/identity-domain-validation-2025-11-19.md
--- a/docs/design/v1.0.0/identity-page-customization-guide.md
+++ b/docs/design/v1.0.0/identity-page-customization-guide.md
--- a/docs/design/v1.0.0/identity-page.html
+++ b/docs/design/v1.0.0/identity-page.html
--- a/docs/design/v1.0.0/implementation-guide-expose-deleted-at.md
+++ b/docs/design/v1.0.0/implementation-guide-expose-deleted-at.md
--- a/docs/projectplan/v1/implementation-plan.md
+++ b/docs/projectplan/v1/implementation-plan.md
@@ -4,8 +4,8 @@

 This document provides a comprehensive, dependency-ordered implementation plan for StarPunk V1, taking the project from its current state to a fully functional IndieWeb CMS.

-**Current State**: Phase 5 Complete - RSS feed and container deployment (v0.9.5)
-**Current Version**: 0.9.5
+**Current State**: V1.1.0 Released - Full-text search, custom slugs, and RSS fixes
+**Current Version**: 1.1.0 "SearchLight"
 **Target State**: Working V1 with all features implemented, tested, and documented
 **Estimated Total Effort**: ~40-60 hours of focused development
 **Completed Effort**: ~35 hours (Phases 1-5 mostly complete)
@@ -13,7 +13,7 @@ This document provides a comprehensive, dependency-ordered implementation plan f

 ## Progress Summary

-**Last Updated**: 2025-11-24
+**Last Updated**: 2025-11-25

 ### Completed Phases ✅

@@ -25,68 +25,74 @@ This document provides a comprehensive, dependency-ordered implementation plan f
 | 3.1 - Authentication | ✅ Complete | 0.8.0 | 96% (51 tests) | [Phase 3 Report](/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md) |
 | 4.1-4.4 - Web Interface | ✅ Complete | 0.5.2 | 87% (405 tests) | Phase 4 implementation |
 | 5.1-5.2 - RSS Feed | ✅ Complete | 0.6.0 | 96% | ADR-014, ADR-015 |
+| 6 - Micropub | ✅ Complete | 1.0.0 | 95% | [v1.0.0 Release](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md) |
+| V1.1 - Search & Enhancements | ✅ Complete | 1.1.0 | 598 tests | [v1.1.0 Report](/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md) |

 ### Current Status 🔵

-**Phase 6**: Micropub Endpoint (NOT YET IMPLEMENTED)
- **Status**: NOT STARTED - Planned for V1 but not yet implemented
- **Current Blocker**: Need to complete Micropub implementation
- **Progress**: 0%
+**V1.1.0 RELEASED** - StarPunk "SearchLight"
+- **Status**: ✅ COMPLETE - Released 2025-11-25
+- **Major Features**: Full-text search, custom slugs, RSS fixes
+- **Test Coverage**: 598 tests (588 passing)
+- **Backwards Compatible**: 100%

-### Remaining Phases ⏳
+### Completed V1 Features ✅

-| Phase | Estimated Effort | Priority | Status |
-|-------|-----------------|----------|---------|
-| 6 - Micropub | 9-12 hours | HIGH | ❌ NOT IMPLEMENTED |
-| 7 - REST API (Notes CRUD) | 3-4 hours | LOW (optional) | ❌ NOT IMPLEMENTED |
-| 8 - Testing & QA | 9-12 hours | HIGH | ⚠️ PARTIAL (standards validation pending) |
-| 9 - Documentation | 5-7 hours | HIGH | ⚠️ PARTIAL (some docs complete) |
-| 10 - Release Prep | 3-5 hours | CRITICAL | ⏳ PENDING |
+All core V1 features are now complete:
+- ✅ IndieAuth authentication
+- ✅ Micropub endpoint (v1.0.0)
+- ✅ Notes management CRUD
+- ✅ RSS feed generation
+- ✅ Web interface (public & admin)
+- ✅ Full-text search (v1.1.0)
+- ✅ Custom slugs (v1.1.0)
+- ✅ Database migrations

-**Overall Progress**: ~70% complete (Phases 1-5 done, Phase 6 critical blocker for V1)
+### Optional Features (Not Required for V1)
+
+| Feature | Estimated Effort | Priority | Status |
+|---------|-----------------|----------|---------|
+| REST API (Notes CRUD) | 3-4 hours | LOW | ⏳ DEFERRED to v1.2.0 |
+| Enhanced Documentation | 5-7 hours | MEDIUM | ⏳ ONGOING |
+| Performance Optimization | 3-5 hours | LOW | ⏳ As needed |
+
+**Overall Progress**: ✅ **100% V1 COMPLETE** - All required features implemented

 ---

-## CRITICAL: Unimplemented Features in v0.9.5
+## V1 Features Implementation Status

-These features are **IN SCOPE for V1** but **NOT YET IMPLEMENTED** as of v0.9.5:
+All V1 required features have been successfully implemented:

-### 1. Micropub Endpoint ❌
-**Status**: NOT IMPLEMENTED
-**Routes**: `/api/micropub` does not exist
-**Impact**: Cannot publish from external Micropub clients (Quill, Indigenous, etc.)
-**Required for V1**: YES (core IndieWeb feature)
-**Tracking**: Phase 6 (9-12 hours estimated)
+### 1. Micropub Endpoint ✅
+**Status**: IMPLEMENTED (v1.0.0)
+**Routes**: `/api/micropub` fully functional
+**Features**: Create notes, mp-slug support, IndieAuth integration
+**Testing**: Comprehensive test suite, Micropub.rocks validated

-### 2. Notes CRUD API ❌
-**Status**: NOT IMPLEMENTED
-**Routes**: `/api/notes/*` do not exist
-**Impact**: No RESTful JSON API for notes management
-**Required for V1**: NO (optional, Phase 7)
-**Note**: Admin web interface uses forms, not API
+### 2. IndieAuth Integration ✅
+**Status**: IMPLEMENTED (v1.0.0)
+**Features**: Authorization endpoint, token verification
+**Integration**: Works with IndieLogin.com and other providers
+**Security**: Token validation, PKCE support

-### 3. RSS Feed Active Generation ⚠️
-**Status**: CODE EXISTS but route may not be wired correctly
-**Route**: `/feed.xml` should exist but needs verification
-**Impact**: RSS syndication may not be working
-**Required for V1**: YES (core syndication feature)
-**Implemented in**: v0.6.0 (feed module exists, route should be active)
+### 3. RSS Feed Generation ✅
+**Status**: IMPLEMENTED (v0.6.0, fixed in v1.1.0)
+**Route**: `/feed.xml` active and working
+**Features**: Valid RSS 2.0, newest-first ordering
+**Validation**: W3C feed validator passed

-### 4. IndieAuth Token Endpoint ❌
-**Status**: AUTHORIZATION ENDPOINT ONLY
-**Current**: Only authentication flow implemented (for admin login)
-**Missing**: Token endpoint for Micropub authentication
-**Impact**: Cannot authenticate Micropub requests
-**Required for V1**: YES (required for Micropub)
-**Note**: May use external IndieAuth server instead of self-hosted
+### 4. Full-Text Search ✅
+**Status**: IMPLEMENTED (v1.1.0)
+**Features**: SQLite FTS5, search UI, API endpoint
+**Routes**: `/search`, `/api/search`
+**Security**: XSS prevention, query validation

-### 5. Microformats Validation ⚠️
-**Status**: MARKUP EXISTS but not validated
-**Current**: Templates have microformats (h-entry, h-card, h-feed)
-**Missing**: IndieWebify.me validation tests
-**Impact**: May not parse correctly in microformats parsers
-**Required for V1**: YES (standards compliance)
-**Tracking**: Phase 8.2 (validation tests)
+### 5. Custom Slugs ✅
+**Status**: IMPLEMENTED (v1.1.0)
+**Features**: Micropub mp-slug support
+**Validation**: Reserved slug protection, sanitization
+**Integration**: Seamless with existing slug generation

 ---

--- a/docs/design/v1.0.0/indieauth-assessment.md
+++ b/docs/design/v1.0.0/indieauth-assessment.md
--- a/docs/design/v1.0.0/indieauth-client-diagnosis.md
+++ b/docs/design/v1.0.0/indieauth-client-diagnosis.md
--- a/docs/design/v1.0.0/indieauth-client-discovery-analysis.md
+++ b/docs/design/v1.0.0/indieauth-client-discovery-analysis.md
--- a/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
+++ b/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
--- a/docs/design/v1.0.0/indieauth-client-discovery-root-cause-analysis.md
+++ b/docs/design/v1.0.0/indieauth-client-discovery-root-cause-analysis.md
--- a/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
+++ b/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
--- a/docs/design/v1.0.0/indieauth-endpoint-discovery-security.md
+++ b/docs/design/v1.0.0/indieauth-endpoint-discovery-security.md
--- a/docs/design/v1.0.0/indieauth-endpoint-discovery.md
+++ b/docs/design/v1.0.0/indieauth-endpoint-discovery.md
--- a/docs/design/v1.0.0/indieauth-fix-summary.md
+++ b/docs/design/v1.0.0/indieauth-fix-summary.md
--- a/docs/design/v1.0.0/indieauth-identity-page.md
+++ b/docs/design/v1.0.0/indieauth-identity-page.md
--- a/docs/design/v1.0.0/indieauth-questions-answered.md
+++ b/docs/design/v1.0.0/indieauth-questions-answered.md
--- a/docs/design/v1.0.0/indieauth-removal-analysis.md
+++ b/docs/design/v1.0.0/indieauth-removal-analysis.md
--- a/docs/design/v1.0.0/indieauth-removal-architectural-review.md
+++ b/docs/design/v1.0.0/indieauth-removal-architectural-review.md
--- a/docs/design/v1.0.0/indieauth-removal-implementation-guide.md
+++ b/docs/design/v1.0.0/indieauth-removal-implementation-guide.md
--- a/docs/design/v1.0.0/indieauth-removal-phases.md
+++ b/docs/design/v1.0.0/indieauth-removal-phases.md
--- a/docs/design/v1.0.0/indieauth-removal-plan.md
+++ b/docs/design/v1.0.0/indieauth-removal-plan.md
--- a/docs/design/v1.0.0/indieauth-removal-questions.md
+++ b/docs/design/v1.0.0/indieauth-removal-questions.md
--- a/docs/design/v1.0.0/indieauth-spec-url-standardization-2025-11-24.md
+++ b/docs/design/v1.0.0/indieauth-spec-url-standardization-2025-11-24.md
--- a/docs/design/v1.0.0/indieauth-token-verification-diagnosis.md
+++ b/docs/design/v1.0.0/indieauth-token-verification-diagnosis.md
@@ -0,0 +1,160 @@
+# IndieAuth Token Verification Diagnosis
+
+## Executive Summary
+
+**The Problem**: StarPunk is receiving HTTP 405 Method Not Allowed when verifying tokens with gondulf.thesatelliteoflove.com
+
+**The Cause**: The gondulf IndieAuth provider does not implement the W3C IndieAuth specification correctly
+
+**The Solution**: The provider needs to be fixed - StarPunk's implementation is correct
+
+## Why We Make GET Requests
+
+You asked: "Why are we making GET requests to these endpoints?"
+
+**Answer**: Because the W3C IndieAuth specification explicitly requires GET requests for token verification.
+
+### The IndieAuth Token Endpoint Dual Purpose
+
+The token endpoint serves two distinct purposes with different HTTP methods:
+
+1. **Token Issuance (POST)**
+   - Client sends authorization code
+   - Server returns new access token
+   - State-changing operation
+
+2. **Token Verification (GET)**
+   - Resource server sends token in Authorization header
+   - Token endpoint returns token metadata
+   - Read-only operation
+
+### Why This Design Makes Sense
+
+The specification follows RESTful principles:
+
+- **GET** = Read data (verify a token exists and is valid)
+- **POST** = Create/modify data (issue a new token)
+
+This is similar to how you might:
+- GET /users/123 to read user information
+- POST /users to create a new user
+
+## The Specific Problem
+
+### What Should Happen
+```
+StarPunk → GET https://gondulf.thesatelliteoflove.com/token
+           Authorization: Bearer abc123...
+
+Gondulf  → 200 OK
+           {
+             "me": "https://thesatelliteoflove.com",
+             "client_id": "https://starpunk.example",
+             "scope": "create"
+           }
+```
+
+### What Actually Happens
+```
+StarPunk → GET https://gondulf.thesatelliteoflove.com/token
+           Authorization: Bearer abc123...
+
+Gondulf  → 405 Method Not Allowed
+           (Server doesn't support GET on /token)
+```
+
+## Code Analysis
+
+### Our Implementation (Correct)
+
+From `/home/phil/Projects/starpunk/starpunk/auth_external.py` line 425:
+
+```python
+def _verify_with_endpoint(endpoint: str, token: str) -> Dict[str, Any]:
+    """
+    Verify token with the discovered token endpoint
+
+    Makes GET request to endpoint with Authorization header.
+    """
+    headers = {
+        'Authorization': f'Bearer {token}',
+        'Accept': 'application/json',
+    }
+
+    response = httpx.get(  # ← Correct: Using GET
+        endpoint,
+        headers=headers,
+        timeout=VERIFICATION_TIMEOUT,
+        follow_redirects=True,
+    )
+```
+
+### IndieAuth Spec Reference
+
+From W3C IndieAuth Section 6.3.4:
+
+> "If an external endpoint needs to verify that an access token is valid, it **MUST** make a **GET request** to the token endpoint containing an HTTP `Authorization` header with the Bearer Token according to RFC6750."
+
+(Emphasis added)
+
+## Why the Provider is Wrong
+
+The gondulf IndieAuth provider appears to:
+1. Only implement POST for token issuance
+2. Not implement GET for token verification
+3. Return 405 for any GET requests to /token
+
+This is only a partial implementation of IndieAuth.
+
+## Impact Analysis
+
+### What This Breaks
+- StarPunk cannot authenticate users through gondulf
+- Any other spec-compliant Micropub client would also fail
+- The provider is not truly IndieAuth compliant
+
+### What This Doesn't Break
+- Our code is correct
+- We can work with any compliant IndieAuth provider
+- The architecture is sound
+
+## Solutions
+
+### Option 1: Fix the Provider (Recommended)
+The gondulf provider needs to:
+1. Add GET method support to /token endpoint
+2. Verify bearer tokens from Authorization header
+3. Return appropriate JSON response
+
+### Option 2: Use a Different Provider
+Known compliant providers:
+- IndieAuth.com
+- IndieLogin.com
+- Self-hosted IndieAuth servers that implement full spec
+
+### Option 3: Work Around (Not Recommended)
+We could add a non-compliant mode, but this would:
+- Violate the specification
+- Encourage bad implementations
+- Add unnecessary complexity
+- Create security concerns
+
+## Summary
+
+**Your Question**: "Why are we making GET requests to these endpoints?"
+
+**Answer**: Because that's what the IndieAuth specification requires for token verification. We're doing it right. The gondulf provider is doing it wrong.
+
+**Action Required**: The gondulf IndieAuth provider needs to implement GET support on their token endpoint to be IndieAuth compliant.
+
+## References
+
+1. [W3C IndieAuth - Token Verification](https://www.w3.org/TR/indieauth/#token-verification)
+2. [RFC 6750 - OAuth 2.0 Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
+3. [StarPunk Implementation](https://github.com/starpunk/starpunk/blob/main/starpunk/auth_external.py)
+
+## Contact Information for Provider
+
+If you need to report this to the gondulf provider:
+
+"Your IndieAuth token endpoint at https://gondulf.thesatelliteoflove.com/token returns HTTP 405 Method Not Allowed for GET requests. Per the W3C IndieAuth specification Section 6.3.4, the token endpoint MUST support GET requests with Bearer authentication for token verification. Currently it appears to only support POST for token issuance."
--- a/docs/design/v1.0.0/initial-files.md
+++ b/docs/design/v1.0.0/initial-files.md
--- a/docs/design/v1.0.0/initial-schema-implementation-guide.md
+++ b/docs/design/v1.0.0/initial-schema-implementation-guide.md
--- a/docs/design/v1.0.0/initial-schema-quick-reference.md
+++ b/docs/design/v1.0.0/initial-schema-quick-reference.md
--- a/docs/design/v1.0.0/micropub-401-diagnosis.md
+++ b/docs/design/v1.0.0/micropub-401-diagnosis.md
--- a/docs/design/v1.0.0/micropub-endpoint-design.md
+++ b/docs/design/v1.0.0/micropub-endpoint-design.md
--- a/docs/design/v1.0.0/micropub-phase1-architecture-review.md
+++ b/docs/design/v1.0.0/micropub-phase1-architecture-review.md
--- a/docs/design/v1.0.0/micropub-phase3-architecture-review.md
+++ b/docs/design/v1.0.0/micropub-phase3-architecture-review.md
--- a/docs/design/v1.0.0/micropub-v1-implementation-progress.md
+++ b/docs/design/v1.0.0/micropub-v1-implementation-progress.md
--- a/docs/design/v1.0.0/migration-failure-diagnosis-v1.0.0-rc.1.md
+++ b/docs/design/v1.0.0/migration-failure-diagnosis-v1.0.0-rc.1.md
--- a/docs/design/v1.0.0/migration-fix-quick-reference.md
+++ b/docs/design/v1.0.0/migration-fix-quick-reference.md
--- a/docs/design/v1.0.0/migration-race-condition-answers.md
+++ b/docs/design/v1.0.0/migration-race-condition-answers.md
--- a/docs/design/v1.0.0/migration-race-condition-fix-implementation.md
+++ b/docs/design/v1.0.0/migration-race-condition-fix-implementation.md
--- a/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
+++ b/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
--- a/docs/design/v1.0.0/phase-1.1-core-utilities.md
+++ b/docs/design/v1.0.0/phase-1.1-core-utilities.md
--- a/Show More
+++ b/Show More