docs(ai-new-thread): clarify master-ai is local-only; production runs from Gitea+Coolify

ai-new-thread.md

@@ -39,9 +39,11 @@ graph TD
 
 ## 2. Directory Structure & Individual Git Repositories
 
-Your local directory `master-ai` is a **unified workspace** housing folders that map directly to **individual, independent repositories on Gitea** (`https://git.vibnai.com/mark`). 
+> **`master-ai` is a LOCAL development workspace on Mark's Mac. It does not exist in production and is never accessed by any running cloud service.** Production runs entirely from the individual Gitea repositories → Coolify builds → running containers on `34.19.250.135`. Once a change is pushed to the matching Gitea remote, `master-ai` is completely out of the picture.
 
-DO NOT treat `master-ai` as a single monorepo on Gitea. You must push changes inside specific directories to their matching Gitea remote targets.
+The local `master-ai` directory houses folders that each map to an **independent Gitea repository**. The `master-ai` git repo itself is just a convenience — a single place to commit and track changes across all sub-projects before pushing each one to its own Gitea remote.
+
+DO NOT treat `master-ai` as a single monorepo on Gitea — it is not deployed as one. You must push changes inside specific directories to their matching Gitea remote targets.
 
 ```
 /Users/markhenderson/master-ai/           <-- Local Parent Directory
@@ -57,25 +59,40 @@ DO NOT treat `master-ai` as a single monorepo on Gitea. You must push changes in
                                               Remote 'coolify_telemetry_gitea' -> https://git.vibnai.com/mark/vibn-telemetry-service.git
 ```
 
-### Git Remotes Reference (Configured in `/Users/markhenderson/master-ai`):
+### Git Remotes Reference (local Mac remotes — these exist only on Mark's machine):
-* `coolify_agent_gitea`     : `https://git.vibnai.com/mark/vibn-agent-runner.git`
-* `coolify_gitea`           : `https://git.vibnai.com/mark/vibn-frontend.git`
-* `coolify_api_gitea`       : `https://git.vibnai.com/mark/vibn-api.git`
-* `coolify_telemetry_gitea` : `https://git.vibnai.com/mark/vibn-telemetry-service.git`
-* `gitea`                   : `https://git.vibnai.com/mark/master-ai.git`  *(share-only: for a coworker's local setup; **builds do NOT use this**)*
-* `origin`                  : `https://github.com/MawkOne/master-ai.git`  *(GitHub mirror)*
 
-**How deploys actually work:** `master-ai` is a single git repo. Each cloud app builds from its **own** Gitea
+These are git remotes configured in the local `master-ai` repo. They are the **one-way bridge** between local development and production. Production Coolify services pull directly from the Gitea URLs; they have no knowledge of `master-ai`.
-remote, from the matching subfolder. To ship a change, commit in `master-ai`, then
-`git push <remote> HEAD:main` (e.g. `git push coolify_gitea HEAD:main` for vibn-frontend), then trigger the
-Coolify deploy for that app (see `VIBNDEV.md`). `vibn-code` is a nested submodule with its own `.git` — commit &
-push it via its own `origin`. Secret `.env*` files at the repo root are gitignored — never commit them.
 
-**⚠️ IMPORTANT — never use `git subtree push` for these remotes.** Coolify is configured with
+| Remote | Gitea URL | What it deploys |
-`vibn-frontend` as its **base directory**, so it expects the full `master-ai` repo at the remote root
+|---|---|---|
-and resolves the Dockerfile at `vibn-frontend/Dockerfile`. A subtree push flattens the repo to just the
+| `coolify_gitea` | `https://git.vibnai.com/mark/vibn-frontend.git` | vibn-frontend (Next.js platform) |
-subfolder contents, making the `vibn-frontend/` subdirectory disappear and breaking the build with
+| `coolify_agent_gitea` | `https://git.vibnai.com/mark/vibn-agent-runner.git` | vibn-agent-runner |
-`open Dockerfile: no such file or directory`. Always use `git push <remote> HEAD:main [--force]`.
+| `coolify_api_gitea` | `https://git.vibnai.com/mark/vibn-api.git` | vibn-api |
+| `coolify_telemetry_gitea` | `https://git.vibnai.com/mark/vibn-telemetry-service.git` | vibn-telemetry-service |
+| `gitea` | `https://git.vibnai.com/mark/master-ai.git` | *(share-only — coworker local setup; **builds do NOT use this**)* |
+| `origin` | `https://github.com/MawkOne/master-ai.git` | *(GitHub mirror only — not used by Coolify)* |
+
+**The full deploy lifecycle:**
+```
+Local Mac (master-ai)  →  git push <remote> HEAD:main  →  Gitea repo  →  Coolify build  →  Production
+         ↑                                                      ↑
+  master-ai ends here                                  Production begins here
+```
+
+1. Make changes in `master-ai/vibn-frontend/` (or whichever subfolder).
+2. `git commit` in `master-ai`.
+3. `git push coolify_gitea HEAD:main` (or relevant remote) — **this is the complete hand-off**.
+4. Coolify detects the push, builds a Docker image from the Gitea repo, and deploys it.
+5. `master-ai` is no longer involved. Production runs entirely from the Gitea repo + Coolify.
+
+`vibn-code` is a nested submodule with its own `.git` — commit & push it via its own `origin`.
+Secret `.env*` files at the repo root are gitignored — never commit them.
+
+**⚠️ NEVER use `git subtree push` for these remotes.** Coolify is configured with `vibn-frontend` as its **base directory**, so it expects the full `master-ai` repo structure at the Gitea root and resolves the Dockerfile at `vibn-frontend/Dockerfile`. A subtree push flattens the repo to just the subfolder contents, making `vibn-frontend/` disappear and breaking the build with `open Dockerfile: no such file or directory`. Always use:
+```bash
+git push <remote> HEAD:main          # normal
+git push <remote> HEAD:main --force  # if remote has diverged
+```
 
 ### Deploying the Telemetry Service manually via Coolify UI:
 Because Coolify's API strictly blocks the programmatic creation of GitHub/Gitea Apps, the Telemetry service must be linked manually once:
@@ -147,8 +164,14 @@ VibnCode overrides local OS actions to communicate with your cloud containers (o
    ```bash
    git commit -m "commit message" --no-verify
    ```
-3. **Push to Individual remotes**:
+3. **Push to Individual remotes (the ONLY way changes reach production)**:
-   Always commit inside the specific project folder, and push to the matching Gitea remote (e.g., `git push coolify_agent_gitea branch-name` for `vibn-agent-runner`).
+   Commit in `master-ai`, then push the relevant subfolder's remote. Production never reads from `master-ai` directly — the push to Gitea is the complete hand-off.
+   ```bash
+   git push coolify_gitea HEAD:main           # deploy vibn-frontend
+   git push coolify_agent_gitea HEAD:main     # deploy vibn-agent-runner
+   git push coolify_api_gitea HEAD:main       # deploy vibn-api
+   git push coolify_telemetry_gitea HEAD:main # deploy vibn-telemetry-service
+   ```
 
 ---