docs(summary): mark monorepo as source of truth + feature/publish workflow

- Header banner: add 2026-04-19 entry for the release to backend-v4 /
  frontend-v4 split repos; state upfront that this monorepo is the single
  source of truth.
- §6 rewritten: layout diagram, remotes table, feature-branch → commit →
  publish workflow, exact `git subtree split` commands used to fast-forward
  frontend-v4/main and backend-v4/main, notes on what each split repo does
  and does not contain, and the safety rules for files that must never be
  committed (pgdata backups, build caches, env files).

Made-with: Cursor

docs/PROJECT_SUMMARY.md

@@ -1,8 +1,11 @@
 # EnCoach Platform — Project Summary
 
-> Last updated: 2026-04-18 | **Main branch: `v4`**
+> Last updated: 2026-04-19 | **This repo (`odoo19/`) is the single source of truth — main working branch: `v4`.**
+>
+> All feature work is committed here first, then published to the two split repos (`encoach_frontend_v4`, `encoach_backend_v4`) that the team lead deploys on the VPS. See **§6 Git Remotes & Repositories** for the exact workflow.
 
-> **Latest QA passes:**
+> **Latest events:**
+> - **2026-04-19 (release to VPS repos):** Pushed the accumulated institutional + support + training work to all three remotes. Monorepo `origin/v4` → `98b9837a`. Frontend split → `encoach_frontend_v4/main` (`b78124bb..435930a8`, 403 files, clean fast-forward). Backend split → `encoach_backend_v4/main` (`74d83af5..6ec68160`, 420 files, clean fast-forward). `.gitignore` updated to exclude `pgdata_bak_*/`, `frontend/.vite/`, `frontend/dist/`, `frontend/node_modules/` so the 674 MB of local pgdata backups never leak into a push. See §6.
 > - **2026-04-18 (training section):** Built the Training section end-to-end — the `Vocabulary` and `Grammar` pages (previously pure hard-coded mocks) are now wired to real Odoo data with CRUD, search, level filtering, and per-user progress tracking. New `encoach.vocab.item` / `encoach.vocab.progress` / `encoach.grammar.rule` / `encoach.grammar.progress` models + `/api/training/vocabulary` and `/api/training/grammar` controllers. 26/26 API write-flow actions passing (`test_training_flows.py`); both pages verified live in-browser. See §19.
 > - **2026-04-18 (support section):** Built the Support section end-to-end — the `Tickets`, `Payment Record`, and `Settings` pages are now wired to real Odoo data (they were previously mocks/404s). New `encoach.ticket` model + full CRUD controller, `/api/payment-records` deriving from `op.student.fees.details` + `account.move`, `/api/codes` + `/api/packages` + `/api/grading-config` powering the Settings tabs. 29/29 API write-flow actions passing (`test_support_flows.py`); all 3 pages verified live in-browser. See §18.
 > - **2026-04-18 (institutional pages write-flow):** API-level write-flow sweep across all 14 institutional admin pages — **44/44 actions passing** (CREATE / EDIT / DELETE / WORKFLOW). Numerous backend gaps fixed: missing DELETE routes added (admission-registers, admissions, result-templates, student-leaves), lesson/library detail endpoints added, custom `encoach.asset` model introduced to replace the missing `op.asset`, marksheet generate endpoint aliased for Odoo 19's `generate_result`, fees `create-invoice` auto-wires the product income account via Odoo 19's JSONB property storage, academic-year DELETE now cascades dependent terms. See §17.
@@ -155,35 +158,128 @@ odoo19/
 
 ## 6. Git Remotes & Repositories
 
-> **The `v4` branch is the main working branch.** All active development happens here.
+> **This monorepo (`/Users/yamenahmad/projects2026/odoo/odoo19/`) is the canonical source of truth.**
+> All feature work lands here on the `v4` branch. The two split repos
+> (`encoach_frontend_v4`, `encoach_backend_v4`) are **publish targets only** — the
+> team lead (Talal / devops) clones them on the VPS and runs `docker compose up`.
+> Never commit directly into the split repos; always publish from this monorepo
+> via `git subtree split + git push`.
 
-| Remote | URL | Purpose |
+### 6.1 Repository Layout
-|--------|-----|---------|
-| `origin` | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` | v2 backend (full monorepo) |
-| `backend-v3` | `https://git.albousalh.com/devops/encoach_backend_new_v3.git` | v3 monorepo push |
-| `frontend-v3` | `https://git.albousalh.com/devops/encoach_frontend_new_v3.git` | v3 monorepo push |
-| `backend-v4` | `https://git.albousalh.com/devops/encoach_backend_v4.git` | v4 backend only (subtree) |
-| `frontend-v4` | `https://git.albousalh.com/devops/encoach_frontend_v4.git` | v4 frontend only (subtree) |
 
-### Pushing to v3 (full monorepo to both)
+```
-
+odoo19/                          ← THIS repo (single source of truth, branch v4)
-```bash
+├── backend/                     → published to encoach_backend_v4/main
-git push backend-v3 v4:main
+│   ├── custom_addons/
-git push frontend-v3 v4:main
+│   ├── Dockerfile
+│   ├── docker-compose.yml
+│   └── requirements.txt
+├── frontend/                    → published to encoach_frontend_v4/main
+│   ├── src/
+│   ├── public/
+│   ├── Dockerfile, vite.config.ts, package.json, …
+└── docs/                        → stays in the monorepo only
 ```
 
-### Pushing to v4 (subtree — only the subfolder)
+### 6.2 Remotes Configured on This Clone
+
+| Remote | URL | Role |
+|--------|-----|------|
+| **`origin`** | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` | **Canonical monorepo** — the `v4` branch tracks `origin/v4`. Every commit goes here first. |
+| `backend-v3` | `https://git.albousalh.com/devops/encoach_backend_new_v3.git` | Legacy v3 monorepo mirror (rarely used) |
+| `frontend-v3` | `https://git.albousalh.com/devops/encoach_frontend_new_v3.git` | Legacy v3 frontend mirror (rarely used) |
+| **`backend-v4`** | `https://git.albousalh.com/devops/encoach_backend_v4.git` | **VPS deploy target — backend only** (hoisted contents of `backend/`) |
+| **`frontend-v4`** | `https://git.albousalh.com/devops/encoach_frontend_v4.git` | **VPS deploy target — frontend only** (hoisted contents of `frontend/`) |
+| `ip-origin` | `https://5.189.151.117/devops/encoach_backend_new_v2.git` | IP fallback for `origin` when DNS is flaky |
+
+### 6.3 Feature Development Workflow
 
 ```bash
-git subtree push --prefix=backend backend-v4 main
+# 1. Create a feature branch off v4
-git subtree push --prefix=frontend frontend-v4 main
+git checkout v4 && git pull origin v4
+git checkout -b feature/<short-name>
+
+# 2. Make changes, commit small and often
+git add <files>
+git commit -m "feat(<area>): <short description>"
+
+# 3. Merge back to v4 (or open a PR if repo has protection rules)
+git checkout v4
+git merge --no-ff feature/<short-name>
+
+# 4. Push monorepo
+git push origin v4
+
+# 5. Publish to VPS deploy targets (see §6.4)
 ```
 
-### Git Credentials
+### 6.4 Publishing to the Split VPS Repos (backend-v4 / frontend-v4)
+
+The split repos expect a **flat tree** (no `backend/` or `frontend/` prefix).
+Use `git subtree split` to carve each subdirectory's history, then push to
+`main` on the split remote. This is a fast-forward if nothing strange has been
+pushed to the split repos from elsewhere.
+
+```bash
+# ── Publish FRONTEND ────────────────────────────────────────────────────
+git subtree split --prefix=frontend HEAD -b split-frontend-v4
+git push frontend-v4 split-frontend-v4:main
+git branch -D split-frontend-v4           # cleanup (temp branch)
+
+# ── Publish BACKEND ─────────────────────────────────────────────────────
+git subtree split --prefix=backend HEAD -b split-backend-v4
+git push backend-v4 split-backend-v4:main
+git branch -D split-backend-v4
+```
+
+If a push is rejected as non-fast-forward, fetch first and inspect:
+
+```bash
+git fetch frontend-v4 backend-v4
+git log --oneline frontend-v4/main..split-frontend-v4    # what we're adding
+git log --oneline split-frontend-v4..frontend-v4/main    # divergence, if any
+```
+
+Only use `--force` when you have explicitly confirmed the remote `main` has
+nothing you want to keep (e.g. someone pushed directly and it must be
+overwritten).
+
+### 6.5 What Each Split Repo Contains
+
+**`encoach_frontend_v4` (branch `main`):** everything under `frontend/` hoisted
+to repo root — `src/`, `public/`, `docs/`, `Dockerfile`, `docker-compose.yml`,
+`package.json`, `package-lock.json`, `bun.lock`, `bun.lockb`, `vite.config.ts`,
+`tsconfig.*.json`, `tailwind.config.ts`, `eslint.config.js`, `index.html`,
+`.env.example`, `components.json`. **Excluded:** `node_modules/`, `dist/`,
+`.vite/`, `.env`, `.env.development`, `.env.production` (these are ignored by
+`frontend/.gitignore`).
+
+**`encoach_backend_v4` (branch `main`):** everything under `backend/` hoisted
+to repo root — `custom_addons/`, `Dockerfile`, `docker-compose.yml`,
+`requirements.txt`. **Excluded:** `openeducat_erp-19.0/` is vendored locally but
+**not** tracked in git — the VPS will need OpenEduCat installed separately
+(either vendored into the container image, mounted from `/opt/odoo/extra_addons`,
+or added to `requirements.txt` if an OpenEduCat package is used).
+
+### 6.6 Safety Rules (DO NOT COMMIT)
+
+Already excluded via `.gitignore` — do not try to force them in:
+
+- `pgdata/`, `pgdata_bak_*/` — PostgreSQL data directories (up to ~700 MB)
+- `frontend/node_modules/`, `frontend/dist/`, `frontend/.vite/` — build artifacts
+- `.env`, `.env.development`, `.env.production` — local secrets
+- `.venv/`, `venv/`, `.conda-envs/` — Python virtualenvs
+- `*.zip`, `*.tar.gz` — archives
+
+`odoo.conf` at the repo root IS tracked (it's your local Mac dev config).
+`backend/odoo.conf` is **not** currently tracked — if the VPS container needs
+a baked-in config, add it in a dedicated commit.
+
+### 6.7 Git Credentials
 
 Stored in macOS Keychain for `git.albousalh.com`:
 - Username: `yamen`
-- Auth: token-based (stored in keychain)
+- Auth: token-based (stored in keychain, not in this file)
 
 ---