From 8c80607df9b5e9ab9cfa115381a5b9d8c222eb84 Mon Sep 17 00:00:00 2001
From: curo1305 <curo1305@proton.me>
Date: Sun, 21 Jun 2026 20:43:45 +0200
Subject: [PATCH] fix(dev-env): complete local startup configuration

---
 .env.example | 18 ++++++++++++++++++
 AGENTS.md    |  7 +++++++
 CLAUDE.md    |  7 +++++++
 3 files changed, 32 insertions(+)

diff --git a/.env.example b/.env.example
index e592935..df26c85 100644
--- a/.env.example
+++ b/.env.example
@@ -17,6 +17,8 @@ POSTGRES_PASSWORD=changeme_super
 MINIO_ROOT_USER=minioadmin
 MINIO_ROOT_PASSWORD=changeme_minio_root
 MINIO_ENDPOINT=minio:9000
+# Browser-resolvable endpoint used in presigned URLs.
+MINIO_PUBLIC_ENDPOINT=localhost:9000
 # App-level access key. docker-compose.yml provisions this user and a bucket-scoped policy.
 MINIO_ACCESS_KEY=docuvault_app
 MINIO_SECRET_KEY=changeme_minio_app
@@ -74,3 +76,19 @@ ONEDRIVE_TENANT_ID=common
 # Backend and frontend URLs — used to construct OAuth callback/redirect URLs
 BACKEND_URL=http://localhost:8000
 FRONTEND_URL=http://localhost:5173
+
+# ── AI Defaults ──────────────────────────────────────────────────────────────
+DEFAULT_AI_PROVIDER=ollama
+DEFAULT_AI_MODEL=llama3.2
+SYSTEM_PROMPT=
+
+# ── Auth/session durations ───────────────────────────────────────────────────
+ACCESS_TOKEN_EXPIRE_MINUTES=15
+REFRESH_TOKEN_EXPIRE_DAYS=30
+REFRESH_TOKEN_EXPIRE_HOURS=16
+
+# ── Development logging and observability ────────────────────────────────────
+LOG_LEVEL=INFO
+LOG_JSON=true
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=CHANGEME-replace-with-strong-password
diff --git a/AGENTS.md b/AGENTS.md
index 7c28a1c..8a95e65 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -129,6 +129,13 @@ Phase 12 gap-closure: migration-gated Compose startup (migrate service, service_
 
 ## Development Setup
 
+### Local environment contract
+
+- The repository-root `.env` is the complete local-development configuration and must remain excluded from Git.
+- Codex and Claude must update both `.env` and `.env.example` whenever a change adds, removes, or renames an environment variable required by the app or Docker Compose.
+- Preserve existing local secret values unless rotation is required; never copy `.env` secrets into tracked files, logs, commits, or responses.
+- Before declaring startup work complete, run `docker compose config --quiet` and verify every required variable is present and non-empty.
+
 ```bash
 # Start all services
 docker compose up
diff --git a/CLAUDE.md b/CLAUDE.md
index 779ba2c..b8b2c4b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -125,6 +125,13 @@ All phases are marked complete in `.planning/ROADMAP.md`. The app is functional
 
 ## Development Setup
 
+### Local environment contract
+
+- The repository-root `.env` is the complete local-development configuration and must remain excluded from Git.
+- Codex and Claude must update both `.env` and `.env.example` whenever a change adds, removes, or renames an environment variable required by the app or Docker Compose.
+- Preserve existing local secret values unless rotation is required; never copy `.env` secrets into tracked files, logs, commits, or responses.
+- Before declaring startup work complete, run `docker compose config --quiet` and verify every required variable is present and non-empty.
+
 ```bash
 # Start all services
 docker compose up