From 95fc8a457817b435578d758a3fd8427c4987e08d Mon Sep 17 00:00:00 2001
From: h <h@kotikot.com>
Date: Thu, 27 Aug 2026 23:45:51 +0200
Subject: [PATCH] docs(env): documented .env.example, token-based claude auth
 in README

Every variable the compose file, the gateway and config.py read, grouped
and explained, including the ones the Jarvis rework will need
(CLAUDE_CODE_OAUTH_TOKEN, TELEGRAM_*, T3_*, KOMODO_*).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .env.example | 80 ++++++++++++++++++++++++++++++++++++++++------------
 README.md    | 12 ++++----
 2 files changed, 67 insertions(+), 25 deletions(-)

diff --git a/.env.example b/.env.example
index d8b8373..9b8aa50 100644
--- a/.env.example
+++ b/.env.example
@@ -1,40 +1,84 @@
-# Which services to run. Everything is behind a profile: db, gateway, obsidian.
+# beaver-agent - единственный .env стека.
+# Его читают: docker compose (профили, порты, postgres), gateway (env_file)
+# и config.py (os.environ). Секреты живут только здесь, в git - этот example.
+# Сгенерировать секрет: openssl rand -hex 32
+
+### Compose ###################################################################
+
+# Какие сервисы поднимать: db (postgres), gateway, obsidian (obsidian-headless)
 COMPOSE_PROFILES=db,gateway,obsidian
 
+# Ветка/тег beaver-gateway, из которого собирается образ шлюза
 GATEWAY_REF=main
 
-# Uncomment when developing against a sibling ../beaver-gateway checkout.
-# Pure code edits then need only `docker compose restart gateway`
+# Dev на маке: gateway собирается из соседнего ../beaver-gateway
 #COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
 
+### Postgres ##################################################################
+
 POSTGRES_USER=beaver
-POSTGRES_PASSWORD=CHANGE-ME-strong-random-password
+POSTGRES_PASSWORD=
 POSTGRES_DB=beaver
+# Порт наружу только через docker-compose.override.yml (пример рядом)
+#PORT_POSTGRES=5432
 
-# Admin UI login. Used only to mint/revoke tokens.
+### Gateway: admin и сессии ###################################################
+
+# Логин в admin UI; токены для клиентов выпускаются там
 ADMIN_USER=admin
-ADMIN_PASS=CHANGE-ME-admin-password
+ADMIN_PASS=
+# Подпись session-cookie admin UI
+SESSION_SECRET=
 
-# openssl rand -hex 32
-SESSION_SECRET=CHANGE-ME-random-hex
+### Claude ####################################################################
 
-# Sniffed from the Raycast desktop app
-RAYCAST_DEVICE_ID=CHANGE-ME-32-byte-hex
-RAYCAST_BEARER=rca_CHANGE-ME
+# OAuth-токен подписки для Claude Agent SDK внутри контейнера.
+# На маке: `claude setup-token` (живёт год). Тратит лимиты подписки как
+# обычный Claude Code. Отзыв = перевыпуск; утёк - перевыпусти сразу.
+CLAUDE_CODE_OAUTH_TOKEN=
 
-FIREFLY_BASE_URL=https://firefly.example.com
-FIREFLY_PAT=changeme
+### Telegram (frontend, с S5) #################################################
 
-# example: CALENDAR_MCPS=work=https://calendar-mcp.com/mcp/AAAA,home=https://calendar-mcp.com/mcp/BBBB
+# @BotFather → токен; там же Bot Settings → Topics → включить в личных чатах
+TELEGRAM_BOT_TOKEN=
+# Твой numeric id (@userinfobot). Единственный, кому бот отвечает
+TELEGRAM_USER_ID=
+
+### Raycast ###################################################################
+
+# 64 hex, один раз: python3 -c 'import secrets;print(secrets.token_hex(32))'
+RAYCAST_DEVICE_ID=
+# rca_... из десктоп-приложения Raycast (см. raycast-api)
+RAYCAST_BEARER=
+
+### MCP, к которым ходят агенты ###############################################
+
+# Firefly III: адрес и Personal Access Token
+FIREFLY_BASE_URL=
+FIREFLY_PAT=
+# Календари: name=url,name=url (пусто - без календарей)
 CALENDAR_MCPS=
-
+# MCP beavergram (telegram-history)
 BEAVERGRAM_MCP=
 
+### t3code (руки диспетчера, с S10) ###########################################
+
+# `t3 serve --tailscale-serve --host <tailnet-ip>` на маке → адрес
+T3_URL=
+# `t3 auth session issue --token-only`
+T3_TOKEN=
+
+### Komodo (python_tool с перечисленными действиями, с S8) ####################
+
+KOMODO_URL=
+KOMODO_KEY=
+KOMODO_SECRET=
+
+### Порты хоста и внешний адрес ###############################################
+
 PORT_MESSAGES=62990
 PORT_MCP=62991
 PORT_ADMIN=62992
 PORT_MARKDOWN=62993
-
-# Public URL where the reverse proxy in front (see ./caddy) terminates.
-# Leave empty for raw-port localhost / dev setups.
+# Публичный URL за reverse proxy (см. ./caddy). Пусто для localhost/dev
 PUBLIC_BASE_URL=
diff --git a/README.md b/README.md
index 6a94f13..0a2650b 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ Uses Claude Code and Raycast subscriptions for agents, has some MCPs set up. You
 
 ```bash
 cp .env.example .env
-# fill CHANGE-ME
+# every empty value is documented inline; secrets: openssl rand -hex 32
 nvim .env
 
 # build raycast config on your mac (beta by default, consider checking raycast-api for instructions)
@@ -53,12 +53,10 @@ docker restart beaver-obsidian
 
 ### 3. Set up claude
 
-```bash
-docker exec -it beaver-gateway claude /login
-docker exec -it beaver-gateway bash -c 'cd /vault && claude --dangerously-skip-permissions --model claude-opus-4-7'
-```
-
-Click through every dialog, then `/exit` or Ctrl+C.
+On your mac run `claude setup-token` and put the result into `.env` as
+`CLAUDE_CODE_OAUTH_TOKEN`. That is the whole auth: no `/login` inside the
+container, no dialogs. The token draws from your subscription limits like
+regular Claude Code; rotate it by running `claude setup-token` again.
 
 ### 4. Mint a token