docs(docker): use external ./.odek folder for Telegram state, drop named volume

Replace the odek-tg-state named volume with a local ./.odek bind mount (an
external host folder like ./workspace) for both Telegram services. Add
docker/.odek/ with a .gitkeep, gitignore its contents, and sync the guide,
README, and Dockerfile comment to the folder-based model (layout, gitignore
note, compose snippet, mount explanation, and singleton-lock gotcha).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jkyberneees

.gitignore

@@ -8,7 +8,9 @@ odek-bin
 notify-channel-proposal.md
 internal/mcpclient/testdata/fakeserver
 
-# Docker Compose examples — local secrets and agent scratch dir
+# Docker Compose examples — local secrets and agent scratch dirs
 docker/.env
 docker/workspace/*
 !docker/workspace/.gitkeep
+docker/.odek/*
+!docker/.odek/.gitkeep

DOCKER_COMPOSE_USER_GUIDE.md

@@ -40,11 +40,12 @@ odek/
 ├── .env                       # your API key + model settings (gitignored)
 ├── config.restricted.json     # Restricted permission policy
 ├── config.godmode.json        # Godmode (YOLO) permission policy
-└── workspace/                 # the directory the agent works in (mounted into the container)
+├── workspace/                 # the directory the agent works in (mounted into the container)
+└── .odek/                     # Telegram bot state: sessions, skills, lock (mounted in)
 ```
 
-> Add `.env` and `workspace/` to your `.gitignore` so you never commit secrets or
-> scratch files.
+> Add `.env`, `workspace/`, and `.odek/` to your `.gitignore` so you never commit secrets
+> or scratch files.
 
 ---
 
@@ -75,8 +76,8 @@ FROM alpine:latest
 RUN apk add --no-cache ca-certificates git bash coreutils curl jq
 
 # Run as a non-root user — defense in depth even inside the container.
-# Pre-create ~/.odek owned by the user so a mounted named volume (used for
-# Telegram session state in §13) inherits uid 1000 ownership and is writable.
+# Pre-create ~/.odek owned by the user so it's writable for config, sessions,
+# and the Telegram lock (whether backed by an image dir or a mounted folder).
 RUN adduser -D -u 1000 odek \
  && mkdir -p /home/odek/.odek /workspace \
  && chown -R odek:odek /home/odek/.odek /workspace
@@ -452,9 +453,9 @@ ODEK_TELEGRAM_SESSION_TTL_HOURS=24          # optional
 
 ### 13c. Compose services
 
-Add these to `docker-compose.yml`. Note the **named volume for `/home/odek/.odek`**: it
-persists per‑chat sessions, the daily‑budget counter, and the singleton lock across
-restarts. No `ports` are needed.
+Add these to `docker-compose.yml`. State (per‑chat sessions, the daily‑budget counter, and
+the singleton lock) lives in a local **`./.odek` folder** — an external host folder, just
+like `./workspace` — so it survives restarts and is easy to inspect. No `ports` are needed.
 
 ```yaml
   # ── Telegram bot — Restricted (approvals via inline keyboards) ──
@@ -466,8 +467,8 @@ restarts. No `ports` are needed.
     command: ["telegram"]
     volumes:
       - ./workspace:/workspace
+      - ./.odek:/home/odek/.odek
       - ./config.restricted.json:/home/odek/.odek/config.json:ro
-      - odek-tg-state:/home/odek/.odek
     restart: unless-stopped
 
   # ── Telegram bot — Godmode (no prompts; disposable container) ──
@@ -479,19 +480,22 @@ restarts. No `ports` are needed.
     command: ["telegram"]
     volumes:
       - ./workspace:/workspace
+      - ./.odek:/home/odek/.odek
       - ./config.godmode.json:/home/odek/.odek/config.json:ro
-      - odek-tg-state:/home/odek/.odek
     restart: unless-stopped
+```
+
+Create the folder first (so the container's non‑root user can write to it) and gitignore
+its contents:
 
-volumes:
-  odek-tg-state:
+```bash
+mkdir -p .odek && chmod 777 .odek && touch .odek/.gitkeep
 ```
 
-> The `:ro` config mount and the writable `odek-tg-state` volume both target
-> `/home/odek/.odek`. Compose layers them: the bind mount wins for `config.json`, the
-> named volume holds everything else (sessions, lock, budget). If your Compose version
-> errors on overlapping mounts, drop the `:ro` bind and instead bake the policy into the
-> image, or copy it into the volume once at startup.
+> The `./.odek` bind mounts at `/home/odek/.odek`, and `config.json` is bind‑mounted on top
+> of it — a nested file‑over‑directory mount. Compose layers them: the `:ro` `config.json`
+> wins for that one file, and `./.odek` holds everything else (sessions, lock, budget).
+> Docker leaves a harmless empty `./.odek/config.json` stub on the host as the mount point.
 
 ### 13d. Run it
 
@@ -522,16 +526,16 @@ Stop either with `docker compose --profile telegram-restricted down` (matching p
 | `/help` | List all commands |
 | `/new` | Archive the current session, start fresh |
 
-Voice and photo messages are supported too. Sessions persist per chat (visible via
-`odek session list` against the mounted state volume).
+Voice and photo messages are supported too. Sessions persist per chat in the local
+`./.odek` folder (inspect with `odek session list` against that directory).
 
 ### 13f. Telegram‑specific gotchas
 
 - **One poller per token.** Telegram allows a single long‑poller per bot token; a second
   one gets `409 Conflict`. So you **cannot run the Restricted and Godmode bot services at
   the same time with the same token** — pick one, or create a second bot via @BotFather
-  for the other. A singleton PID lock at `~/.odek/telegram.pid` (kept in the shared state
-  volume) backs this up — a second `odek telegram` that finds a live lock won't start.
+  for the other. A singleton PID lock at `~/.odek/telegram.pid` (kept in the shared `./.odek`
+  folder) backs this up — a second `odek telegram` that finds a live lock won't start.
 - **Optional health endpoint.** The `telegram` command takes no CLI flags — configure it
   via env. Set `ODEK_TELEGRAM_HEALTH_ADDR=0.0.0.0:9090` in `.env` (and add a `ports:`
   mapping) to expose `GET /health` for an orchestrator's liveness probe.

docker/.odek/.gitkeep

@@ -63,8 +63,8 @@ RUN apk add --no-cache ca-certificates git bash coreutils curl jq
 # (the mkdir/chown, ENV HOME, USER, and WORKDIR lines all work unchanged).
 
 # Run as a non-root user — defense in depth even inside the container.
-# Pre-create ~/.odek owned by the user so a mounted named volume (used for
-# Telegram session state) inherits uid 1000 ownership and is writable.
+# Pre-create ~/.odek owned by the user so it's writable for config, sessions,
+# and the Telegram lock (whether backed by an image dir or a mounted folder).
 RUN adduser -D -u 1000 odek \
  && mkdir -p /home/odek/.odek /workspace \
  && chown -R odek:odek /home/odek/.odek /workspace

docker/Dockerfile

@@ -92,7 +92,8 @@ docker compose --profile telegram-restricted up --build -d   # approvals in chat
 docker compose --profile telegram-godmode up --build -d      # no prompts
 ```
 
-Message your bot `/start`. Sessions persist in the `odek-tg-state` volume.
+Message your bot `/start`. State (sessions, skills, `telegram.pid`) persists in the
+local `./.odek` folder — an external host folder, just like `./workspace`.
 
 > **Only run one Telegram profile at a time per token** — Telegram allows a single
 > long-poller per bot (a second gets `409 Conflict`). Create a second bot via

docker/README.md

@@ -51,6 +51,9 @@ services:
     restart: "no"
 
   # ── Telegram bot — Restricted (approvals via inline keyboards) ──
+  # State (sessions, skills, telegram.pid) lives in the local ./.odek folder —
+  # an external folder on the host, just like ./workspace. config.restricted.json
+  # is layered on top of ./.odek/config.json to set the approval policy.
   odek-telegram-restricted:
     profiles: ["telegram-restricted"]
     build:
@@ -61,11 +64,13 @@ services:
     command: ["telegram"]
     volumes:
       - ./workspace:/workspace
+      - ./.odek:/home/odek/.odek
       - ./config.restricted.json:/home/odek/.odek/config.json:ro
-      - odek-tg-state:/home/odek/.odek
     restart: unless-stopped
 
-  # ── Telegram bot — Godmode (no prompts; disposable container) ──
+  # ── Telegram bot — Godmode (no prompts; unrestricted) ──
+  # Same ./.odek state folder; config.godmode.json is layered on top of
+  # ./.odek/config.json to force the unrestricted (action: allow) policy.
   odek-telegram-godmode:
     profiles: ["telegram-godmode"]
     build:
@@ -76,9 +81,6 @@ services:
     command: ["telegram"]
     volumes:
       - ./workspace:/workspace
+      - ./.odek:/home/odek/.odek
       - ./config.godmode.json:/home/odek/.odek/config.json:ro
-      - odek-tg-state:/home/odek/.odek
     restart: unless-stopped
-
-volumes:
-  odek-tg-state: