From f10d0679da6250230c9f57efdfcb3b3fdaec7a02 Mon Sep 17 00:00:00 2001
From: Phil Skentelbery <phil@thesatelliteoflove.com>
Date: Wed, 10 Dec 2025 11:24:23 -0700
Subject: [PATCH] feat(tags): Add database schema and tags module (v1.3.0 Phase
 1)

Implements tag/category system backend following microformats2 p-category specification.

Database changes:
- Migration 008: Add tags and note_tags tables
- Normalized tag storage (case-insensitive lookup, display name preserved)
- Indexes for performance

New module:
- starpunk/tags.py: Tag management functions
  - normalize_tag: Normalize tag strings
  - get_or_create_tag: Get or create tag records
  - add_tags_to_note: Associate tags with notes (replaces existing)
  - get_note_tags: Retrieve note tags (alphabetically ordered)
  - get_tag_by_name: Lookup tag by normalized name
  - get_notes_by_tag: Get all notes with specific tag
  - parse_tag_input: Parse comma-separated tag input

Model updates:
- Note.tags property (lazy-loaded, prefer pre-loading in routes)
- Note.to_dict() add include_tags parameter

CRUD updates:
- create_note() accepts tags parameter
- update_note() accepts tags parameter (None = no change, [] = remove all)

Micropub integration:
- Pass tags to create_note() (tags already extracted by extract_tags())
- Return tags in q=source response

Per design doc: docs/design/v1.3.0/microformats-tags-design.md

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/deployment/INDEX.md                      |  41 --
 .../2025-11-18-auth-redirect-loop-fix.md      |   0
 .../v1.0.0}/2025-11-18-quickfix-auth-loop.md  |   0
 ...-11-19-container-implementation-summary.md |   0
 ...igration-implementation-quick-reference.md |   0
 ...igration-system-implementation-guidance.md |   0
 ...-migration-system-implementation-report.md |   0
 .../v1.0.0}/2025-11-19-todo-test-updates.md   |   0
 .../2025-11-22-auth-route-prefix-fix.md       |   0
 .../2025-11-22-authorization-endpoint-fix.md  |   0
 .../v1.0.0}/2025-11-22-grant-type-fix.md      |   0
 .../2025-11-24-endpoint-discovery-analysis.md |   0
 .../2025-11-24-indieauth-removal-complete.md  |   0
 ...25-11-24-migration-detection-hotfix-rc3.md |   0
 .../2025-11-24-migration-fix-v1.0.0-rc.2.md   |   0
 ...5-11-24-phase1-indieauth-server-removal.md |   0
 .../2025-11-24-v1.0.0-rc.5-implementation.md  |   0
 .../v1.0.0}/ADR-025-implementation-report.md  |   0
 .../v1.0.0}/ADR-025-implementation-summary.md |   0
 .../v1.0.0}/ADR-025-versioning-guidance.md    |   0
 .../v1.0.0}/ARCHITECT-FINAL-ANALYSIS.md       |   0
 .../v1.0.0}/container-deployment.md           |   0
 .../v1.0.0}/custom-slug-bug-diagnosis.md      |   0
 .../v1.0.0}/custom-slug-bug-implementation.md |   0
 .../database-migration-architecture.md        |   0
 .../database-migration-conflict-diagnosis.md  |   0
 .../delete-nonexistent-note-error-analysis.md |   0
 .../delete-route-404-fix-implementation.md    |   0
 .../v1.0.0}/delete-route-fix-summary.md       |   0
 .../delete-route-implementation-spec.md       |   0
 .../v1.0.0}/dependencies-diagram.md           |   0
 .../v1.0.0}/endpoint-discovery-answers.md     |   0
 .../error-handling-rest-vs-web-patterns.md    |   0
 .../v1 => design/v1.0.0}/feature-scope.md     |   0
 .../v1.0.0}/fix-hardcoded-endpoints.md        |   0
 .../identity-domain-validation-2025-11-19.md  |   0
 .../identity-page-customization-guide.md      |   0
 .../v1.0.0}/identity-page.html                |   0
 .../implementation-guide-expose-deleted-at.md |   0
 .../v1.0.0}/implementation-plan.md            |   0
 .../v1.0.0}/indieauth-assessment.md           |   0
 .../v1.0.0}/indieauth-client-diagnosis.md     |   0
 .../indieauth-client-discovery-analysis.md    |   0
 ...uth-client-discovery-fix-implementation.md |   0
 ...th-client-discovery-root-cause-analysis.md |   0
 ...dieauth-detailed-logging-implementation.md |   0
 .../indieauth-endpoint-discovery-security.md  |   0
 .../v1.0.0}/indieauth-endpoint-discovery.md   |   0
 .../v1.0.0}/indieauth-fix-summary.md          |   0
 .../v1.0.0}/indieauth-identity-page.md        |   0
 .../v1.0.0}/indieauth-questions-answered.md   |   0
 .../v1.0.0}/indieauth-removal-analysis.md     |   0
 .../indieauth-removal-architectural-review.md |   0
 .../indieauth-removal-implementation-guide.md |   0
 .../v1.0.0}/indieauth-removal-phases.md       |   0
 .../v1.0.0}/indieauth-removal-plan.md         |   0
 .../v1.0.0}/indieauth-removal-questions.md    |   0
 ...uth-spec-url-standardization-2025-11-24.md |   0
 .../indieauth-token-verification-diagnosis.md |   0
 docs/design/{ => v1.0.0}/initial-files.md     |   0
 .../initial-schema-implementation-guide.md    |   0
 .../initial-schema-quick-reference.md         |   0
 .../v1.0.0}/micropub-401-diagnosis.md         |   0
 .../{ => v1.0.0}/micropub-endpoint-design.md  |   0
 .../micropub-phase1-architecture-review.md    |   0
 .../micropub-phase3-architecture-review.md    |   0
 .../micropub-v1-implementation-progress.md    |   0
 ...migration-failure-diagnosis-v1.0.0-rc.1.md |   0
 .../v1.0.0}/migration-fix-quick-reference.md  |   0
 .../migration-race-condition-answers.md       |   0
 ...ation-race-condition-fix-implementation.md |   0
 ...auth-metadata-implementation-2025-11-19.md |   0
 .../{ => v1.0.0}/phase-1.1-core-utilities.md  |   0
 .../{ => v1.0.0}/phase-1.1-quick-reference.md |   0
 .../{ => v1.0.0}/phase-1.2-data-models.md     |   0
 .../{ => v1.0.0}/phase-1.2-quick-reference.md |   0
 .../v1.0.0}/phase-2-architectural-review.md   |   0
 .../v1.0.0}/phase-2-implementation-report.md  |   0
 .../phase-2.1-implementation-20251118.md      |   0
 .../phase-2.1-notes-management.md             |   0
 .../{ => v1.0.0}/phase-2.1-quick-reference.md |   0
 .../phase-3-authentication-20251118.md        |   0
 ...e-3-authentication-architectural-review.md |   0
 .../phase-3-authentication-implementation.md  |   0
 .../{ => v1.0.0}/phase-3-authentication.md    |   0
 ...ase-4-architectural-assessment-20251118.md |   0
 .../phase-4-error-handling-fix.md             |   0
 .../{ => v1.0.0}/phase-4-quick-reference.md   |   0
 .../v1.0.0}/phase-4-test-fixes.md             |   0
 .../{ => v1.0.0}/phase-4-web-interface.md     |   0
 .../v1.0.0}/phase-5-approval-summary.md       |   0
 .../phase-5-container-architectural-review.md |   0
 ...phase-5-container-implementation-report.md |   0
 .../{ => v1.0.0}/phase-5-executive-summary.md |   0
 .../phase-5-pre-implementation-review.md      |   0
 .../{ => v1.0.0}/phase-5-quick-reference.md   |   0
 .../{ => v1.0.0}/phase-5-rss-and-container.md |   0
 .../phase-5-rss-implementation-20251119.md    |   0
 .../v1.0.0}/phase-5-validation-report.md      |   0
 .../v1.0.0}/phase1-completion-guide.md        |   0
 docs/design/{ => v1.0.0}/project-structure.md |   0
 .../v1 => design/v1.0.0}/quick-reference.md   |   0
 .../v1.0.0}/review-v1.0.0-rc.5.md             |   0
 .../v1.0.0}/setup-complete-2025-11-18.md      |   0
 ...t-failure-analysis-deleted-at-attribute.md |   0
 .../v1.0.0}/troubleshooting.md                |   0
 .../v1.0.0}/v0.9.1-implementation-report.md   |   0
 .../v1.0.0/v1-planning-overview.md}           |   0
 .../v1.0.0-rc.1-hotfix-instructions.md        |   0
 ...migration-race-condition-implementation.md |   0
 .../v1.0.0}/v1.0.0-release-validation.md      |   0
 .../v1.0.0}/v1.0.1-hotfix-plan.md             |   0
 ...11-25-hotfix-v1.1.1-rc.2-implementation.md |   0
 .../2025-11-25-v1.0.1-micropub-url-fix.md     |   0
 .../auth-redirect-loop-diagnosis.md           |   0
 .../auth-redirect-loop-diagram.md             |   0
 .../auth-redirect-loop-executive-summary.md   |   0
 .../auth-redirect-loop-fix-implementation.md  |   0
 .../hotfix-v1.1.1-rc2-consolidated.md         |   0
 .../v1.1.1}/hotfix-v1.1.1-rc2-review.md       |   0
 .../hotfix-v1.1.1-rc2-route-conflict.md       |   0
 .../{ => v1.1.1}/hotfix-validation-script.md  |   0
 .../indieauth-pkce-authentication.md          |   0
 .../v1.1.1}/potential-features.md             |   0
 .../v1.1 => design/v1.1.1}/priority-work.md   |   0
 .../v1.1.1}/syndication-features.md           |   0
 .../{ => v1.1.1}/token-security-migration.md  |   0
 .../v1.1.1}/upgrade-to-v1.1.1.md              |   0
 .../v1.1.1}/v1.1.0-feature-architecture.md    |   0
 .../v1.1.0-implementation-decisions.md        |   0
 .../v1.1.1}/v1.1.0-implementation-plan.md     |   0
 .../v1.1.1}/v1.1.0-implementation-report.md   |   0
 .../v1.1.1/v1.1.0-release-status.md}          |   0
 .../v1.1.1}/v1.1.0-search-ui-validation.md    |   0
 .../v1.1.1}/v1.1.0-validation-report.md       |   0
 .../v1.1.1}/v1.1.1-architecture-overview.md   |   0
 .../v1.1.1}/v1.1.1-final-release-review.md    |   0
 .../v1.1.1-instrumentation-assessment.md      |   0
 .../v1.1.1-phase1-architectural-review.md     |   0
 .../v1.1.1}/v1.1.1-phase1-implementation.md   |   0
 .../v1.1.1-phase2-architectural-review.md     |   0
 .../v1.1.1}/v1.1.1-phase2-implementation.md   |   0
 .../v1.1.1}/v1.1.1-phase3-implementation.md   |   0
 .../2025-11-26-phase2-architect-review.md     |   0
 .../2025-11-26-v1.1.2-phase1-review.md        |   0
 .../2025-11-26-v1.1.2-phase2-complete.md      |   0
 ...1-26-v1.1.2-phase2-feed-formats-partial.md |   0
 .../2025-11-27-phase3-architect-review.md     |   0
 .../2025-11-27-v1.1.2-phase3-complete.md      |   0
 ...2025-11-28-v1.1.2-rc.1-architect-review.md |   0
 ...025-11-28-v1.1.2-rc.1-production-issues.md |   0
 .../v1.1.2}/2025-11-28-v1.1.2-rc.2-fixes.md   |   0
 .../caption-alttext-update.md}                |   0
 .../feed-media-handling-options.md            |   0
 .../{ => v1.1.2}/feed-media-option2-design.md |   0
 .../v1.1.2}/upgrade-to-v1.1.2.md              |   0
 .../v1.1.2/v1.1.2-caption-alttext-update.md   | 153 ++++++++
 .../v1.1.2}/v1.1.2-options.md                 |   0
 .../v1.1.2-phase1-metrics-implementation.md   |   0
 .../v1.1.2}/v1.1.2-syndicate-architecture.md  |   0
 .../2025-11-28-v1.2.0-design-complete.md      |   0
 .../2025-11-28-v1.2.0-media-display-fixes.md} |   0
 .../2025-11-28-v1.2.0-phase1-custom-slugs.md  |   0
 .../2025-11-28-v1.2.0-phase1-review.md        |   0
 ...11-28-v1.2.0-phase2-author-microformats.md |   0
 .../2025-11-28-v1.2.0-phase2-review.md        |   0
 .../2025-11-28-v1.2.0-phase3-media-upload.md  |   0
 .../2025-11-28-v1.2.0-phase3-review.md        |   0
 .../2025-12-09-feed-media-implementation.md   |   0
 .../2025-12-09-media-display-validation.md    |   0
 .../media-css-design.md}                      |   0
 .../{ => v1.2.0}/media-display-fixes.md       |   0
 docs/design/v1.2.0/v1.2.0-media-css-design.md | 114 ++++++
 .../v1.2.0}/v1.X.X-indieweb-options.md        |   0
 .../v1.2.0}/v1.X.X-options.md                 |   0
 docs/examples/INDEX.md                        |  46 ---
 docs/migration/INDEX.md                       |  39 --
 docs/projectplan/INDEX.md                     | 166 --------
 docs/projectplan/ROADMAP.md                   | 368 ------------------
 docs/releases/INDEX.md                        |  45 ---
 docs/reports/INDEX.md                         | 140 -------
 docs/reviews/INDEX.md                         |  38 --
 docs/security/INDEX.md                        |  51 ---
 migrations/008_add_tags.sql                   |  26 ++
 starpunk/micropub.py                          |   9 +-
 starpunk/models.py                            |  30 +-
 starpunk/notes.py                             |  37 +-
 starpunk/tags.py                              | 243 ++++++++++++
 188 files changed, 601 insertions(+), 945 deletions(-)
 delete mode 100644 docs/deployment/INDEX.md
 rename docs/{reports => design/v1.0.0}/2025-11-18-auth-redirect-loop-fix.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-18-quickfix-auth-loop.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-19-container-implementation-summary.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-19-migration-implementation-quick-reference.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-19-migration-system-implementation-guidance.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-19-migration-system-implementation-report.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-19-todo-test-updates.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-22-auth-route-prefix-fix.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-22-authorization-endpoint-fix.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-22-grant-type-fix.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-24-endpoint-discovery-analysis.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-24-indieauth-removal-complete.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-24-migration-detection-hotfix-rc3.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-24-migration-fix-v1.0.0-rc.2.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-24-phase1-indieauth-server-removal.md (100%)
 rename docs/{reports => design/v1.0.0}/2025-11-24-v1.0.0-rc.5-implementation.md (100%)
 rename docs/{reports => design/v1.0.0}/ADR-025-implementation-report.md (100%)
 rename docs/{reports => design/v1.0.0}/ADR-025-implementation-summary.md (100%)
 rename docs/{reports => design/v1.0.0}/ADR-025-versioning-guidance.md (100%)
 rename docs/{reports => design/v1.0.0}/ARCHITECT-FINAL-ANALYSIS.md (100%)
 rename docs/{deployment => design/v1.0.0}/container-deployment.md (100%)
 rename docs/{reports => design/v1.0.0}/custom-slug-bug-diagnosis.md (100%)
 rename docs/{reports => design/v1.0.0}/custom-slug-bug-implementation.md (100%)
 rename docs/{architecture => design/v1.0.0}/database-migration-architecture.md (100%)
 rename docs/{reports => design/v1.0.0}/database-migration-conflict-diagnosis.md (100%)
 rename docs/{reports => design/v1.0.0}/delete-nonexistent-note-error-analysis.md (100%)
 rename docs/{reports => design/v1.0.0}/delete-route-404-fix-implementation.md (100%)
 rename docs/{reports => design/v1.0.0}/delete-route-fix-summary.md (100%)
 rename docs/{reports => design/v1.0.0}/delete-route-implementation-spec.md (100%)
 rename docs/{projectplan/v1 => design/v1.0.0}/dependencies-diagram.md (100%)
 rename docs/{architecture => design/v1.0.0}/endpoint-discovery-answers.md (100%)
 rename docs/{reviews => design/v1.0.0}/error-handling-rest-vs-web-patterns.md (100%)
 rename docs/{projectplan/v1 => design/v1.0.0}/feature-scope.md (100%)
 rename docs/{migration => design/v1.0.0}/fix-hardcoded-endpoints.md (100%)
 rename docs/{reports => design/v1.0.0}/identity-domain-validation-2025-11-19.md (100%)
 rename docs/{examples => design/v1.0.0}/identity-page-customization-guide.md (100%)
 rename docs/{examples => design/v1.0.0}/identity-page.html (100%)
 rename docs/{reports => design/v1.0.0}/implementation-guide-expose-deleted-at.md (100%)
 rename docs/{projectplan/v1 => design/v1.0.0}/implementation-plan.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-assessment.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-client-diagnosis.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-client-discovery-analysis.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-client-discovery-fix-implementation.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-client-discovery-root-cause-analysis.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-detailed-logging-implementation.md (100%)
 rename docs/{security => design/v1.0.0}/indieauth-endpoint-discovery-security.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-endpoint-discovery.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-fix-summary.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-identity-page.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-questions-answered.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-removal-analysis.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-removal-architectural-review.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-removal-implementation-guide.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-removal-phases.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-removal-plan.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-removal-questions.md (100%)
 rename docs/{reports => design/v1.0.0}/indieauth-spec-url-standardization-2025-11-24.md (100%)
 rename docs/{architecture => design/v1.0.0}/indieauth-token-verification-diagnosis.md (100%)
 rename docs/design/{ => v1.0.0}/initial-files.md (100%)
 rename docs/design/{ => v1.0.0}/initial-schema-implementation-guide.md (100%)
 rename docs/design/{ => v1.0.0}/initial-schema-quick-reference.md (100%)
 rename docs/{reports => design/v1.0.0}/micropub-401-diagnosis.md (100%)
 rename docs/design/{ => v1.0.0}/micropub-endpoint-design.md (100%)
 rename docs/{reviews => design/v1.0.0}/micropub-phase1-architecture-review.md (100%)
 rename docs/{reviews => design/v1.0.0}/micropub-phase3-architecture-review.md (100%)
 rename docs/{reports => design/v1.0.0}/micropub-v1-implementation-progress.md (100%)
 rename docs/{reports => design/v1.0.0}/migration-failure-diagnosis-v1.0.0-rc.1.md (100%)
 rename docs/{architecture => design/v1.0.0}/migration-fix-quick-reference.md (100%)
 rename docs/{architecture => design/v1.0.0}/migration-race-condition-answers.md (100%)
 rename docs/{reports => design/v1.0.0}/migration-race-condition-fix-implementation.md (100%)
 rename docs/{reports => design/v1.0.0}/oauth-metadata-implementation-2025-11-19.md (100%)
 rename docs/design/{ => v1.0.0}/phase-1.1-core-utilities.md (100%)
 rename docs/design/{ => v1.0.0}/phase-1.1-quick-reference.md (100%)
 rename docs/design/{ => v1.0.0}/phase-1.2-data-models.md (100%)
 rename docs/design/{ => v1.0.0}/phase-1.2-quick-reference.md (100%)
 rename docs/{reviews => design/v1.0.0}/phase-2-architectural-review.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-2-implementation-report.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-2.1-implementation-20251118.md (100%)
 rename docs/design/{ => v1.0.0}/phase-2.1-notes-management.md (100%)
 rename docs/design/{ => v1.0.0}/phase-2.1-quick-reference.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-3-authentication-20251118.md (100%)
 rename docs/{reviews => design/v1.0.0}/phase-3-authentication-architectural-review.md (100%)
 rename docs/design/{ => v1.0.0}/phase-3-authentication-implementation.md (100%)
 rename docs/design/{ => v1.0.0}/phase-3-authentication.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-4-architectural-assessment-20251118.md (100%)
 rename docs/design/{ => v1.0.0}/phase-4-error-handling-fix.md (100%)
 rename docs/design/{ => v1.0.0}/phase-4-quick-reference.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-4-test-fixes.md (100%)
 rename docs/design/{ => v1.0.0}/phase-4-web-interface.md (100%)
 rename docs/{reviews => design/v1.0.0}/phase-5-approval-summary.md (100%)
 rename docs/{reviews => design/v1.0.0}/phase-5-container-architectural-review.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-5-container-implementation-report.md (100%)
 rename docs/design/{ => v1.0.0}/phase-5-executive-summary.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-5-pre-implementation-review.md (100%)
 rename docs/design/{ => v1.0.0}/phase-5-quick-reference.md (100%)
 rename docs/design/{ => v1.0.0}/phase-5-rss-and-container.md (100%)
 rename docs/{reports => design/v1.0.0}/phase-5-rss-implementation-20251119.md (100%)
 rename docs/{architecture => design/v1.0.0}/phase-5-validation-report.md (100%)
 rename docs/{architecture => design/v1.0.0}/phase1-completion-guide.md (100%)
 rename docs/design/{ => v1.0.0}/project-structure.md (100%)
 rename docs/{projectplan/v1 => design/v1.0.0}/quick-reference.md (100%)
 rename docs/{architecture => design/v1.0.0}/review-v1.0.0-rc.5.md (100%)
 rename docs/{reports => design/v1.0.0}/setup-complete-2025-11-18.md (100%)
 rename docs/{reports => design/v1.0.0}/test-failure-analysis-deleted-at-attribute.md (100%)
 rename docs/{operations => design/v1.0.0}/troubleshooting.md (100%)
 rename docs/{reports => design/v1.0.0}/v0.9.1-implementation-report.md (100%)
 rename docs/{projectplan/v1/README.md => design/v1.0.0/v1-planning-overview.md} (100%)
 rename docs/{reports => design/v1.0.0}/v1.0.0-rc.1-hotfix-instructions.md (100%)
 rename docs/{reports => design/v1.0.0}/v1.0.0-rc.5-migration-race-condition-implementation.md (100%)
 rename docs/{architecture => design/v1.0.0}/v1.0.0-release-validation.md (100%)
 rename docs/{releases => design/v1.0.0}/v1.0.1-hotfix-plan.md (100%)
 rename docs/{reports => design/v1.1.1}/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md (100%)
 rename docs/{reports => design/v1.1.1}/2025-11-25-v1.0.1-micropub-url-fix.md (100%)
 rename docs/design/{ => v1.1.1}/auth-redirect-loop-diagnosis.md (100%)
 rename docs/design/{ => v1.1.1}/auth-redirect-loop-diagram.md (100%)
 rename docs/design/{ => v1.1.1}/auth-redirect-loop-executive-summary.md (100%)
 rename docs/design/{ => v1.1.1}/auth-redirect-loop-fix-implementation.md (100%)
 rename docs/design/{ => v1.1.1}/hotfix-v1.1.1-rc2-consolidated.md (100%)
 rename docs/{architecture => design/v1.1.1}/hotfix-v1.1.1-rc2-review.md (100%)
 rename docs/design/{ => v1.1.1}/hotfix-v1.1.1-rc2-route-conflict.md (100%)
 rename docs/design/{ => v1.1.1}/hotfix-validation-script.md (100%)
 rename docs/design/{ => v1.1.1}/indieauth-pkce-authentication.md (100%)
 rename docs/{projectplan/v1.1 => design/v1.1.1}/potential-features.md (100%)
 rename docs/{projectplan/v1.1 => design/v1.1.1}/priority-work.md (100%)
 rename docs/{projectplan/v1.1 => design/v1.1.1}/syndication-features.md (100%)
 rename docs/design/{ => v1.1.1}/token-security-migration.md (100%)
 rename docs/{operations => design/v1.1.1}/upgrade-to-v1.1.1.md (100%)
 rename docs/{architecture => design/v1.1.1}/v1.1.0-feature-architecture.md (100%)
 rename docs/{architecture => design/v1.1.1}/v1.1.0-implementation-decisions.md (100%)
 rename docs/{reports => design/v1.1.1}/v1.1.0-implementation-plan.md (100%)
 rename docs/{reports => design/v1.1.1}/v1.1.0-implementation-report.md (100%)
 rename docs/{projectplan/v1.1/RELEASE-STATUS.md => design/v1.1.1/v1.1.0-release-status.md} (100%)
 rename docs/{architecture => design/v1.1.1}/v1.1.0-search-ui-validation.md (100%)
 rename docs/{architecture => design/v1.1.1}/v1.1.0-validation-report.md (100%)
 rename docs/{architecture => design/v1.1.1}/v1.1.1-architecture-overview.md (100%)
 rename docs/{reviews => design/v1.1.1}/v1.1.1-final-release-review.md (100%)
 rename docs/{architecture => design/v1.1.1}/v1.1.1-instrumentation-assessment.md (100%)
 rename docs/{reviews => design/v1.1.1}/v1.1.1-phase1-architectural-review.md (100%)
 rename docs/{reports => design/v1.1.1}/v1.1.1-phase1-implementation.md (100%)
 rename docs/{reviews => design/v1.1.1}/v1.1.1-phase2-architectural-review.md (100%)
 rename docs/{reports => design/v1.1.1}/v1.1.1-phase2-implementation.md (100%)
 rename docs/{reports => design/v1.1.1}/v1.1.1-phase3-implementation.md (100%)
 rename docs/{reviews => design/v1.1.2}/2025-11-26-phase2-architect-review.md (100%)
 rename docs/{reviews => design/v1.1.2}/2025-11-26-v1.1.2-phase1-review.md (100%)
 rename docs/{reports => design/v1.1.2}/2025-11-26-v1.1.2-phase2-complete.md (100%)
 rename docs/{reports => design/v1.1.2}/2025-11-26-v1.1.2-phase2-feed-formats-partial.md (100%)
 rename docs/{reviews => design/v1.1.2}/2025-11-27-phase3-architect-review.md (100%)
 rename docs/{reports => design/v1.1.2}/2025-11-27-v1.1.2-phase3-complete.md (100%)
 rename docs/{reviews => design/v1.1.2}/2025-11-28-v1.1.2-rc.1-architect-review.md (100%)
 rename docs/{reports => design/v1.1.2}/2025-11-28-v1.1.2-rc.1-production-issues.md (100%)
 rename docs/{reports => design/v1.1.2}/2025-11-28-v1.1.2-rc.2-fixes.md (100%)
 rename docs/design/{v1.1.2-caption-alttext-update.md => v1.1.2/caption-alttext-update.md} (100%)
 rename docs/design/{ => v1.1.2}/feed-media-handling-options.md (100%)
 rename docs/design/{ => v1.1.2}/feed-media-option2-design.md (100%)
 rename docs/{operations => design/v1.1.2}/upgrade-to-v1.1.2.md (100%)
 create mode 100644 docs/design/v1.1.2/v1.1.2-caption-alttext-update.md
 rename docs/{projectplan => design/v1.1.2}/v1.1.2-options.md (100%)
 rename docs/{reports => design/v1.1.2}/v1.1.2-phase1-metrics-implementation.md (100%)
 rename docs/{architecture => design/v1.1.2}/v1.1.2-syndicate-architecture.md (100%)
 rename docs/{reviews => design/v1.2.0}/2025-11-28-v1.2.0-design-complete.md (100%)
 rename docs/{reports/2025-11-28-media-display-fixes.md => design/v1.2.0/2025-11-28-v1.2.0-media-display-fixes.md} (100%)
 rename docs/{reports => design/v1.2.0}/2025-11-28-v1.2.0-phase1-custom-slugs.md (100%)
 rename docs/{reviews => design/v1.2.0}/2025-11-28-v1.2.0-phase1-review.md (100%)
 rename docs/{reports => design/v1.2.0}/2025-11-28-v1.2.0-phase2-author-microformats.md (100%)
 rename docs/{reviews => design/v1.2.0}/2025-11-28-v1.2.0-phase2-review.md (100%)
 rename docs/{reports => design/v1.2.0}/2025-11-28-v1.2.0-phase3-media-upload.md (100%)
 rename docs/{reviews => design/v1.2.0}/2025-11-28-v1.2.0-phase3-review.md (100%)
 rename docs/{reports => design/v1.2.0}/2025-12-09-feed-media-implementation.md (100%)
 rename docs/{reports => design/v1.2.0}/2025-12-09-media-display-validation.md (100%)
 rename docs/design/{v1.2.0-media-css-design.md => v1.2.0/media-css-design.md} (100%)
 rename docs/design/{ => v1.2.0}/media-display-fixes.md (100%)
 create mode 100644 docs/design/v1.2.0/v1.2.0-media-css-design.md
 rename docs/{projectplan => design/v1.2.0}/v1.X.X-indieweb-options.md (100%)
 rename docs/{projectplan => design/v1.2.0}/v1.X.X-options.md (100%)
 delete mode 100644 docs/examples/INDEX.md
 delete mode 100644 docs/migration/INDEX.md
 delete mode 100644 docs/projectplan/INDEX.md
 delete mode 100644 docs/projectplan/ROADMAP.md
 delete mode 100644 docs/releases/INDEX.md
 delete mode 100644 docs/reports/INDEX.md
 delete mode 100644 docs/reviews/INDEX.md
 delete mode 100644 docs/security/INDEX.md
 create mode 100644 migrations/008_add_tags.sql
 create mode 100644 starpunk/tags.py

diff --git a/docs/deployment/INDEX.md b/docs/deployment/INDEX.md
deleted file mode 100644
index 080b4b4..0000000
--- a/docs/deployment/INDEX.md
+++ /dev/null
@@ -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
diff --git a/docs/reports/2025-11-18-auth-redirect-loop-fix.md b/docs/design/v1.0.0/2025-11-18-auth-redirect-loop-fix.md
similarity index 100%
rename from docs/reports/2025-11-18-auth-redirect-loop-fix.md
rename to docs/design/v1.0.0/2025-11-18-auth-redirect-loop-fix.md
diff --git a/docs/reports/2025-11-18-quickfix-auth-loop.md b/docs/design/v1.0.0/2025-11-18-quickfix-auth-loop.md
similarity index 100%
rename from docs/reports/2025-11-18-quickfix-auth-loop.md
rename to docs/design/v1.0.0/2025-11-18-quickfix-auth-loop.md
diff --git a/docs/reports/2025-11-19-container-implementation-summary.md b/docs/design/v1.0.0/2025-11-19-container-implementation-summary.md
similarity index 100%
rename from docs/reports/2025-11-19-container-implementation-summary.md
rename to docs/design/v1.0.0/2025-11-19-container-implementation-summary.md
diff --git a/docs/reports/2025-11-19-migration-implementation-quick-reference.md b/docs/design/v1.0.0/2025-11-19-migration-implementation-quick-reference.md
similarity index 100%
rename from docs/reports/2025-11-19-migration-implementation-quick-reference.md
rename to docs/design/v1.0.0/2025-11-19-migration-implementation-quick-reference.md
diff --git a/docs/reports/2025-11-19-migration-system-implementation-guidance.md b/docs/design/v1.0.0/2025-11-19-migration-system-implementation-guidance.md
similarity index 100%
rename from docs/reports/2025-11-19-migration-system-implementation-guidance.md
rename to docs/design/v1.0.0/2025-11-19-migration-system-implementation-guidance.md
diff --git a/docs/reports/2025-11-19-migration-system-implementation-report.md b/docs/design/v1.0.0/2025-11-19-migration-system-implementation-report.md
similarity index 100%
rename from docs/reports/2025-11-19-migration-system-implementation-report.md
rename to docs/design/v1.0.0/2025-11-19-migration-system-implementation-report.md
diff --git a/docs/reports/2025-11-19-todo-test-updates.md b/docs/design/v1.0.0/2025-11-19-todo-test-updates.md
similarity index 100%
rename from docs/reports/2025-11-19-todo-test-updates.md
rename to docs/design/v1.0.0/2025-11-19-todo-test-updates.md
diff --git a/docs/reports/2025-11-22-auth-route-prefix-fix.md b/docs/design/v1.0.0/2025-11-22-auth-route-prefix-fix.md
similarity index 100%
rename from docs/reports/2025-11-22-auth-route-prefix-fix.md
rename to docs/design/v1.0.0/2025-11-22-auth-route-prefix-fix.md
diff --git a/docs/reports/2025-11-22-authorization-endpoint-fix.md b/docs/design/v1.0.0/2025-11-22-authorization-endpoint-fix.md
similarity index 100%
rename from docs/reports/2025-11-22-authorization-endpoint-fix.md
rename to docs/design/v1.0.0/2025-11-22-authorization-endpoint-fix.md
diff --git a/docs/reports/2025-11-22-grant-type-fix.md b/docs/design/v1.0.0/2025-11-22-grant-type-fix.md
similarity index 100%
rename from docs/reports/2025-11-22-grant-type-fix.md
rename to docs/design/v1.0.0/2025-11-22-grant-type-fix.md
diff --git a/docs/reports/2025-11-24-endpoint-discovery-analysis.md b/docs/design/v1.0.0/2025-11-24-endpoint-discovery-analysis.md
similarity index 100%
rename from docs/reports/2025-11-24-endpoint-discovery-analysis.md
rename to docs/design/v1.0.0/2025-11-24-endpoint-discovery-analysis.md
diff --git a/docs/reports/2025-11-24-indieauth-removal-complete.md b/docs/design/v1.0.0/2025-11-24-indieauth-removal-complete.md
similarity index 100%
rename from docs/reports/2025-11-24-indieauth-removal-complete.md
rename to docs/design/v1.0.0/2025-11-24-indieauth-removal-complete.md
diff --git a/docs/reports/2025-11-24-migration-detection-hotfix-rc3.md b/docs/design/v1.0.0/2025-11-24-migration-detection-hotfix-rc3.md
similarity index 100%
rename from docs/reports/2025-11-24-migration-detection-hotfix-rc3.md
rename to docs/design/v1.0.0/2025-11-24-migration-detection-hotfix-rc3.md
diff --git a/docs/reports/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
similarity index 100%
rename from docs/reports/2025-11-24-migration-fix-v1.0.0-rc.2.md
rename to docs/design/v1.0.0/2025-11-24-migration-fix-v1.0.0-rc.2.md
diff --git a/docs/reports/2025-11-24-phase1-indieauth-server-removal.md b/docs/design/v1.0.0/2025-11-24-phase1-indieauth-server-removal.md
similarity index 100%
rename from docs/reports/2025-11-24-phase1-indieauth-server-removal.md
rename to docs/design/v1.0.0/2025-11-24-phase1-indieauth-server-removal.md
diff --git a/docs/reports/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
similarity index 100%
rename from docs/reports/2025-11-24-v1.0.0-rc.5-implementation.md
rename to docs/design/v1.0.0/2025-11-24-v1.0.0-rc.5-implementation.md
diff --git a/docs/reports/ADR-025-implementation-report.md b/docs/design/v1.0.0/ADR-025-implementation-report.md
similarity index 100%
rename from docs/reports/ADR-025-implementation-report.md
rename to docs/design/v1.0.0/ADR-025-implementation-report.md
diff --git a/docs/reports/ADR-025-implementation-summary.md b/docs/design/v1.0.0/ADR-025-implementation-summary.md
similarity index 100%
rename from docs/reports/ADR-025-implementation-summary.md
rename to docs/design/v1.0.0/ADR-025-implementation-summary.md
diff --git a/docs/reports/ADR-025-versioning-guidance.md b/docs/design/v1.0.0/ADR-025-versioning-guidance.md
similarity index 100%
rename from docs/reports/ADR-025-versioning-guidance.md
rename to docs/design/v1.0.0/ADR-025-versioning-guidance.md
diff --git a/docs/reports/ARCHITECT-FINAL-ANALYSIS.md b/docs/design/v1.0.0/ARCHITECT-FINAL-ANALYSIS.md
similarity index 100%
rename from docs/reports/ARCHITECT-FINAL-ANALYSIS.md
rename to docs/design/v1.0.0/ARCHITECT-FINAL-ANALYSIS.md
diff --git a/docs/deployment/container-deployment.md b/docs/design/v1.0.0/container-deployment.md
similarity index 100%
rename from docs/deployment/container-deployment.md
rename to docs/design/v1.0.0/container-deployment.md
diff --git a/docs/reports/custom-slug-bug-diagnosis.md b/docs/design/v1.0.0/custom-slug-bug-diagnosis.md
similarity index 100%
rename from docs/reports/custom-slug-bug-diagnosis.md
rename to docs/design/v1.0.0/custom-slug-bug-diagnosis.md
diff --git a/docs/reports/custom-slug-bug-implementation.md b/docs/design/v1.0.0/custom-slug-bug-implementation.md
similarity index 100%
rename from docs/reports/custom-slug-bug-implementation.md
rename to docs/design/v1.0.0/custom-slug-bug-implementation.md
diff --git a/docs/architecture/database-migration-architecture.md b/docs/design/v1.0.0/database-migration-architecture.md
similarity index 100%
rename from docs/architecture/database-migration-architecture.md
rename to docs/design/v1.0.0/database-migration-architecture.md
diff --git a/docs/reports/database-migration-conflict-diagnosis.md b/docs/design/v1.0.0/database-migration-conflict-diagnosis.md
similarity index 100%
rename from docs/reports/database-migration-conflict-diagnosis.md
rename to docs/design/v1.0.0/database-migration-conflict-diagnosis.md
diff --git a/docs/reports/delete-nonexistent-note-error-analysis.md b/docs/design/v1.0.0/delete-nonexistent-note-error-analysis.md
similarity index 100%
rename from docs/reports/delete-nonexistent-note-error-analysis.md
rename to docs/design/v1.0.0/delete-nonexistent-note-error-analysis.md
diff --git a/docs/reports/delete-route-404-fix-implementation.md b/docs/design/v1.0.0/delete-route-404-fix-implementation.md
similarity index 100%
rename from docs/reports/delete-route-404-fix-implementation.md
rename to docs/design/v1.0.0/delete-route-404-fix-implementation.md
diff --git a/docs/reports/delete-route-fix-summary.md b/docs/design/v1.0.0/delete-route-fix-summary.md
similarity index 100%
rename from docs/reports/delete-route-fix-summary.md
rename to docs/design/v1.0.0/delete-route-fix-summary.md
diff --git a/docs/reports/delete-route-implementation-spec.md b/docs/design/v1.0.0/delete-route-implementation-spec.md
similarity index 100%
rename from docs/reports/delete-route-implementation-spec.md
rename to docs/design/v1.0.0/delete-route-implementation-spec.md
diff --git a/docs/projectplan/v1/dependencies-diagram.md b/docs/design/v1.0.0/dependencies-diagram.md
similarity index 100%
rename from docs/projectplan/v1/dependencies-diagram.md
rename to docs/design/v1.0.0/dependencies-diagram.md
diff --git a/docs/architecture/endpoint-discovery-answers.md b/docs/design/v1.0.0/endpoint-discovery-answers.md
similarity index 100%
rename from docs/architecture/endpoint-discovery-answers.md
rename to docs/design/v1.0.0/endpoint-discovery-answers.md
diff --git a/docs/reviews/error-handling-rest-vs-web-patterns.md b/docs/design/v1.0.0/error-handling-rest-vs-web-patterns.md
similarity index 100%
rename from docs/reviews/error-handling-rest-vs-web-patterns.md
rename to docs/design/v1.0.0/error-handling-rest-vs-web-patterns.md
diff --git a/docs/projectplan/v1/feature-scope.md b/docs/design/v1.0.0/feature-scope.md
similarity index 100%
rename from docs/projectplan/v1/feature-scope.md
rename to docs/design/v1.0.0/feature-scope.md
diff --git a/docs/migration/fix-hardcoded-endpoints.md b/docs/design/v1.0.0/fix-hardcoded-endpoints.md
similarity index 100%
rename from docs/migration/fix-hardcoded-endpoints.md
rename to docs/design/v1.0.0/fix-hardcoded-endpoints.md
diff --git a/docs/reports/identity-domain-validation-2025-11-19.md b/docs/design/v1.0.0/identity-domain-validation-2025-11-19.md
similarity index 100%
rename from docs/reports/identity-domain-validation-2025-11-19.md
rename to docs/design/v1.0.0/identity-domain-validation-2025-11-19.md
diff --git a/docs/examples/identity-page-customization-guide.md b/docs/design/v1.0.0/identity-page-customization-guide.md
similarity index 100%
rename from docs/examples/identity-page-customization-guide.md
rename to docs/design/v1.0.0/identity-page-customization-guide.md
diff --git a/docs/examples/identity-page.html b/docs/design/v1.0.0/identity-page.html
similarity index 100%
rename from docs/examples/identity-page.html
rename to docs/design/v1.0.0/identity-page.html
diff --git a/docs/reports/implementation-guide-expose-deleted-at.md b/docs/design/v1.0.0/implementation-guide-expose-deleted-at.md
similarity index 100%
rename from docs/reports/implementation-guide-expose-deleted-at.md
rename to docs/design/v1.0.0/implementation-guide-expose-deleted-at.md
diff --git a/docs/projectplan/v1/implementation-plan.md b/docs/design/v1.0.0/implementation-plan.md
similarity index 100%
rename from docs/projectplan/v1/implementation-plan.md
rename to docs/design/v1.0.0/implementation-plan.md
diff --git a/docs/architecture/indieauth-assessment.md b/docs/design/v1.0.0/indieauth-assessment.md
similarity index 100%
rename from docs/architecture/indieauth-assessment.md
rename to docs/design/v1.0.0/indieauth-assessment.md
diff --git a/docs/architecture/indieauth-client-diagnosis.md b/docs/design/v1.0.0/indieauth-client-diagnosis.md
similarity index 100%
rename from docs/architecture/indieauth-client-diagnosis.md
rename to docs/design/v1.0.0/indieauth-client-diagnosis.md
diff --git a/docs/reports/indieauth-client-discovery-analysis.md b/docs/design/v1.0.0/indieauth-client-discovery-analysis.md
similarity index 100%
rename from docs/reports/indieauth-client-discovery-analysis.md
rename to docs/design/v1.0.0/indieauth-client-discovery-analysis.md
diff --git a/docs/reports/indieauth-client-discovery-fix-implementation.md b/docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
similarity index 100%
rename from docs/reports/indieauth-client-discovery-fix-implementation.md
rename to docs/design/v1.0.0/indieauth-client-discovery-fix-implementation.md
diff --git a/docs/reports/indieauth-client-discovery-root-cause-analysis.md b/docs/design/v1.0.0/indieauth-client-discovery-root-cause-analysis.md
similarity index 100%
rename from docs/reports/indieauth-client-discovery-root-cause-analysis.md
rename to docs/design/v1.0.0/indieauth-client-discovery-root-cause-analysis.md
diff --git a/docs/reports/indieauth-detailed-logging-implementation.md b/docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
similarity index 100%
rename from docs/reports/indieauth-detailed-logging-implementation.md
rename to docs/design/v1.0.0/indieauth-detailed-logging-implementation.md
diff --git a/docs/security/indieauth-endpoint-discovery-security.md b/docs/design/v1.0.0/indieauth-endpoint-discovery-security.md
similarity index 100%
rename from docs/security/indieauth-endpoint-discovery-security.md
rename to docs/design/v1.0.0/indieauth-endpoint-discovery-security.md
diff --git a/docs/architecture/indieauth-endpoint-discovery.md b/docs/design/v1.0.0/indieauth-endpoint-discovery.md
similarity index 100%
rename from docs/architecture/indieauth-endpoint-discovery.md
rename to docs/design/v1.0.0/indieauth-endpoint-discovery.md
diff --git a/docs/reports/indieauth-fix-summary.md b/docs/design/v1.0.0/indieauth-fix-summary.md
similarity index 100%
rename from docs/reports/indieauth-fix-summary.md
rename to docs/design/v1.0.0/indieauth-fix-summary.md
diff --git a/docs/architecture/indieauth-identity-page.md b/docs/design/v1.0.0/indieauth-identity-page.md
similarity index 100%
rename from docs/architecture/indieauth-identity-page.md
rename to docs/design/v1.0.0/indieauth-identity-page.md
diff --git a/docs/architecture/indieauth-questions-answered.md b/docs/design/v1.0.0/indieauth-questions-answered.md
similarity index 100%
rename from docs/architecture/indieauth-questions-answered.md
rename to docs/design/v1.0.0/indieauth-questions-answered.md
diff --git a/docs/reports/indieauth-removal-analysis.md b/docs/design/v1.0.0/indieauth-removal-analysis.md
similarity index 100%
rename from docs/reports/indieauth-removal-analysis.md
rename to docs/design/v1.0.0/indieauth-removal-analysis.md
diff --git a/docs/architecture/indieauth-removal-architectural-review.md b/docs/design/v1.0.0/indieauth-removal-architectural-review.md
similarity index 100%
rename from docs/architecture/indieauth-removal-architectural-review.md
rename to docs/design/v1.0.0/indieauth-removal-architectural-review.md
diff --git a/docs/architecture/indieauth-removal-implementation-guide.md b/docs/design/v1.0.0/indieauth-removal-implementation-guide.md
similarity index 100%
rename from docs/architecture/indieauth-removal-implementation-guide.md
rename to docs/design/v1.0.0/indieauth-removal-implementation-guide.md
diff --git a/docs/architecture/indieauth-removal-phases.md b/docs/design/v1.0.0/indieauth-removal-phases.md
similarity index 100%
rename from docs/architecture/indieauth-removal-phases.md
rename to docs/design/v1.0.0/indieauth-removal-phases.md
diff --git a/docs/architecture/indieauth-removal-plan.md b/docs/design/v1.0.0/indieauth-removal-plan.md
similarity index 100%
rename from docs/architecture/indieauth-removal-plan.md
rename to docs/design/v1.0.0/indieauth-removal-plan.md
diff --git a/docs/reports/indieauth-removal-questions.md b/docs/design/v1.0.0/indieauth-removal-questions.md
similarity index 100%
rename from docs/reports/indieauth-removal-questions.md
rename to docs/design/v1.0.0/indieauth-removal-questions.md
diff --git a/docs/reports/indieauth-spec-url-standardization-2025-11-24.md b/docs/design/v1.0.0/indieauth-spec-url-standardization-2025-11-24.md
similarity index 100%
rename from docs/reports/indieauth-spec-url-standardization-2025-11-24.md
rename to docs/design/v1.0.0/indieauth-spec-url-standardization-2025-11-24.md
diff --git a/docs/architecture/indieauth-token-verification-diagnosis.md b/docs/design/v1.0.0/indieauth-token-verification-diagnosis.md
similarity index 100%
rename from docs/architecture/indieauth-token-verification-diagnosis.md
rename to docs/design/v1.0.0/indieauth-token-verification-diagnosis.md
diff --git a/docs/design/initial-files.md b/docs/design/v1.0.0/initial-files.md
similarity index 100%
rename from docs/design/initial-files.md
rename to docs/design/v1.0.0/initial-files.md
diff --git a/docs/design/initial-schema-implementation-guide.md b/docs/design/v1.0.0/initial-schema-implementation-guide.md
similarity index 100%
rename from docs/design/initial-schema-implementation-guide.md
rename to docs/design/v1.0.0/initial-schema-implementation-guide.md
diff --git a/docs/design/initial-schema-quick-reference.md b/docs/design/v1.0.0/initial-schema-quick-reference.md
similarity index 100%
rename from docs/design/initial-schema-quick-reference.md
rename to docs/design/v1.0.0/initial-schema-quick-reference.md
diff --git a/docs/reports/micropub-401-diagnosis.md b/docs/design/v1.0.0/micropub-401-diagnosis.md
similarity index 100%
rename from docs/reports/micropub-401-diagnosis.md
rename to docs/design/v1.0.0/micropub-401-diagnosis.md
diff --git a/docs/design/micropub-endpoint-design.md b/docs/design/v1.0.0/micropub-endpoint-design.md
similarity index 100%
rename from docs/design/micropub-endpoint-design.md
rename to docs/design/v1.0.0/micropub-endpoint-design.md
diff --git a/docs/reviews/micropub-phase1-architecture-review.md b/docs/design/v1.0.0/micropub-phase1-architecture-review.md
similarity index 100%
rename from docs/reviews/micropub-phase1-architecture-review.md
rename to docs/design/v1.0.0/micropub-phase1-architecture-review.md
diff --git a/docs/reviews/micropub-phase3-architecture-review.md b/docs/design/v1.0.0/micropub-phase3-architecture-review.md
similarity index 100%
rename from docs/reviews/micropub-phase3-architecture-review.md
rename to docs/design/v1.0.0/micropub-phase3-architecture-review.md
diff --git a/docs/reports/micropub-v1-implementation-progress.md b/docs/design/v1.0.0/micropub-v1-implementation-progress.md
similarity index 100%
rename from docs/reports/micropub-v1-implementation-progress.md
rename to docs/design/v1.0.0/micropub-v1-implementation-progress.md
diff --git a/docs/reports/migration-failure-diagnosis-v1.0.0-rc.1.md b/docs/design/v1.0.0/migration-failure-diagnosis-v1.0.0-rc.1.md
similarity index 100%
rename from docs/reports/migration-failure-diagnosis-v1.0.0-rc.1.md
rename to docs/design/v1.0.0/migration-failure-diagnosis-v1.0.0-rc.1.md
diff --git a/docs/architecture/migration-fix-quick-reference.md b/docs/design/v1.0.0/migration-fix-quick-reference.md
similarity index 100%
rename from docs/architecture/migration-fix-quick-reference.md
rename to docs/design/v1.0.0/migration-fix-quick-reference.md
diff --git a/docs/architecture/migration-race-condition-answers.md b/docs/design/v1.0.0/migration-race-condition-answers.md
similarity index 100%
rename from docs/architecture/migration-race-condition-answers.md
rename to docs/design/v1.0.0/migration-race-condition-answers.md
diff --git a/docs/reports/migration-race-condition-fix-implementation.md b/docs/design/v1.0.0/migration-race-condition-fix-implementation.md
similarity index 100%
rename from docs/reports/migration-race-condition-fix-implementation.md
rename to docs/design/v1.0.0/migration-race-condition-fix-implementation.md
diff --git a/docs/reports/oauth-metadata-implementation-2025-11-19.md b/docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
similarity index 100%
rename from docs/reports/oauth-metadata-implementation-2025-11-19.md
rename to docs/design/v1.0.0/oauth-metadata-implementation-2025-11-19.md
diff --git a/docs/design/phase-1.1-core-utilities.md b/docs/design/v1.0.0/phase-1.1-core-utilities.md
similarity index 100%
rename from docs/design/phase-1.1-core-utilities.md
rename to docs/design/v1.0.0/phase-1.1-core-utilities.md
diff --git a/docs/design/phase-1.1-quick-reference.md b/docs/design/v1.0.0/phase-1.1-quick-reference.md
similarity index 100%
rename from docs/design/phase-1.1-quick-reference.md
rename to docs/design/v1.0.0/phase-1.1-quick-reference.md
diff --git a/docs/design/phase-1.2-data-models.md b/docs/design/v1.0.0/phase-1.2-data-models.md
similarity index 100%
rename from docs/design/phase-1.2-data-models.md
rename to docs/design/v1.0.0/phase-1.2-data-models.md
diff --git a/docs/design/phase-1.2-quick-reference.md b/docs/design/v1.0.0/phase-1.2-quick-reference.md
similarity index 100%
rename from docs/design/phase-1.2-quick-reference.md
rename to docs/design/v1.0.0/phase-1.2-quick-reference.md
diff --git a/docs/reviews/phase-2-architectural-review.md b/docs/design/v1.0.0/phase-2-architectural-review.md
similarity index 100%
rename from docs/reviews/phase-2-architectural-review.md
rename to docs/design/v1.0.0/phase-2-architectural-review.md
diff --git a/docs/reports/phase-2-implementation-report.md b/docs/design/v1.0.0/phase-2-implementation-report.md
similarity index 100%
rename from docs/reports/phase-2-implementation-report.md
rename to docs/design/v1.0.0/phase-2-implementation-report.md
diff --git a/docs/reports/phase-2.1-implementation-20251118.md b/docs/design/v1.0.0/phase-2.1-implementation-20251118.md
similarity index 100%
rename from docs/reports/phase-2.1-implementation-20251118.md
rename to docs/design/v1.0.0/phase-2.1-implementation-20251118.md
diff --git a/docs/design/phase-2.1-notes-management.md b/docs/design/v1.0.0/phase-2.1-notes-management.md
similarity index 100%
rename from docs/design/phase-2.1-notes-management.md
rename to docs/design/v1.0.0/phase-2.1-notes-management.md
diff --git a/docs/design/phase-2.1-quick-reference.md b/docs/design/v1.0.0/phase-2.1-quick-reference.md
similarity index 100%
rename from docs/design/phase-2.1-quick-reference.md
rename to docs/design/v1.0.0/phase-2.1-quick-reference.md
diff --git a/docs/reports/phase-3-authentication-20251118.md b/docs/design/v1.0.0/phase-3-authentication-20251118.md
similarity index 100%
rename from docs/reports/phase-3-authentication-20251118.md
rename to docs/design/v1.0.0/phase-3-authentication-20251118.md
diff --git a/docs/reviews/phase-3-authentication-architectural-review.md b/docs/design/v1.0.0/phase-3-authentication-architectural-review.md
similarity index 100%
rename from docs/reviews/phase-3-authentication-architectural-review.md
rename to docs/design/v1.0.0/phase-3-authentication-architectural-review.md
diff --git a/docs/design/phase-3-authentication-implementation.md b/docs/design/v1.0.0/phase-3-authentication-implementation.md
similarity index 100%
rename from docs/design/phase-3-authentication-implementation.md
rename to docs/design/v1.0.0/phase-3-authentication-implementation.md
diff --git a/docs/design/phase-3-authentication.md b/docs/design/v1.0.0/phase-3-authentication.md
similarity index 100%
rename from docs/design/phase-3-authentication.md
rename to docs/design/v1.0.0/phase-3-authentication.md
diff --git a/docs/reports/phase-4-architectural-assessment-20251118.md b/docs/design/v1.0.0/phase-4-architectural-assessment-20251118.md
similarity index 100%
rename from docs/reports/phase-4-architectural-assessment-20251118.md
rename to docs/design/v1.0.0/phase-4-architectural-assessment-20251118.md
diff --git a/docs/design/phase-4-error-handling-fix.md b/docs/design/v1.0.0/phase-4-error-handling-fix.md
similarity index 100%
rename from docs/design/phase-4-error-handling-fix.md
rename to docs/design/v1.0.0/phase-4-error-handling-fix.md
diff --git a/docs/design/phase-4-quick-reference.md b/docs/design/v1.0.0/phase-4-quick-reference.md
similarity index 100%
rename from docs/design/phase-4-quick-reference.md
rename to docs/design/v1.0.0/phase-4-quick-reference.md
diff --git a/docs/reports/phase-4-test-fixes.md b/docs/design/v1.0.0/phase-4-test-fixes.md
similarity index 100%
rename from docs/reports/phase-4-test-fixes.md
rename to docs/design/v1.0.0/phase-4-test-fixes.md
diff --git a/docs/design/phase-4-web-interface.md b/docs/design/v1.0.0/phase-4-web-interface.md
similarity index 100%
rename from docs/design/phase-4-web-interface.md
rename to docs/design/v1.0.0/phase-4-web-interface.md
diff --git a/docs/reviews/phase-5-approval-summary.md b/docs/design/v1.0.0/phase-5-approval-summary.md
similarity index 100%
rename from docs/reviews/phase-5-approval-summary.md
rename to docs/design/v1.0.0/phase-5-approval-summary.md
diff --git a/docs/reviews/phase-5-container-architectural-review.md b/docs/design/v1.0.0/phase-5-container-architectural-review.md
similarity index 100%
rename from docs/reviews/phase-5-container-architectural-review.md
rename to docs/design/v1.0.0/phase-5-container-architectural-review.md
diff --git a/docs/reports/phase-5-container-implementation-report.md b/docs/design/v1.0.0/phase-5-container-implementation-report.md
similarity index 100%
rename from docs/reports/phase-5-container-implementation-report.md
rename to docs/design/v1.0.0/phase-5-container-implementation-report.md
diff --git a/docs/design/phase-5-executive-summary.md b/docs/design/v1.0.0/phase-5-executive-summary.md
similarity index 100%
rename from docs/design/phase-5-executive-summary.md
rename to docs/design/v1.0.0/phase-5-executive-summary.md
diff --git a/docs/reports/phase-5-pre-implementation-review.md b/docs/design/v1.0.0/phase-5-pre-implementation-review.md
similarity index 100%
rename from docs/reports/phase-5-pre-implementation-review.md
rename to docs/design/v1.0.0/phase-5-pre-implementation-review.md
diff --git a/docs/design/phase-5-quick-reference.md b/docs/design/v1.0.0/phase-5-quick-reference.md
similarity index 100%
rename from docs/design/phase-5-quick-reference.md
rename to docs/design/v1.0.0/phase-5-quick-reference.md
diff --git a/docs/design/phase-5-rss-and-container.md b/docs/design/v1.0.0/phase-5-rss-and-container.md
similarity index 100%
rename from docs/design/phase-5-rss-and-container.md
rename to docs/design/v1.0.0/phase-5-rss-and-container.md
diff --git a/docs/reports/phase-5-rss-implementation-20251119.md b/docs/design/v1.0.0/phase-5-rss-implementation-20251119.md
similarity index 100%
rename from docs/reports/phase-5-rss-implementation-20251119.md
rename to docs/design/v1.0.0/phase-5-rss-implementation-20251119.md
diff --git a/docs/architecture/phase-5-validation-report.md b/docs/design/v1.0.0/phase-5-validation-report.md
similarity index 100%
rename from docs/architecture/phase-5-validation-report.md
rename to docs/design/v1.0.0/phase-5-validation-report.md
diff --git a/docs/architecture/phase1-completion-guide.md b/docs/design/v1.0.0/phase1-completion-guide.md
similarity index 100%
rename from docs/architecture/phase1-completion-guide.md
rename to docs/design/v1.0.0/phase1-completion-guide.md
diff --git a/docs/design/project-structure.md b/docs/design/v1.0.0/project-structure.md
similarity index 100%
rename from docs/design/project-structure.md
rename to docs/design/v1.0.0/project-structure.md
diff --git a/docs/projectplan/v1/quick-reference.md b/docs/design/v1.0.0/quick-reference.md
similarity index 100%
rename from docs/projectplan/v1/quick-reference.md
rename to docs/design/v1.0.0/quick-reference.md
diff --git a/docs/architecture/review-v1.0.0-rc.5.md b/docs/design/v1.0.0/review-v1.0.0-rc.5.md
similarity index 100%
rename from docs/architecture/review-v1.0.0-rc.5.md
rename to docs/design/v1.0.0/review-v1.0.0-rc.5.md
diff --git a/docs/reports/setup-complete-2025-11-18.md b/docs/design/v1.0.0/setup-complete-2025-11-18.md
similarity index 100%
rename from docs/reports/setup-complete-2025-11-18.md
rename to docs/design/v1.0.0/setup-complete-2025-11-18.md
diff --git a/docs/reports/test-failure-analysis-deleted-at-attribute.md b/docs/design/v1.0.0/test-failure-analysis-deleted-at-attribute.md
similarity index 100%
rename from docs/reports/test-failure-analysis-deleted-at-attribute.md
rename to docs/design/v1.0.0/test-failure-analysis-deleted-at-attribute.md
diff --git a/docs/operations/troubleshooting.md b/docs/design/v1.0.0/troubleshooting.md
similarity index 100%
rename from docs/operations/troubleshooting.md
rename to docs/design/v1.0.0/troubleshooting.md
diff --git a/docs/reports/v0.9.1-implementation-report.md b/docs/design/v1.0.0/v0.9.1-implementation-report.md
similarity index 100%
rename from docs/reports/v0.9.1-implementation-report.md
rename to docs/design/v1.0.0/v0.9.1-implementation-report.md
diff --git a/docs/projectplan/v1/README.md b/docs/design/v1.0.0/v1-planning-overview.md
similarity index 100%
rename from docs/projectplan/v1/README.md
rename to docs/design/v1.0.0/v1-planning-overview.md
diff --git a/docs/reports/v1.0.0-rc.1-hotfix-instructions.md b/docs/design/v1.0.0/v1.0.0-rc.1-hotfix-instructions.md
similarity index 100%
rename from docs/reports/v1.0.0-rc.1-hotfix-instructions.md
rename to docs/design/v1.0.0/v1.0.0-rc.1-hotfix-instructions.md
diff --git a/docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md b/docs/design/v1.0.0/v1.0.0-rc.5-migration-race-condition-implementation.md
similarity index 100%
rename from docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md
rename to docs/design/v1.0.0/v1.0.0-rc.5-migration-race-condition-implementation.md
diff --git a/docs/architecture/v1.0.0-release-validation.md b/docs/design/v1.0.0/v1.0.0-release-validation.md
similarity index 100%
rename from docs/architecture/v1.0.0-release-validation.md
rename to docs/design/v1.0.0/v1.0.0-release-validation.md
diff --git a/docs/releases/v1.0.1-hotfix-plan.md b/docs/design/v1.0.0/v1.0.1-hotfix-plan.md
similarity index 100%
rename from docs/releases/v1.0.1-hotfix-plan.md
rename to docs/design/v1.0.0/v1.0.1-hotfix-plan.md
diff --git a/docs/reports/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md b/docs/design/v1.1.1/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md
similarity index 100%
rename from docs/reports/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md
rename to docs/design/v1.1.1/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md
diff --git a/docs/reports/2025-11-25-v1.0.1-micropub-url-fix.md b/docs/design/v1.1.1/2025-11-25-v1.0.1-micropub-url-fix.md
similarity index 100%
rename from docs/reports/2025-11-25-v1.0.1-micropub-url-fix.md
rename to docs/design/v1.1.1/2025-11-25-v1.0.1-micropub-url-fix.md
diff --git a/docs/design/auth-redirect-loop-diagnosis.md b/docs/design/v1.1.1/auth-redirect-loop-diagnosis.md
similarity index 100%
rename from docs/design/auth-redirect-loop-diagnosis.md
rename to docs/design/v1.1.1/auth-redirect-loop-diagnosis.md
diff --git a/docs/design/auth-redirect-loop-diagram.md b/docs/design/v1.1.1/auth-redirect-loop-diagram.md
similarity index 100%
rename from docs/design/auth-redirect-loop-diagram.md
rename to docs/design/v1.1.1/auth-redirect-loop-diagram.md
diff --git a/docs/design/auth-redirect-loop-executive-summary.md b/docs/design/v1.1.1/auth-redirect-loop-executive-summary.md
similarity index 100%
rename from docs/design/auth-redirect-loop-executive-summary.md
rename to docs/design/v1.1.1/auth-redirect-loop-executive-summary.md
diff --git a/docs/design/auth-redirect-loop-fix-implementation.md b/docs/design/v1.1.1/auth-redirect-loop-fix-implementation.md
similarity index 100%
rename from docs/design/auth-redirect-loop-fix-implementation.md
rename to docs/design/v1.1.1/auth-redirect-loop-fix-implementation.md
diff --git a/docs/design/hotfix-v1.1.1-rc2-consolidated.md b/docs/design/v1.1.1/hotfix-v1.1.1-rc2-consolidated.md
similarity index 100%
rename from docs/design/hotfix-v1.1.1-rc2-consolidated.md
rename to docs/design/v1.1.1/hotfix-v1.1.1-rc2-consolidated.md
diff --git a/docs/architecture/hotfix-v1.1.1-rc2-review.md b/docs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md
similarity index 100%
rename from docs/architecture/hotfix-v1.1.1-rc2-review.md
rename to docs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md
diff --git a/docs/design/hotfix-v1.1.1-rc2-route-conflict.md b/docs/design/v1.1.1/hotfix-v1.1.1-rc2-route-conflict.md
similarity index 100%
rename from docs/design/hotfix-v1.1.1-rc2-route-conflict.md
rename to docs/design/v1.1.1/hotfix-v1.1.1-rc2-route-conflict.md
diff --git a/docs/design/hotfix-validation-script.md b/docs/design/v1.1.1/hotfix-validation-script.md
similarity index 100%
rename from docs/design/hotfix-validation-script.md
rename to docs/design/v1.1.1/hotfix-validation-script.md
diff --git a/docs/design/indieauth-pkce-authentication.md b/docs/design/v1.1.1/indieauth-pkce-authentication.md
similarity index 100%
rename from docs/design/indieauth-pkce-authentication.md
rename to docs/design/v1.1.1/indieauth-pkce-authentication.md
diff --git a/docs/projectplan/v1.1/potential-features.md b/docs/design/v1.1.1/potential-features.md
similarity index 100%
rename from docs/projectplan/v1.1/potential-features.md
rename to docs/design/v1.1.1/potential-features.md
diff --git a/docs/projectplan/v1.1/priority-work.md b/docs/design/v1.1.1/priority-work.md
similarity index 100%
rename from docs/projectplan/v1.1/priority-work.md
rename to docs/design/v1.1.1/priority-work.md
diff --git a/docs/projectplan/v1.1/syndication-features.md b/docs/design/v1.1.1/syndication-features.md
similarity index 100%
rename from docs/projectplan/v1.1/syndication-features.md
rename to docs/design/v1.1.1/syndication-features.md
diff --git a/docs/design/token-security-migration.md b/docs/design/v1.1.1/token-security-migration.md
similarity index 100%
rename from docs/design/token-security-migration.md
rename to docs/design/v1.1.1/token-security-migration.md
diff --git a/docs/operations/upgrade-to-v1.1.1.md b/docs/design/v1.1.1/upgrade-to-v1.1.1.md
similarity index 100%
rename from docs/operations/upgrade-to-v1.1.1.md
rename to docs/design/v1.1.1/upgrade-to-v1.1.1.md
diff --git a/docs/architecture/v1.1.0-feature-architecture.md b/docs/design/v1.1.1/v1.1.0-feature-architecture.md
similarity index 100%
rename from docs/architecture/v1.1.0-feature-architecture.md
rename to docs/design/v1.1.1/v1.1.0-feature-architecture.md
diff --git a/docs/architecture/v1.1.0-implementation-decisions.md b/docs/design/v1.1.1/v1.1.0-implementation-decisions.md
similarity index 100%
rename from docs/architecture/v1.1.0-implementation-decisions.md
rename to docs/design/v1.1.1/v1.1.0-implementation-decisions.md
diff --git a/docs/reports/v1.1.0-implementation-plan.md b/docs/design/v1.1.1/v1.1.0-implementation-plan.md
similarity index 100%
rename from docs/reports/v1.1.0-implementation-plan.md
rename to docs/design/v1.1.1/v1.1.0-implementation-plan.md
diff --git a/docs/reports/v1.1.0-implementation-report.md b/docs/design/v1.1.1/v1.1.0-implementation-report.md
similarity index 100%
rename from docs/reports/v1.1.0-implementation-report.md
rename to docs/design/v1.1.1/v1.1.0-implementation-report.md
diff --git a/docs/projectplan/v1.1/RELEASE-STATUS.md b/docs/design/v1.1.1/v1.1.0-release-status.md
similarity index 100%
rename from docs/projectplan/v1.1/RELEASE-STATUS.md
rename to docs/design/v1.1.1/v1.1.0-release-status.md
diff --git a/docs/architecture/v1.1.0-search-ui-validation.md b/docs/design/v1.1.1/v1.1.0-search-ui-validation.md
similarity index 100%
rename from docs/architecture/v1.1.0-search-ui-validation.md
rename to docs/design/v1.1.1/v1.1.0-search-ui-validation.md
diff --git a/docs/architecture/v1.1.0-validation-report.md b/docs/design/v1.1.1/v1.1.0-validation-report.md
similarity index 100%
rename from docs/architecture/v1.1.0-validation-report.md
rename to docs/design/v1.1.1/v1.1.0-validation-report.md
diff --git a/docs/architecture/v1.1.1-architecture-overview.md b/docs/design/v1.1.1/v1.1.1-architecture-overview.md
similarity index 100%
rename from docs/architecture/v1.1.1-architecture-overview.md
rename to docs/design/v1.1.1/v1.1.1-architecture-overview.md
diff --git a/docs/reviews/v1.1.1-final-release-review.md b/docs/design/v1.1.1/v1.1.1-final-release-review.md
similarity index 100%
rename from docs/reviews/v1.1.1-final-release-review.md
rename to docs/design/v1.1.1/v1.1.1-final-release-review.md
diff --git a/docs/architecture/v1.1.1-instrumentation-assessment.md b/docs/design/v1.1.1/v1.1.1-instrumentation-assessment.md
similarity index 100%
rename from docs/architecture/v1.1.1-instrumentation-assessment.md
rename to docs/design/v1.1.1/v1.1.1-instrumentation-assessment.md
diff --git a/docs/reviews/v1.1.1-phase1-architectural-review.md b/docs/design/v1.1.1/v1.1.1-phase1-architectural-review.md
similarity index 100%
rename from docs/reviews/v1.1.1-phase1-architectural-review.md
rename to docs/design/v1.1.1/v1.1.1-phase1-architectural-review.md
diff --git a/docs/reports/v1.1.1-phase1-implementation.md b/docs/design/v1.1.1/v1.1.1-phase1-implementation.md
similarity index 100%
rename from docs/reports/v1.1.1-phase1-implementation.md
rename to docs/design/v1.1.1/v1.1.1-phase1-implementation.md
diff --git a/docs/reviews/v1.1.1-phase2-architectural-review.md b/docs/design/v1.1.1/v1.1.1-phase2-architectural-review.md
similarity index 100%
rename from docs/reviews/v1.1.1-phase2-architectural-review.md
rename to docs/design/v1.1.1/v1.1.1-phase2-architectural-review.md
diff --git a/docs/reports/v1.1.1-phase2-implementation.md b/docs/design/v1.1.1/v1.1.1-phase2-implementation.md
similarity index 100%
rename from docs/reports/v1.1.1-phase2-implementation.md
rename to docs/design/v1.1.1/v1.1.1-phase2-implementation.md
diff --git a/docs/reports/v1.1.1-phase3-implementation.md b/docs/design/v1.1.1/v1.1.1-phase3-implementation.md
similarity index 100%
rename from docs/reports/v1.1.1-phase3-implementation.md
rename to docs/design/v1.1.1/v1.1.1-phase3-implementation.md
diff --git a/docs/reviews/2025-11-26-phase2-architect-review.md b/docs/design/v1.1.2/2025-11-26-phase2-architect-review.md
similarity index 100%
rename from docs/reviews/2025-11-26-phase2-architect-review.md
rename to docs/design/v1.1.2/2025-11-26-phase2-architect-review.md
diff --git a/docs/reviews/2025-11-26-v1.1.2-phase1-review.md b/docs/design/v1.1.2/2025-11-26-v1.1.2-phase1-review.md
similarity index 100%
rename from docs/reviews/2025-11-26-v1.1.2-phase1-review.md
rename to docs/design/v1.1.2/2025-11-26-v1.1.2-phase1-review.md
diff --git a/docs/reports/2025-11-26-v1.1.2-phase2-complete.md b/docs/design/v1.1.2/2025-11-26-v1.1.2-phase2-complete.md
similarity index 100%
rename from docs/reports/2025-11-26-v1.1.2-phase2-complete.md
rename to docs/design/v1.1.2/2025-11-26-v1.1.2-phase2-complete.md
diff --git a/docs/reports/2025-11-26-v1.1.2-phase2-feed-formats-partial.md b/docs/design/v1.1.2/2025-11-26-v1.1.2-phase2-feed-formats-partial.md
similarity index 100%
rename from docs/reports/2025-11-26-v1.1.2-phase2-feed-formats-partial.md
rename to docs/design/v1.1.2/2025-11-26-v1.1.2-phase2-feed-formats-partial.md
diff --git a/docs/reviews/2025-11-27-phase3-architect-review.md b/docs/design/v1.1.2/2025-11-27-phase3-architect-review.md
similarity index 100%
rename from docs/reviews/2025-11-27-phase3-architect-review.md
rename to docs/design/v1.1.2/2025-11-27-phase3-architect-review.md
diff --git a/docs/reports/2025-11-27-v1.1.2-phase3-complete.md b/docs/design/v1.1.2/2025-11-27-v1.1.2-phase3-complete.md
similarity index 100%
rename from docs/reports/2025-11-27-v1.1.2-phase3-complete.md
rename to docs/design/v1.1.2/2025-11-27-v1.1.2-phase3-complete.md
diff --git a/docs/reviews/2025-11-28-v1.1.2-rc.1-architect-review.md b/docs/design/v1.1.2/2025-11-28-v1.1.2-rc.1-architect-review.md
similarity index 100%
rename from docs/reviews/2025-11-28-v1.1.2-rc.1-architect-review.md
rename to docs/design/v1.1.2/2025-11-28-v1.1.2-rc.1-architect-review.md
diff --git a/docs/reports/2025-11-28-v1.1.2-rc.1-production-issues.md b/docs/design/v1.1.2/2025-11-28-v1.1.2-rc.1-production-issues.md
similarity index 100%
rename from docs/reports/2025-11-28-v1.1.2-rc.1-production-issues.md
rename to docs/design/v1.1.2/2025-11-28-v1.1.2-rc.1-production-issues.md
diff --git a/docs/reports/2025-11-28-v1.1.2-rc.2-fixes.md b/docs/design/v1.1.2/2025-11-28-v1.1.2-rc.2-fixes.md
similarity index 100%
rename from docs/reports/2025-11-28-v1.1.2-rc.2-fixes.md
rename to docs/design/v1.1.2/2025-11-28-v1.1.2-rc.2-fixes.md
diff --git a/docs/design/v1.1.2-caption-alttext-update.md b/docs/design/v1.1.2/caption-alttext-update.md
similarity index 100%
rename from docs/design/v1.1.2-caption-alttext-update.md
rename to docs/design/v1.1.2/caption-alttext-update.md
diff --git a/docs/design/feed-media-handling-options.md b/docs/design/v1.1.2/feed-media-handling-options.md
similarity index 100%
rename from docs/design/feed-media-handling-options.md
rename to docs/design/v1.1.2/feed-media-handling-options.md
diff --git a/docs/design/feed-media-option2-design.md b/docs/design/v1.1.2/feed-media-option2-design.md
similarity index 100%
rename from docs/design/feed-media-option2-design.md
rename to docs/design/v1.1.2/feed-media-option2-design.md
diff --git a/docs/operations/upgrade-to-v1.1.2.md b/docs/design/v1.1.2/upgrade-to-v1.1.2.md
similarity index 100%
rename from docs/operations/upgrade-to-v1.1.2.md
rename to docs/design/v1.1.2/upgrade-to-v1.1.2.md
diff --git a/docs/design/v1.1.2/v1.1.2-caption-alttext-update.md b/docs/design/v1.1.2/v1.1.2-caption-alttext-update.md
new file mode 100644
index 0000000..009d62f
--- /dev/null
+++ b/docs/design/v1.1.2/v1.1.2-caption-alttext-update.md
@@ -0,0 +1,153 @@
+# Caption Display Update - Alt Text Only (v1.1.2)
+
+## Status
+**Superseded by media-display-fixes.md**
+
+This document contains an earlier approach to caption handling. The authoritative specification is now in `media-display-fixes.md` which provides a complete solution for media display including caption handling, CSS constraints, and homepage media.
+
+## Context
+
+User has clarified that media captions should be used as alt text only, not displayed as visible `<figcaption>` elements in the note body.
+
+## Decision
+
+Remove all visible caption display from templates while maintaining caption data for accessibility (alt text) purposes.
+
+## Required Changes
+
+### 1. CSS Updates
+
+**File:** `/home/phil/Projects/starpunk/static/css/style.css`
+
+**Remove:** Lines related to figcaption styling (line 17 in the media CSS section)
+
+```css
+/* REMOVE THIS LINE */
+.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }
+```
+
+The remaining CSS should be:
+
+```css
+/* Media Display Styles (v1.2.0) - Updated for alt-text only captions */
+.note-media { margin-bottom: var(--spacing-md); }
+.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }
+
+/* Multiple media items grid */
+.note-media { display: flex; flex-wrap: wrap; gap: var(--spacing-md); }
+.note-media .media-item { flex: 1 1 100%; }
+
+/* Desktop: side-by-side for multiple images */
+@media (min-width: 768px) {
+  .note-media .media-item:only-child { flex: 1 1 100%; }
+  .note-media .media-item:not(:only-child) { flex: 1 1 calc(50% - var(--spacing-sm)); }
+}
+```
+
+### 2. Template Updates
+
+#### File: `/home/phil/Projects/starpunk/templates/note.html`
+
+**Change:** Lines 17-29 - Simplify media display structure
+
+**From:**
+```html
+{% if note.media %}
+<div class="note-media">
+  {% for item in note.media %}
+  <figure class="media-item">
+    <img src="{{ url_for('public.media_file', path=item.path) }}"
+         alt="{{ item.caption or 'Image' }}"
+         class="u-photo"
+         width="{{ item.width }}"
+         height="{{ item.height }}">
+    {% if item.caption %}
+    <figcaption>{{ item.caption }}</figcaption>
+    {% endif %}
+  </figure>
+  {% endfor %}
+</div>
+{% endif %}
+```
+
+**To:**
+```html
+{% if note.media %}
+<div class="note-media">
+  {% for item in note.media %}
+  <div class="media-item">
+    <img src="{{ url_for('public.media_file', path=item.path) }}"
+         alt="{{ item.caption or 'Image' }}"
+         class="u-photo"
+         width="{{ item.width }}"
+         height="{{ item.height }}">
+  </div>
+  {% endfor %}
+</div>
+{% endif %}
+```
+
+**Changes:**
+- Replace `<figure>` with `<div>` (simpler, no semantic figure/caption relationship)
+- Remove the `{% if item.caption %}` block and `<figcaption>` element entirely
+- Keep caption in `alt` attribute for accessibility
+
+#### File: `/home/phil/Projects/starpunk/templates/index.html`
+
+**Status:** No changes needed
+- Index template doesn't display media items in the preview
+- Only shows truncated content
+
+### 3. Feed Generators
+
+**Status:** No changes needed
+
+The feed generators already handle captions correctly:
+- RSS, ATOM, and JSON Feed all use captions as alt text in `<img>` tags
+- JSON Feed also includes captions in attachment metadata (correct behavior)
+
+**Current implementation (correct):**
+```python
+# In all feed generators
+caption = media_item.get('caption', '')
+content_html += f'<img src="{media_url}" alt="{caption}" />'
+```
+
+## Rationale
+
+1. **Simplicity**: Removing visible captions reduces visual clutter
+2. **Accessibility**: Alt text provides necessary context for screen readers
+3. **User Intent**: Captions are metadata, not content to be displayed
+4. **Clean Design**: Images speak for themselves without redundant text
+
+## Implementation Checklist
+
+- [ ] Update CSS to remove figcaption styles
+- [ ] Update note.html template to remove figcaption elements
+- [ ] Test with images that have captions
+- [ ] Test with images without captions
+- [ ] Verify alt text is properly set
+- [ ] Test responsive layout still works
+- [ ] Verify feed output unchanged
+
+## Testing Requirements
+
+1. **Visual Testing:**
+   - Confirm no caption text appears below images
+   - Verify image layout unchanged
+   - Test responsive behavior on mobile/desktop
+
+2. **Accessibility Testing:**
+   - Inspect HTML to confirm alt attributes are set
+   - Test with screen reader to verify alt text is announced
+
+3. **Feed Testing:**
+   - Verify RSS/ATOM/JSON feeds still include alt text
+   - Confirm JSON Feed attachments retain title field
+
+## Standards Compliance
+
+- **HTML**: Valid use of img alt attribute
+- **Accessibility**: WCAG 2.1 Level A compliance for images
+- **IndieWeb**: Maintains u-photo microformat class
+- **Progressive Enhancement**: Images functional without CSS
\ No newline at end of file
diff --git a/docs/projectplan/v1.1.2-options.md b/docs/design/v1.1.2/v1.1.2-options.md
similarity index 100%
rename from docs/projectplan/v1.1.2-options.md
rename to docs/design/v1.1.2/v1.1.2-options.md
diff --git a/docs/reports/v1.1.2-phase1-metrics-implementation.md b/docs/design/v1.1.2/v1.1.2-phase1-metrics-implementation.md
similarity index 100%
rename from docs/reports/v1.1.2-phase1-metrics-implementation.md
rename to docs/design/v1.1.2/v1.1.2-phase1-metrics-implementation.md
diff --git a/docs/architecture/v1.1.2-syndicate-architecture.md b/docs/design/v1.1.2/v1.1.2-syndicate-architecture.md
similarity index 100%
rename from docs/architecture/v1.1.2-syndicate-architecture.md
rename to docs/design/v1.1.2/v1.1.2-syndicate-architecture.md
diff --git a/docs/reviews/2025-11-28-v1.2.0-design-complete.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-design-complete.md
similarity index 100%
rename from docs/reviews/2025-11-28-v1.2.0-design-complete.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-design-complete.md
diff --git a/docs/reports/2025-11-28-media-display-fixes.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-media-display-fixes.md
similarity index 100%
rename from docs/reports/2025-11-28-media-display-fixes.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-media-display-fixes.md
diff --git a/docs/reports/2025-11-28-v1.2.0-phase1-custom-slugs.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-phase1-custom-slugs.md
similarity index 100%
rename from docs/reports/2025-11-28-v1.2.0-phase1-custom-slugs.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-phase1-custom-slugs.md
diff --git a/docs/reviews/2025-11-28-v1.2.0-phase1-review.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-phase1-review.md
similarity index 100%
rename from docs/reviews/2025-11-28-v1.2.0-phase1-review.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-phase1-review.md
diff --git a/docs/reports/2025-11-28-v1.2.0-phase2-author-microformats.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-phase2-author-microformats.md
similarity index 100%
rename from docs/reports/2025-11-28-v1.2.0-phase2-author-microformats.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-phase2-author-microformats.md
diff --git a/docs/reviews/2025-11-28-v1.2.0-phase2-review.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-phase2-review.md
similarity index 100%
rename from docs/reviews/2025-11-28-v1.2.0-phase2-review.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-phase2-review.md
diff --git a/docs/reports/2025-11-28-v1.2.0-phase3-media-upload.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-phase3-media-upload.md
similarity index 100%
rename from docs/reports/2025-11-28-v1.2.0-phase3-media-upload.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-phase3-media-upload.md
diff --git a/docs/reviews/2025-11-28-v1.2.0-phase3-review.md b/docs/design/v1.2.0/2025-11-28-v1.2.0-phase3-review.md
similarity index 100%
rename from docs/reviews/2025-11-28-v1.2.0-phase3-review.md
rename to docs/design/v1.2.0/2025-11-28-v1.2.0-phase3-review.md
diff --git a/docs/reports/2025-12-09-feed-media-implementation.md b/docs/design/v1.2.0/2025-12-09-feed-media-implementation.md
similarity index 100%
rename from docs/reports/2025-12-09-feed-media-implementation.md
rename to docs/design/v1.2.0/2025-12-09-feed-media-implementation.md
diff --git a/docs/reports/2025-12-09-media-display-validation.md b/docs/design/v1.2.0/2025-12-09-media-display-validation.md
similarity index 100%
rename from docs/reports/2025-12-09-media-display-validation.md
rename to docs/design/v1.2.0/2025-12-09-media-display-validation.md
diff --git a/docs/design/v1.2.0-media-css-design.md b/docs/design/v1.2.0/media-css-design.md
similarity index 100%
rename from docs/design/v1.2.0-media-css-design.md
rename to docs/design/v1.2.0/media-css-design.md
diff --git a/docs/design/media-display-fixes.md b/docs/design/v1.2.0/media-display-fixes.md
similarity index 100%
rename from docs/design/media-display-fixes.md
rename to docs/design/v1.2.0/media-display-fixes.md
diff --git a/docs/design/v1.2.0/v1.2.0-media-css-design.md b/docs/design/v1.2.0/v1.2.0-media-css-design.md
new file mode 100644
index 0000000..51e13ab
--- /dev/null
+++ b/docs/design/v1.2.0/v1.2.0-media-css-design.md
@@ -0,0 +1,114 @@
+# CSS Design for Media Display (v1.2.0)
+
+## Status
+**Superseded by media-display-fixes.md**
+
+This document contains an earlier design iteration. The authoritative specification is now in `media-display-fixes.md` which provides a more comprehensive solution including template refactoring and consistent media display across all pages.
+
+## Problem Statement
+Images uploaded via the media upload feature display at full resolution, breaking layout bounds and creating poor user experience. Need CSS rules to constrain and style images appropriately.
+
+## Design Decision
+
+### CSS Rules to Add
+
+Add the following CSS rules after line 49 (after `.empty-state` rules) in `/home/phil/Projects/starpunk/static/css/style.css`:
+
+```css
+/* Media Display Styles (v1.2.0) */
+.note-media { margin-bottom: var(--spacing-md); }
+.note-media figure, .e-content figure { margin: 0 0 var(--spacing-md) 0; }
+.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }
+.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }
+
+/* Multiple media items grid */
+.note-media { display: flex; flex-wrap: wrap; gap: var(--spacing-md); }
+.note-media .media-item { flex: 1 1 100%; }
+
+/* Desktop: side-by-side for multiple images */
+@media (min-width: 768px) {
+  .note-media .media-item:only-child { flex: 1 1 100%; }
+  .note-media .media-item:not(:only-child) { flex: 1 1 calc(50% - var(--spacing-sm)); }
+}
+```
+
+## Rationale
+
+### 1. Responsive Image Constraints
+- `max-width: 100%` ensures images never exceed container width
+- `height: auto` maintains aspect ratio
+- `display: block` removes inline spacing issues
+- Works with existing HTML `width` and `height` attributes for proper aspect ratio hints
+
+### 2. Consistent Visual Design
+- `border-radius: var(--border-radius)` matches existing design system (4px)
+- Uses existing spacing variables for consistent margins
+- Caption styling matches `.note-meta` text style (0.875rem, light gray)
+
+### 3. Flexible Layout
+- Single images take full width
+- Multiple images display in a responsive grid
+- Mobile: stacked vertically (100% width each)
+- Desktop: two columns for multiple images (50% width each)
+- Flexbox with gap provides clean spacing
+
+### 4. Scope Coverage
+- `.note-media img` - images in the media section
+- `.e-content img` - images in markdown content
+- `.u-photo` - microformats photo class (covers both media and author photos)
+- Applies to both `figure` and standalone `img` elements
+
+### 5. Performance Considerations
+- No complex calculations or transforms
+- Leverages browser native image sizing
+- Uses existing CSS variables (no new computations)
+- Respects HTML width/height attributes for layout stability
+
+## Alternative Approaches Considered
+
+### Object-fit Approach (Rejected)
+```css
+img { object-fit: cover; width: 100%; height: 400px; }
+```
+- Rejected: Crops images, losing content
+- Rejected: Fixed height doesn't work for varied aspect ratios
+
+### Container Query Approach (Rejected)
+```css
+@container (min-width: 600px) { ... }
+```
+- Rejected: Limited browser support
+- Rejected: Unnecessary complexity for this use case
+
+### CSS Grid Approach (Rejected)
+```css
+.note-media { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
+```
+- Rejected: More complex than needed
+- Rejected: Less flexible for single vs multiple images
+
+## Implementation Notes
+
+1. **Location in style.css**: Insert after line 49, before `.form-group` rules
+2. **Testing Required**:
+   - Single image display
+   - Multiple images (2, 3, 4 images)
+   - Portrait and landscape orientations
+   - Mobile and desktop viewports
+   - Images in markdown content
+   - Author avatar photos
+
+3. **Browser Compatibility**: All rules use widely supported CSS features (flexbox, max-width, CSS variables)
+
+4. **Future Enhancements** (not for v1.2.0):
+   - Lightbox/modal for full-size viewing
+   - Lazy loading optimization
+   - WebP format support
+   - Image galleries with thumbnails
+
+## Standards Compliance
+
+- **IndieWeb**: Preserves `.u-photo` microformat class
+- **Accessibility**: Maintains alt text display, proper figure/figcaption semantics
+- **Performance**: No JavaScript required, pure CSS solution
+- **Progressive Enhancement**: Images remain functional without CSS
\ No newline at end of file
diff --git a/docs/projectplan/v1.X.X-indieweb-options.md b/docs/design/v1.2.0/v1.X.X-indieweb-options.md
similarity index 100%
rename from docs/projectplan/v1.X.X-indieweb-options.md
rename to docs/design/v1.2.0/v1.X.X-indieweb-options.md
diff --git a/docs/projectplan/v1.X.X-options.md b/docs/design/v1.2.0/v1.X.X-options.md
similarity index 100%
rename from docs/projectplan/v1.X.X-options.md
rename to docs/design/v1.2.0/v1.X.X-options.md
diff --git a/docs/examples/INDEX.md b/docs/examples/INDEX.md
deleted file mode 100644
index c5bd71a..0000000
--- a/docs/examples/INDEX.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Examples Documentation Index
-
-This directory contains example implementations, code samples, and usage patterns for StarPunk CMS.
-
-## Available Examples
-
-### Identity Page
-- **[identity-page.html](identity-page.html)** - Example IndieAuth identity page
-- **[identity-page-customization-guide.md](identity-page-customization-guide.md)** - Guide for customizing identity pages
-
-## Example Categories
-
-### IndieAuth Examples
-- Identity page setup and customization
-- Endpoint discovery implementation
-- Authentication flow examples
-
-## How to Use Examples
-
-### For Integration
-1. Copy example files to your project
-2. Customize for your specific needs
-3. Follow accompanying documentation
-
-### For Learning
-- Study examples to understand patterns
-- Use as reference for your own implementation
-- Adapt to your use case
-
-## Contributing Examples
-
-When adding new examples:
-1. Include working code
-2. Add documentation explaining the example
-3. Update this index
-4. Follow project coding standards
-
-## Related Documentation
-- **[../design/](../design/)** - Feature designs
-- **[../standards/](../standards/)** - Coding standards
-- **[../architecture/](../architecture/)** - System architecture
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
diff --git a/docs/migration/INDEX.md b/docs/migration/INDEX.md
deleted file mode 100644
index 617eec2..0000000
--- a/docs/migration/INDEX.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Migration Guides Index
-
-This directory contains migration guides for upgrading between versions and making configuration changes.
-
-## Migration Guides
-
-- **[fix-hardcoded-endpoints.md](fix-hardcoded-endpoints.md)** - Migrate from hardcoded TOKEN_ENDPOINT to dynamic endpoint discovery
-
-## Migration Types
-
-### Configuration Migrations
-Guides for updating configuration between versions:
-- Environment variable changes
-- Configuration file updates
-- Feature flag migrations
-
-### Code Migrations
-Guides for updating code that uses StarPunk:
-- API changes
-- Breaking changes
-- Deprecated feature replacements
-
-## How to Use Migration Guides
-
-1. **Identify Your Version**: Check current version with `python -c "from starpunk import __version__; print(__version__)"`
-2. **Find Relevant Guide**: Look for migration guide for your target version
-3. **Follow Steps**: Complete migration steps in order
-4. **Test**: Verify system works after migration
-5. **Update**: Update version numbers and documentation
-
-## Related Documentation
-- **[../standards/versioning-strategy.md](../standards/versioning-strategy.md)** - Versioning guidelines
-- **[CHANGELOG.md](../../CHANGELOG.md)** - Version change log
-- **[../decisions/](../decisions/)** - ADRs documenting breaking changes
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
diff --git a/docs/projectplan/INDEX.md b/docs/projectplan/INDEX.md
deleted file mode 100644
index ff9a1af..0000000
--- a/docs/projectplan/INDEX.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# StarPunk Project Planning Index
-
-## Overview
-
-This directory contains all project planning documentation for StarPunk, organized by version and planning phase. Use this index to navigate to the appropriate documentation.
-
-## Current Status
-
-**Latest Release**: v1.1.0 "SearchLight" (2025-11-25)
-**Project Status**: Production Ready - V1 Feature Complete
-
-## Directory Structure
-
-```
-/docs/projectplan/
-├── INDEX.md                 (this file)
-├── ROADMAP.md              → Future development roadmap
-├── v1/                     → V1.0 planning (COMPLETE)
-│   ├── README.md           → V1 planning overview
-│   ├── implementation-plan.md → Detailed implementation phases
-│   ├── feature-scope.md    → In/out of scope decisions
-│   ├── quick-reference.md  → Developer quick reference
-│   └── dependencies-diagram.md → Module dependencies
-└── v1.1/                   → V1.1 planning (COMPLETE)
-    ├── RELEASE-STATUS.md   → V1.1.0 release tracking
-    ├── priority-work.md    → Completed priority items
-    └── potential-features.md → Feature backlog
-```
-
-## Quick Navigation
-
-### For Current Development
-- [Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md) - Future versions and features
-- [V1.1 Release Status](/home/phil/Projects/starpunk/docs/projectplan/v1.1/RELEASE-STATUS.md) - Latest release details
-
-### For Historical Reference
-- [V1 Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md) - How V1 was built
-- [Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md) - V1 scope decisions
-
-### For Daily Work
-- [Quick Reference](/home/phil/Projects/starpunk/docs/projectplan/v1/quick-reference.md) - Commands and lookups
-- [Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md) - Feature backlog
-
-## Version History
-
-### V1.1.0 "SearchLight" (Released 2025-11-25)
-- Full-text search with FTS5
-- Custom slugs via Micropub
-- RSS feed fixes
-- Migration improvements
-- [Full Release Details](/home/phil/Projects/starpunk/docs/projectplan/v1.1/RELEASE-STATUS.md)
-
-### V1.0.0 (Released 2025-11-24)
-- IndieAuth authentication
-- Micropub endpoint
-- Notes management
-- RSS syndication
-- Web interface
-- [Implementation Report](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md)
-
-## Key Documents
-
-### Planning Documents
-1. **[Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md)**
-   - Future version planning
-   - Feature timeline
-   - Design principles
-
-2. **[V1 Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)**
-   - Phase-by-phase implementation
-   - Task tracking
-   - Test requirements
-
-3. **[Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md)**
-   - In/out of scope matrix
-   - Decision framework
-   - Lines of code budget
-
-### Status Documents
-1. **[V1.1 Release Status](/home/phil/Projects/starpunk/docs/projectplan/v1.1/RELEASE-STATUS.md)**
-   - Latest release tracking
-   - Completed features
-   - Test coverage
-
-2. **[Priority Work](/home/phil/Projects/starpunk/docs/projectplan/v1.1/priority-work.md)**
-   - Critical items (completed)
-   - Implementation notes
-   - Success criteria
-
-### Reference Documents
-1. **[Quick Reference](/home/phil/Projects/starpunk/docs/projectplan/v1/quick-reference.md)**
-   - Common commands
-   - File checklist
-   - Configuration guide
-
-2. **[Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)**
-   - Feature backlog
-   - Implementation options
-   - Priority scoring
-
-## Related Documentation
-
-### Architecture
-- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
-- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
-- [Architecture Decision Records](/home/phil/Projects/starpunk/docs/decisions/)
-
-### Implementation Reports
-- [V1.1.0 Implementation Report](/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md)
-- [V1.0.0 Implementation Report](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md)
-- [All Reports](/home/phil/Projects/starpunk/docs/reports/)
-
-### Standards
-- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
-- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
-- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
-
-## How to Use This Documentation
-
-### For New Contributors
-1. Read the [Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md)
-2. Review [Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md)
-3. Check [Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)
-
-### For Implementation
-1. Check [Current Status](#current-status) above
-2. Review relevant ADRs in `/docs/decisions/`
-3. Follow [Quick Reference](/home/phil/Projects/starpunk/docs/projectplan/v1/quick-reference.md)
-4. Document in `/docs/reports/`
-
-### For Planning
-1. Review [Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md)
-2. Check [Feature Backlog](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)
-3. Create ADRs for major decisions
-4. Update this index when adding documents
-
-## Maintenance
-
-This planning documentation should be updated:
-- After each release (update status, versions)
-- When planning new features (update roadmap)
-- When making scope decisions (update feature documents)
-- When creating new planning documents (update this index)
-
-## Success Metrics
-
-Project planning success is measured by:
-- ✅ All V1 features implemented
-- ✅ 598 tests (588 passing)
-- ✅ IndieWeb compliance achieved
-- ✅ Documentation complete
-- ✅ Production ready
-
-## Philosophy
-
-> "Every line of code must justify its existence. When in doubt, leave it out."
-
-This philosophy guides all planning and implementation decisions.
-
----
-
-**Index Created**: 2025-11-25
-**Last Updated**: 2025-11-25
-**Maintained By**: StarPunk Architect
-
-For questions about project planning, consult the Architect agent or review the ADRs.
\ No newline at end of file
diff --git a/docs/projectplan/ROADMAP.md b/docs/projectplan/ROADMAP.md
deleted file mode 100644
index 5580672..0000000
--- a/docs/projectplan/ROADMAP.md
+++ /dev/null
@@ -1,368 +0,0 @@
-# StarPunk Roadmap
-
-## Current Status
-
-**Latest Version**: v1.1.2 "Syndicate"
-**Released**: 2025-11-27
-**Status**: Production Ready
-
-StarPunk has achieved V1 feature completeness with all core IndieWeb functionality implemented:
-- ✅ IndieAuth authentication
-- ✅ Micropub endpoint
-- ✅ Notes management
-- ✅ RSS syndication
-- ✅ Full-text search
-- ✅ Custom slugs
-
-## Version History
-
-### Released Versions
-
-#### v1.1.2 "Syndicate" (2025-11-27)
-- Multi-format feed support (RSS 2.0, ATOM 1.0, JSON Feed 1.1)
-- Content negotiation for automatic format selection
-- Feed caching with LRU eviction and TTL expiration
-- ETag support with 304 conditional responses
-- Feed statistics dashboard in admin panel
-- OPML 2.0 export for feed discovery
-- Complete metrics instrumentation
-
-#### v1.1.1 (2025-11-26)
-- Fix metrics dashboard 500 error
-- Add data transformer for metrics template
-
-#### v1.1.0 "SearchLight" (2025-11-25)
-- Full-text search with FTS5
-- Complete search UI
-- Custom slugs via Micropub mp-slug
-- RSS feed ordering fix
-- Migration system improvements
-
-#### v1.0.1 (2025-11-24)
-- Fixed Micropub URL double-slash bug
-- Minor bug fixes
-
-#### v1.0.0 (2025-11-24)
-- Initial production release
-- IndieAuth authentication
-- Micropub server implementation
-- Notes CRUD functionality
-- RSS feed generation
-- Web interface (public & admin)
-
-## Future Roadmap
-
-### v1.1.1 "Polish" (Superseded)
-**Timeline**: Completed as hotfix
-**Status**: Released as hotfix (2025-11-26)
-**Note**: Critical fixes released immediately, remaining scope moved to v1.2.0
-
-Planned Features:
-
-#### Search Configuration System (3-4 hours)
-- `SEARCH_ENABLED` flag for sites that don't need search
-- `SEARCH_TITLE_LENGTH` configurable limit (currently hardcoded at 100)
-- Enhanced search term highlighting in results
-- Search result relevance scoring display
-- Graceful FTS5 degradation with fallback to LIKE queries
-
-#### Performance Monitoring Foundation (4-6 hours)
-- Add timing instrumentation to key operations
-- Database query performance logging
-- Slow query detection and warnings (configurable threshold)
-- Memory usage tracking in production
-- `/admin/performance` dashboard with real-time metrics
-
-#### Production Readiness Improvements (3-5 hours)
-- Graceful degradation when FTS5 unavailable
-- Better error messages for common configuration issues
-- Database connection pooling optimization
-- Improved logging structure with configurable levels
-- Enhanced health check endpoints (`/health` and `/health/ready`)
-
-#### Bug Fixes & Edge Cases (2-3 hours)
-- Fix 10 flaky timing tests from migration race conditions
-- Handle Unicode edge cases in slug generation
-- RSS feed memory optimization for large note counts
-- Session timeout handling improvements
-
-Technical Decisions:
-- [ADR-052: Configuration System Architecture](/home/phil/Projects/starpunk/docs/decisions/ADR-052-configuration-system-architecture.md)
-- [ADR-053: Performance Monitoring Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-053-performance-monitoring-strategy.md)
-- [ADR-054: Structured Logging Architecture](/home/phil/Projects/starpunk/docs/decisions/ADR-054-structured-logging-architecture.md)
-- [ADR-055: Error Handling Philosophy](/home/phil/Projects/starpunk/docs/decisions/ADR-055-error-handling-philosophy.md)
-
-### v1.1.2 "Syndicate" (Completed)
-**Timeline**: Completed 2025-11-27
-**Status**: Released
-**Actual Effort**: ~10 hours across 3 phases
-**Focus**: Expanded syndication format support
-
-Delivered Features:
-- ✅ **Phase 1: Metrics Instrumentation**
-  - Comprehensive metrics collection system
-  - Business metrics tracking for feed operations
-  - Foundation for performance monitoring
-- ✅ **Phase 2: Multi-Format Feeds**
-  - RSS 2.0 (existing, enhanced)
-  - ATOM 1.0 feed at `/feed.atom` (RFC 4287 compliant)
-  - JSON Feed 1.1 at `/feed.json`
-  - Content negotiation at `/feed`
-  - Auto-discovery links for all formats
-- ✅ **Phase 3: Feed Enhancements**
-  - Feed caching with LRU eviction (50 entries max)
-  - TTL-based expiration (5 minutes default)
-  - ETag support with SHA-256 checksums
-  - HTTP 304 conditional responses
-  - Feed statistics dashboard
-  - OPML 2.0 export at `/opml.xml`
-  - Content-Type negotiation (optional)
-  - Feed validation tests
-
-See: [ADR-038: Syndication Formats](/home/phil/Projects/starpunk/docs/decisions/ADR-038-syndication-formats.md)
-
-### v1.2.0 "Polish"
-**Timeline**: December 2025 (Next Release)
-**Focus**: Quality improvements and production readiness
-**Effort**: 12-18 hours
-
-Next Planned Features:
-- **Search Configuration System** (3-4 hours)
-  - `SEARCH_ENABLED` flag for sites that don't need search
-  - `SEARCH_TITLE_LENGTH` configurable limit
-  - Enhanced search term highlighting
-  - Search result relevance scoring display
-- **Performance Monitoring Dashboard** (4-6 hours)
-  - Extend existing metrics infrastructure
-  - Database query performance tracking
-  - Memory usage monitoring
-  - `/admin/performance` dedicated dashboard
-- **Production Improvements** (3-5 hours)
-  - Better error messages for configuration issues
-  - Enhanced health check endpoints
-  - Database connection pooling optimization
-  - Structured logging with configurable levels
-- **Bug Fixes** (2-3 hours)
-  - Unicode edge cases in slug generation
-  - Session timeout handling improvements
-  - RSS feed memory optimization for large counts
-
-### v1.3.0 "Semantic"
-**Timeline**: Q1 2026
-**Focus**: Enhanced semantic markup, organization, and advanced feed media
-**Effort**: 10-16 hours for microformats2, 12-18 hours for feed media, plus category system
-
-Planned Features:
-- **Strict Microformats2 Compliance** (10-16 hours)
-  - Complete h-entry properties (p-name, p-summary, p-author)
-  - Author h-card implementation
-  - h-feed wrapper for index pages
-  - Full IndieWeb parser compatibility
-  - Microformats2 validation suite
-  - See: [ADR-040: Microformats2 Compliance](/home/phil/Projects/starpunk/docs/decisions/ADR-040-microformats2-compliance.md)
-- **Enhanced Feed Media Support** (12-18 hours) - Full Standardization Phase A
-  - Multiple image sizes/thumbnails (150px, 320px, 640px, 1280px)
-  - Full Media RSS implementation (media:group, all attributes)
-  - Enhanced JSON Feed attachments
-  - ATOM enclosure links for all media
-  - See: [ADR-059: Full Feed Media Standardization](/home/phil/Projects/starpunk/docs/decisions/ADR-059-full-feed-media-standardization.md)
-- **Tag/Category System**
-  - Database schema for tags
-  - Tag-based filtering
-  - Tag clouds
-  - Category RSS/ATOM/JSON feeds
-  - p-category microformats2 support
-- **Hierarchical Slugs**
-  - Support for `/` in slugs
-  - Directory-like organization
-  - Breadcrumb navigation with microformats2
-- **Draft Management**
-  - Explicit draft status
-  - Draft preview
-  - Scheduled publishing
-- **Search Enhancements**
-  - Tag search
-  - Date range filtering
-  - Advanced query syntax
-
-### v1.4.0 "Connections"
-**Timeline**: Q2 2026
-**Focus**: IndieWeb social features
-
-Planned Features:
-- **Webmentions**
-  - Receive endpoint
-  - Send on publish
-  - Display received mentions
-  - Moderation interface
-- **IndieAuth Provider** (optional)
-  - Self-hosted IndieAuth server
-  - Token endpoint
-  - Client registration
-- **Reply Contexts**
-  - In-reply-to support
-  - Like/repost posts
-  - Bookmark posts
-
-### v1.4.0 "Media"
-**Timeline**: Q3 2026
-**Focus**: Rich content support and podcast/video syndication
-
-Planned Features:
-- **Media Uploads**
-  - Image upload via Micropub
-  - File management interface
-  - Thumbnail generation
-  - CDN integration (optional)
-- **Photo Posts**
-  - Instagram-like photo notes
-  - Gallery views
-  - EXIF data preservation
-- **Audio/Podcast Support** (10-16 hours) - Full Standardization Phase B
-  - Podcast RSS with iTunes namespace
-  - Audio duration extraction
-  - Episode metadata support
-  - Apple/Google podcast compatibility
-  - See: [ADR-059: Full Feed Media Standardization](/home/phil/Projects/starpunk/docs/decisions/ADR-059-full-feed-media-standardization.md)
-- **Video Support** (16-24 hours) - Full Standardization Phase C
-  - Video upload handling
-  - Poster image generation
-  - Video in Media RSS feeds
-  - HTML5 video embedding
-
-### v2.0.0 "MultiUser"
-**Timeline**: 2027
-**Focus**: Multi-author support (BREAKING CHANGES)
-
-Major Features:
-- **User Management**
-  - Multiple authors
-  - Role-based permissions
-  - User profiles
-- **Content Attribution**
-  - Per-note authorship
-  - Author pages
-  - Author RSS feeds
-- **Collaborative Features**
-  - Draft sharing
-  - Editorial workflow
-  - Comment system
-
-## Design Principles
-
-All future development will maintain these core principles:
-
-1. **Simplicity First**: Every feature must justify its complexity
-2. **IndieWeb Standards**: Full compliance with specifications
-3. **Progressive Enhancement**: Core functionality works without JavaScript
-4. **Data Portability**: User data remains exportable and portable
-5. **Backwards Compatibility**: Minor versions preserve compatibility
-
-## Feature Request Process
-
-To propose new features:
-
-1. **Check Alignment**
-   - Does it align with IndieWeb principles?
-   - Does it solve a real user problem?
-   - Can it be implemented simply?
-
-2. **Document Proposal**
-   - Create issue or discussion
-   - Describe use case clearly
-   - Consider implementation complexity
-
-3. **Architectural Review**
-   - Impact on existing features
-   - Database schema changes
-   - API compatibility
-
-4. **Priority Assessment**
-   - User value vs. complexity
-   - Maintenance burden
-   - Dependencies on other features
-
-## Deferred Features
-
-These features have been considered but deferred indefinitely:
-
-- **Static Site Generation**: Conflicts with dynamic Micropub
-- **Multi-language UI**: Low priority for single-user system
-- **Advanced Analytics**: Privacy concerns, use external tools
-- **Comments System**: Use Webmentions instead
-- **WYSIWYG Editor**: Markdown is sufficient
-- **Mobile App**: Web interface is mobile-friendly
-
-## Support Lifecycle
-
-### Version Support
-- **Current Release** (v1.1.0): Full support
-- **Previous Minor** (v1.0.x): Security fixes only
-- **Older Versions**: Community support only
-
-### Compatibility Promise
-- **Database**: Migrations always provided
-- **API**: Micropub/IndieAuth remain stable
-- **Configuration**: Changes documented in upgrade guides
-
-## Contributing
-
-StarPunk welcomes contributions that align with its philosophy:
-
-### Code Contributions
-- Follow existing patterns
-- Include tests
-- Document changes
-- Keep it simple
-
-### Documentation
-- User guides
-- API documentation
-- Deployment guides
-- Migration guides
-
-### Testing
-- Bug reports with reproduction steps
-- Compatibility testing
-- Performance testing
-- Security testing
-
-## Technology Evolution
-
-### Near-term Considerations
-- Python 3.12+ adoption
-- SQLite WAL mode
-- HTTP/2 support
-- Container optimizations
-
-### Long-term Possibilities
-- Alternative database backends (PostgreSQL)
-- Federation protocols (ActivityPub)
-- Real-time features (WebSockets)
-- AI-assisted writing (local models)
-
-## Success Metrics
-
-StarPunk success is measured by:
-- **Simplicity**: Lines of code remain minimal
-- **Reliability**: Uptime and stability
-- **Standards Compliance**: Passing validators
-- **User Satisfaction**: Feature completeness
-- **Performance**: Response times <300ms
-
-## Philosophy
-
-> "Every line of code must justify its existence. When in doubt, leave it out."
-
-This philosophy guides all development decisions. StarPunk aims to be the simplest possible IndieWeb CMS that works correctly, not the most feature-rich.
-
----
-
-**Document Created**: 2025-11-25
-**Last Updated**: 2025-11-25
-**Status**: Living Document
-
-For the latest updates, see:
-- [Release Notes](/home/phil/Projects/starpunk/CHANGELOG.md)
-- [Project Plan](/home/phil/Projects/starpunk/docs/projectplan/)
-- [Architecture Decisions](/home/phil/Projects/starpunk/docs/decisions/)
\ No newline at end of file
diff --git a/docs/releases/INDEX.md b/docs/releases/INDEX.md
deleted file mode 100644
index 8fa56d6..0000000
--- a/docs/releases/INDEX.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Release Documentation Index
-
-This directory contains release-specific documentation, release notes, and version information.
-
-## Release Documentation
-
-- **[v1.0.1-hotfix-plan.md](v1.0.1-hotfix-plan.md)** - v1.0.1 hotfix plan and details
-
-## Release Process
-
-1. **Prepare Release**
-   - Update version numbers
-   - Update CHANGELOG.md
-   - Run full test suite
-   - Build container
-
-2. **Tag Release**
-   - Create git tag matching version
-   - Push tag to repository
-
-3. **Deploy**
-   - Build and push container image
-   - Deploy to production
-   - Monitor for issues
-
-4. **Announce**
-   - Post release notes
-   - Update documentation
-   - Notify users
-
-## Version History
-
-See [CHANGELOG.md](../../CHANGELOG.md) for complete version history.
-
-See [docs/projectplan/ROADMAP.md](../projectplan/ROADMAP.md) for future releases.
-
-## Related Documentation
-- **[../standards/versioning-strategy.md](../standards/versioning-strategy.md)** - Versioning guidelines
-- **[../standards/version-implementation-guide.md](../standards/version-implementation-guide.md)** - How to implement versions
-- **[CHANGELOG.md](../../CHANGELOG.md)** - Change log
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
diff --git a/docs/reports/INDEX.md b/docs/reports/INDEX.md
deleted file mode 100644
index f24a632..0000000
--- a/docs/reports/INDEX.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# Implementation Reports Index
-
-This directory contains implementation reports created by developers for architect review. Reports document completed work, implementation details, test results, and decisions made during development.
-
-## Report Format
-
-Reports typically include:
-- **Date**: YYYY-MM-DD-description.md format
-- **Summary**: What was implemented
-- **Technical Details**: How it was implemented
-- **Test Results**: Coverage and test outcomes
-- **Issues Encountered**: Problems and solutions
-- **Next Steps**: Follow-up tasks
-
-## All Reports (Chronological)
-
-### November 2025
-
-#### v1.1.0 Implementation
-- **[2025-11-25-v1.0.1-micropub-url-fix.md](2025-11-25-v1.0.1-micropub-url-fix.md)** - Micropub URL double-slash fix
-
-#### v1.0.0 Implementation & Fixes
-- **[2025-11-24-v1.0.0-rc.5-implementation.md](2025-11-24-v1.0.0-rc.5-implementation.md)** - RC.5 implementation
-- **[2025-11-24-phase1-indieauth-server-removal.md](2025-11-24-phase1-indieauth-server-removal.md)** - Custom IndieAuth server removal
-- **[2025-11-24-indieauth-removal-complete.md](2025-11-24-indieauth-removal-complete.md)** - IndieAuth removal completion
-- **[2025-11-24-endpoint-discovery-analysis.md](2025-11-24-endpoint-discovery-analysis.md)** - Endpoint discovery analysis
-- **[2025-11-24-migration-fix-v1.0.0-rc.2.md](2025-11-24-migration-fix-v1.0.0-rc.2.md)** - Migration fix for RC.2
-- **[2025-11-24-migration-detection-hotfix-rc3.md](2025-11-24-migration-detection-hotfix-rc3.md)** - Migration detection hotfix
-
-#### Phase 5 Implementation
-- **[2025-11-19-container-implementation-summary.md](2025-11-19-container-implementation-summary.md)** - Container deployment
-- **[2025-11-19-migration-system-implementation-report.md](2025-11-19-migration-system-implementation-report.md)** - Migration system
-- **[2025-11-19-migration-system-implementation-guidance.md](2025-11-19-migration-system-implementation-guidance.md)** - Migration guidance
-- **[2025-11-19-migration-implementation-quick-reference.md](2025-11-19-migration-implementation-quick-reference.md)** - Quick reference
-
-#### Phase 1-4 Implementation
-- **[2025-11-18-auth-redirect-loop-fix.md](2025-11-18-auth-redirect-loop-fix.md)** - Auth redirect loop resolution
-- **[2025-11-18-quickfix-auth-loop.md](2025-11-18-quickfix-auth-loop.md)** - Quick fix implementation
-
-### Specific Feature Reports
-
-#### Authentication & IndieAuth
-- **[indieauth-client-discovery-analysis.md](indieauth-client-discovery-analysis.md)** - Client discovery analysis
-- **[indieauth-client-discovery-fix-implementation.md](indieauth-client-discovery-fix-implementation.md)** - Fix implementation
-- **[indieauth-client-discovery-root-cause-analysis.md](indieauth-client-discovery-root-cause-analysis.md)** - Root cause
-- **[indieauth-detailed-logging-implementation.md](indieauth-detailed-logging-implementation.md)** - Logging implementation
-- **[indieauth-fix-summary.md](indieauth-fix-summary.md)** - Fix summary
-- **[indieauth-removal-analysis.md](indieauth-removal-analysis.md)** - Removal analysis
-- **[indieauth-removal-questions.md](indieauth-removal-questions.md)** - Q&A
-- **[indieauth-spec-url-standardization-2025-11-24.md](indieauth-spec-url-standardization-2025-11-24.md)** - URL standardization
-
-#### Database & Migrations
-- **[database-migration-conflict-diagnosis.md](database-migration-conflict-diagnosis.md)** - Conflict diagnosis
-- **[migration-failure-diagnosis-v1.0.0-rc.1.md](migration-failure-diagnosis-v1.0.0-rc.1.md)** - Failure diagnosis
-- **[migration-race-condition-fix-implementation.md](migration-race-condition-fix-implementation.md)** - Race condition fix
-- **[v1.0.0-rc.5-migration-race-condition-implementation.md](v1.0.0-rc.5-migration-race-condition-implementation.md)** - RC.5 migration fix
-
-#### Micropub
-- **[micropub-401-diagnosis.md](micropub-401-diagnosis.md)** - 401 error diagnosis
-- **[micropub-v1-implementation-progress.md](micropub-v1-implementation-progress.md)** - Implementation progress
-
-#### Bug Fixes
-- **[custom-slug-bug-diagnosis.md](custom-slug-bug-diagnosis.md)** - Custom slug bug
-- **[custom-slug-bug-implementation.md](custom-slug-bug-implementation.md)** - Bug fix
-- **[delete-nonexistent-note-error-analysis.md](delete-nonexistent-note-error-analysis.md)** - Delete error
-- **[delete-route-404-fix-implementation.md](delete-route-404-fix-implementation.md)** - 404 fix
-- **[delete-route-fix-summary.md](delete-route-fix-summary.md)** - Fix summary
-- **[delete-route-implementation-spec.md](delete-route-implementation-spec.md)** - Implementation spec
-
-#### Testing
-- **[2025-11-19-todo-test-updates.md](2025-11-19-todo-test-updates.md)** - Test updates
-- **[test-failure-analysis-deleted-at-attribute.md](test-failure-analysis-deleted-at-attribute.md)** - Test failure analysis
-- **[phase-4-test-fixes.md](phase-4-test-fixes.md)** - Phase 4 test fixes
-
-### Version-Specific Reports
-
-#### ADR Implementation
-- **[ADR-025-implementation-report.md](ADR-025-implementation-report.md)** - ADR-025 implementation
-- **[ADR-025-implementation-summary.md](ADR-025-implementation-summary.md)** - Summary
-- **[ADR-025-versioning-guidance.md](ADR-025-versioning-guidance.md)** - Versioning guidance
-
-#### Phase Implementation
-- **[phase-2.1-implementation-20251118.md](phase-2.1-implementation-20251118.md)** - Phase 2.1
-- **[phase-2-implementation-report.md](phase-2-implementation-report.md)** - Phase 2
-- **[phase-3-authentication-20251118.md](phase-3-authentication-20251118.md)** - Phase 3
-- **[phase-4-architectural-assessment-20251118.md](phase-4-architectural-assessment-20251118.md)** - Phase 4 assessment
-- **[phase-5-container-implementation-report.md](phase-5-container-implementation-report.md)** - Phase 5
-- **[phase-5-pre-implementation-review.md](phase-5-pre-implementation-review.md)** - Pre-implementation review
-- **[phase-5-rss-implementation-20251119.md](phase-5-rss-implementation-20251119.md)** - RSS implementation
-
-#### Version Releases
-- **[v0.9.1-implementation-report.md](v0.9.1-implementation-report.md)** - v0.9.1 release
-- **[v1.0.0-rc.1-hotfix-instructions.md](v1.0.0-rc.1-hotfix-instructions.md)** - RC.1 hotfix
-- **[v1.1.0-implementation-plan.md](v1.1.0-implementation-plan.md)** - v1.1.0 plan
-- **[v1.1.0-implementation-report.md](v1.1.0-implementation-report.md)** - v1.1.0 report
-
-### Special Reports
-- **[ARCHITECT-FINAL-ANALYSIS.md](ARCHITECT-FINAL-ANALYSIS.md)** - Comprehensive architectural analysis
-- **[implementation-guide-expose-deleted-at.md](implementation-guide-expose-deleted-at.md)** - Implementation guide
-- **[oauth-metadata-implementation-2025-11-19.md](oauth-metadata-implementation-2025-11-19.md)** - OAuth metadata
-- **[identity-domain-validation-2025-11-19.md](identity-domain-validation-2025-11-19.md)** - Identity validation
-- **[setup-complete-2025-11-18.md](setup-complete-2025-11-18.md)** - Setup completion
-
-## How to Use Reports
-
-### For Architects
-- Review reports to verify implementation quality
-- Check that decisions align with ADRs
-- Identify patterns for future standards
-
-### For Developers
-- Learn from past implementations
-- Find solutions to similar problems
-- Understand implementation context
-
-### For Project Management
-- Track implementation progress
-- Understand what was delivered
-- Plan future work based on lessons learned
-
-## Creating New Reports
-
-When completing work, create a report with:
-1. **Filename**: `YYYY-MM-DD-brief-description.md`
-2. **Summary**: What was done
-3. **Implementation**: Technical details
-4. **Testing**: Test results and coverage
-5. **Issues**: Problems encountered and solutions
-6. **Next Steps**: Follow-up tasks
-
-## Related Documentation
-- **[../architecture/](../architecture/)** - System architecture
-- **[../decisions/](../decisions/)** - ADRs referenced in reports
-- **[../design/](../design/)** - Design specs implemented
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
-**Total Reports**: 57
diff --git a/docs/reviews/INDEX.md b/docs/reviews/INDEX.md
deleted file mode 100644
index b220562..0000000
--- a/docs/reviews/INDEX.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Architectural Reviews Index
-
-This directory contains architectural reviews, design critiques, and retrospectives conducted by the architect agent.
-
-## Phase Reviews
-
-- **[phase-2-architectural-review.md](phase-2-architectural-review.md)** - Phase 2 architecture review
-- **[phase-3-authentication-architectural-review.md](phase-3-authentication-architectural-review.md)** - Phase 3 authentication review
-- **[phase-5-container-architectural-review.md](phase-5-container-architectural-review.md)** - Phase 5 container deployment review
-- **[phase-5-approval-summary.md](phase-5-approval-summary.md)** - Phase 5 approval summary
-
-## Feature Reviews
-
-### Micropub
-- **[micropub-phase1-architecture-review.md](micropub-phase1-architecture-review.md)** - Phase 1 Micropub review
-- **[micropub-phase3-architecture-review.md](micropub-phase3-architecture-review.md)** - Phase 3 Micropub review
-
-### Error Handling
-- **[error-handling-rest-vs-web-patterns.md](error-handling-rest-vs-web-patterns.md)** - REST vs Web error handling patterns
-
-## Purpose of Reviews
-
-Architectural reviews ensure:
-- Design quality and consistency
-- Adherence to standards
-- Alignment with project philosophy
-- Technical soundness
-- Maintainability
-
-## Related Documentation
-- **[../decisions/](../decisions/)** - ADRs resulting from reviews
-- **[../architecture/](../architecture/)** - Architectural documentation
-- **[../reports/](../reports/)** - Implementation reports
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
diff --git a/docs/security/INDEX.md b/docs/security/INDEX.md
deleted file mode 100644
index 0f0f1f0..0000000
--- a/docs/security/INDEX.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Security Documentation Index
-
-This directory contains security-related documentation, vulnerability analyses, and security best practices.
-
-## Security Guides
-
-- **[indieauth-endpoint-discovery-security.md](indieauth-endpoint-discovery-security.md)** - Security considerations for IndieAuth endpoint discovery
-
-## Security Topics
-
-### Authentication & Authorization
-- IndieAuth security
-- Token management
-- Session security
-
-### Data Protection
-- Secure storage
-- Encryption
-- Data privacy
-
-### Network Security
-- HTTPS enforcement
-- Endpoint validation
-- CSRF protection
-
-## Security Principles
-
-StarPunk follows these security principles:
-- **Secure by Default**: Security is enabled by default
-- **Minimal Attack Surface**: Fewer features mean fewer vulnerabilities
-- **Defense in Depth**: Multiple layers of security
-- **Fail Closed**: Deny access when uncertain
-- **Principle of Least Privilege**: Minimal permissions by default
-
-## Reporting Security Issues
-
-If you discover a security vulnerability:
-1. **Do NOT** create a public issue
-2. Email security details to project maintainer
-3. Allow time for patch before disclosure
-4. Coordinated disclosure benefits everyone
-
-## Related Documentation
-- **[../decisions/](../decisions/)** - Security-related ADRs
-- **[../standards/](../standards/)** - Security coding standards
-- **[../architecture/](../architecture/)** - Security architecture
-
----
-
-**Last Updated**: 2025-11-25
-**Maintained By**: Documentation Manager Agent
diff --git a/migrations/008_add_tags.sql b/migrations/008_add_tags.sql
new file mode 100644
index 0000000..40ab584
--- /dev/null
+++ b/migrations/008_add_tags.sql
@@ -0,0 +1,26 @@
+-- Migration 008: Add tag support for notes
+-- Version: 1.3.0
+-- Per microformats2 p-category specification
+
+-- Tags table (normalized tag storage)
+CREATE TABLE IF NOT EXISTS tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT UNIQUE NOT NULL,           -- Normalized tag name (lowercase, trimmed)
+    display_name TEXT NOT NULL,          -- Original display name (preserves case)
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Note-tag junction table
+CREATE TABLE IF NOT EXISTS note_tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    note_id INTEGER NOT NULL,
+    tag_id INTEGER NOT NULL,
+    FOREIGN KEY (note_id) REFERENCES notes(id) ON DELETE CASCADE,
+    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE,
+    UNIQUE(note_id, tag_id)
+);
+
+-- Indexes for performance
+CREATE INDEX IF NOT EXISTS idx_tags_name ON tags(name);
+CREATE INDEX IF NOT EXISTS idx_note_tags_note ON note_tags(note_id);
+CREATE INDEX IF NOT EXISTS idx_note_tags_tag ON note_tags(tag_id);
diff --git a/starpunk/micropub.py b/starpunk/micropub.py
index 0e2a4e8..2b6b2e5 100644
--- a/starpunk/micropub.py
+++ b/starpunk/micropub.py
@@ -318,7 +318,8 @@ def handle_create(data: dict, token_info: dict):
             content=content,
             published=True,  # Micropub posts are published by default
             created_at=published_date,
-            custom_slug=custom_slug
+            custom_slug=custom_slug,
+            tags=tags if tags else None  # Pass tags to create_note (v1.3.0)
         )
 
         # Build permalink URL
@@ -403,9 +404,9 @@ def handle_query(args: dict, token_info: dict):
         if note.title:
             mf2["properties"]["name"] = [note.title]
 
-        # Tags not implemented in V1, skip category property
-        # if hasattr(note, 'tags') and note.tags:
-        #     mf2["properties"]["category"] = note.tags
+        # Add tags if present (v1.3.0)
+        if note.tags:
+            mf2["properties"]["category"] = [tag["display_name"] for tag in note.tags]
 
         return jsonify(mf2), 200
 
diff --git a/starpunk/models.py b/starpunk/models.py
index 98662e1..70c95a8 100644
--- a/starpunk/models.py
+++ b/starpunk/models.py
@@ -121,6 +121,11 @@ class Note:
         default=None, repr=False, compare=False, init=False
     )
 
+    # Cached tags (loaded separately, not from database row)
+    _cached_tags: Optional[list[dict]] = field(
+        default=None, repr=False, compare=False, init=False
+    )
+
     @classmethod
     def from_row(cls, row: sqlite3.Row | dict[str, Any], data_dir: Path) -> "Note":
         """
@@ -358,8 +363,27 @@ class Note:
         """
         return self.published
 
+    @property
+    def tags(self) -> list[dict]:
+        """
+        Get note tags (lazy-loaded, but prefer pre-loading in routes)
+
+        Routes should pre-load tags using:
+            object.__setattr__(note, '_cached_tags', tags)
+
+        This property exists as a fallback for lazy loading.
+
+        Returns:
+            List of tag dicts with 'name' and 'display_name'
+        """
+        if self._cached_tags is None:
+            from starpunk.tags import get_note_tags
+            tags = get_note_tags(self.id)
+            object.__setattr__(self, "_cached_tags", tags)
+        return self._cached_tags
+
     def to_dict(
-        self, include_content: bool = False, include_html: bool = False
+        self, include_content: bool = False, include_html: bool = False, include_tags: bool = False
     ) -> dict[str, Any]:
         """
         Serialize note to dictionary
@@ -370,6 +394,7 @@ class Note:
         Args:
             include_content: Include markdown content in output
             include_html: Include rendered HTML in output
+            include_tags: Include tags in output (v1.3.0)
 
         Returns:
             Dictionary with note data
@@ -410,6 +435,9 @@ class Note:
         if include_html:
             data["html"] = self.html
 
+        if include_tags:
+            data["tags"] = [tag["display_name"] for tag in self.tags]
+
         return data
 
     def verify_integrity(self) -> bool:
diff --git a/starpunk/notes.py b/starpunk/notes.py
index 7cb7415..5440092 100644
--- a/starpunk/notes.py
+++ b/starpunk/notes.py
@@ -134,7 +134,11 @@ def _get_existing_slugs(db) -> set[str]:
 
 
 def create_note(
-    content: str, published: bool = False, created_at: Optional[datetime] = None, custom_slug: Optional[str] = None
+    content: str,
+    published: bool = False,
+    created_at: Optional[datetime] = None,
+    custom_slug: Optional[str] = None,
+    tags: Optional[list[str]] = None
 ) -> Note:
     """
     Create a new note
@@ -148,6 +152,7 @@ def create_note(
         published: Whether the note should be published (default: False)
         created_at: Creation timestamp (default: current UTC time)
         custom_slug: Optional custom slug (from Micropub mp-slug property)
+        tags: Optional list of tag display names (v1.3.0)
 
     Returns:
         Note object with all metadata and content loaded
@@ -294,7 +299,16 @@ def create_note(
     # Create Note object
     note = Note.from_row(row, data_dir)
 
-    # 9. UPDATE FTS INDEX (if available)
+    # 9. ADD TAGS (v1.3.0)
+    if tags:
+        try:
+            from starpunk.tags import add_tags_to_note
+            add_tags_to_note(note_id, tags)
+        except Exception as e:
+            # Tag addition failure should not prevent note creation
+            current_app.logger.warning(f"Failed to add tags to note {slug}: {e}")
+
+    # 10. UPDATE FTS INDEX (if available)
     try:
         from starpunk.search import update_fts_index, has_fts_table
         db_path = Path(current_app.config["DATABASE_PATH"])
@@ -540,6 +554,7 @@ def update_note(
     id: Optional[int] = None,
     content: Optional[str] = None,
     published: Optional[bool] = None,
+    tags: Optional[list[str]] = None
 ) -> Note:
     """
     Update a note's content and/or published status
@@ -553,6 +568,7 @@ def update_note(
         id: Note ID to update (mutually exclusive with slug)
         content: New markdown content (None = no change)
         published: New published status (None = no change)
+        tags: New tags list (None = no change, [] = remove all tags) (v1.3.0)
 
     Returns:
         Updated Note object with new content and metadata
@@ -608,8 +624,8 @@ def update_note(
     if slug is not None and id is not None:
         raise ValueError("Cannot provide both slug and id")
 
-    if content is None and published is None:
-        raise ValueError("Must provide at least one of content or published to update")
+    if content is None and published is None and tags is None:
+        raise ValueError("Must provide at least one of content, published, or tags to update")
 
     # Validate content if provided
     if content is not None:
@@ -695,7 +711,16 @@ def update_note(
             f"Failed to update note: {existing_note.slug}",
         )
 
-    # 6. UPDATE FTS INDEX (if available and content changed)
+    # 6. UPDATE TAGS (v1.3.0)
+    if tags is not None:
+        try:
+            from starpunk.tags import add_tags_to_note
+            add_tags_to_note(existing_note.id, tags)
+        except Exception as e:
+            # Tag update failure should not prevent note update
+            current_app.logger.warning(f"Failed to update tags for note {existing_note.slug}: {e}")
+
+    # 7. UPDATE FTS INDEX (if available and content changed)
     if content is not None:
         try:
             from starpunk.search import update_fts_index, has_fts_table
@@ -707,7 +732,7 @@ def update_note(
             # FTS update failure should not prevent note update
             current_app.logger.warning(f"Failed to update FTS index for note {existing_note.slug}: {e}")
 
-    # 7. RETURN UPDATED NOTE
+    # 8. RETURN UPDATED NOTE
     updated_note = get_note(slug=existing_note.slug, load_content=True)
 
     return updated_note
diff --git a/starpunk/tags.py b/starpunk/tags.py
new file mode 100644
index 0000000..21714b5
--- /dev/null
+++ b/starpunk/tags.py
@@ -0,0 +1,243 @@
+"""
+Tag management for StarPunk
+
+Functions:
+    normalize_tag: Normalize tag string for storage
+    get_or_create_tag: Get existing tag or create new one
+    add_tags_to_note: Associate tags with a note
+    remove_tags_from_note: Remove tag associations
+    get_note_tags: Get all tags for a note
+    get_notes_by_tag: Get all notes with a specific tag
+"""
+
+import re
+from typing import Optional
+
+from flask import current_app
+
+from starpunk.database import get_db
+
+
+def normalize_tag(tag: str) -> tuple[str, str]:
+    """
+    Normalize a tag string
+
+    Args:
+        tag: Raw tag string
+
+    Returns:
+        Tuple of (normalized_name, display_name)
+
+    Examples:
+        >>> normalize_tag("  IndieWeb  ")
+        ('indieweb', 'IndieWeb')
+        >>> normalize_tag("Machine Learning")
+        ('machine-learning', 'Machine Learning')
+    """
+    # Step 1: Strip whitespace for display_name
+    display_name = tag.strip()
+
+    # Step 2: Strip leading # characters
+    normalized = display_name.lstrip('#')
+
+    # Step 3: Replace spaces and slashes with hyphens
+    normalized = normalized.replace(' ', '-').replace('/', '-')
+
+    # Step 4: Remove characters not in [a-zA-Z0-9_-]
+    normalized = re.sub(r'[^a-zA-Z0-9_-]', '', normalized)
+
+    # Step 5: Collapse consecutive hyphens to single hyphen
+    normalized = re.sub(r'-+', '-', normalized)
+
+    # Step 6: Strip leading/trailing hyphens
+    normalized = normalized.strip('-')
+
+    # Step 7: Convert to lowercase for normalized name
+    normalized = normalized.lower()
+
+    return normalized, display_name
+
+
+def get_or_create_tag(display_name: str) -> int:
+    """
+    Get existing tag ID or create new tag
+
+    Args:
+        display_name: Tag display name
+
+    Returns:
+        Tag ID
+    """
+    db = get_db(current_app)
+    normalized_name, clean_display = normalize_tag(display_name)
+
+    # Try to find existing tag
+    tag = db.execute(
+        "SELECT id FROM tags WHERE name = ?",
+        (normalized_name,)
+    ).fetchone()
+
+    if tag:
+        return tag['id']
+
+    # Create new tag
+    cursor = db.execute(
+        "INSERT INTO tags (name, display_name) VALUES (?, ?)",
+        (normalized_name, clean_display)
+    )
+    db.commit()
+    return cursor.lastrowid
+
+
+def add_tags_to_note(note_id: int, tags: list[str]) -> None:
+    """
+    Associate tags with a note
+
+    Replaces all existing tags for the note.
+
+    Args:
+        note_id: Note database ID
+        tags: List of tag display names
+    """
+    db = get_db(current_app)
+
+    # Remove existing tags
+    db.execute("DELETE FROM note_tags WHERE note_id = ?", (note_id,))
+
+    # Add new tags
+    for tag_display in tags:
+        tag_id = get_or_create_tag(tag_display)
+        db.execute(
+            "INSERT INTO note_tags (note_id, tag_id) VALUES (?, ?)",
+            (note_id, tag_id)
+        )
+
+    db.commit()
+
+
+def get_note_tags(note_id: int) -> list[dict]:
+    """
+    Get all tags for a note
+
+    Args:
+        note_id: Note database ID
+
+    Returns:
+        List of tag dicts with 'name' and 'display_name'
+        Ordered alphabetically by display_name (case-insensitive)
+
+    Query should use: ORDER BY LOWER(tags.display_name) ASC
+    """
+    db = get_db(current_app)
+    tags = db.execute(
+        """
+        SELECT tags.name, tags.display_name
+        FROM tags
+        JOIN note_tags ON tags.id = note_tags.tag_id
+        WHERE note_tags.note_id = ?
+        ORDER BY LOWER(tags.display_name) ASC
+        """,
+        (note_id,)
+    ).fetchall()
+
+    return [dict(tag) for tag in tags]
+
+
+def get_tag_by_name(name: str) -> Optional[dict]:
+    """
+    Get tag by normalized name
+
+    Args:
+        name: Tag name (will be normalized before lookup)
+
+    Returns:
+        Tag dict with 'id', 'name', 'display_name' or None
+    """
+    db = get_db(current_app)
+    normalized_name, _ = normalize_tag(name)
+
+    tag = db.execute(
+        "SELECT id, name, display_name FROM tags WHERE name = ?",
+        (normalized_name,)
+    ).fetchone()
+
+    return dict(tag) if tag else None
+
+
+def get_notes_by_tag(tag_name: str) -> list:
+    """
+    Get all published notes with a specific tag
+
+    Args:
+        tag_name: Normalized tag name
+
+    Returns:
+        List of Note objects with tags pre-loaded
+    """
+    from starpunk.notes import get_note
+
+    db = get_db(current_app)
+    rows = db.execute(
+        """
+        SELECT DISTINCT notes.id
+        FROM notes
+        JOIN note_tags ON notes.id = note_tags.note_id
+        JOIN tags ON note_tags.tag_id = tags.id
+        WHERE tags.name = ? AND notes.published = 1
+        ORDER BY notes.created_at DESC
+        """,
+        (tag_name,)
+    ).fetchall()
+
+    notes = []
+    for row in rows:
+        note = get_note(id=row['id'])
+        if note:
+            # Pre-load tags
+            tags = get_note_tags(note.id)
+            object.__setattr__(note, '_cached_tags', tags)
+            notes.append(note)
+
+    return notes
+
+
+def parse_tag_input(input_string: str) -> list[str]:
+    """
+    Parse comma-separated tag input from admin form
+
+    Splits on commas, trims whitespace, filters empties,
+    deduplicates by normalized name (keeps first occurrence).
+
+    Args:
+        input_string: Comma-separated tags (e.g., "Python, IndieWeb, Web")
+
+    Returns:
+        List of unique tag display names
+
+    Examples:
+        >>> parse_tag_input("Python, IndieWeb, Web")
+        ['Python', 'IndieWeb', 'Web']
+        >>> parse_tag_input("Python, python, PYTHON")
+        ['Python']  # First occurrence wins
+        >>> parse_tag_input("  ,  , valid ,  ")
+        ['valid']
+    """
+    if not input_string:
+        return []
+
+    # Split on commas and strip whitespace
+    tags = [tag.strip() for tag in input_string.split(',')]
+
+    # Filter empty strings
+    tags = [tag for tag in tags if tag]
+
+    # Deduplicate by normalized name (keep first occurrence)
+    seen = set()
+    unique_tags = []
+    for tag in tags:
+        normalized, _ = normalize_tag(tag)
+        if normalized and normalized not in seen:
+            seen.add(normalized)
+            unique_tags.append(tag)
+
+    return unique_tags