OSVauco/docs/HANDOFF.md

# HANDOFF — Vauco OS

**Sist oppdatert:** 2026-06-29 20:42 CEST
**Skrevet av:** Perplexity (for Chris Christiansen)
**Status:** Fase D — VM oppgradert, Gitea som primær, Ollama neste

### REPO TRUTH AND BACKUP STATUS (2026-07-16)

- Gitea is the authoritative source of truth for OSVauco.
- Main was successfully pushed to Gitea and is now aligned at commit e2f43391549a1950f081aa1bc9c1b2ecd3582ef5.
- GitHub is not part of the active automation path.
- GitHub is only an optional manual backup mirror.
- The current Gitea post-receive hook for GitHub mirroring is non-blocking and may fail without affecting the authoritative Gitea repo.
- Do not rely on GitHub mirror status for operational truth.
- If backup is needed later, it can be done manually after the primary Gitea path is stable.


### Gitea + OPAX-MCP status (2026-07-07)

- Gitea er migrert til CPU-VM `gitea-cpu-vm` og svarer på `http://34.170.51.84:3000` og `/api/v1/version`.
- OSVauco-repoet på dev-VM har remotes:
  - `origin` + `gitea`: `http://34.170.51.84:3000/chris/OSVauco.git`.
- Alle tidligere hardkodede Gitea-IP-er er oppdatert til CPU-VM:
  - `opax-mcp/server.py` (`GITEA_URL` default),
  - `emma/emma_gitea.py` (Emma-klient),
  - `.gemini/GEMINI.md` (PRIMARY_GIT, testkommandoer),
  - `dev-start.sh` (`GITEA_REMOTE`).
- Ny `opax-mcp/gitea_handler.py` er lagt til og bruker `GITEA_URL`/`GITEA_TOKEN` fra env for Gitea-API-kall.
- Neste steg (ikke utført ennå):
  - Verifisere `GITEA_TOKEN` via `gcloud secrets versions access --secret=gitea-token`,
  - kjøre enkel `curl` mot `"$GITEA_URL/api/v1/version"` med token,
  - deretter koble OPAX-MCP/Gitea-tools til den nye instansen.

Dette dokumentet er oppdatert til å reflektere at Gitea på CPU-VM er ny primær Git-master; GitHub er fortsatt kun legacy/backup.

---

## ⚠️ KRITISKE REGLER — les alltid først

- **Hovedapp:** `main.py` i rot — IKKJE `agents/core-logic/app.py`
- **Dockerfile:** `agents/core-logic/Dockerfile` — WORKDIR `/app`, CMD uvicorn main:app
- **Region:** `us-central1` | **Service:** `osvauco-agent` | **Prosjekt:** `propane-will-491900-m5`
- **ALDRI** `--audiences`-flag med `gcloud auth print-identity-token` — det er for service accounts, ikke user accounts
- **IAP identity token:** hentes fra GCE metadata server, IKKE fra gcloud CLI
- **Primær Git:** `http://34.170.51.84:3000/chris/OSVauco` — Gitea er nå kilde, GitHub er kun backup.
- **git remote:** `origin` = Gitea. GitHub-remote er fjernet.
- **Emma rapporterer til:** Chris Christiansen `chris.christiansen@vauco.no` — ingen andre kan gi GO
- **emma_runner.py finnes IKKE** — riktig fil er `emma/emma_run.py`
- **Ollama:** IKKE installert ennå — neste oppgave

---

## 📈 STRATEGISK FASEPLAN: Gitea som Source of Truth
**Status:** Planlagt

### Arkitekturbeslutning (Låst)
- **Gitea:** Eneste "Source of Truth" for all kode.
- **OPAX-MCP:** Eneste eksterne agent-gateway (over HTTPS).
- **GitHub:** Kun en potensiell passiv backup/mirror, ikke i operativ flyt.

### Domene-rollemodell (Låst)
- **`git.vauco.no` → Gitea:** Source of truth for kode.
- **`opax.vauco.no` → OPAX-MCP:** Ekstern agent-gateway.
- **`ops.vauco.no` → Parkert:** Droppes inntil videre for å redusere kompleksitet.

---

### Fase 1: Stabiliser `opax-mcp` konfigurasjon
*   **Beslutning (Låst):** Alternativ B er valgt. `opax-mcp.yaml` blir eneste autoritative kilde til sannhet for deploy-konfigurasjon.
*   **Filer/Tjenester:** `opax-mcp.yaml`, `cloudbuild.mcp.yaml`, Cloud Run `opax-mcp`.
*   **Verifisering:** `gcloud run services describe opax-mcp` viser korrekt konfigurasjon.

**Fase 1 – TODO:**
*   **Mål:** Én autoritativ deploy-kilde for opax-mcp (ikke manuell gcloud run deploy --source .).
*   **Ferdig-kriterie:** Live-opax-mcp bygges fra en definert pipeline som matcher opax-mcp.yaml (samme env-sett og image-vei).

### Fase 2: Etablere Gitea-capability bak OPAX-MCP
*   **Mål:** Etablere Gitea-funksjonalitet bak gatewayen, med tydelig skille mellom repo/Gitea og CI/CD.
*   **Filer/Tjenester:** `opax-mcp` (som gateway), en ny/dedikert Gitea-agent service.
*   **Verifisering:** `curl` til `opax-mcp` ruter et Gitea-kall korrekt til backend-tjenesten og gir HTTP 200.
*   **Ferdig-kriterie:** Gitea-funksjonalitet er tilgjengelig via `opax-mcp`, implementert i en separat tjeneste.

**Fase 2 – Gitea Capabilities (Scope):**

**Repo-lesing (Read-only):**
*   `list_repo_files`: Viser filer og mapper i en gitt bane.
*   `get_file_content`: Henter innholdet i en spesifikk fil.
*   `list_commits`: Viser de siste commits for en branch.
*   `list_open_issues`: Viser åpne issues i repoet.

**Repo-skriving (Operator-only):**
*   `update_file`: Oppdaterer en eksisterende fil (erstatter `push_file`).
*   `create_issue`: Oppretter en ny issue.
*   `create_branch`: Oppretter en ny branch.
*   `create_commit`: Lager en ny commit med endringer.

**Fase 2 – Implementasjonsretning (B-prime):**

**Blocker / Prerequisite for Implementasjon:**
*   `GITEA_URL` og `GITEA_REPO` **må** legges til som autoritative miljøvariabler i `opax-mcp.yaml` før koding av Gitea-handleren starter.
*   Hardkodede fallback-verdier i `server.py` skal ikke lenger være kilde til sannhet for konfigurasjon.
*   Logikken i `server.py` kan fortsatt bruke mønsteret `p.get('repo', GITEA_REPO)` for fleksibilitet, men kun etter at `GITEA_REPO` er deklarativt definert i YAML-filen.

1.  **Modul:** Ny fil `opax-mcp/gitea_handler.py` opprettes. Dette blir en **intern modul** i `opax-mcp`-servicen, ikke en egen microservice.
2.  **Logikk:** `opax-mcp/server.py` importerer `gitea_handler` og delegerer alle Gitea-relaterte kall (`list_repo_files`, `update_file`, etc.) dit. CICD-kall forblir i `server.py`.
3.  **Autentisering:**
    *   **Ekstern (klient → OPAX-MCP):** Håndteres av IAP, som i dag. Ingen endring.
    *   **Intern (OPAX-MCP → Gitea):** `gitea_handler.py` bruker et dedikert API-token til å autentisere seg mot Gitea.
4.  **Secrets:** `opax-mcp.yaml` må oppdateres med `GITEA_URL` og en referanse til secret `GITEA_API_TOKEN_SECRET`.

### Fase 3: Gitea-drevet CI/CD
*   **Mål:** Sikre at Cloud Build utelukkende trigges av `git push` til Gitea.
*   **Filer/Tjenester:** Cloud Build Triggers, Gitea webhooks, `cloudbuild.yaml`.
*   **Verifisering:** Et `git push` til Gitea starter en ny kjøring i Cloud Build.
*   **Ferdig-kriterie:** CI/CD-pipelinen er 100% Gitea-drevet.

### Fase 4: Fjerne GitHub fra daglig drift
*   **Mål:** Fjerne alle operative bindinger til GitHub.
*   **Filer/Tjenester:** `cloudbuild.yaml` (GitHub App-kobling), diverse skript.
*   **Verifisering:** Ingen skript eller pipelines feiler etter at GitHub-integrasjoner er fjernet.
*   **Ferdig-kriterie:** GitHub er kun en passiv backup.

---

## 🎯 NESTE OPPGAVE (prioritert)

### 1. Installer Ollama på osvauco-dev-vm
```bash
curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl enable ollama
sudo sed -i 's|ExecStart=.*|ExecStart=/usr/local/bin/ollama serve|' /etc/systemd/system/ollama.service
sudo sed -i '/ExecStart/a Environment="OLLAMA_HOST=0.0.0.0"' /etc/systemd/system/ollama.service
sudo systemctl daemon-reload && sudo systemctl restart ollama
```

### 2. Pull modeller
```bash
ollama pull gemma3:4b      # 3.3 GB — lett, rask
ollama pull qwen2.5:7b     # 4.7 GB — sterkere
```

### 3. Test Ollama
```bash
curl http://localhost:11434/api/generate -d '{"model":"gemma3:4b","prompt":"hei","stream":false}'
```

### 4. Oppdater opax-mcp/server.py (PARKERT/ERSTATTET)
- **Note:** Erstattet av Fase 1: `opax-mcp.yaml` som autoritativ deploy-path. Kodeendringer til `opax-mcp` skal følge den nye, stabile deploy-prosessen.

### 5. Oppdater boot.sh — Ollama autostart-sjekk
- Legg til seksjon `[ OLLAMA ]` i `scripts/boot.sh` som sjekker at Ollama kjører

### 6. Emma-gpu-vm — kun ved behov
- Legg til aliaser i `boot.sh`:
  - `emma-start` — starter emma-gpu-vm
  - `emma-stop` — stopper emma-gpu-vm

---

## 🖥 Infrastruktur per 2026-06-29

| Ressurs | Spec | Status | Kostnad/mnd |
|---------|------|--------|-------------|
| `osvauco-dev-vm` | e2-standard-4, 16GB RAM, 50GB SSD, us-central1-b | ✅ Kjører | ~NOK 550 |
| `emma-gpu-vm` | GPU, europe-west4-a | 💤 Stoppet | ~NOK 30 (kun disk) |
| Cloud Run `opax-mcp` | MCP-server, us-central1 | ✅ Kjører | ~NOK 50 |
| Cloud Run `osvauco-agent` | Hovedagent, us-central1 | ✅ Kjører | inkl. over |
| Load Balancer + DNS | opax.vauco.no, 34.98.77.173 | ✅ Kjører | ~NOK 150 |
| **TOTAL** | | | **~NOK 780/mnd** |

**Tidligere kostnad (emma alltid på):** NOK 6,000+/mnd

---

## ✅ Fullført i dag (2026-06-29)

| Oppgave | Status |
|---------|--------|
| `git remote origin` endret fra GitHub til Gitea på aktiv dev-VM (osvauco-gpu-vm) | ✅ |
| `github`-remote fjernet (duplikat) | ✅ |
| `git pull origin main` fungerer igjen | ✅ |
| `boot.sh` kjører komplett uten å henge | ✅ |
| `osvauco-dev-vm` oppgradert: e2-medium → e2-standard-4 (16GB RAM) | ✅ |
| Disk utvidet: 20GB → 50GB | ✅ |
| `emma-gpu-vm` stoppet (spare kostnad) | ✅ |
| GitHub avviklet som primær kilde, Gitea er nå master | ✅ |

*emma-gpu-vm er klargjort, men ikke tatt i bruk som primær dev-node ennå.*

---

## 🔑 Credentials

- **GitHub PAT:** Secret Manager → `GITHUB_PAT` (oppdatert 2026-06-25)
- **MCP-Secret:** Secret Manager → `mcp-server-key`
- **Prosjekt:** `propane-will-491900-m5`
- **IAP OAuth Client ID:** `357036551735-kq8nt7ld38hfqlcfb3n52ef7tala4meo.apps.googleusercontent.com`
- **VM compute SA:** `357036551735-compute@developer.gserviceaccount.com`
- **Ollama (når installert):** `http://localhost:11434`
- **Emma-gpu-vm IP:** `34.13.238.133` (kun når startet)

---

## 🏗 Arkitektur (nå)

```
Bruker
  └─► Jason (Vertex AI Agent Engine, Gemini 2.5 Pro)
        └─► osvauco-agent (Cloud Run)
              └─► opax-mcp (Cloud Run, 16 tools)
                    └─► [IAP] opax.vauco.no

osvauco-dev-vm (e2-standard-4, 16GB)
  └─► Gemini CLI / Claude CLI (opax/opax2)
  └─► Ollama (localhost:11434) ← INSTALLERES NESTE
        ├─► gemma3:4b  (lett)
        └─► qwen2.5:7b (sterk)
  └─► Emma (lokal agent)
        ├─► Morfisk minne (SQLite)
        ├─► Guardrails (5-nivå)
        └─► OPAX-klient

emma-gpu-vm (stoppet — start ved behov)
  └─► gemma3:27b (tung modell for kunder)
```

---

## 🔑 TILGANGSMODELL OG PROFILER

**Beslutning:**
- OPAX-MCP er felles ekstern gateway over HTTPS.
- Repo- og driftsverktøy er kun for operator-profiler.
- Familieprofiler og senere sluttbrukerprofiler skal ikke ha generell repo-oversikt eller generiske kodeverktøy.
- Sluttbrukere får kun oppgavebaserte capabilities med avgrenset scope.
- Nye brukere og nye hjem/oppsett skal på sikt kunne opprettes via blueprints/profiler, ikke via full teknisk tilgang.

**Operativ tolkning:**
- “Ekstern klient” betyr Perplexity, mobilflater, familieassistenter og andre agenter/VM-er som ikke skal ha direkte tilgang til intern repo/serverstruktur.
- Disse klientene skal gå via OPAX-MCP, ikke direkte mot Gitea eller interne driftstjenester.
- Full repo-innsikt, push/write og driftstools forblir for operatornivå.
- Familie- og sluttbrukerflater skal eksponere trygge, oppgavebaserte funksjoner i stedet for generelle utviklerverktøy.
- Arkitekturen skal støtte én kjerneplattform med ulike profiler: Operator, Family og senere kunde/hjem-blueprints.

PROFILMODELL – HVEM FÅR HVA VIA OPAX-MCP

Operator-profil (deg og evt. få betrodde)
- Full tilgang til OPAX-MCP-verktøy for repo, drift og CICD.
- Kan lese og skrive direkte mot Gitea via Gitea-capability (list_commits, get_file, push_file, issues).
- Kan trigge og overvåke Cloud Build / Cloud Run via CICD-capability.
- Kan endre arkitektur, secrets og konfigurasjon når det er nødvendig.
- Krav: sterk auth (MCP_SECRET), bevisst bruk, og commit/push-praksis mot Gitea som sannhet.

Family-profil (familie og nærmeste)
- Ingen generell repo-innsikt og ingen generiske kodeverktøy.
- Tilgang til oppgavebaserte capabilities (f.eks. familieplan, handleliste, meldinger, status) via OPAX-MCP.
- Kan bruke agenter og assistenter som går via OPAX-MCP, men bare innenfor trygge, avgrensede flows.
- Repo-tilgang for family skjer indirekte, som del av oppgaveverktøy, ikke som “fri coding”.
- Krav: enkel, mobilvennlig auth og minimal risiko for å påvirke drift eller arkitektur.

Blueprint-/kunde-/hjem-profiler (senere)
- Malbaserte profiler som beskriver hvilket sett med capabilities og hvilke grenser en ny “hjem” eller kunde får.
- Hver blueprint definerer:
  - Hvilke moduler som er aktive (Gitea-lesing, meldinger, økonomi, osv.).
  - Hvilke verktøy er synlige i OPAX-MCP for den profilen.
  - Hvilke ressurser (repoer, prosjekter, noder) er innenfor scope.
- Opprettelse av nye profiler skal skje som en bevisst handling via blueprint, ikke via ad-hoc åpning av hele systemet.

**Tilgangsmatrise – Gitea Capabilities (Fase 2):**
*   **Operator-profil:**
    *   **Repo-lesing:** Full tilgang.
    *   **Repo-skriving:** Full tilgang.
*   **Family-profil:**
    *   **Repo-lesing:** Kun tilgang til spesifikke, trygge funksjoner (f.eks. `get_file_content` for en handleliste). Ingen generell fil-listing.
    *   **Repo-skriving:** Ingen tilgang.
*   **Blueprint/Kunde/Hjem-profil:**
    *   **Repo-lesing:** Ingen tilgang som standard. Må aktiveres eksplisitt i blueprint.
    *   **Repo-skriving:** Ingen tilgang som standard.

---

## 🔁 LÆRINGSSLØYFE FOR AGENTER OG LLM-DRIFT

**Mål:**
- Systemet skal forbedres mens vi jobber, ikke bare etterpå.
- Høyere kvalitet skal komme fra bedre dataflyt, bedre seleksjon og bedre feedback, ikke bare større modeller.

**Prinsipper:**
- Good data beats more data: verifiserte hendelser, faktiske diff-er, reelle feil og ekte outcome-logg er mer verdifulle enn mye støy.
- Bad data compounds: feil antakelser, uverifiserte forklaringer og gamle docs som behandles som sannhet skal ikke mates tilbake ukritisk.
- Scaling laws i praksis: mer kontekst, flere steg og mer historikk gir bare bedre resultater hvis datakvaliteten holdes høy.
- Moore’s law betyr at rå compute over tid blir billigere og mer tilgjengelig, men det løser ikke alene kvalitetsproblemet i agent- og LLM-drift.
- Bedre hardware uten bedre datahygiene gir bare raskere produksjon av de samme feilene. Derfor skal systemet utnytte begge lover samtidig: Moore’s law på compute-siden, og scaling laws på modell/data-siden.
- Arbeidslogg, handoff, learnings og verifiseringsoutput skal brukes som kuratert læringsgrunnlag for neste agent og senere trenings-/finetunegrunnlag.
- Hver økt skal produsere små, høyverdige datapunkter: diagnose, plan, apply, verifisering, avvik, beslutning.
- Praktisk betyr det at mer GPU, mer kontekst og større modeller først gir varig verdi når læringsgrunnlaget er kuratert, verifisert og forankret i reell drift.
- Strategien er: bruk økende compute til å forsterke god læring, ikke til å skalere opp støy.

**Operativ regel:**
- Agenter skal ikke “lære” av egne antakelser alene.
- De skal lære av dokumentert virkelighet: rå output, godkjente diff-er, bekreftede feil, bekreftede fixes og tydelig markerte blockers.

**Bruk:**
- Dette gjelder Gemini på VM, OPAX-MCP, fremtidige LLM API-agenter og senere intern eval/finetune/RAG.
- Målet er at neste agent starter klokere enn forrige, uten å arve ukritisk støy.

---

## 🚚 Gitea-migreringsplan

Diagnose har avdekket at en aktiv Gitea-instans kjører på en midlertidig VM, og at lastbalanserer peker feil. Dette løses ved en kontrollert migrering til en ny, permanent VM, ikke ved å fikse den gamle.

*   **Kilde-VM:** `osvauco-dev-from-snap` (i `us-west4-a`)
*   **Kilde-data:** `/opt/gitea/data/` (inneholder `app.ini` med `ROOT_URL=http://34.170.51.84:3000/`)

*   **Mål-VM:** Ny `gitea-cpu-vm` (i `us-central1-b`, som per arkitekturbeslutning)
*   **Mål-data:** `/opt/gitea/data/`

**Nøkkelsteg ved migrering:**
1.  Data fra kilde-VM må kopieres til mål-VM.
2.  `ROOT_URL` i `app.ini` på mål-VM **må** oppdateres fra `http://34.170.51.84:3000/` til `https://git.vauco.no/`.
3.  Lastbalanserer-backend (`vauco-os-backend`) må pekes til den nye `gitea-cpu-vm` **etter** at migreringen er testet og verifisert.

---

## 📚 Relevante docs

| Dok | Innhold |
|-----|---------|
| `docs/LEARNINGS.md` | Append-only lærdomslogg |
| `docs/AGENT_RULEBOOK.md` | Boot-protokoll, deploy-regler |
| `.gemini/GEMINI.md` | Instrukser til Gemini CLI på VM |
| `scripts/boot.sh` | Session-starter, aliaser, TUI-valg |
| `scripts/vm-teardown.sh` | Cron 03:00 CEST — stopper dev-vm |
| `docs/DNS-OG-INFRASTRUKTUR.md` | DNS-kart, IAP-routing |

---

### HANDOFF 2026-07-07: Etablering av autoritativ deploy-pipeline

**Mål:** Gjøre `opax-mcp.yaml` til den eneste autoritative sannheten for deploy av `opax-mcp`-tjenesten, og fjerne den gamle, manuelle deploy-flyten.

**1. Analyse og opprydding av `opax-mcp.yaml`**
*   **Analyse:** En "diff" mellom live Cloud Run-tjenesten og `opax-mcp.yaml` avdekket avvik. Live hadde gamle GitHub-variabler, mens YAML-filen hadde mange nye (Gitea, Twilio, Gmail).
*   **Beslutning:** For å gjøre første autoritative deploy så trygg som mulig, ble det besluttet å midlertidig fjerne Gitea-spesifikke variabler (`GITEA_URL`, `GITEA_TOKEN`) fra `opax-mcp.yaml`.
*   **Resultat:** `opax-mcp.yaml` er patchet og committet. Den representerer nå en ren basis-konfigurasjon uten aktiv Gitea-runtime.

**2. Opprettelse av deklarativ pipeline (`cloudbuild.deploy.yaml`)**
*   **Analyse:** Den eksisterende `cloudbuild.mcp.yaml` brukte en imperativ `gcloud run deploy`-kommando som overstyrte manifest-filen.
*   **Beslutning:** En ny, dedikert og deklarativ pipeline-fil ble opprettet.
*   **Resultat:** `cloudbuild.deploy.yaml` er opprettet og committet. Den bygger et image med unik `$BUILD_ID`, rendrer en midlertidig kopi av `opax-mcp.yaml` med den nye image-taggen, og deployer med `gcloud run services replace`.

**3. Rekonfigurering av Cloud Build Trigger (feilet)**
*   **Mål:** Peker den eksisterende Gitea-webhook-triggeren (`gitea-osvauco-main`) fra den gamle `cloudbuild.mcp.yaml` til den nye `cloudbuild.deploy.yaml`.
*   **Problem:** `gcloud`-CLIet for å oppdatere/gjenopprette webhook-triggere viste seg å være kantete og feilet gjentatte ganger.
*   **Resultat:** Den gamle triggeren ble slettet i et forsøk på å gjenopprette den, men gjenopprettingen feilet. Plattformen er derfor **uten en aktiv CI/CD-trigger for `opax-mcp` akkurat nå.**

**4. Strategisk avklaring og neste steg**
*   **Vurdering:** Banen med Cloud Build webhooks er teknisk mulig, men føles som en unødvendig kompleks tilpasning. En egen, OPAX-styrt deploy-bro (Modell B) er et bedre langsiktig mål.
*   **Beslutning:** Vi fullfører den enkle webhook-flyten (Modell A) nå for å få en automatisert pipeline raskt, men planlegger for Modell B senere.

---
### Status og neste konkrete handling

| Artefakt | Status |
|---|---|
| `opax-mcp.yaml` | ✅ Klar for autoritativ deploy (midlertidig uten Gitea-vars) |
| `cloudbuild.deploy.yaml` | ✅ Klar og committet |
| **Cloud Build Trigger** | 🔴 **MANGLER.** Må gjenopprettes manuelt. |

**Neste handling:** Gjenopprett `gitea-osvauco-main` manuelt i Cloud Console med den nye `cloudbuild.deploy.yaml` som byggefil for å re-aktivere CI/CD-pipelinen.