docs: expand engineering handbook and contributor guide

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing Guide
+
+## Purpose
+This repository is the standalone productized Workdock platform.
+
+Use this file as the quick-start guide for future coders. It complements:
+- `DEPLOYMENT.md`
+- `backend/workflows/templates/workflows/project_wiki.html`
+- `backend/workflows/templates/workflows/developer_handbook.html`
+
+If you change architecture, deployment flow, or operational behavior, update the relevant documentation in the same branch.
+
+## Branch Policy
+- `develop`: active integration branch
+- `main`: stable branch for production promotion
+- short-lived feature branches: branch from `develop`, merge back into `develop`
+
+Do not use `main` as the default development branch.
+
+## Current Delivery Model
+- GitHub Actions is used for CI
+- the current test server is local/LAN-only
+- deployment to the test server is manual from a LAN-connected machine
+
+Standard test deployment command:
+
+```bash
+./scripts/deploy_test_from_mac.sh
+```
+
+Why:
+- GitHub-hosted runners cannot reliably reach the private LAN target at `192.168.2.55`
+
+## Architecture Summary
+Main stack:
+- Django
+- Celery
+- PostgreSQL
+- Redis
+- Caddy
+
+Important repository areas:
+- `backend/config/`: Django configuration
+- `backend/workflows/`: application code
+- `backend/workflows/templates/workflows/`: templates and in-app documentation
+- `backend/workflows/static/workflows/`: CSS and JS
+- `backend/media/templates/`: PDF HTML templates
+
+Current backend modularization:
+- `views.py`: thin route wrapper layer
+- split view modules:
+  - `request_views.py`
+  - `account_views.py`
+  - `admin_config_views.py`
+  - `form_builder_views.py`
+  - `observability_views.py`
+  - `integration_admin_views.py`
+  - `welcome_email_views.py`
+  - `intro_builder_views.py`
+- `tasks.py`: async task entrypoints/orchestration
+- `pdf_rendering.py` and `pdf_sections.py`: PDF rendering
+- `email_workflows.py` and `notification_dispatch.py`: mail/notification orchestration
+- `models.py`: stable import facade over split model modules
+
+## Engineering Rules
+1. Preserve runtime behavior while refactoring.
+2. Prefer shared UI/system primitives over page-local one-off patterns.
+3. Do not silently overwrite environment-specific configuration data.
+4. Treat database-backed admin configuration as runtime state, not seed data.
+5. Update docs when workflow or architecture changes.
+
+## Code vs Data
+Not all visible behavior comes from code.
+
+Code-driven:
+- page layout
+- permissions
+- routing
+- task behavior
+- deploy scripts
+
+Database-driven:
+- app registry order and visibility
+- branding and company config
+- builder settings
+- intro checklist items
+- notification templates and rules
+
+If local UI and server UI differ, check the database-backed config before assuming a code drift.
+
+## Testing Rules
+Minimum validation after non-trivial changes:
+
+```bash
+docker compose exec -T web python manage.py check
+docker compose exec -T web python manage.py test
+```
+
+Also verify specifically when changing:
+- PDFs
+- deployment/config
+- templates/UI
+
+## Documentation Rules
+Keep these current:
+- `DEPLOYMENT.md`
+- `PRODUCTIZATION_ROADMAP.md`
+- `backend/workflows/templates/workflows/project_wiki.html`
+- `backend/workflows/templates/workflows/developer_handbook.html`
+
+## Recommended Change Flow
+1. Start from `develop`
+2. Implement the change
+3. Validate locally
+4. Update docs if needed
+5. Push to GitHub
+6. Let CI run
+7. Deploy from the Mac if runtime verification is needed
+8. Promote `develop` to `main` when stable