🧹 chore(ci): establish dev integration governance

.github/pull_request_template.md

@@ -2,6 +2,9 @@
 
 <!-- What changed and why. Keep it short, 2-4 lines. -->
 
+> Community and maintenance PRs must target `dev`. `main` accepts only a
+> promotion PR whose source is this repository's `dev` branch.
+
 ## Scope
 
 <!-- Check all areas touched by this PR. -->

.github/workflows/main-promotion.yml

@@ -0,0 +1,42 @@
+name: Main Promotion
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+
+permissions:
+  contents: read
+
+jobs:
+  verify-source:
+    name: Verify dev promotion source
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Require the repository dev branch
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
+          REPOSITORY: ${{ github.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ "${BASE_REF}" != "main" ]; then
+            echo "Expected a pull request targeting main, got ${BASE_REF}." >&2
+            exit 1
+          fi
+
+          if [ "${HEAD_REPOSITORY}" != "${REPOSITORY}" ] || [ "${HEAD_REF}" != "dev" ]; then
+            echo "main accepts promotions only from ${REPOSITORY}:dev." >&2
+            echo "Received ${HEAD_REPOSITORY}:${HEAD_REF}." >&2
+            exit 1
+          fi

.github/workflows/pr-check.yml

@@ -4,9 +4,11 @@ on:
   pull_request:
     branches:
       - main
+      - dev
   push:
     branches:
       - main
+      - dev
 
 permissions:
   contents: read

.github/workflows/pr-template.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - main
+      - dev
     types:
       - opened
       - edited

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to CPA Manager Plus
+
+Thanks for contributing. `main` is the stable release branch and remains the
+repository default branch. All feature, fix, documentation, and maintenance
+work is integrated through `dev` before it is promoted to `main`.
+
+## Branch and Pull Request Flow
+
+1. Fork the repository and add the upstream remote.
+2. Fetch `upstream/dev` and create your working branch from it.
+3. Open your pull request against `seakee/CPA-Manager-Plus:dev`.
+4. Address review feedback and keep the branch current with `upstream/dev`.
+5. A maintainer promotes the tested repository `dev` branch to `main`.
+
+Do not open a feature or fix pull request directly to `main`. `main` accepts
+only a pull request from this repository's `dev` branch.
+
+```bash
+git remote add upstream https://github.com/seakee/CPA-Manager-Plus.git
+git fetch upstream
+git switch -c fix/short-description upstream/dev
+
+# Before requesting review, update your branch as appropriate for your team.
+git fetch upstream
+git rebase upstream/dev
+```
+
+## Before Opening a Pull Request
+
+- Read the pull request template and complete every applicable section.
+- Keep each pull request focused; do not combine unrelated features and fixes.
+- Include tests for changed behavior and run the checks relevant to your scope.
+- Add screenshots or recordings for visible UI changes.
+- Preserve both CPA Panel and Full Docker semantics when your change affects
+  authentication, setup, proxying, collection, or monitoring.
+- Never commit secrets, admin keys, CPA Management Keys, SQLite data, generated
+  runtime files, or local configuration.
+
+## Local Verification
+
+Use the narrowest checks that cover your change, then run broader checks when
+the change crosses frontend, Manager Server, packaging, or runtime boundaries.
+
+| Area | Command |
+| --- | --- |
+| Frontend type and lint | `npm run type-check` and `npm run lint` |
+| Frontend and repository tests | `npm run test` |
+| Frontend bundle | `npm run build` |
+| Manager Server | `npm run manager-server:test` |
+| Concurrent backend behavior | `cd apps/manager-server && go test -race ./...` |
+
+CI runs the applicable checks on pull requests to `dev`. Passing CI does not
+replace mode-specific manual verification where the pull request template
+requires it.
+
+## Maintainer Promotion
+
+After `dev` is reviewed and tested, open a pull request from
+`seakee/CPA-Manager-Plus:dev` to `main`. The promotion must pass the same CI,
+the source-branch gate, required review, and branch-protection rules before it
+is merged. Create release tags only from the verified `main` commit.