.env.example

# !!! SECURITY WARNING !!!
# This file is tracked by git. DO NOT put real API keys or secrets here.
# Copy this file to .env.local and put your secrets there.
# .env.local is ignored by git.
# if you dont know what this means ask a professional for setting up keys
# !!! YOU HAVE BEEN WARNED !!!

# --- AI Inference ---
# Providers are managed in the AI-Hub (/ai) and stored in data/ai/config.json
# (API keys encrypted, or browser-only). The env vars below are the LEGACY
# single-endpoint config: on first start without data/ai/config.json they are
# migrated into a provider automatically. See docs/ai-platform.md.
LLM_API_BASE_URL=http://localhost:11434
LLM_MODEL=gpt-oss:20b
# Optional API key (server-side only — never use NEXT_PUBLIC_ for secrets!)
# LLM_API_KEY=sk-...
# Keys can also be referenced from providers as "ENV:MY_VAR".

# Legacy names (still honored as fallback, deprecated):
# NEXT_PUBLIC_LLM_API_BASE_URL, NEXT_PUBLIC_LLM_MODEL, NEXT_PUBLIC_LLM_API_KEY

# --- Credentials at rest ---
# Optional: 64 hex chars (32 bytes) used as AES-256-GCM master key for
# data/secure/. If unset, a key file is generated at data/secure/master.key.
# WORKSPACE_MASTER_KEY=

# --- Tool execution ---
# API tools refuse to call private/loopback addresses unless this is set.
# Needed e.g. when a tool endpoint runs on localhost.
# ALLOW_LOCAL_TOOL_URLS=1

# --- Wissensgraph: Quellen und Pfade (§6, M3/M4/M6) ---
# Obsidian-Vaults dürfen nur unter data/vaults/ liegen — oder unter einer
# der hier genannten Wurzeln (Doppelpunkt-getrennt, Pfad-Politik analog
# zum SSRF-Schutz).
# OW_VAULT_ROOTS=/srv/vaults:/home/me/Obsidian
# Dasselbe für git-backup-Arbeitsverzeichnisse (Default: data/).
# OW_GIT_ROOTS=/srv/backup
# Token für den github-rdf-Connector (private Repos, höheres Rate-Limit).
# GITHUB_TOKEN wird als Fallback ebenfalls gelesen.
# OW_GITHUB_TOKEN=

# --- Vektorsuche (§7.5, M8) ---
# Ohne diese beiden Variablen sagt die Suche ehrlich „kein Embedding-
# Provider konfiguriert" und arbeitet rein mit dem Volltext-Index.
# Der Provider ist eine ID oder ein Label aus dem AI-Hub (/ai).
# OW_EMBEDDING_PROVIDER=ollama
# OW_EMBEDDING_MODEL=nomic-embed-text

# --- Zugangs-Tokens: MCP-Server (§7.6) UND Föderation (§7.4) ---
# Externe Agenten (Claude Desktop, ein zweiter Workspace) retrieven über
# POST/GET/DELETE /api/mcp auf dem Wissensgraphen. OHNE diese Variable ist
# der Endpunkt aus — es gibt keinen anonymen Zugang.
# Jeder Eintrag bindet ein Token an eine Identität: "user" nennt den
# Nutzer, in dessen Namen der Zugang handelt — seine Rechte aus graph/acl
# sind die Rechte des Tokens (M13, §17). Default ist der Einzelnutzer.
#   scopes (optional)        -> zusätzliche VERENGUNG als Named-Graph-Muster
#                               (workspace, public, presentation, meta,
#                               vocab, shapes, import/*, import/<id>,
#                               inferred/*, shared/<id>, *). Ein Zugang darf
#                               damit weniger sehen als sein Nutzer, nie
#                               mehr. graph/acl trifft kein Muster.
#   sparql: true            -> Werkzeug graph_sparql (read-only)
#   write: true + writeScope -> Werkzeug graph_write (Default aus);
#                               writeScope: workspace | public | shared/<id>.
#                               Wirkt nur, wenn die ACL dem Nutzer dort
#                               acl:Write gibt.
#   rateLimitPerMinute       -> Default 120
# Dieselben Tokens gelten für die EINGEHENDE Föderation
# (GET|POST /api/graph/federation/sparql, read-only): ein Token mit
# "sparql": true sieht dort genau seine scopes; ohne gültiges Token ist das
# Dataset leer (die Query läuft, sieht aber nichts). Ausgehende
# SERVICE-Abfragen brauchen kein Token, sondern einen registrierten
# Endpoint unter /graph/federation.
# OW_MCP_TOKENS='[{"id":"claude-desktop","label":"Claude Desktop","token":"<mind. 16 Zeichen>","user":"default","sparql":true}]'

# --- Betrieb: Base-Path, Runtime, Identität (§5.2, M12) ---
# Vollständige Betriebsdoku: docs/deployment.md
# Unterpfad der Installation, wenn die App nicht an der Wurzel liegt
# (z. B. /workspace hinter einem Reverse-Proxy). Im Home-Assistant-Add-on
# ermittelt scripts/start.mjs den Ingress-Pfad selbst über die
# Supervisor-API; diese Variable ist dann nicht nötig.
# OW_BASE_PATH=/workspace
# Ingress-Modus erzwingen (1) oder verhindern (0). Ohne Angabe entscheidet
# das Vorhandensein von SUPERVISOR_TOKEN.
# OW_INGRESS=1
# Runtime-Kennung für die Anzeige (server | ha-addon); setzt der Start-Schritt.
# OW_RUNTIME=server
# Port des Next-Prozesses hinter dem Ingress-Proxy (Default 3001).
# OW_INTERNAL_PORT=3001
# Persistentes Datenverzeichnis (Add-on: /data) und Anwendungs-Nutzer.
# OW_DATA_DIR=/data
# OW_UID=1001
# OW_GID=1001

# Woher die Identität kommt:
#   single-user  (Default) kein Anmeldeverfahren
#   ha-ingress   Home Assistant (X-Remote-User-*)
#   proxy-header vorgelagerter OIDC-Proxy (oauth2-proxy)
#   oidc-bearer  Token der Anfrage, gegen die JWKS des Issuers geprüft
# Wer überhaupt hereinkommt, entscheidet der vorgelagerte Proxy bzw. Home
# Assistant; WAS eine Identität dann sehen darf, steht seit M13 als
# Web-Access-Control-RDF in graph/acl (§17, docs/multi-user.md).
# OW_AUTH_MODE=single-user
# OW_AUTH_USER_HEADER=x-forwarded-user
# OW_AUTH_NAME_HEADER=x-forwarded-preferred-username
# OW_AUTH_GROUPS_HEADER=x-forwarded-groups
# OW_OIDC_ISSUER=https://id.example.org/realms/main
# OW_OIDC_AUDIENCE=open-workspace
# OW_OIDC_JWKS_URL=https://id.example.org/realms/main/protocol/openid-connect/certs

# --- Rate-Limit des Assistenten ---
# Turns je Minute und Aufrufer an POST /api/chat. Gezählt wird pro
# geprüfter Identität, sonst pro Absenderadresse; darüber antwortet die
# Route mit 429 und Retry-After. Ein Turn kostet bis zu vier
# Inferenz-Aufrufe (Tool-Loop) — das Limit schützt Quote und GPU vor einer
# hängenden Schleife im Client, nicht vor Missbrauch. 0 schaltet es ab.
# OW_CHAT_RATE_LIMIT=20

# --- Multi-User: Verwalter-Seed (§17.2, M13) ---
# Nutzer mit acl:Control auf den instanzweiten Graphen (meta, vocab,
# shapes). Wirkt NUR beim Anlegen fehlender Standardregeln beim Start —
# danach ist graph/acl die Wahrheit, und Freigaben werden unter
# /graph/access verwaltet. Ohne Angabe gehört die Installation dem
# Einzelnutzer ("default").
# OW_ADMIN_USERS=alice,bob

# Öffentliche Adresse dieser Installation als Instanz-Base. Nur mit einer
# HTTP(S)-Base sind Entitäts-IRIs dereferenzierbar (§17.5:
# GET /u/<userId>/<type>/<id> mit Content Negotiation, /.well-known/void).
# Ohne Angabe entsteht eine urn:ow:<uuid>:-Base — die ist stabil, aber
# nicht auflösbar, und die Route sagt das ehrlich.
# OW_INSTANCE_BASE=https://ws.example.org/id/

# --- Beobachtungen: Zeitreihen aus Home Assistant erfassen ---
# (docs/beobachtungen.md, CAUSAL_LAYER_SPEC §6)
#
# Zugang: Im Add-on entsteht SUPERVISOR_TOKEN automatisch, sobald
# `homeassistant_api: true` im Manifest steht — dann ist hier nichts zu
# tun. Außerhalb des Add-ons trägt der Connector die URL, und der
# Long-Lived Access Token steht in der hier benannten Variablen (der
# Connector speichert nur ihren NAMEN, nie den Token selbst).
# OW_HA_TOKEN=eyJhbGciOi...
#
# Zeigt die HA-URL auf eine private Adresse (192.168.x, homeassistant.local),
# greift der SSRF-Schutz der Connector-Schicht. Derselbe Schalter wie beim
# Tool-Executor öffnet ihn:
# ALLOW_LOCAL_TOOL_URLS=1
#
# Takt des Erfassungslaufs in Sekunden (Default 600, Minimum 60).
# 0 schaltet den Zeitgeber ab — dann wird nur noch auf Anforderung erfasst
# (POST /api/graph/observations/capture), etwa aus einem externen Cron.
# Achtung: Was Home Assistant nach purge_keep_days verwirft, ist weg —
# ein abgeschalteter Zeitgeber heißt Datenverlust, nicht Ruhe.
# OW_CAPTURE_INTERVAL=600

# --- Nur für Tests ---
# Live-Föderationstest gegen Wikidata (braucht Netz). Ohne diese Variable
# überspringt sich der Test sichtbar, statt ein Ergebnis vorzutäuschen.
# OW_FEDERATION_LIVE=1