tg-bot-ts/.claude/REFERENCE.md

TG Bot — Developer Reference

Cabal Online TG (Territory/Guild) planning Discord bot. TypeScript, discord.js v14, Node 22, ts-node/nodemon. Two Docker stacks: /opt/docker/tg-bot-ts-dev/ (dev), /opt/docker/tg-bot-ts/ (prod). JSON file persistence under data/.

This supersedes the old TG_BOT_REFERENCE.md and REFERENCE_OLD.md — both merged here, with fixed/stale items removed after a full read of the current codebase.

---

1. Core conventions

• Namespace pattern. Every system/UI module is export const Foo = { methodA, methodB } — PascalCase export, camelCase methods, kebab-case filenames (tg-key.ts, persistent-message.ts). Imports stay namespaced at the call site (Score.submit(...), format.char(...)) so origin is always clear.
• Named params everywhere — functions take { key: value } objects, not positional args (trivial single-arg cases like Emoji.get(key) excepted).
• Command files export a *Commands namespace (e.g. ScoreInjectCommands, SetLayoutCommands) — routers import the namespace, never raw handler functions directly.
• Discord.Interaction.options(interaction) (src/discord/interaction.ts) — typed option-reading wrapper, used by newer subcommands (score/set.ts, poll/call.ts, poll/confirm-no.ts, admin/*.ts). Older subcommands still call interaction.options.getString(...) directly with an as any cast (documented discord.js v14 typing gap on option getters) — both patterns coexist, migrate opportunistically rather than in bulk.
• TZ=Etc/GMT-2, set via .env and docker-compose.yml on both stacks — critical for week/day boundary logic (cron timezone must match).
• Auto-discovery pattern for UI layouts and scheduler jobs: drop a file in layouts/ or scheduler/, it self-registers via require() scan + duck-typing at module load. No manual registration list.
• Runtime.phase(name, fn, { priority, name }) (src/systems/runtime.ts) — lifecycle system. Phases run in order: load → restore → connect → schedule → ready. Modules self-register their own phase hooks at module load (e.g. src/ui/result/index.ts calls Runtime.phase("restore", restoreResultLayout, ...) itself) — dispatcher index.ts files stay pure, zero business logic.
• RuntimeEvents — pub/sub on top of Runtime, async, try/catch per handler so one bad listener doesn't kill others. Events declared: scoreSubmitted, pollLocked, pollConfirmed, weekReset, allScoresSubmitted (only scoreSubmitted and allScoresSubmitted are actually emitted anywhere today).
• Logger convention — every module: const log = Logger.for("module-name") from @systems/logger. Use log.debug for diagnostic tracing, not console.log (still used ad-hoc in several older files — not yet fully migrated).
• Git workflow: dev → master. See MERGE_CHECKLIST.md for the full merge/deploy procedure. Never edit prod files directly — always dev → commit → push → merge.

---

2. Path aliases (tsconfig.json)

@root/*  @src/*  @data/*  @tests/*  @messages/*  @tgHistory/*  @scripts/*
@helpers/*  @systems/*  @registry/*  @commands/*  @subcommands/*  @handlers/*
@utils  @types  @format  @emojis  @characters  @paths
@scheduler/*  @systems/scheduler
@discord  @discord/*
@ui  @ui/*  @ui/poll  @ui/types  @ui/layout  @ui/result  @ui/leaderboard

@format → src/systems/format.ts (pure functions, no business-logic imports beyond Emoji). @ui/layout → src/ui/layout.ts (business-aware formatting wrapper — imports Config/Bringer/Leaves, which format.ts deliberately does not). Scripts in scripts/ are included in tsconfig.json, so @systems/*-style aliases resolve there too, alongside relative ../src/... imports.

---

3. Architecture

Canonical score submission path

All score writes must go through Score.submit (src/systems/score.ts) — the single entry point that:

1. Writes to tg-history/<key>.json
2. Calls WRank.recordScore
3. Snapshots wRankAtSubmission ({ rank, delta }) from the live W.Rank entry before recording, onto the TGScore — so a historical Result reload always shows rank-as-it-was, not rank-as-it-is-now (explicit "data fidelity" design decision)
4. Emits RuntimeEvents("scoreSubmitted", { historyKey, character }) → triggers Leaderboard update + allScoresSubmitted → Result auto-post

Live callers of the canonical path: /tg score set (subcommands/score/set.ts), the score modal (handlers/modals.ts), and /tg-admin score-inject.

tg-history file shape — fixed 2026-07-31, was silently dropping every field but scores. Score.submit's local loadHistory/saveHistory used to round-trip only { scores: TGScore[] }, never reading/writing date/slot/confirmed/nationKD. The FIRST score ever submitted for a new TG key would create a file with nothing but scores on it — permanently, since nothing else ever wrote the rest back in. This diverged from the older systems/history.ts's upsertScore() (a parallel, largely-legacy code path — see /tg result view|set|post vs /tg-admin result post below), which always initializes the full TGResult shape and is what the current admin result path was silently assuming existed. Found 50 affected files in dev's data/tg-history/ alone (spanning weeks), almost certainly present in prod too. loadHistory now fills in any missing fields from TGKey.parse(historyKey) + sane defaults every time it reads a file, self-healing on the next score submitted for that key. scripts/migrate-history-shape.py <data_dir> does a one-time backfill for files that won't get touched again (safe, idempotent, gitignored data dir) — run this on prod too, same as migrate-stats-shape.py/fix-class-keys.py.

Two parallel result-posting systems exist and don't fully agree on file shape — /tg result view|set|post (subcommands/result/{view,set,post}.ts + systems/history.ts's loadResult/upsertScore/setNationKD) directly reads result.nationKD.capella.k etc. and would throw on a scores-only file. /tg-admin result post (subcommands/admin/result-post.ts + systems/result.ts's Result.post + PersistentMessage) is the newer canonical path — it never reads nationKD from the file at all, computing K/D by summing score.k/score.d directly, so it was unaffected by the missing-fields bug even before today's fix. Not consolidated; be aware which one you're touching.

Result.post() now returns { ok: boolean; reason?: string } instead of void — fixed 2026-07-31. It used to silently no-op (results channel unconfigured, or zero rows from buildRows — e.g. no attendance AND no scores for that historyKey) while /tg-admin result post's handler unconditionally replied "✅ Result posted" regardless of whether anything happened. All four callers (admin/result-post.ts, index.ts's allScoresSubmitted listener, scheduler/midnight-results.ts, scripts/backfill-results.ts) updated to check it; the admin command now surfaces the real reason to the moderator instead of a false positive.

src/systems/scores.ts is a parallel legacy module (submitScore, normalizeSlot, detectSlot) that does not emit RuntimeEvents — a write through it silently skips Leaderboard/Result updates. Its submitScore export is only imported by src/subcommands/score/submitCore.ts, which is itself unused dead code (no other file imports it) — safe to delete, but harmless as-is. normalizeSlot/detectSlot from the same file are still actively used by several live subcommands (score/set.ts, score/get.ts, result/*.ts) — only submitScore itself is the dead/bypassable part.

Character class serialization

Character.class is typed as CharacterClass (object) in memory but stored as plain ClassKey string on disk. Hydration/dehydration boundary lives in characters.ts: Char.hydrate(raw, ownerKey) expands on read, Char.dehydrate(char) collapses on write.

src/helpers/serialize.ts — safe accessors for use at write boundaries outside characters.ts: serializeClass(cls), hydrateClass(cls), serializeCharacter(char), hydrateCharacter(raw). serializeClass() is wired into Score.submit (score.ts) at the TGScore.class write. 2026-07-31: found a SECOND unsafe character.class.key access in the same function (Score.submit's call to WRank.recordScore(...), a few lines below the already-fixed one) — proof the sweep is genuinely incomplete, not just theoretically so; MERGE_CHECKLIST.md's "run fix-class-keys.py every merge" requirement is still real and should NOT be assumed retired. Other call sites doing typeof x.class === "object" ? x.class.key : x.class inline (format.ts, result.ts, poll.ts conflict/vote-entry paths, etc.) haven't been swept to use the shared helper yet — functionally safe (same defensive check), just not consolidated.

Downstream rendering must tolerate a missing/undefined class too — Emoji.class() and Emoji.nation() (src/systems/emojis.ts) used to call .toLowerCase() directly on the extracted key with no guard, crashing the whole interaction (Cannot read properties of undefined (reading 'toLowerCase')) whenever a TGScore.class was missing AND the character it referred to no longer existed in CharacterRegistry (deleted/renamed character with orphaned old history). Fixed 2026-07-31 — both now return "" for a falsy/missing class or nation instead of throwing, letting the Emoji.class(x) || x || "?" fallback pattern already used throughout the layout files degrade to a "?" placeholder instead of killing the command.

Poll persistence

src/systems/pollPersistence.ts — serializes Map/Set to JSON arrays, persists to data/poll-state.json. persist.save(polls) after every mutation; persist.load() on clientReady. /tg poll reload poll reloads from disk + re-renders.

Parse-error visibility: Store.read() (src/systems/store.ts) swallows JSON parse errors internally and returns null — persist.load()'s own try/catch never actually sees them (it only catches errors from deserialize()), so a malformed poll-state.json fails silently with no log line anywhere. Still an open gap.

Adding attendees to an already-locked poll (src/systems/pollAttendees.ts)

/tg poll inject explicitly refuses once a poll is locked (by design — pre-lock it's just recording a vote). Once locked, a player who showed up without voting had NO way back in: the Submit Score button gates on state.lockedYesKeys, snapshotted once at lock time and never touched again, so they'd hit "You weren't in this TG" forever. Added 2026-07-31.

addAttendeesToLockedPoll(slot, userKeys[]) does three things per player, ALL required — this is the part worth remembering if extending it:

1. state.lockedYesKeys — the actual gate the Submit Score button checks
2. state.yes (a synthetic injected:<userKey> VoteEntry) — so they show up in the rendered poll roster too, not just invisibly able to submit
3. Attendance.addPlayer({ historyKey, userKey }) — new Attendance method (append-only, doesn't touch other players) — otherwise Result.post() (which reads Attendance.players() first) would never find them even after they successfully submit

Two entry points share this one function, since Discord modals can only contain text inputs (no select menus — confirmed while designing this, ruled out a multi-select dropdown for that reason):

• /tg poll add-attendee name: (subcommands/poll/add-attendee.ts) — single player, autocomplete, no typo risk. Moderator-gated at the poll group level in tg.ts.
• /tg-admin poll add-attendees (subcommands/admin/poll-add-attendees.ts) — opens a modal with one Paragraph text input, comma/newline-separated (parseUserKeyList), for adding several latecomers at once. Modal submit routed in handlers/modals.ts via poll_add_attendees:<slot> customId.

Scheduler

src/systems/scheduler/<job>.ts — each file exports job: ScheduledJob, auto-imported into STATIC_JOBS in scheduler/index.ts (not fully drop-in — new files must still be added to the import list there). Current jobs: weekly-reset (0 0 * * 1), midnight-cleanup, midnight-snapshot, midnight-results. Slot open/lock/close/sleep-check crons are registered separately per active TGSlot from config, inside Scheduler.schedule() itself (not the auto-discovered STATIC_JOBS list) — any new per-slot-relative job needs another param threaded through Scheduler.schedule/reschedule and index.ts's callback set, same pattern as onPollOpen/onPollLock/onPollClose/onSleepCheck.

Sleep Check (src/systems/sleepCheck.ts)

Opt-in "are you awake?" nudge for players on Config.roles.sleepCheck (empty by default — nobody is checked until roles are added via /tg-config roles add-sleep-check).

• State and messaging are fully decoupled — this is a deliberate, explicit design constraint, not an accident. VoteEntry.sleepCheckPending (renders 💤 as the LAST indicator on that player's poll row, after bringer/borrowed/cockroach — see base-layout.ts's formatRow) can be set two ways — automatically the instant a checked player votes Yes (SleepCheck.flagIfChecked, called from handlers/buttons.ts), or manually by a moderator (/tg-admin sleep-check set) — but neither path ever sends a message. The DM confirm prompt is sent ONLY by the scheduled per-slot cron (onSleepCheck in index.ts, fires at tgHour - sleepCheckMinutesBefore, default 20 min, /tg-config tg set-sleep-check-minutes), which DMs everyone currently flagged for that poll (sweepPollForSleepCheck). There is intentionally no "send it now" path anywhere — an earlier version of this had an immediate-DM catch-up for late voters and an immediate-DM on moderator set; both were explicitly removed per user instruction (2026-07-30) specifically because a state change must never itself trigger a message. Do not reintroduce that coupling — if a future feature needs an immediate notification, it needs to be a clearly separate, explicitly-named action, not folded into flagging.
• Ignoring the DM leaves the flag (and emoji) in place — there's no auto-clear. It only clears via the "I'm awake!" button (sleep_confirm customId, routed in interactions.ts), or naturally resets on the next poll cycle (fresh VoteEntry objects).
• DM-with-channel-fallback pattern, same as borrow.ts's sendBorrowRequestDM — if the user's DMs are closed, falls back to tagging them in the poll channel with the same button.
• Manual override: /tg-admin sleep-check set|clear name: (subcommands/admin/sleep-check.ts) lets a moderator flag or clear a specific player regardless of the role list — state only, per above. Looks up their current Yes entry in the single active poll ([...polls.keys()][0], same "active poll" assumption most admin poll commands make).
• PollState.sleepCheckFiredAt is still set by the sweep (audit trail — "has tonight's sweep run for this poll") but nothing currently branches on it; the late-voter catch-up that used to consume it was removed along with the immediate-DM paths above.
• Known gap, explicitly deferred (2026-07-30): any code path that rebuilds a voter's VoteEntry wholesale after the initial vote (character switch, conflict/reclaim, admin/userMap.ts fix-voter) does NOT carry sleepCheckPending forward — switching character after being flagged silently clears the indicator without an actual confirmation. See Pending §7.

W.Rank reset

WRank.resetWeek() (src/systems/wrank.ts) — anchored to UTC noon to avoid the UTC+2 offset causing a wrong week key at local Monday 00:00. Reads from prevWeek without mutating it, writes only to newWeek, single WRank.save() at the end. Computes Bringer inline from prevWeek data (rank 1 AND tgCount >= goal) rather than calling Bringer.update.

Bringer.update({ week }) — separate mid-week path (called after score changes, currently not wired into any live call site — grep shows no callers). Requires currentRank === 1 AND tgCount >= goal.

TextAlign (src/ui/text-align.ts)

Approximate column alignment in Discord embeds (not monospace) using invisible filler characters.

• Character widths are real gg sans font metrics (advance width / units-per-em), extracted once via Python fontTools from the actual font file — not approximated.
• Filler character is Thin Space ( ), calibrated to FILLER_WIDTH = 0.203 via live Discord embed testing — it doesn't exist in gg sans itself, so this value can't be derived from the font and is empirical by necessity. Embeds and plain chat messages render fillers at different widths; this constant is embeds-only.
• Discord custom emoji tags <:name:id> are detected via regex and treated as one fixed-width unit (EMOJI_WIDTH = 1.0), not measured character-by-character — the ID string length has nothing to do with rendered width.
• Layout.formatRow's .trim() silently strips edge filler characters whenever padding lands at the very start/end of the templated string (e.g. an empty {indicators} token right after a padded {name}). Any string needing filler preserved at an edge must be built with plain template literals instead of Layout.formatRow.
• Known accepted limitation: guillemet-containing names («Deystroyer») show a small residual sub-filler alignment drift vs. equal-.length plain names in some layouts — below the precision floor of whole-number filler counts, and FILLER_WIDTH itself was calibrated using guillemet-containing references, so a "guillemet correction" double-counts. Don't re-attempt without fresh calibration from scratch.
• Multi-column technique: when a row has a primary line plus a secondary stats line, the shared column's target width must be max(primary texts, secondary texts) combined (see sequential/sequential-extra-stats layouts: scoreColumn = [...allScores, ...allAtks]) — otherwise a wide secondary value won't fit under a narrow primary one.
• Gap constants (SCORE_GAP, KD_GAP, etc.) are declared per-layout, not shared — Result's sequential.ts and Leaderboard's sequential-extra-stats.ts each tune their own values for their own row shape.
• /tg-admin test-align — permanent-or-not dev tool for live calibration testing (filler_type: hangul/thin/hair). Still present, marked [TEMP] in its command description.

EmbedHelpers (src/ui/embed-helpers.ts)

• chunkRows / addNationFields — splits rows into 1024-char field chunks. Emoji-dense rows (~280-300 chars each) can force a split at as few as 4-5 players, introducing a visible Discord field-gap mid-list. Considered semi-deprecated for heavy-content lists.
• addPerPlayerGrid / addPerPlayerColumn — one Discord field per player, immune to the 1024-char limit entirely (each field holds only one row). Trade-off: a visible inter-field gap between every player, always. This is the preferred default for new layouts — the sequential* layout family uses it.

PersistentMessage (src/systems/persistent-message.ts)

Two APIs: legacy/simple (post/get/set/delete/list, one message per store+key, used by Updates) and slotted (registerSlot/updateSlot/getSlotSnapshot, multiple independently-updatable embeds in one message). Slotted mode: updating one slot rebuilds only that embed and reuses other registered slots from their last-saved snapshot (frozen) — this is the deliberate default ("update only what you ask for"); a syncAll-style rebuild-everything mode was discussed and explicitly deferred as unneeded debt.

In use for: Leaderboard's main + highlights slots (two embeds, one message — Discord doesn't support side-by-side embeds, they always stack vertically, hence Highlights renders below Main).

Layouts

Poll, Result, and Leaderboard each support multiple named layouts, auto-discovered from their layouts/ directory and selected via Config (poll.layout / result.layout / leaderboard.layout). Each exports a PollLayout/ResultLayout/LeaderboardLayout object with buildEmbed + formatRow.

Current config defaults (data/config.json): poll.layout = "side-by-side", result.layout = "sequential", leaderboard.layout = "sequential-extra-stats".

TEMPLATE = "{wrank} {class} {name}{indicators} {score} {kd}"-style strings — Layout.formatRow does token replacement, collapses repeated ASCII spaces (/ +/, not \s), then trims. Filler chars (U+2009) survive the collapse since regex only targets literal ASCII space.

Bringer display: Layout.bringer(char, week) returns the bringer emoji or "". In name blocks it's appended as name + TextAlign.gap(1) + bringerTag, and that combined string is used for both width measurement and rendering, so alignment stays consistent. Storm Bringer → Procyon, Luminous Bringer → Capella — easy to get backwards, worth memorizing.

Leaderboard layout family (src/ui/leaderboard/layouts/): default (baseline, no alignment tech), side-by-side/side-by-side-stacked (inline grid, chunk-split risk), stacked-tg-top/bottom/score, stacked-with-rank, horizontal-combined (single mixed-nation list), horizontal-sequential / horizontal-sequential-stacked / horizontal-sequential-extra-stats (the TextAlign reference implementations — Capella then Procyon, full column alignment), side-by-side-sequential (2-column grid variant of sequential, 2 lines/player due to narrower columns).

Result layout family (src/ui/result/layouts/): default/inline (pre-TextAlign, no alignment), sequential (TextAlign-aligned, name padding intentionally omitted — small rosters, low variance, explicit call), sequential-arrow (↳ continuation line for stats instead of column-locked second line).

---

4. Data files

• data/characters.json — { [userKey]: { characters: SerializableCharacter[] } }
• data/usermap.json — Discord ID/username → { file, aliases }
• data/wrank.json — { [weekKey]: WRankWeek }, keyed "2026-W27"
• data/tg-history/<key>.json — { scores: TGScore[] }, keyed "2026-07-14-20" (see TGKey, src/systems/tg-key.ts)
• data/poll-state.json — serialized PollState[] (Map/Set as arrays)
• data/leaves.json — per-character "left TG" records, keyed by character name, cumulative all-time count + full history
• data/config.json — bot config (channels, roles, wrank goal, slots, layouts)
• data/.message-ids/{store}.json, data/snapshots/{store}/{key}/{slot}.json — PersistentMessage state (gitignored, need mkdir -p on fresh environments)
• messages/ — per-user and global vote message pools; messages/emojis.json legacy fallback if data/emojis/ is missing
• data/emojis/*.json — categorized emoji maps (classes, wrank, wrank-up/down [full 0-100 + _Q], wrank-gold, wrank-neutral, anima-mastery, circle, misc)

---

5. Channels

Configured keys in Config.channels: poll, results, score, updates, leaderboard, announcements. #score channel is configured but has no dedicated handler behavior yet — purpose still TBD. There is no mod-panel/user-panel channel key or any scaffolding for either (see Pending §7 — these are unbuilt, not just unfinished).

---

6. Versioning & changelog

Format: data/updates/vX.Y.Z/update.json, posted via /tg-admin updates post version:vX.Y.Z. Patch = bug fixes, Minor = new player-facing features, Major = architectural overhaul.

data/updates/versions.json currently lists v0.9.1 as latest, but a v0.9.2 directory already exists on disk — the index just hasn't been updated/posted yet.

---

7. Pending / known gaps

Verified against current code — items from the old docs that are already resolved have been removed (notably: CharacterRegistry ownerKey hydration is fixed; wrank up/down emoji sets are complete 0–100; Discord.Interaction options wrapper exists and is in active use for new code; moderator-role checks already take an arbitrary role list rather than being hardcoded).

Still open, real:

• Score bypass path — src/systems/scores.ts's submitScore() doesn't emit scoreSubmitted; its only caller (subcommands/score/submitCore.ts) is itself dead/unused code. Low risk today (nothing live calls it) but worth deleting to remove the trap.
• Class serialization sweep incomplete — serializeClass() (helpers/serialize.ts) is wired into Score.submit only; other inline typeof x.class === "object" ? ... : ... checks scattered across format.ts, result.ts, poll.ts etc. still work but aren't consolidated onto the shared helper.
• Poll JSON parse errors are silent — Store.read() swallows JSON.parse failures with no log; malformed poll-state.json (or any Store-read file) fails invisibly.
• User panel (#user-panel, not yet a config key) — persistent per-user ephemeral panel for character switching/adding/nation/sharing after voting Yes. Not started.
• Mod panel (#mod-panel, not yet a config key) — moderator roster + poll-injection UI wrapping existing poll inject logic. Not started.
• Command/autocomplete registry — subcommand routing is still manual group/sub string matching in tg.ts/tgAdmin.ts/tgConfig.ts + autocomplete.ts. Real bugs have recurred here twice (duplicate/shadowing checks, getSubcommandGroup() throwing on top-level commands — now consistently guarded with getSubcommandGroup(false)). Scheduler-style auto-discovery is the proposed fix, not built.
• Result auto-post only on allScoresSubmitted, not on every scoreSubmitted like Leaderboard.
• Cockroach (leave) indicator is all-time, not weekly — Leaves counts every historical leave for a character forever; the original design intent (visible for the TG's week, then fade, while the underlying count stays permanent) isn't implemented.
• WRankPosition type unused — declared in types.ts but WRankEntry/core rank data still uses flat currentRank/previousRank fields (only the UI-layer LeaderboardRow/ResultRow wrap them in a position object).
• Snapshot-based manual data correction — PersistentMessage slots store/reuse embed snapshots, but there's no "hand-edit JSON, then rebuild embed from the edited snapshot instead of live data" flow; Result/Leaderboard always rebuild from live data.
• Character-switch drops sleepCheckPending — VoteEntry rebuild sites that replace a voter's entry wholesale after they switch character (character.ts's performSwitch, conflict.ts's switch/reclaim handlers, admin/userMap.ts's fix-voter) don't carry sleepCheckPending forward. A player flagged for sleep-check who then switches character loses the 💤 indicator without actually confirming. Flagged by user 2026-07-30, explicitly deferred — should NOT clear the flag on switch, needs each rebuild site to spread the prior entry's sleepCheckPending through.
• Impersonation doesn't re-check moderator role — getImpersonation() only checks presence in the impersonation map, not whether the impersonating Discord user currently still holds the moderator role. If a moderator's role were revoked while they still had an active /tg impersonate session, they could still act/submit as the impersonated player until it's manually released. Flagged 2026-07-30, explicitly deferred — low priority, "harden later."
• Some /tg-admin commands had NO permission gate at all — found 2026-07-31 while adding result post-all: result post, leaderboard post, leaderboard post-highlights had neither an in-code moderator check nor setDefaultMemberPermissions on the command itself, meaning any guild member could invoke them. Fixed for these four (subcommands/admin/result-post.ts now has a shared requireModerator() guard). Not audited elsewhere — other /tg-admin subcommand files should be spot-checked for the same gap before assuming they're safe; several already had their own inline checks (score-inject.ts, userMap.ts, announcement.ts, updates.ts do not — same gap, unaudited/unfixed).
• Deferred to a future update, explicitly not built yet (per user, 2026-07-31): auto-vote for configured players. Idea: certain players (chronic latecomers who never vote but reliably show up) get automatically added to a poll's Yes list by default, without having to be manually added via /tg poll add-attendee(s) every time. Needs: a configured list of userKeys (probably Config.poll.autoVoteUserKeys: string[], mirroring the sleepCheck role-list pattern — though the user hasn't decided between a role-based or explicit-userKey-list approach), a visible indicator distinguishing "the system voted for them" from a real self-vote (some emoji, not yet chosen), and a decision on WHEN this fires (poll open? lock time?). Do not build without checking in — explicitly deferred, not just unprioritized.

Low priority / cosmetic:

• Secondary stats line indentation in sequential layouts — reported as slightly off in some cases, unverified without live Discord testing.
• Nation logo image for the leaderboard — deferred, needs a custom graphic (Discord embed fields can't render inline images).
• Score approximation for non-submitters (average of recent TGs) — idea only, not designed.
• Bringer.update() has no live caller — either wire it in for the described mid-week use case or remove it.

---

8. Commands reference (key ones)

/tg poll

• start — post poll for active slot
• lock [message] [simulate_close] — lock voting, snapshot lockedYesKeys; simulate_close:true also shows Submit Score button
• reload [target] — reload from disk + re-render (all/config/messages/emojis/characters/wrank/poll)
• inject <name> <yes|no> / remove-vote <name> — manual vote management, pre-lock only (refuses on a locked poll)
• add-attendee name: — the post-lock equivalent of inject: adds one late-arriving player (autocomplete) to an already-locked poll so they pass the Submit Score gate. See "Adding attendees" above for the multi-add modal variant.
• confirm <yes|no> [message] [tag] — confirm TG result, optionally tag roles
• mark-left <char_name> / unmark-left — cockroach indicator
• seed — inject all registered players as Yes (layout testing)
• purge — bulk-delete bot messages from poll channel

/tg call / /tg poll confirm-no

call (top-level, gated by Config.roles.callGame) — ends TG early, shows called-game image, Submit Score still works. confirm-no (moderator only) — marks TG cancelled, no Submit Score button.

/tg score

• set pts: [slot:] [k:] [d:] [atk:] [def:] [heal:] [name:] — canonical submission path. atk/def/heal are StringOptions accepting K/M shorthand (500K, 1.4M, case-insensitive, comma-as-decimal too — 3,4M == 3.4M) via the shared parseStatValue({raw, label}) helper (@helpers/stat-value) — same parser used by the Submit Score modal and /tg-admin score-inject. Returns { value?, error? }, not a bare number — callers check .error, not === undefined, since a value can now fail for two different reasons (bad format vs. above the sanity cap) and each needs its own message.
• Sanity ceiling (Config.tg.maxStatValue, default 50,000,000, /tg-config tg set-max-stat-value) — added 2026-07-31 after real corrupted data was found in prod (players typing e.g. 150.0M or 124000M, both intended as a single realistic value but parsed literally per the shorthand rules into a nonsense multi-billion number, silently accepted with no upstream check). Deliberately configurable rather than hardcoded — real observed ATK/DEF tops out around 10-13M today, but that ceiling is a game-balance fact that can shift, not a hard invariant of the code.
• get [name:] — view score

/tg char

add, remove, set-active, set-nation, share/unshare, borrow/accept/decline, active. set-stats currently disabled ("being redesigned", short-circuits to a placeholder reply).

/tg-admin

• score-inject — moderator manual score correction, emits scoreSubmitted same as normal flow. atk/def/heal accept the same K/M shorthand as /tg score set.
• score-modal name: [slot:] — moderator only, opens the Submit Score modal on behalf of any player (for testing, or backfilling a missed submission). The modal's customId carries the target userKey (score_submit:<slot>:<userKey>) so the submit handler (handlers/modals.ts) attributes it to the named player, not whoever's Discord client the moderator is using — checked again at submit time in case moderator status changes between opening and submitting.
• result post / leaderboard post / leaderboard post-highlights — manual (re)post with autocomplete
• result post-all [slot:] — posts/updates EVERY TG result for a slot (default 20), not just one. Collects candidate historyKeys from the union of Attendance.all() and tg-history/*.json filenames (so backfilled/copied history with no attendance record still gets picked up), then calls Result.post() per key with a 1.2s delay between posts to avoid rate limits, editing the deferred reply every 5 keys as a progress indicator. "Update" isn't special-cased — Result.post() → PersistentMessage.post() already edits in place if that key was posted before.
• poll add-attendees — modal-based multi-add for a locked poll, see "Adding attendees" above
• test-align — [TEMP] TextAlign calibration tool
• reset-week — manually trigger TG.resetWeek() (testing only)
• updates post|preview|list / announcement post|preview|list — changelog and announcement management
• user map|unmap|list — Discord ID ↔ userKey registration
• poll fix-voter|show-entry — repair/inspect a live poll entry
• sleep-check set|clear name: — manually flag/clear a player's sleep check regardless of role, set sends the DM immediately

/tg-config

Moderator/config-role gated. message *, roles * (moderator/config/tag/sleep-check — set/add/remove/reset-<role>), channel set-*, slot add|remove, wrank set-goal|set-post-on-reset, tg set-* (including set-sleep-check-minutes), poll set-layout, set-result-layout, set-leaderboard-layout. Role/slot-timing config changes take effect on the next Scheduler.schedule() call — currently only run at startup, so cron-timing changes (set-duration, set-sleep-check-minutes, slot add/remove) need a bot restart to actually apply, same pre-existing limitation as everything else scheduler-timing-related.