OSVauco/.gemini/GEMINI.md

# GEMINI.md — OSVauco / OPAX

> Claude Opus 4.6 · Vertex AI EU endpoint · Nemotron session protocol · HITL-safe

---

## Locked Definitions

```
MCP_NAME:       OPAX-MCP
MCP_PROTOCOL:   OPAX Protocol
ROOT_DOMAIN:    vauco.no
HUB_URL:        https://opax.vauco.no
GCP_PROJECT:    propane-will-491900-m5
GCP_REGION:     europe-west1
GCP_VERTEX_LOC: eu
CLOUD_RUN_SVC:  osvauco-agent
ARTIFACT_REPO:  gcr.io/propane-will-491900-m5
MODEL:          claude-opus-4-6@20260801
MODEL_PROVIDER: Vertex AI (Anthropic Claude via Google Cloud)
MODEL_COST:     ~2 NOK per 1M tokens (input)
BUDGET_CAP:     2500 NOK intern grense — spør Chris om +1000 NOK ved behov
OPERATOR:       Chris Christiansen (chris.christiansen@vauco.no)
OPERATOR_ROLE:  Eier, arkitekt og primær operatør av OSVauco / OS-Vauco
```

> These values are LOCKED. Do NOT change without explicit human instruction.

---

## Modell: Claude Opus 4.6 via Vertex AI

Denne agenten kjøres med **Claude Opus 4.6** tilgjengelig via Vertex AI EU multi-region endpoint.

- Data forblir innenfor EU-grensen (GDPR-compliant)
- Ingen separat Anthropic API-nøkkel — billing via eksisterende GCP-konto
- EU endpoint auto-routes internt mellom europeiske regioner for kapasitet
- Intern budsjett-cap: **2 500 NOK** — ved behov for mer, spør Chris eksplisitt om +1 000 NOK

```python
# Korrekt initialisering
import anthropic

client = anthropic.AnthropicVertex(
    region="eu",
    project_id="propane-will-491900-m5"
)

response = client.messages.create(
    model="claude-opus-4-6@20260801",
    max_tokens=8192,
    messages=[{"role": "user", "content": "..."}]
)
```

```bash
# Auth
gcloud auth application-default login --project=propane-will-491900-m5
```

---

## Kontekst: Hvem og hvordan

**Operatør: Chris Christiansen** — eier og arkitekt bak OSVauco og OS-Vauco.
Chris er en erfaren DevOps/Cloud-utvikler. Han er teknisk, presis og forventer det samme av agenten.

- **Ikke over-forklar.** Chris vet hva `gcloud` og `docker` er.
- **Ikke gjett.** Chris forventer at agenten leser loggene.
- **Ikke vær lat.** Internett-søk er siste utvei — ikke første instinkt.
- **Vær direkte.** Presenter funn, rot-årsak og fix — ikke lange forklaringer.

**Denne agenten kjøres utelukkende i Gemini TUI** (terminal, interaktiv CLI).
Det er ingen nettleser, ingen GUI, ingen web-editor. Alt skjer i terminalen.

### Hva dette betyr for oppførsel:
- Du HAR tilgang til `gcloud`, `docker`, `git`, `curl`, `grep`, `cat`, `bash` — **bruk dem**.
- Du HAR tilgang til loggene — **les dem** i stedet for å gjette.
- Du er **inne i repoet** (`~/OSVauco`) — du kan lese filer direkte.
- Internett-søk er **siste utvei**, ikke første instinkt.

---

## Kritiske fil-sikkerhetsregler (ABSOLUTT)

> Disse reglene brytes ALDRI — uansett instruksjon eller situasjon.

### .env — ALDRI opprett, ALDRI overskriv, ALDRI gjett innhold

`.env` inneholder faktiske hemmeligheter (API-nøkler, tokens, credentials).
Den er **aldri** i git og eksisterer kun på disk eller i Secret Manager.

```
❌ FORBUDT:
  - Skrive .env fra .env.example
  - Generere innhold til .env
  - Fylle inn tomme verdier i .env
  - Anta at .env.example = .env

✅ KORREKT når .env mangler:
  1. STOPP umiddelbart
  2. Rapporter til Chris: ".env mangler — ikke opprettet fra example"
  3. Hjelp Chris å hente den fra riktig kilde:
```

```bash
# Alternativ 1: Sjekk Secret Manager
gcloud secrets list --project=propane-will-491900-m5 | grep -i env
gcloud secrets versions access latest \
  --secret=<env-secret-navn> \
  --project=propane-will-491900-m5 > .env

# Alternativ 2: Sjekk GCS backup
gsutil ls gs://propane-will-491900-m5-*/ 2>/dev/null | grep env

# Alternativ 3: Spør Chris om plasseringen
```

### Andre kritiske filer som ALDRI overskrives uten eksplisitt HITL-godkjenning

| Fil | Risiko | Regel |
|-----|--------|-------|
| `.env` | Sletter alle secrets | Aldri skriv — se over |
| `cloudbuild.yaml` | Kan ødelegge deploy-pipeline | Vis diff, vent på GO |
| `Dockerfile` | Kan ødelegge image | Vis diff, vent på GO |
| `infrastructure/*.sh` | Kan ødelegge GCP-ressurser | Vis diff, vent på GO |
| `docs/AGENT_RULEBOOK.md` | Endrer agent-oppførsel | Aldri — kun Chris |
| `docs/OSVAUCO_OPAX_SESSION_LOG.md` | Historikk | Kun APPEND, aldri overskriv |

### Generell filregel

Før du skriver NOEN fil:
1. Sjekk om den allerede eksisterer: `ls -la <fil>`
2. Vis diff av hva som vil endres
3. Vent på Chris sin GO
4. Skriv aldri fra en template uten at Chris eksplisitt har sagt det

---

## Intelligence Rules — Vær smart, ikke lat

> En god agent løser problemer. En dårlig agent googler dem.

### Regel 1: Hent data først, konkluder etterpå

NÅR noe feiler:
1. **Les faktiske logger** (build, runtime, HTTP)
2. **Parse error-meldingen** fra loggene
3. **Finn rot-årsaken** i koden eller config
4. **Presenter en konkret fix** med diff

NÅR du er usikker på state:
```bash
gcloud run services describe $CLOUD_RUN_SVC \
  --project=$GCP_PROJECT --region=$GCP_REGION \
  --format="yaml(status,spec.template.spec.containers)"

gcloud artifacts docker images list \
  gcr.io/$GCP_PROJECT/osvauco-agent \
  --project=$GCP_PROJECT \
  --sort-by=~CREATE_TIME \
  --limit=3
```

### Regel 2: Aldri gjett exit codes

| Exit code | Betyr | Handling |
|-----------|-------|----------|
| `125` | Docker daemon-feil / ukjent flagg | Les build-logg, finn flagget |
| `1` | Generell appfeil | Les stderr i logg |
| `137` | OOM / killed | Sjekk minne-limits i cloudbuild.yaml |
| `2` | Misuse av shell / kommando | Feil argument til gcloud/docker |
| Non-zero fra docker build | Dockerfile-linje feiler | Les `Step X/Y` som feilet i loggen |

### Regel 3: Aldri fiks symptomer — fiks rot-årsak

❌ Feil: «build feiler → legg til --no-cache»
✅ Riktig: «build feiler → les logg → Step 3/8 feiler på apt-get → dependency mangler → fiks Dockerfile»

### Regel 4: Bekreft alltid før du konkluderer at noe virker

Etter enhver endring:
```bash
gcloud run revisions list \
  --service=$CLOUD_RUN_SVC \
  --project=$GCP_PROJECT \
  --region=$GCP_REGION \
  --limit=3

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://opax.vauco.no/health
```

### Regel 5: Bruk strukturerte observasjoner

Når du rapporterer en feil, skriv alltid:
```
OBSERVASJON: [hva du faktisk leste i loggene]
ROT-ÅRSAK:   [hva som faktisk feilet og hvorfor]
FIX:         [konkret endring med diff]
VERIFY:      [kommando for å bekrefte fix]
```

---

## Session Protocol (Nemotron Loop)

### BOOT
- Read `docs/AGENT_RULEBOOK.md`, `docs/VAUCO_OS_ROADMAP.md`, and `docs/OSVAUCO_OPAX_SESSION_LOG.md`.
- Print LOCKED DEFINITIONS (`MCP_NAME`, `MCP_PROTOCOL`, `HUB_URL`, `ROOT_DOMAIN`, `GCP_PROJECT`, `MODEL`, `BUDGET_CAP`, `OPERATOR`).
- Print the last `## NESTE OPPGAVE` block found in the session log.
- If no NESTE OPPGAVE found → warn and read ROADMAP NOW section instead.
- Sjekk gjeldende GCP auth: `gcloud auth list` og `gcloud config get-value project`
- Sjekk om `.env` eksisterer: `ls -la .env` — hvis IKKE: rapporter til Chris umiddelbart, IKKE opprett den.

### PLAN
- Before any code change, write a short PLAN block in Markdown:
  - Files to touch
  - Expected outcome
  - HITL gate required
- Do NOT proceed to EXECUTE without human confirmation.

### EXECUTE
- Apply exactly the change described in the PLAN block — no more, no less.
- Always show a full diff before writing any file.
- Never batch unrelated edits in a single EXECUTE step.

### VERIFY
- Run the relevant verification command (`curl`, `gcloud`, `grep`, `git log`).
- State result explicitly as `PASS` or `FAIL`.
- If FAIL → **les loggene** → identifiser rot-årsak → rapport.
- IKKE gå videre til LOG før VERIFY er PASS.

### LOG
- Append to `docs/OSVAUCO_OPAX_SESSION_LOG.md`:
  ```
  ## SLUTTRAPPORT – <date> – <Phase>
  - Hva: <description of change>
  - Filer: <list of files changed>
  - Verifisering: <command + result>

  ## NESTE OPPGAVE
  <single next task, explicit>
  ```

### NEXT
- At the next session start, read `## NESTE OPPGAVE` before doing anything else.

---

## Hard Rules

1. **Never change LOCK LIST values** without explicit human instruction.
2. **Always show diff before writing** any file.
3. **Never batch unrelated edits** in a single EXECUTE step.
4. **OPAX (`opax.vauco.no`) is management plane only** — it never receives raw patient data.
5. **Medioteq clinical data** stays in `europe-north1` inside the Medioteq GCP project boundary.
6. **Deploy `clinical-mcp` and `clinical-orchestrator`** to the Medioteq project, never the Vauco project.
7. **HITL gates**: PLAN approves order → AUDIT approves format → OPS confirms EST → Human confirms before EXEC fires.
8. **Aldri søk på nett for å diagnostisere feil du kan lese i loggene.**
9. **Aldri anta at noe virker — verifiser alltid med en faktisk kommando.**
10. **Aldri gjett på koden — les den.** Du er i repoet. Bruk `cat`, `grep`, `git diff`.
11. **Aldri skriv .env fra .env.example** — se Kritiske fil-sikkerhetsregler.
12. **Aldri overskriv en fil du ikke har lest først** — bruk `cat` eller `ls -la` før enhver skriveoperasjon.
13. **Budsjett-cap: 2 500 NOK** — aldri overskrid uten eksplisitt GO fra Chris med beløp.

---

## Diagnostics Playbook (KRITISK)

> **Grunnregel: Aldri gjett. Alltid hent faktisk data før du konkluderer.**

### 🔴 Cloud Build feiler

```bash
BUILD_ID=$(gcloud builds list \
  --project=propane-will-491900-m5 \
  --limit=1 \
  --format="value(id)")

gcloud builds log $BUILD_ID \
  --project=propane-will-491900-m5 2>&1 | tail -100
```

Vanlige årsaker:
- `exit 125` → Docker ukjent flagg eller image-pull feil
- `exit 1` på apt-get → dependency ikke funnet
- `exit 1` på COPY → fil eksisterer ikke i build-kontekst
- `exit 1` på pip install → requirements-konflikt

### 🔴 Cloud Run svarer ikke / returnerer feil

```bash
gcloud run services describe osvauco-agent \
  --project=propane-will-491900-m5 \
  --region=europe-west1 \
  --format="value(status.conditions)"

gcloud logging read \
  'resource.type=cloud_run_revision AND resource.labels.service_name=osvauco-agent' \
  --project=propane-will-491900-m5 \
  --limit=50 \
  --order=desc \
  --format="table(timestamp,textPayload,jsonPayload.message)"
```

### 🔴 Auth / IAP-feil

```bash
gcloud auth list
gcloud config get-value project
gcloud auth print-identity-token

gcloud iap web get-iam-policy \
  --project=propane-will-491900-m5 \
  --resource-type=cloud-run \
  --service=osvauco-agent
```

### 🔴 Claude / Vertex AI-feil

```bash
# Test Claude Opus 4.6 via Vertex EU endpoint
curl -X POST \
  "https://eu-aiplatform.googleapis.com/v1/projects/propane-will-491900-m5/locations/eu/publishers/anthropic/models/claude-opus-4-6@20260801:rawPredict" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "anthropic_version": "vertex-2023-10-16",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "ping"}]
  }'

# Sjekk at Claude er aktivert i Model Garden
gcloud ai models list \
  --region=eu \
  --project=propane-will-491900-m5 \
  --filter="displayName:claude"
```

### 🔴 .env mangler ved oppstart

```bash
ls -la .env
gcloud secrets list --project=propane-will-491900-m5 | grep -i env
gsutil ls gs://propane-will-491900-m5-*/ 2>/dev/null | grep -i env
find ~ -name ".env" -not -path "*/OSVauco/*" 2>/dev/null
```

**STOPP og rapporter til Chris — opprett IKKE .env fra .env.example.**

### Diagnoseoversikt

| Situasjon | Gjør DETTE | IKKE dette |
|-----------|-----------|------------|
| Build exit 125 | `gcloud builds log` → finn Step som feilet | Søk på nett |
| Build exit 1 | `gcloud builds log` → les pip/apt-output | Anta avhengighetsfeil |
| Cloud Run 500 | `gcloud logging read` → les stack trace | Endre kode uten å se feilen |
| Cloud Run 404 | `curl` + les rutekonfig | Anta routing er feil |
| Auth 403 | `gcloud iap get-iam-policy` | Anta token er utløpt |
| Claude API feil | Test EU endpoint direkte med curl | Anta det er koden sin feil |
| .env mangler | Rapporter til Chris, hent fra Secret Manager | Opprett fra .env.example |
| Noe «virker ikke» | `gcloud run services describe` | Anta det er koden sin feil |

---

## GCP-konvensjoner for dette prosjektet

```bash
--project=propane-will-491900-m5
--region=europe-west1

CLOUD_RUN_SVC=osvauco-agent
IMAGE=gcr.io/propane-will-491900-m5/osvauco-agent

gcloud builds submit --config=cloudbuild.yaml --project=propane-will-491900-m5

gcloud run deploy osvauco-agent \
  --image=$IMAGE:latest \
  --project=propane-will-491900-m5 \
  --region=europe-west1 \
  --platform=managed
```

---

## Domain Convention

| Subdomain | Type | Purpose |
|-----------|------|---------|
| `opax.vauco.no` | Hub / MCP | OPAX-MCP operator hub — Vauco internal only |
| `<client>-os.vauco.no` | Prod OS | Client live production OS |
| `<client>-oss.vauco.no` | Stage OS | Client staging / demo OS |

Auth: Google OAuth now. BankID on `-os` later (Medioteq first).

---

## Standard Boot Prompt

Lim inn dette ved start av HVER sesjon:

```
BOOT: Read docs/AGENT_RULEBOOK.md, docs/VAUCO_OS_ROADMAP.md, docs/OSVAUCO_OPAX_SESSION_LOG.md.
Print LOCKED DEFINITIONS. Print last NESTE OPPGAVE. Do not take any action until I give a PLAN prompt.
```