# VAUCO OS — MASTERPLAN

**Eier:** Chris Christiansen · Vauco AS · Org.nr 935 989 779
**Sist oppdatert:** 2026-06-12
**Status:** 🟢 AUTORITATIV — én kilde til sannhet for hele Vauco-økosystemet

> **Regel #1:** Denne filen er sannheten. Hvis en annen fil sier noe annet — denne vinner.
> **Regel #2:** Endringer her krever eksplisitt `PLAN APPROVED` fra Chris.
> **Regel #3:** Roadmap → seksjon 7. Sesjonsstatus → `docs/HANDOFF.md`. Ingen andre handoff-filer.

---

## Lessons Learned
- Cloud Build smoke-tests require: hardcoded canonical BASE_URL, bare identity token (no --audiences), and explicit run.invoker IAM binding for the Cloud Build service account on every service.
- **2026-06-10 — Absolutte filstier i Python:** Bruk alltid `Path(__file__).parent / "..."` for å referere til statiske filer og konfigurasjon i FastAPI/Cloud Run. Aldri relativ sti som `"static/file.html"` — dette bryter når WORKDIR avviker fra repo-rot (f.eks. i Docker). Regelen gjelder alle fremtidige tjenester og klientleveranser.
- **2026-06-10 — Dockerfile COPY static/:** `static/`-mappen må eksplisitt kopieres inn i Docker-imaget via `COPY static/ ./static/`. Den kopieres ikke automatisk selv om build-konteksten er repo-roten.
- **2026-06-10 — app.py mangler GET /:** FastAPI returnerer `{"detail":"Not Found"}` for alle ruter som ikke er definert. Sørg alltid for at rot-ruten er eksplisitt definert.
- **2026-06-12 — Mappestruktur må verifiseres mot repo:** MASTERPLAN-dokumentasjon av mappestruktur må alltid verifiseres via GitHub API før bygging. Antakelser om struktur er ikke nok.

---

## 1. Plattformhierarki — sannheten i én modell

```
Vauco AS  (selskap, eier alle merkevarer)
│
├── vauco.no  (APEX — bedriftens salgs- og portalside; ansiktet utad)
│
└── VAUCO OS  (plattform)
      └── OPAX  (engine — Cloud Run, RAG, agentic arkitektur, IAP)
            ├── Modul #1 · CostGuard       (live på costguard.oss.vauco.no)
            ├── Modul #2 · Threadstone     (landingsside live, app i bygg)
            └── Modul #3 · [navngis senere]

Separat merkevare (parkert):
└── Proof of Curiosity
```

| Nivå | Hva | Hvem ser det |
|---|---|---|
| **vauco.no (apex)** | Bedriftens salgsportal | Alle |
| Vauco OS | Plattformen Chris bygger | Internt |
| OPAX | Engine som driver modulene | Internt + utviklere |
| Modul | Det kundene kjøper | Kunder |

**Ikke selg Vauco OS. Ikke selg OPAX. De er interne verktøy.**

---

## 2. Registrerte domener — fasit

**Aktive subdomener:**

| Domene/subdomen | Teknologi | Status |
|----------|-----------|--------|
| `vauco.no` (apex) | GCS + LB + CDN | ✅ LIVE 2026-06-05 |
| `opax.vauco.no` | LB + IAP → Cloud Run | ✅ Live (IP 34.98.77.173) |
| `oss.vauco.no` | Staging | ✅ Aktiv |
| `costguard.oss.vauco.no` | Cloud Run via IAP | ✅ Live |
| `threadstone.vauco.no` | GitHub Pages | ✅ Live |
| `app.threadstone.vauco.no` | GitHub Pages | ⚠️ CNAME satt, side mangler |
| `os.vauco.no` | Prod-miljø | 🔮 Fase C |

**Email-infra:** MX + SPF/DKIM/DMARC ✅ Live 2026-06-10

---

## 3. Repo-struktur — fasit

### Aktive repos (5)

| Repo | Formål | Synlighet |
|------|--------|-----------|
| `OSVauco` | Mono-repo: OPAX-engine, infra, Terraform, all dokumentasjon | Privat |
| `vauco-bootstrap` | Terraform-modul for kunde-provisjonering | Privat |
| `vauco-site` | `vauco.no` salgsportal | Public |
| `threadstone-landing` | `threadstone.vauco.no` landingsside | Public |
| `vauco-saas.github.io` | Threadstone-app frontend | Public |

> **Regel:** Nytt repo krever eksplisitt `REPO APPROVED` fra Chris.

---

## 4. OSVauco — FAKTISK mappestruktur (verifisert 2026-06-12)

> **VIKTIG:** Denne seksjonen er verifisert mot GitHub API. Ikke anta struktur — alltid verifiser.

```
OSVauco/                          (root)
├── main.py          (26 KB)    ⭐ HOVUDAPPLIKASJON — FastAPI app + alle ruter
├── AGENTS.md
├── CLAUDE.md                   ← Kontekstfil for Claude-agenter
├── README.md
├── CNAME
├── cloudbuild.yaml             ← CI/CD trigger
├── cloudbuild.base.yaml
├── requirements.txt
├── .env.example / .env.prefilled
├── dev-startup.sh / opax.sh
│
├── agents/                     ← Agent-logikk (ikke hovudapp)
├── architecture/               ← Arkitekturdokumenter
├── auth/                       ← Auth-logikk
├── data/
├── dialogflow/                 ← Dialogflow-integrasjon
├── docs/                       ← All dokumentasjon
│   ├── MASTERPLAN.md
│   ├── ROADMAP.md
│   ├── HANDOFF.md
│   ├── AGENT_RULEBOOK.md
│   ├── UNIVERSAL_BOOT_PROMPT.md
│   ├── LEARNINGS.md
│   ├── ARCHITECTURE.md
│   ├── AGENTIC_CONTRACT_MCP_PROVISIONING.md
│   ├── DNS-OG-INFRASTRUKTUR.md
│   ├── SECRETS-SETUP.md
│   ├── LEARNINGS_CICD_2026-06-10.md
│   ├── GCP_Best_Practices.md
│   └── gemma/
│       └── world.md   ❌ MANGLER — blokkerer ML-3a/Emma-boot
├── infrastructure/
├── master_hub/                 ← Eksisterer — formål ikke klarlagt
├── ml/
├── opax-mcp/                   ← MCP-server (ikke agents/mcp_server/)
├── protocols/
├── scripts/
└── static/
    ├── opax.html               ✅ CG4d prisingskalkulator
    ├── costguard-dashboard.html ✅ CG6 klient-dashboard
    ├── jason.html
    ├── billing-dashboard.html
    ├── costguard.html
    ├── command-hub.html
    └── admin.html
```

**Kritiske korreksjoner fra tidligere feil dokumentasjon:**
- `main.py` (rot) er hovudapplikasjonen — IKKE `agents/core-logic/app.py`
- MCP-server ligger i `opax-mcp/` — IKKE `agents/mcp_server/`
- `master_hub/` og `dialogflow/` eksisterer — formål må kartlegges
- Nye ruter/endepunkter legges i `main.py` — ikke i agents/

---

## 4b. vauco.no — salgsportal

| Versjon | Inneholder | Trigger |
|---------|------------|---------|
| V1 (MVP) ✅ | Hero + modul-grid + om-oss + kontakt | LIVE 2026-06-05 |
| V2 | Sales-CTA + ROI-kalkulator | Etter første betalende kunde |
| V3 | Blogg, kundereferanser | Når 3+ kunder |

---

## 5. Dokumenthierarki

| Fil | Rolle |
|-----|-------|
| `docs/MASTERPLAN.md` | Autoritativ sannhet |
| `docs/ROADMAP.md` | Faser og status |
| `docs/HANDOFF.md` | Sesjonsstatus — overskrives hver sesjon |
| `docs/AGENT_RULEBOOK.md` | Locked agent-regler |
| `docs/UNIVERSAL_BOOT_PROMPT.md` | Boot-protokoll v1.4 |
| `CLAUDE.md` | Kontekst for Claude-agenter (rot) |
| `docs/gemma/world.md` | Emma sin kontekstpakke ❌ mangler |

---

## 6. AI-modell — tofase-strategi

### Fase 1 — Nå
| Parameter | Verdi |
|-----------|-------|
| Intern stand-in | Perplexity (Sonnet 4.6) via GitHub MCP |
| Kundemodell (Jason) | `gemini-2.5-flash` via Vertex AI |
| Region | `us-central1` |

### Fase 2 — Gemma (trigger: kreditter < 20% eller første kunde)
| Parameter | Verdi |
|-----------|-------|
| Emma (intern) | `gemma-4-12b-it` int4 · GCP `g2-standard-4` Spot VM |
| Jason (kunder) | `gemini-2.5-flash` via Vertex — uendret |

---

## 7. Roadmap — kortversjon

> Full status i `docs/ROADMAP.md`.

### 🔴 NOW
- [x] CG4d — Prisingskalkulator i `static/opax.html` ✅ 2026-06-12
- [x] CG5a — Delivery layer: `POST /notify/webhook` ✅ live (commit 4a1e23e, Sonar)
- [x] CG5b — E-postvarsler: `POST /notify/email` via SendGrid ✅ live
- [x] CG6 — Klient-dashboard `static/costguard-dashboard.html` ✅ 2026-06-12
- [ ] len(agents)-bugfix i `/run/dag` 🔴
- [ ] CG5-onboard — Klient-onboarding flow 🔴
- [ ] CG5c — SMS-varsler: `POST /notify/sms` via Twilio [Guard+]

### 🟠 NEXT
- CI1 — opax-mcp/ full CI/CD-kanal
- ML-3a — GPU-VM for Emma + `docs/gemma/world.md` opprettes
- C4 — Medioteq partnerstrategimøte

---

## 8. Agent-identitet

| Identitet | E-post | Modell | Status |
|-----------|--------|--------|--------|
| Eier | `chris.christiansen@vauco.no` | — | ✅ Aktiv |
| Jason Vauger | `jason.vauger@vauco.no` | `gemini-2.5-flash` | ✅ Live |
| Emma Vauger | `emma.vauger@vauco.no` | `gemma-4-12b-it` | 🔮 ML-3a |

**Forbudte kontoer:** `tinius.vauger`, `ccv` — aldri gi tilganger.

---

## 9. Cloud Run — live endepunkter

**Service:** `osvauco-agent` · `us-central1` · `propane-will-491900-m5`
**Public URL:** `https://opax.vauco.no`

| Endepunkt | Fil | Status |
|-----------|-----|--------|
| `GET /` | `main.py` | ✅ Serverer opax.html |
| `GET /health` | `main.py` | ✅ |
| `POST /run` | `main.py` | ✅ |
| `GET /static/jason.html` | `main.py` | ✅ |
| `GET /billing/tokens/by-module` | `main.py` | ✅ |
| `GET /billing/tokens/estimate` | `main.py` | ✅ |
| `GET /billing/summary` | `main.py` | ✅ |
| `GET /billing/anomalies` | `main.py` | ✅ |
| `GET /billing/history` | `main.py` | ✅ |
| `GET /billing/budget` | `main.py` | ✅ |
| `POST /billing/budget` | `main.py` | ✅ |
| `POST /notify/webhook` | `main.py` | ✅ CG5a live |
| `POST /notify/email` | `main.py` | ✅ CG5b live |
| `POST /notify/sms` | `main.py` | 🔴 CG5c |
| `GET /notify/channels` | `main.py` | 🔴 OQ-29 |

---

## 10. Go-to-market

### CostGuard — prismodell v2 (godkjent 2026-06-12)

> **Prinsipp:** Push-first — Jason finner kunden, ikke omvendt.
> **Pitch:** *"Du trenger ikke lære et nytt verktøy. Jason finner deg."*

| Tier | GCP-spend/mnd | Pris | Kjerneløfte |
|------|--------------|------|-------------|
| **Starter** | $0–$3k | $499/mnd | Synlighet |
| **Guard** | $3k–$15k | $999/mnd | Kontroll |
| **Shield** | $15k–$50k | $1.999/mnd | Automatisering |
| **Enterprise** | >$50k | $3.500+/mnd | Platform |

**Delivery layer:**
```
GCP-event → Jason → Delivery layer → Webhook (CG5a) / E-post (CG5b) / SMS (CG5c)
```

**Markedsposisjon:**

| Konkurrent | Pris | CostGuard vinner på |
|-----------|------|--------------------|
| Kubecost Business | $199/mnd | GCP-native + Jason AI |
| Apptio Cloudability | $1.930/mnd | Enklere, push-first |
| CloudHealth | $5.400+/mnd | Pris + SMB-fokus |

### Medioteq — Joint Venture
> Partnersamarbeid, ikke SaaS-kunde. C4 = partnerstrategimøte.

---

## 11. Kjente hull

| ID | Problem | Prioritet |
|----|---------|----------|
| OQ-15 | BQ billing_export tabell | Medium |
| OQ-17 | `github-token` secret mangler | Medium |
| OQ-18 | VM alltid-på kostnad | Høy |
| OQ-21 | `app.threadstone.vauco.no` CNAME uten side | Lav |
| OQ-26 | `docs/gemma/world.md` mangler | Høy (ML-3a blokkert) |
| OQ-27 | `master_hub/` formål ikke dokumentert | Medium |
| OQ-28 | `dialogflow/` formål ikke dokumentert | Medium |
| OQ-29 | `GET /notify/channels` mangler i `main.py` — CG6 faller tilbake på defaults | Lav |

---

## 12. OPAX — status

**Ferdig:**
- ✅ opax.html LIVE via `GET /` (main.py)
- ✅ Jason-chat LIVE
- ✅ Billing dashboard + Chart.js donut (CG4b)
- ✅ Token Intelligence endepunkter
- ✅ CI5+CI6 — opax-mcp live
- ✅ CG4d — Prisingskalkulator i opax.html
- ✅ CG5a — POST /notify/webhook live
- ✅ CG5b — POST /notify/email live
- ✅ CG6 — Klient-dashboard costguard-dashboard.html

**Gjenstår:** len(agents)-bugfix i /run/dag · CG5-onboard · CG5c · CI1 · ML-3a

---

*OSVauco | propane-will-491900-m5 | us-central1 | Autoritativ fra 2026-05-31 | Oppdatert 2026-06-12*

---

## 13. Telefoni & AI-agent Plan — Phase E tillegg

### Konsept: Twilio som kommunikasjonsryggrad
Et Twilio-nummer er grunnmuren for SMS, tale og AI-agent telefoni.
Alt bygger på samme konto og nummer.

---

### Lag 1 — Grunnmur (gjøres NÅ, Phase D)
Allerede planlagt:
- Twilio-konto opprettet
- TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER
  lagret i Secret Manager
- send_sms fungerer via opax-mcp

---

### Lag 2 — Inngående AI-telefonsvarer (Phase E, Uke 3-4)

#### Konsept
Kunder/kontakter ringer Twilio-nummeret.
Emma-agenten tar samtalen, transkriberer og svarer med tale.

#### Teknisk stack
- Twilio Programmable Voice + Conversation Relay (WebSocket)
- Ollama (emma modell) på osvauco-dev-vm som LLM
- Whisper eller Twilio Speech Recognition for STT
- Twilio TTS (eller Google TTS) for tale tilbake

#### Flyt
Innringer → Twilio → WebSocket → opax-mcp → Ollama (Emma)
Emma svarer → TTS → Twilio → Innringer

#### Hva Emma kan gjøre under samtalen
- Svare på spørsmål om OSVauco-tjenester
- Slå opp kundedata i backend
- Booke møter og sende SMS-bekreftelse
- Si "ett øyeblikk" og hente live data via MCP-tools
- Eskalere til Chris eller Jason med full samtale-kontekst

#### Implementasjon
1. Legg til /voice webhook-endepunkt i opax-mcp
2. Konfigurer Twilio Voice URL til opax-mcp Cloud Run
3. Bygg ConversationRelay WebSocket-handler
4. Koble til Ollama via eksisterende MCP-infrastruktur
5. Definer Emma sin persona og instrukser for telefon
6. Test med internt nummer først

---

### Lag 3 — Utgående AI-anrop (Phase E, Uke 5-6)

#### Konsept
Emma ringer proaktivt — f.eks. kostnadsvarsler,
møtepåminnelser, oppfølging av kunder.

#### Flyt
Trigger (kostnadsspike / planlagt tid)
→ Emma initierer anrop via Twilio Outbound API
→ Samme ConversationRelay-stack som inngående

#### Bruksområder
- "Hei, jeg ringer fra Vauco — dere nærmer dere
  budsjettgrensen på GCP denne måneden"
- Møtepåminnelse dagen før
- Oppfølging etter demo

---

### Lag 4 — Multikanal-orkestrering (Phase F)

#### Konsept
Emma bestemmer selv hvilken kanal som passer:
- Lav prioritet → SMS
- Medium → E-post (Gmail API, allerede oppe)
- Høy prioritet → Telefonanrop
- Intern → Google Chat webhook

#### Implementasjon
Legg til kanalvalg-logikk i Emma sin system-prompt:
  "Velg kanal basert på hastegrad og brukerpreferanse"

---

### Personas per kanal

| Kanal | Avsender | Persona |
|---|---|---|
| SMS | +47-Twilio-nummer | Nøytral, kort |
| E-post | jason.vauger@vauco.no | Profesjonell |
| Telefon inngående | Emma | Vennlig, hjelpsom |
| Telefon utgående | Emma | Proaktiv, konsis |

---

### Kostnadsestimat Twilio

| Tjeneste | Kostnad |
|---|---|
| Telefonnummer | ~$1/mnd |
| SMS utgående (NO) | ~$0.07/SMS |
| Voice inngående | ~$0.0085/min |
| Voice utgående | ~$0.014/min |
| Trial credits | $15 gratis ved oppstart |