Merge feature/v1.3.0-tags-microformats into main

Release candidate v1.3.0-rc.1 with tags/categories and enhanced Microformats2 support.

Major features:
- Complete tag/category system with Micropub support
- Strict Microformats2 compliance (p-category, h-feed properties)
- Tag archive pages at /tags/{tag}
- Enhanced h-entry markup with dt-updated
- Proper h-feed structure on collection pages

Generated with Claude Code

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

CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0-rc.1] - 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

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 
-   - 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/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`
+See `docs/DOCUMENTATION.md` for the authoritative documentation structure, navigation guidance, and key references.
 
 ## 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
-- [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
 

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