fix(media): Add MAX_CONTENT_LENGTH and debug file capture - v1.4.2

- Set Flask MAX_CONTENT_LENGTH to 50MB (matches MAX_FILE_SIZE)
- Save failed uploads to data/debug/ for analysis
- Log magic bytes when both Pillow and HEIC parsers fail

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

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

CHANGELOG.md

@@ -7,7 +7,237 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.2.0-rc.2] - 2025-12-09
+## [1.4.2] - 2025-12-16
+
+### Added
+
+- HEIC/HEIF image format support for iPhone photo uploads
+- Automatic HEIC to JPEG conversion (browsers cannot display HEIC)
+- Graceful error handling if pillow-heif library not installed
+
+### Dependencies
+
+- Added `pillow-heif` for HEIC image processing
+- Updated `Pillow` from 10.0.* to 10.1.* (required by pillow-heif)
+
+## [1.4.1] - 2025-12-16
+
+### Fixed
+
+- Media upload failures are now logged for debugging and observability
+- Validation errors (invalid format, file too large) logged at WARNING level
+- Optimization failures logged at WARNING level
+- Variant generation failures logged at WARNING level (upload continues)
+- Unexpected errors logged at ERROR level with error type and message
+- Successful uploads logged at INFO level with file details
+- Removed duplicate logging in Micropub media endpoint
+
+## [1.4.0rc1] - 2025-12-16
+
+### Added
+
+- **Large Image Support** - Accept and optimize images up to 50MB (Phase 1)
+  - Increased file size limit from 10MB to 50MB for image uploads
+  - Tiered resize strategy based on input size:
+    - <=10MB: 2048px max dimension, 95% quality
+    - 10-25MB: 1600px max dimension, 90% quality
+    - 25-50MB: 1280px max dimension, 85% quality
+  - Iterative quality reduction if output still >10MB after optimization
+  - Rejects if optimization cannot achieve <=10MB target (minimum 640px at 70% quality)
+  - Animated GIF detection with 10MB size limit (cannot be resized)
+  - All optimized images kept at or under 10MB for web performance
+
+- **Image Variants** - Multiple image sizes for responsive delivery (Phase 2)
+  - Four variants generated automatically on upload:
+    - thumb: 150x150 center crop for thumbnails
+    - small: 320px width for mobile/low bandwidth
+    - medium: 640px width for standard display
+    - large: 1280px width for high-res display
+    - original: As uploaded (optimized, <=2048px)
+  - Variants stored in date-organized folders (data/media/YYYY/MM/)
+  - Database tracking in new `media_variants` table
+  - Synchronous/eager generation on upload
+  - Only new uploads get variants (existing media unchanged)
+  - Cascade deletion with parent media
+  - Variants included in `get_note_media()` response (backwards compatible)
+
+- **Micropub Media Endpoint** - W3C-compliant media upload (Phase 3)
+  - New POST `/micropub/media` endpoint for file uploads
+  - Multipart/form-data with single file part named 'file'
+  - Bearer token authentication with `create` scope (no new scope needed)
+  - Returns 201 Created with Location header on success
+  - Automatic variant generation on upload
+  - OAuth 2.0 error format for all error responses
+  - Media endpoint advertised in `q=config` query response
+  - Photo property support in Micropub create requests:
+    - Simple URL strings: `"photo": ["https://example.com/image.jpg"]`
+    - Structured with alt text: `"photo": [{"value": "url", "alt": "description"}]`
+    - Multiple photos supported (max 4 per ADR-057)
+    - External URLs logged and ignored (no download)
+    - Photo captions preserved from alt text
+
+- **Enhanced Feed Media** - Full Media RSS and JSON Feed variants (Phase 4)
+  - RSS 2.0: Complete Media RSS namespace support
+    - `media:group` element for multiple sizes of same image
+    - `media:content` for each variant with dimensions and file size
+    - `media:thumbnail` element for preview images
+    - `media:title` for captions (when present)
+    - `isDefault` attribute on largest available variant
+  - JSON Feed 1.1: `_starpunk` extension with variants
+    - All variants with URLs, dimensions, and sizes
+    - Configurable `about` URL for extension documentation
+    - Default: `https://github.com/yourusername/starpunk`
+    - Override via `STARPUNK_ABOUT_URL` config
+  - ATOM 1.0: Enclosures with title attribute for captions
+  - Backwards compatible: Feeds work with and without variants
+
+### Changed
+
+- **Image Optimization** - Enhanced for large file handling
+  - `optimize_image()` now accepts `original_size` parameter
+  - Returns both optimized image and bytes (avoids re-saving)
+  - Iterative quality reduction loop for difficult-to-compress images
+  - Safety check prevents infinite loops (minimum 640px dimension)
+
+- **Media Storage** - Extended with variant support
+  - `save_media()` generates variants synchronously after saving original
+  - Variants cleaned up automatically on generation failure
+  - Database records original as 'original' variant type
+  - File size passed efficiently without redundant I/O
+
+### Technical Details
+
+- **Migration 009**: Add `media_variants` table
+  - Tracks variant_type, path, dimensions, and file size
+  - Foreign key to media table with cascade delete
+  - Unique constraint on (media_id, variant_type)
+  - Index on media_id for efficient lookups
+
+- **New Functions**:
+  - `get_optimization_params(file_size)` - Tiered resize strategy
+  - `generate_variant()` - Single variant generation
+  - `generate_all_variants()` - Full variant set with DB storage
+  - `extract_photos()` - Micropub photo property parsing
+  - `_attach_photos_to_note()` - Photo attachment to notes
+
+- **Modified Functions**:
+  - `validate_image()` - 50MB limit, animated GIF detection
+  - `optimize_image()` - Size-aware tiered optimization
+  - `save_media()` - Variant generation integration
+  - `get_note_media()` - Includes variants (when present)
+  - `handle_query()` - Advertises media-endpoint in config
+  - `handle_create()` - Photo property extraction and attachment
+  - `generate_rss_streaming()` - Media RSS support
+  - `_build_item_object()` - JSON Feed variants
+  - `generate_atom_streaming()` - Enclosure title attributes
+
+- **Configuration Options**:
+  - `STARPUNK_ABOUT_URL` - JSON Feed extension documentation URL
+
+### Standards Compliance
+
+- W3C Micropub Media Endpoint Specification
+- Media RSS 2.0 Specification (RSS Board)
+- JSON Feed 1.1 with custom extension
+- OAuth 2.0 Bearer Token Authentication
+- RFC 3339 date formats in feeds
+
+### Storage Impact
+
+- Variants use approximately 4x storage per image:
+  - Original: 100%
+  - Large (1280px): ~50%
+  - Medium (640px): ~25%
+  - Small (320px): ~12%
+  - Thumb (150x150): ~3%
+- Typical 500KB optimized image → ~900KB total with variants
+- Only new uploads generate variants (existing media unchanged)
+
+### Backwards Compatibility
+
+- Existing media files work unchanged
+- No variants generated for pre-v1.4.0 uploads
+- Feeds handle media with and without variants gracefully
+- `get_note_media()` only includes 'variants' key when variants exist
+- All existing Micropub clients continue to work
+
+### Related Documentation
+
+- ADR-057: Media Attachment Model
+- ADR-058: Image Optimization Strategy
+- ADR-059: Full Feed Media Standardization
+- Design: `/docs/design/v1.4.0/media-implementation-design.md`
+
+## [1.3.1] - 2025-12-10
+
+### Added
+
+- **Feed Tags/Categories** - Tags now appear in all syndication feed formats
+  - RSS 2.0: `<category>` elements for each tag
+  - Atom 1.0: `<category term="slug" label="Display Name"/>` per RFC 4287
+  - JSON Feed 1.1: `tags` array with display names
+  - Tags omitted from feeds when note has no tags
+
+### Technical Details
+
+- Enhanced: `starpunk/feeds/rss.py` with category elements
+- Enhanced: `starpunk/feeds/atom.py` with category elements
+- Enhanced: `starpunk/feeds/json_feed.py` with tags array
+- Enhanced: `starpunk/routes/public.py` pre-loads tags for feed generation
+
+## [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
@@ -20,15 +250,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Both feed formats maintain existing HTML embedding for universal reader support
   - Provides enhanced display in modern feed readers (Feedly, Inoreader, NetNewsWire)
 
-### 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.2.0-rc.1] - 2025-11-28
-
-### Added
 - **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
@@ -72,6 +293,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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

CLAUDE.md

@@ -8,97 +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 
+1. Review `docs/DOCUMENTATION.md` for documentation organization standards
-   - docs/architecture, docs/decisions, docs/standards are of particular interest 
 
-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**
+1. Review `docs/DOCUMENTATION.md` for documentation organization standards
-   - Create implementation reports in `docs/reports/`
-   - Include date in filename: `YYYY-MM-DD-description.md`
 
-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
+See `docs/DOCUMENTATION.md` for the authoritative documentation structure, navigation guidance, and key references.
-
-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/migration/`** - Migration guides for upgrading between versions and configuration changes
-- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions
-- **`docs/releases/`** - Release-specific documentation, release notes, version information
-- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
-- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives
-- **`docs/security/`** - Security-related documentation, vulnerability analyses, best practices
-- **`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`
 
 ## Project Philosophy
 

README.md

@@ -2,13 +2,13 @@
 
 A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.
 
-**Current Version**: 1.1.0
+**Current Version**: 1.2.0
 
 ## Versioning
 
 StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/):
 - Version format: `MAJOR.MINOR.PATCH`
-- Current: `1.1.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)
@@ -29,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
 
@@ -154,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
+- [Microformats2](http://microformats.org/) - h-entry, h-card, h-feed markup
-- [RSS 2.0](https://www.rssboard.org/rss-specification) - Feed syndication
+- [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
 

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`

docs/deployment/INDEX.md

@@ -1,41 +0,0 @@
-# Deployment Documentation Index
-
-This directory contains deployment guides, infrastructure setup instructions, and operations documentation for StarPunk CMS.
-
-## Deployment Guides
-
-- **[container-deployment.md](container-deployment.md)** - Container-based deployment guide (Docker, Podman)
-
-## Deployment Options
-
-### Container Deployment (Recommended)
-Container deployment provides:
-- Consistent environment across platforms
-- Easy updates and rollbacks
-- Resource isolation
-- Simplified dependency management
-
-See: [container-deployment.md](container-deployment.md)
-
-### Manual Deployment
-For manual deployment without containers:
-- Follow [../standards/development-setup.md](../standards/development-setup.md)
-- Configure systemd service
-- Set up reverse proxy (nginx/Caddy)
-- Configure SSL/TLS certificates
-
-### Cloud Deployment
-StarPunk can be deployed to:
-- Any container platform (Kubernetes, Docker Swarm)
-- VPS providers (DigitalOcean, Linode, Vultr)
-- PaaS platforms supporting containers
-
-## Related Documentation
-- **[../standards/development-setup.md](../standards/development-setup.md)** - Development environment setup
-- **[../architecture/](../architecture/)** - System architecture
-- **[README.md](../../README.md)** - Quick start guide
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent