Draft: Sync development into main for next release

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: fireform

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -35,3 +35,5 @@ Please describe the tests that you ran to verify your changes. Provide instructi
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes
 - [ ] Any dependent changes have been merged and published in downstream modules
+- [ ] The **Lint** workflow check passes on this PR ✅
+- [ ] The **Tests** workflow check passes on this PR ✅

.github/workflows/docker-build.yml

@@ -15,4 +15,4 @@ jobs:
 
       - name: Build Docker image
         run: |
-          docker build -t fireform:test .
+          docker build -t fireform:test -f docker/prod/Dockerfile .

.github/workflows/lint.yml

@@ -2,14 +2,13 @@ name: Lint
 
 on:
   push:
-    branches: [main]
+    branches: [main, development]  # post-merge verification after PRs land
   pull_request:
-    branches: [main]
+    branches: [main, development, 'development-*']  # gates all PRs
 
 jobs:
   lint:
     runs-on: ubuntu-latest
-    continue-on-error: true
 
     steps:
       - uses: actions/checkout@v4
@@ -19,11 +18,12 @@ jobs:
         with:
           python-version: "3.11"
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
       - name: Install linter
-        run: |
-          python -m pip install --upgrade pip
-          pip install ruff
+        run: uv pip install --system ruff==0.16.1
 
       - name: Run linter
         run: |
-          ruff check src/ --output-format=github
+          ruff check app/ --output-format=github

.github/workflows/tests.yml

@@ -2,14 +2,29 @@ name: Tests
 
 on:
   push:
-    branches: [main]
+    branches: [main, development]  # post-merge verification after PRs land
   pull_request:
-    branches: [main]
+    branches: [main, development, 'development-*']  # gates all PRs
 
 jobs:
   test:
     runs-on: ubuntu-latest
 
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: fireform
+          POSTGRES_PASSWORD: fireform
+          POSTGRES_DB: fireform
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U fireform"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
       - uses: actions/checkout@v4
 
@@ -18,13 +33,22 @@ jobs:
         with:
           python-version: "3.11"
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
+        run: uv pip install --system -r requirements.txt
 
       - name: Run tests
         env:
           PYTHONPATH: .
         run: |
-          python -m pytest tests/ -v --tb=short
+          python -m pytest tests/ -v --tb=short
+
+      - name: Check for un-migrated model changes
+        env:
+          PYTHONPATH: .
+          DATABASE_URL: postgresql://fireform:fireform@localhost:5432/fireform
+        run: |
+          python -m alembic upgrade head
+          python -m alembic check

.gitignore

@@ -26,4 +26,17 @@ src/inputs/*.pdf
 frontend/release/
 
 # Local Claude Code instructions
-CLAUDE.md
+CLAUDE.md
+
+*temp/
+*.env*
+!*.env.example
+
+# Local benchmark output
+reports/
+
+# Benchmark run output
+benchmark/results/
+
+# Local VS Code workspace configuration
+*.code-workspace

CONTRIBUTING.md

@@ -39,25 +39,14 @@ If you have a great idea for FireForm, we'd love to hear it! Please open an issu
 4. Make sure your code lints.
 5. Issue that pull request!
 
-## 🛠️ Local Development Setup
-
-FireForm uses Docker and Docker Compose for the backend to ensure a consistent environment.
+**Issues are not formally assigned.** You are free to pick any open issue, work on it, and raise a PR directly. If multiple PRs address the same issue, the first one that actually fixes it generally gets preference. To avoid duplicating someone else's work, coordinate with other contributors on our [Discord](https://discord.gg/nBv5b6kF68) before starting.
 
-### Prerequisites
+## 💬 Community
 
-- [Docker](https://docs.docker.com/get-docker/)
-- [Docker Compose](https://docs.docker.com/compose/install/)
-- `make` (optional, but recommended)
-- [Node.js](https://nodejs.org/) 20+ (only needed for the desktop app)
+Join our Discord server to ask questions, discuss issues, and coordinate work with other contributors: https://discord.gg/nBv5b6kF68
 
-### Desktop App Development
-
-The frontend is a vanilla HTML/CSS/JS app wrapped in Electron. To run it locally:
+## 🛠️ Local Development Setup
 
-```bash
-cd frontend
-npm install    # one-time setup
-npm start      # launches the Electron desktop window
-```
+See the [Setup Guide](docs/1.%20SETUP.md) for the full walkthrough: prerequisites, running the backend with Docker, testing endpoints via Swagger UI, day-to-day commands, and troubleshooting.
 
-The backend (API + Ollama) must be running separately via Docker — see `make fireform`.
+Before writing code, read the [Project Structure](docs/2.%20PROJECT_STRUCTURE.md) guide — it explains how the codebase is organized and where new code should go.

GOVERNANCE.md

@@ -0,0 +1,103 @@
+# FireForm Governance
+
+This document describes how the FireForm project is governed: who does what, how decisions are made, and how contributors can grow within the community.
+
+## Roles
+
+FireForm uses three roles. They are intentionally simple.
+
+### Owners
+
+**Organization administrators — set direction, own accountability.**
+
+- Set the project's strategic direction and governance.
+- Manage organization settings, repositories, teams, and permissions.
+- Make major architectural and strategic decisions.
+- Appoint and remove Maintainers.
+- Oversee security and project sustainability.
+
+**GitHub permission:** Organization Owner (full administrative access).
+
+> Every Owner holds the GitHub *Organization Owner* role and therefore has full administrative access. Keep at least two active Owners at all times for continuity.
+
+---
+
+### Maintainers
+
+**Technical leadership — keep the codebase healthy.**
+
+- Review and merge pull requests.
+- Maintain code quality, tests, and releases.
+- Manage issues and support contributors.
+- Lead particular repositories or technical areas.
+- Participate in technical planning.
+
+**GitHub permission:** `Maintain` or `Write`, depending on repository responsibilities.
+
+---
+
+### Contributors
+
+**Community participation — anyone who helps FireForm improve.**
+
+- Contribute code, documentation, tests, and designs.
+- Report bugs and suggest features.
+- Participate in discussions and testing.
+- Earn recognition and a path to become Maintainers.
+
+**GitHub permission:** Public contributors submit pull requests from forks without joining the organization. Additional access is granted only when specifically needed.
+
+---
+
+## Permission Matrix
+
+| Action | Owner | Maintainer | Contributor |
+| :--- | :---: | :---: | :---: |
+| Manage organization settings | ✅ | ❌ | ❌ |
+| Manage repository access | ✅ | Generally ❌ | ❌ |
+| Review pull requests | ✅ | ✅ | Can participate |
+| Merge pull requests | ✅ *(subject to rules)* | ✅ *(subject to rules)* | ❌ |
+| Manage releases | ✅ | If authorized | ❌ |
+| Submit pull requests | ✅ | ✅ | ✅ |
+| Participate in discussions | ✅ | ✅ | ✅ |
+
+> Branch protection rules and required CI checks apply to everyone, including Owners.
+
+---
+
+## Current Maintainers
+
+| Name | GitHub | Area |
+| :--- | :--- | :--- |
+| Marc Vergés Santiago | [@marcvergees](https://github.com/marcvergees) | Core backend, architecture |
+| Vincent Harkins | [@vharkins1](https://github.com/vharkins1) | Core backend, infrastructure |
+
+---
+
+## Promotion Path
+
+The hierarchy is simple, but promotion criteria should be explicit.
+
+**Contributor → Maintainer**
+Sustained, high-quality contributions; good collaboration; demonstrated responsibility and reliability over time. Nominated by an existing Maintainer and approved by the Owners.
+
+**Maintainer → Owner**
+Long-term trust, commitment to the project's future, and unanimous agreement from existing Owners.
+
+A person's role reflects their responsibilities. GitHub permissions should provide only the access appropriate to those responsibilities — with the exception that every Owner receives full organization administration by design.
+
+---
+
+## Decision Making
+
+- **Day-to-day decisions** (code review, issue triage): Maintainers.
+- **Technical direction** (architecture, major dependencies, releases): Maintainers with Owner visibility.
+- **Governance and strategic decisions** (role changes, forks, project future): Owners.
+
+For significant decisions, open a [GitHub Discussion](https://github.com/fireform-core/FireForm/discussions) so the community can participate before a conclusion is reached.
+
+---
+
+## Questions?
+
+Open a [Discussion](https://github.com/fireform-core/FireForm/discussions) or reach out on [Discord](https://discord.gg/nBv5b6kF68).