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

@@ -1,37 +1,84 @@
+# 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=

.gitignore

@@ -3,3 +3,4 @@ config.json
 .venv/
 __pycache__/
 .idea
+docker-compose.override.yml

Makefile

@@ -0,0 +1,33 @@
+.PHONY: up recreate down restart rebuild gateway logs shell deploy
+
+up:
+	docker compose up -d
+
+recreate:
+	docker compose up -d --force-recreate
+
+down:
+	docker compose down
+
+restart:
+	$(MAKE) recreate
+
+rebuild:
+	docker compose build
+	docker compose up -d
+
+gateway:
+	docker compose build gateway
+	docker compose up -d gateway
+
+logs:
+	docker compose logs -f $(filter-out $@,$(MAKECMDGOALS))
+
+shell:
+	docker exec -it beaver-gateway bash
+
+deploy:
+	git push origin main:stable
+
+%:
+	@:

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
 

docker-compose.override.yml.example

@@ -0,0 +1,5 @@
+# Local overrides, not committed. Copy to docker-compose.override.yml.
+services:
+  postgres:
+    ports:
+      - "127.0.0.1:5432:5432"

docker-compose.yml

@@ -4,6 +4,7 @@ x-restart: &restart
 services:
   postgres:
     image: postgres:16-alpine
+    profiles: [db]
     <<: *restart
     env_file: .env
     volumes:
@@ -21,6 +22,7 @@ services:
     build:
       context: .
       dockerfile: obsidian.Dockerfile
+    profiles: [obsidian]
     <<: *restart
     volumes:
       - vault:/vault
@@ -31,6 +33,7 @@ services:
     container_name: beaver-gateway
     build:
       context: https://git.kotikot.com/beaver/beaver-gateway.git#${GATEWAY_REF:-main}
+    profiles: [gateway]
     <<: *restart
     depends_on:
       postgres: