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:          gemini-2.5-pro
MODEL_PROVIDER: Vertex AI (Google) — europe-west1
MODEL_COST:     Vertex pris (Gemini 2.5 Pro)
MODEL_NOTE:     Midlertidig på Gemini inntil Claude-kvote er innvilget. Claude-variant: opax2 (claude-opus-4-7@20260301)
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

# 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": "..."}]
)

# 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:

# 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:

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:

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

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

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

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

# 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

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

--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/MASTERPLAN.md, docs/ROADMAP.md, docs/HANDOFF.md.
Print LOCKED DEFINITIONS. Print NESTE OPPGAVE from HANDOFF.md. Do not take any action until I give a PLAN APPROVED prompt.