📝 docs: Update AGENTS.md and README.md for current project state

`AGENTS.md` was stale — still listed Phases 3–5 as upcoming, referenced
Docker Compose and deleted config files, and omitted Bootstrap 5.3 and
CKEditor 5 from the stack description. Updated to reflect all completed
phases through Phase 5, current stack, Podman Compose instructions, and
environment-variable-based configuration.

`README.md` was last updated in 2019 and referenced Pagure, old setup
instructions, and the GSoC 2018 onboarding flow. Rewrote it with the
current stack, a modernization roadmap showing completed and upcoming
phases, a Podman-based quick start guide, and current community links
(Forgejo, Matrix).

Assisted-by: Claude Opus 4.6 (1M context)
Signed-off-by: Justin Wheeler <jwheel@fedoraproject.org>

AGENTS.md

@@ -10,7 +10,7 @@ Fedora Happiness Packets is a Django web application that enables Fedora communi
 
 ## Modernization Vision
 
-This project was dormant from 2021 to 2026 and is undergoing an incremental modernization effort to bring it back into production as an OpenShift-native containerized application within Fedora's infrastructure. The full plan is tracked in `.claude/plans/valiant-splashing-rainbow.md`.
+This project was dormant from 2021 to 2026 and is undergoing an incremental modernization effort to bring it back into production as an OpenShift-native containerized application within Fedora's infrastructure.
 
 **Completed phases:**
 - Phase 0: Dead code removal and housekeeping
@@ -18,13 +18,13 @@ This project was dormant from 2021 to 2026 and is undergoing an incremental mode
 - Phase 2: Pipenv → Poetry migration, pyproject.toml, v1.0.0 release
 - Phase 2.5: Forgejo Actions CI pipeline (lint + test)
 - Phase 3: Containerfile and Podman migration (replace Docker)
-- Phase 4: Settings refactoring (12-factor, eliminate config files read at import time)
+- Phase 4: Settings refactoring (12-factor env vars, eliminate config files)
 - Phase 5: Frontend modernization (Bootstrap 5.3, self-hosted fonts, CKEditor 5, jQuery removed)
 
 **Upcoming phases:**
 - Phase 6: OpenShift-native manifests (Kustomize, health probes, Routes)
 - Phase 7: Search backend replacement (Haystack/Whoosh → PostgreSQL full-text search)
-- Phase 8: Fedora integration updates (OIDC JWKS discovery, FAS/Noggin API, fedora-messaging)
+- Phase 8: Fedora integration updates (OIDC JWKS discovery, FAS/Noggin API, Redis → Valkey)
 - Phase 9: Forgejo Package Registry and CI/CD (container images, RPM packaging)
 - Phase 10: Production hardening (CSP, HSTS, observability, Celery tuning)
 
@@ -42,7 +42,9 @@ poetry install --without docs
 
 ### Environment Variables
 
-All configuration is via environment variables (12-factor). Copy `.env.example` to `.env` for local development. See `.env.example` for the full list of available variables.
+All configuration is via environment variables (12-factor).
+Copy `.env.example` to `.env` for local development.
+See `.env.example` for the full list of available variables.
 
 ### Running with Podman Compose
 

README.md

@@ -1,64 +1,96 @@
 fedora-happiness-packets
 ========================
 
-[![Join us at #fedora-commops on libera.chat](https://img.shields.io/badge/chat-on%20libera-brightgreen.svg)](https://web.libera.chat/?channels=fedora-commops "Join us at #fedora-commops on libera.chat")
-[![Documentation Status](https://readthedocs.org/projects/fedora-happiness-packets/badge/?version=latest)](https://fedora-happiness-packets.readthedocs.io/?badge=latest)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Fedora Account System authentication support and fedora-messaging integration to [Happiness Packets](https://happinesspackets.io) ([demo](https://happinesspackets.fedorainfracloud.org/))
+Fedora Happiness Packets is a Django web application that enables Fedora community members to send anonymous appreciation messages.
+It integrates with the Fedora Account System (FAS) for user lookup, Fedora OIDC for authentication, and `fedora-messaging` for publishing events to the Fedora message bus.
+
+**Current stack**: Django 5.1, Python 3.12–3.14, Poetry, PostgreSQL, Redis, Celery, Bootstrap 5.3, CKEditor 5.
+
+## Modernization Roadmap
+
+This project was dormant from 2021 to 2026 and is undergoing an incremental modernization effort to bring it back into production as an OpenShift-native containerized application within Fedora's infrastructure.
+
+### Completed
+
+- **Phase 0**: Dead code removal and housekeeping
+- **Phase 1**: Django 2.0 → 5.1 upgrade (four incremental LTS steps) and deprecated package replacement
+- **Phase 2**: Pipenv → Poetry migration, `pyproject.toml`, v1.0.0 release
+- **Phase 2.5**: Forgejo Actions CI pipeline (lint + test)
+- **Phase 3**: Containerfile and Podman migration (replace Docker)
+- **Phase 4**: Settings refactoring (12-factor env vars, eliminate config files)
+- **Phase 5**: Frontend modernization (Bootstrap 5.3, self-hosted fonts, CKEditor 5, jQuery removed)
+
+### Upcoming
+
+- **Phase 6**: OpenShift-native manifests (Kustomize, health probes, Routes)
+- **Phase 7**: Search backend replacement (Haystack/Whoosh → PostgreSQL full-text search)
+- **Phase 8**: Fedora integration updates (OIDC JWKS discovery, FAS/Noggin API, Redis → Valkey)
+- **Phase 9**: Forgejo Package Registry and CI/CD (container images, RPM packaging)
+- **Phase 10**: Production hardening (CSP, HSTS, observability, Celery tuning)
 
 
-## Documentation
+## Development
 
-For more help, read the [project documentation](https://fedora-happiness-packets.readthedocs.io/):
+### Prerequisites
 
-[**fedora-happiness-packets.readthedocs.io**](https://fedora-happiness-packets.readthedocs.io/)
+- [Python 3.12+](https://www.python.org/)
+- [Poetry](https://python-poetry.org/)
+- [Podman](https://podman.io/) and [podman-compose](https://github.com/containers/podman-compose) (for running services locally)
 
-### Contributing guidelines
+### Quick start
 
-See our [contributing guidelines](https://fedora-happiness-packets.readthedocs.io/meta/contributing/) for project guidelines.
+```bash
+# Install dependencies
+poetry install --without docs
 
-### Create development environment
+# Copy environment template
+cp .env.example .env
 
-These instructions run an instance of fedora-happiness-packets on your local machine for development and testing purposes.
-See [setup instructions](https://fedora-happiness-packets.readthedocs.io/setup/development/) in our documentation.
+# Start services (PostgreSQL, Redis, Celery, RabbitMQ)
+podman-compose up --build
+
+# Run migrations (in a separate terminal)
+podman-compose exec web python manage.py migrate
+```
+
+See `.env.example` for all available environment variables.
+
+### Testing and linting
+
+```bash
+# Run all tests with coverage
+poetry run pytest
+
+# Run a specific test file
+poetry run pytest happinesspackets/messaging/tests/test_views.py
+
+# Lint
+poetry run ruff check .
+```
+
+**Note**: Tests that require a database will fail without a running PostgreSQL instance.
+Use `podman-compose` or configure `DB_HOST` to point to an available database.
+
+The test settings module is `happinesspackets.settings.tsting` (intentionally misspelled to avoid import during test discovery).
 
 
 ## Where to find us
 
-Get in touch with us!
-You can find us in [**these places**](https://docs.fedoraproject.org/en-US/commops/#find-commops).
+- **Chat**: [Fedora Community Ops on Matrix](https://matrix.to/#/#commops:fedoraproject.org)
+- **Issues**: [Forgejo issue tracker](https://forge.fedoraproject.org/commops/fedora-happiness-packets/issues)
+- **Community**: [Fedora Community Operations](https://docs.fedoraproject.org/en-US/commops/#find-commops)
 
 
-## »»» New contributor? Start here! «««
+## Contributing
 
-Are you looking for ways to contribute?
-We recommend this path of activities for newcomers to follow:
+Contributions are welcome.
+Please file issues and pull requests on our [Forgejo repository](https://forge.fedoraproject.org/commops/fedora-happiness-packets).
 
-### 1. Read project goals and contributing guidelines
-
-Get to know our project better and what our goals are.
-Our [contributing guidelines](https://fedora-happiness-packets.readthedocs.io/meta/contributing/) explains what fedora-happiness-packets is and what it is not.
-They also explain etiquette on how to work on tickets and send pull requests.
-It is the most important reference when making contributions to the project.
-
-### 2. Create a development environment
-
-See [fedora-happiness-packets#100](https://pagure.io/fedora-commops/fedora-happiness-packets/issue/100 "Issue #100: Set up Happiness Packets development environment").
-
-### 3. Try out fedora-messaging
-
-fedora-messaging is tool for applications in Fedora Infrastructure to emit messages and communicate with other applications.
-It is an important part of integration for our project.
-See [fedora-happiness-packets#103](https://pagure.io/fedora-commops/fedora-happiness-packets/issue/103 "Ticket #103: Install fedora-messaging locally and publish a test message") for more info.
-
-### 4. Look for beginner-friendly tickets
-
-When you complete the previous steps, look for unassigned [beginner-friendly tickets](https://pagure.io/fedora-commops/fedora-happiness-packets/issues?status=Open&tags=good+first+issue&tags=help+wanted&tags=PASSED&priority=30&close_status= "Tickets tagged for newcomers").
-Tickets without an assignee are open for taking.
-Refer to the contributing guidelines for etiquette on claiming a ticket.
+See [`AGENTS.md`](AGENTS.md) for detailed architecture documentation and conventions.
 
 
 ## Legal
 
-This project is licensed under the [Apache License](https://pagure.io/fedora-commops/fedora-happiness-packets/blob/master/f/LICENSE).
+This project is licensed under the [Apache License 2.0](LICENSE).