feat(codex): complete the Codex sign-in from chat with /login

adapters/telegram/.env.example

@@ -20,6 +20,16 @@ AI_BACKEND=claude             # claude | codex | openai-compatible
 # CODEX_HOME/auth.json (persisted in the codex_home volume) or CODEX_ACCESS_TOKEN.
 # Keep CODEX_API_KEY empty in subscription mode: startup fails if it is set, so a
 # subscription deploy cannot accidentally switch to usage-based API billing.
+#
+# First sign-in needs no shell on the host: the bot starts unauthorized and an
+# allow-listed user sends /login IN A DIRECT MESSAGE (the reply carries a one-time
+# code, so starting a sign-in is refused in group chats). Runs are blocked until
+# it completes. CODEX_REQUIRE_AUTH=false only removes the block — without
+# auth.json or CODEX_ACCESS_TOKEN runs then fail inside the Codex CLI instead.
+# CODEX_HOME must stay non-empty: with an empty value startup still fails, since
+# there would be nowhere to persist the login.
+# Full flow, and who ends up owning the Codex account:
+# docs/codex-integration-plan.md#subscription-setup
 CODEX_AUTH_MODE=subscription  # subscription | billing
 CODEX_BIN=codex
 CODEX_HOME=/home/claude/.codex

adapters/telegram/commands.go

@@ -4,6 +4,8 @@ import (
 	"strings"
 
 	"github.com/go-telegram/bot/models"
+
+	"github.com/duckbugio/flock/core/chat"
 )
 
 // CommandName returns the slash command addressed at the start of msg,
@@ -82,22 +84,14 @@ func StripCommandMention(text, botUsername string) string {
 	return token[:at] + rest
 }
 
-// HelpText is the static usage message replied to an allowed user who sends
-// /help. It lists the slash commands the adapter understands. It is an
-// engineering artifact (professional English, no duck flavor) and never reaches
-// the Claude Runner.
-const HelpText = "Flock Telegram assistant — available commands:\n\n" +
-	"/help — show this message\n" +
-	"/new — start a fresh session (forget the current conversation)\n" +
-	"/stop — stop the run currently in progress\n" +
-	"/schedule — manage scheduled jobs (when enabled)\n" +
-	"/goal <criterion> — arm a goal an independent evaluator re-checks after every run " +
-	"(/goal off to disarm)\n\n" +
-	"Send any other message to run it through the assistant."
+// helpTitle names the transport; everything below it is shared with the VK
+// adapter (chat.HelpBody), so the two cannot drift apart.
+const helpTitle = "Flock Telegram assistant — available commands:\n\n"
+
+// HelpText renders the usage message replied to an allowed user who sends /help.
+// It is a thin alias over the shared render, so this adapter owns only its title.
+func HelpText(login chat.LoginVisibility) string { return chat.HelpText(helpTitle, login) }
 
-// WelcomeText is the static usage message replied to an allowed user who sends
-// /start. It is a short greeting prepended to the command help so a brand-new
-// user immediately sees what the bot does and how to use it. Like HelpText it is
-// an engineering artifact (plain English, no duck flavor) and never reaches the
-// Claude Runner — the duck greeting comes from the model on a real message.
-const WelcomeText = "Hi! I'm the Flock assistant.\n\n" + HelpText
+// WelcomeText is the reply to /start: the shared greeting prepended to the help,
+// so a brand-new user immediately sees what the bot does and how to use it.
+func WelcomeText(login chat.LoginVisibility) string { return chat.WelcomeText(helpTitle, login) }

adapters/telegram/commands_test.go

@@ -6,6 +6,8 @@ import (
 	"testing"
 
 	"github.com/go-telegram/bot/models"
+
+	"github.com/duckbugio/flock/core/chat"
 )
 
 // botCmd builds a message whose leading token is a bot_command entity, the shape
@@ -96,12 +98,19 @@ func TestStripCommandMention(t *testing.T) {
 // it can never submit a run); the constant IS the entire payload the handler
 // sends.
 func TestHelpTextListsCommands(t *testing.T) {
-	if HelpText == "" {
-		t.Fatal("HelpText is empty")
-	}
-	for _, cmd := range []string{"/help", "/new", "/stop"} {
-		if !strings.Contains(HelpText, cmd) {
-			t.Fatalf("HelpText does not mention %q:\n%s", cmd, HelpText)
+	// Both renders: production picks between them with LoginVisibilityFor, and the
+	// WITHOUT-login one is what every Claude, Codex-billing and access-token
+	// deployment gets — so testing only the other would leave the common case
+	// uncovered.
+	for _, visibility := range []chat.LoginVisibility{chat.WithLogin, chat.WithoutLogin} {
+		got := HelpText(visibility)
+		if got == "" {
+			t.Fatalf("HelpText(%v) is empty", visibility)
+		}
+		for _, cmd := range []string{"/help", "/new", "/stop"} {
+			if !strings.Contains(got, cmd) {
+				t.Fatalf("HelpText(%v) does not mention %q:\n%s", visibility, cmd, got)
+			}
 		}
 	}
 }

adapters/telegram/deploy/roles/claude_tg_bot/templates/env.j2

@@ -29,6 +29,15 @@ CLAUDE_MAX_COST_PER_REQUEST={{ claude_max_cost_per_request }}
 
 # === CODEX AUTH ===
 # subscription: use persisted {{ codex_home }}/auth.json or CODEX_ACCESS_TOKEN.
+#   With neither, the bot starts unauthorized and an allow-listed user completes
+#   the one-time sign-in from the chat with /login IN A DIRECT MESSAGE. Runs are
+#   blocked until it lands. CODEX_REQUIRE_AUTH=false only removes the block —
+#   without auth.json or CODEX_ACCESS_TOKEN runs then fail inside the Codex CLI
+#   instead.
+#   CODEX_HOME must stay non-empty: with an empty value startup still fails,
+#   since there would be nowhere to persist the login.
+#   Full flow, and who ends up owning the Codex account:
+#   docs/codex-integration-plan.md#subscription-setup
 # billing: requires CODEX_API_KEY and CODEX_BILLING_ACK=true.
 CODEX_BIN={{ codex_bin }}
 CODEX_MODEL={{ codex_model }}

adapters/vk/commands.go

@@ -1,17 +1,19 @@
 package vk
 
-// HelpText is the static usage message for the VK adapter. It mirrors the
-// Telegram adapter's HelpText and lists VK's command surface: VK has no native
-// slash-command UI, so these are plain text commands the receiver intercepts. It
-// is an engineering artifact (professional English, no duck flavor).
-const HelpText = "Flock VK assistant — available commands:\n\n" +
-	"/help — show this message\n" +
-	"/new — start a fresh session (forget the current conversation)\n" +
-	"/stop — stop the run currently in progress\n" +
-	"/schedule — manage scheduled jobs (when enabled)\n" +
-	"/goal <criterion> — arm a goal an independent evaluator re-checks after every run " +
-	"(/goal off to disarm)\n\n" +
-	"Send any other message to run it through the assistant."
+import "github.com/duckbugio/flock/core/chat"
+
+// helpTitle names the transport; everything below it is shared with the Telegram
+// adapter (chat.HelpBody), so the two cannot drift apart. VK has no native
+// slash-command UI, so these are plain text commands the receiver intercepts.
+const helpTitle = "Flock VK assistant — available commands:\n\n"
+
+// helpText renders the usage message. It is a thin alias over the shared render,
+// so this adapter owns only its title. Unexported like welcomeText beside it:
+// nothing outside this package renders VK's help.
+func helpText(login chat.LoginVisibility) string { return chat.HelpText(helpTitle, login) }
+
+// welcomeText is the reply to /start, mirroring the Telegram adapter.
+func welcomeText(login chat.LoginVisibility) string { return chat.WelcomeText(helpTitle, login) }
 
 // goalUsageText is the /goal usage reply, mirroring the Telegram adapter.
 const goalUsageText = "Usage:\n" +