.gitignore

@@ -1,4 +1,3 @@
-/composer.lock
 /.phpunit.cache
 /coverage
 /node_modules

CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing
+
+Thanks for your interest in DishPlanner. It's a small self-hosted project —
+issues and pull requests are both welcome.
+
+## Reporting issues
+
+Use [Issues](https://forge.lvl0.xyz/lvl0/dishplanner/issues).
+
+For bugs, include what you expected, what happened, and enough detail to
+reproduce it. Relevant log output helps; `dev-logs` follows the application log.
+
+## Development setup
+
+Requires PHP 8.2+ and a container runtime (Podman or Docker). The development
+environment runs in containers defined by `docker-compose.yml`.
+
+On NixOS, or anywhere with Nix installed:
+
+```bash
+git clone https://forge.lvl0.xyz/lvl0/dishplanner.git
+cd dishplanner
+nix-shell
+```
+
+The shell prints the available commands on entry and can start the containers
+for you:
+
+| Command | Description |
+|---------|-------------|
+| `dev-up` | Start the development environment |
+| `dev-down` | Stop the development environment |
+| `dev-restart` | Restart the containers |
+| `dev-rebuild` | Full rebuild (removes volumes) |
+| `dev-rebuild-quick` | Quick rebuild (keeps volumes) |
+| `dev-logs [service]` | Follow logs |
+| `dev-logs-db` | Tail database logs |
+| `dev-shell` | Enter the app container |
+| `dev-artisan <cmd>` | Run an artisan command |
+| `dev-test [path]` | Run the PHPUnit suite the CI way |
+| `dev-fix-permissions` | Fix Docker-created file permissions |
+
+Once running:
+
+| Service | URL |
+|---------|-----|
+| App | http://localhost:8000 |
+| Vite | http://localhost:5173 |
+| Mailhog | http://localhost:8025 |
+| MariaDB | localhost:3306 |
+
+Without Nix, start the same containers directly from `docker-compose.yml`.
+Contributions improving the setup instructions for other platforms are welcome.
+
+## Before opening a pull request
+
+Three checks run in CI, and all three must pass. Run them locally first, from
+inside the app container or anywhere the project's dependencies are available:
+
+```bash
+vendor/bin/pint --test                       # code style, Laravel preset
+vendor/bin/phpstan analyse --memory-limit=1G # static analysis, level 7
+php -d memory_limit=512M vendor/bin/phpunit  # PHPUnit on SQLite in memory
+```
+
+Or run the test suite the CI way with `dev-test`.
+
+Some conventions:
+
+- **Static analysis.** PHPStan runs at level 7 with a baseline
+  (`phpstan-baseline.neon`) covering pre-existing findings. Don't add baseline
+  entries to silence errors in code you're writing — fix the cause instead. The
+  baseline is for cases where the analyzer or an upstream docblock is wrong,
+  not real bugs.
+- **Tests.** New behaviour needs a test. Tests run against SQLite in memory and
+  must not reach for the network.
+- **Dependencies.** `composer.lock` is committed. If you change dependencies,
+  commit the updated lockfile alongside `composer.json`.
+
+## Commits
+
+One commit does one thing. Keep each commit passing all three checks so history
+stays bisectable. Separate renames from behaviour changes, and mechanical edits
+from logic.
+
+Commit messages are a single line, referencing the ticket they belong to:
+
+```
+45 - Add Forgejo CI workflow
+```
+
+No body, no trailers.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[GNU AGPL-3.0](LICENSE.md), the same license as the project.

README.md

@@ -1,5 +1,8 @@
 # 🍽️ Dish Planner
 
+[![CI](https://forge.lvl0.xyz/lvl0/dishplanner/badges/workflows/ci.yml/badge.svg)](https://forge.lvl0.xyz/lvl0/dishplanner/actions)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE.md)
+
 A Laravel-based meal planning application that helps households organize and schedule their dishes among multiple users. Built with Laravel, Livewire, and FrankenPHP for a modern, single-container deployment.
 
 ## ✨ Features
@@ -13,7 +16,7 @@ ## ✨ Features
 
 ## 🚀 Self-hosting
 
-The production image is available at `forge.lvl0.xyz/lvl0/dishplanner:latest`.
+The production image is available at `forge.lvl0.xyz/lvl0/dishplanner:latest`. See [CHANGELOG.md](CHANGELOG.md) before upgrading.
 
 ### docker-compose.yml
 
@@ -102,8 +105,10 @@ #### Available Commands
 | `dev-rebuild` | Full rebuild (removes volumes) |
 | `dev-rebuild-quick` | Quick rebuild (keeps volumes) |
 | `dev-logs [service]` | Follow logs |
+| `dev-logs-db` | Tail database logs |
 | `dev-shell` | Enter app container |
 | `dev-artisan <cmd>` | Run artisan commands |
+| `dev-test [path]` | Run the PHPUnit suite the CI way |
 | `dev-fix-permissions` | Fix Docker-created file permissions |
 
 #### Services
@@ -119,6 +124,11 @@ ### Other Platforms
 
 Contributions welcome for development setup instructions on other platforms.
 
+## 🤝 Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+the development setup, the checks that run in CI, and the commit conventions.
+
 ## 📄 License
 
 This project is open-source software licensed under the [AGPL-3.0 license](LICENSE.md).