@rm0nroe/coach-claw 1.0.6

package/coach/bin/switch_to_plugin.py

@@ -0,0 +1,256 @@
+"""Switch Coach control from the npm CLI to the Claude Code plugin.
+
+Removes CLI-installed hook entries from ~/.claude/settings.json so the
+plugin's hooks take over. Also clears a CLI-installed statusLine entry
+if present (the plugin will reinstall its own on the next session via
+statusline_self_patch).
+
+Use case: a user has both distributions installed and the plugin's
+coexistence_check is currently deferring to the CLI (.plugin-deferred
+marker present). They want to flip control. Running
+/coach-claw:switch is the supported way to do that without manually
+editing settings.json.
+
+The npm CLI's installed Python files (~/.claude/hooks/coach-*.py) are
+NOT touched by this script — they remain on disk but are no longer
+referenced from settings.json. Run `npx @rm0nroe/coach-claw uninstall`
+separately for full CLI cleanup.
+
+Atomic write under flock so concurrent /plugin install or other
+settings mutations don't race.
+"""
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+import os
+import shlex
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from coach_paths import resolve_coach_dir  # noqa: E402
+
+SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
+
+HOOK_SCRIPT_NAMES = ("coach-session-start.py", "coach-user-prompt.py")
+COACH_STATUSLINE_MARKERS = (
+    "default-statusline-command.sh",
+    "default_statusline.py",
+)
+# Substring fragments identifying the wrap-shape statusLine entries.
+CLI_WRAP_TRAMPOLINE = "default-statusline-wrap-command.sh"
+PLUGIN_WRAP_SCRIPT = "statusline_wrap.py"
+
+
+def _is_cli_hook(cmd: str, plugin_root: str) -> bool:
+    if not any(name in cmd for name in HOOK_SCRIPT_NAMES):
+        return False
+    if plugin_root and plugin_root in cmd:
+        return False
+    return True
+
+
+def _is_cli_statusline(cmd: str, plugin_root: str) -> bool:
+    """CLI's statusLine uses default-statusline-command.sh; plugin's
+    uses default_statusline.py via bootstrap.sh. Removing the CLI's
+    leaves the plugin's self-patch to reinstall on next SessionStart."""
+    if "default-statusline-command.sh" not in cmd:
+        return False
+    if plugin_root and plugin_root in cmd:
+        return False
+    return True
+
+
+def _strip_cli_hooks(data: dict, plugin_root: str) -> int:
+    """Remove CLI-pattern hook entries in-place. Returns count removed."""
+    removed = 0
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return 0
+    for event in ("SessionStart", "UserPromptSubmit"):
+        groups = hooks.get(event)
+        if not isinstance(groups, list):
+            continue
+        new_groups = []
+        for grp in groups:
+            if not isinstance(grp, dict):
+                new_groups.append(grp)
+                continue
+            inner = grp.get("hooks")
+            if not isinstance(inner, list):
+                new_groups.append(grp)
+                continue
+            new_inner = []
+            for h in inner:
+                if isinstance(h, dict) and _is_cli_hook(str(h.get("command", "")), plugin_root):
+                    removed += 1
+                    continue
+                new_inner.append(h)
+            if new_inner:
+                new_groups.append({**grp, "hooks": new_inner})
+            elif grp.get("hooks"):
+                # Group emptied by removals — drop it entirely.
+                pass
+            else:
+                new_groups.append(grp)
+        if new_groups:
+            hooks[event] = new_groups
+        else:
+            del hooks[event]
+    return removed
+
+
+def _strip_cli_statusline(data: dict, plugin_root: str) -> bool:
+    """Remove the CLI's default statusLine entry if present. Returns True
+    if removed, False if nothing to do or it was someone else's."""
+    sl = data.get("statusLine")
+    if not isinstance(sl, dict):
+        return False
+    if _is_cli_statusline(str(sl.get("command", "")), plugin_root):
+        del data["statusLine"]
+        return True
+    return False
+
+
+def _rewrite_cli_wrap_to_plugin(data: dict, plugin_root: str) -> bool:
+    """If the statusLine is the CLI wrap-shape trampoline AND we have a
+    plugin_root to rewrite to, replace it with the plugin wrap shape.
+    Preserves `.statusline-wrap.json` (operate on settings.json only).
+
+    Returns True when rewritten, False when nothing to do (no statusLine,
+    not a wrap shape, or already plugin shape).
+    """
+    if not plugin_root:
+        return False
+    sl = data.get("statusLine")
+    if not isinstance(sl, dict):
+        return False
+    cmd = str(sl.get("command", ""))
+    # Skip if not the CLI wrap trampoline.
+    if CLI_WRAP_TRAMPOLINE not in cmd:
+        return False
+    # Already pointing at the plugin's bin/ — leave alone.
+    if PLUGIN_WRAP_SCRIPT in cmd and plugin_root in cmd:
+        return False
+    pr = Path(plugin_root)
+    bootstrap = shlex.quote(str(pr / "bin" / "bootstrap.sh"))
+    wrap_py = shlex.quote(str(pr / "bin" / "statusline_wrap.py"))
+    new_cmd = f"{bootstrap} {wrap_py}"
+    data["statusLine"] = {"type": "command", "command": new_cmd}
+    return True
+
+
+def _atomic_write(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = path.with_suffix(path.suffix + ".lock")
+    with open(lock_path, "w") as lock_fh:
+        try:
+            fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
+        except Exception:
+            pass
+        fd, tmp = tempfile.mkstemp(
+            prefix="." + path.name + ".",
+            suffix=".tmp",
+            dir=str(path.parent),
+        )
+        try:
+            with os.fdopen(fd, "w") as fh:
+                json.dump(payload, fh, indent=2)
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp, path)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except Exception:
+                pass
+            raise
+
+
+def _write_marker(coach_dir: Path) -> None:
+    """Persist a marker so `/coach-claw:doctor` and the deferred-state
+    UI know the user explicitly switched."""
+    try:
+        coach_dir.mkdir(parents=True, exist_ok=True)
+        marker = coach_dir / ".cli-uninstalled-by-plugin"
+        marker.write_text(json.dumps({
+            "switched_at": datetime.now(timezone.utc).isoformat(),
+        }))
+        # Clear any stale defer marker since CLI is gone now.
+        defer = coach_dir / ".plugin-deferred"
+        if defer.exists():
+            defer.unlink()
+    except Exception:
+        pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Switch Coach control to the plugin.")
+    parser.add_argument(
+        "--settings",
+        default=str(SETTINGS_PATH),
+        help="Path to settings.json (default: ~/.claude/settings.json)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report what would change without writing.",
+    )
+    args = parser.parse_args(argv)
+
+    settings_path = Path(args.settings)
+    if not settings_path.exists():
+        print(f"settings.json not found at {settings_path}", file=sys.stderr)
+        return 1
+    try:
+        data = json.loads(settings_path.read_text())
+    except Exception as exc:
+        print(f"settings.json is not valid JSON: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(data, dict):
+        print("settings.json is not a JSON object", file=sys.stderr)
+        return 2
+
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    removed_hooks = _strip_cli_hooks(data, plugin_root)
+    rewritten_wrap = _rewrite_cli_wrap_to_plugin(data, plugin_root)
+    # Wrap rewrite already mutated statusLine — don't also strip it.
+    removed_statusline = (
+        False if rewritten_wrap else _strip_cli_statusline(data, plugin_root)
+    )
+
+    if removed_hooks == 0 and not removed_statusline and not rewritten_wrap:
+        print("No CLI hooks or statusLine found in settings.json — nothing to do.")
+        return 0
+
+    if args.dry_run:
+        print(f"Would remove {removed_hooks} CLI hook entries.")
+        if removed_statusline:
+            print("Would remove CLI statusLine entry.")
+        if rewritten_wrap:
+            print("Would rewrite CLI wrap-statusLine to plugin wrap shape.")
+        return 0
+
+    _atomic_write(settings_path, data)
+    _write_marker(resolve_coach_dir())
+
+    print(f"Removed {removed_hooks} CLI hook entries.")
+    if removed_statusline:
+        print("Removed CLI statusLine entry. Plugin will reinstall its own next session.")
+    if rewritten_wrap:
+        print("Rewrote CLI wrap-statusLine to plugin wrap shape (saved original preserved).")
+    print()
+    print("Plugin is now in charge. The CLI's installed files in")
+    print("  ~/.claude/hooks/coach-*.py  and  ~/.claude/coach/")
+    print("are untouched. Run `npx @rm0nroe/coach-claw uninstall` for")
+    print("full CLI removal (optional — coach state in ~/.claude/coach/")
+    print("is shared between distributions and stays put either way).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/bin/themes.py

@@ -0,0 +1,256 @@
+"""Level-name ladders for the rank/level display.
+
+Each theme is a 50-element list — one name per level, ordered L1 → L50.
+The progression arc is the theme's identity: craft (technical mastery),
+forge (blacksmithing), cosmic (stellar/spacetime), ocean (lobster-mascot
+marine depth), plus eight pop-culture-inspired ladders.
+
+Adding a theme: append a new key to THEMES with exactly 50 unique
+single-word entries. The test suite (test_themes.py) enforces both.
+
+The selected theme is read from `~/.claude/coach/.user_config.json`
+via `user_config.get_theme()`. Default = "craft" so existing installs
+without a config file are unchanged.
+
+# Brand safety — pop-culture themes
+
+The eight pop-culture-inspired themes (skyrim, marvel, dc, finalfantasy,
+military, lotr, starwars, hacker) are FAN-INSPIRED and use only:
+
+  - Public-domain mythology (Norse, Greek, Mesopotamian, Hindu, Biblical, etc.)
+  - Real-world historical figures and titles (Caesar, Khan, Shogun, Centurion)
+  - Genre-generic terminology that pre-dates or transcends any single
+    franchise (Knight, Wizard, Mage, Apprentice, Master, Sentinel, etc.)
+  - Common English compound words (Greybeard, Highking, Worldwarden)
+
+Specifically EXCLUDED from every ladder:
+  - Names invented by a franchise (Dovahkiin, Padawan, Vibranium, Maiar)
+  - Named characters from any franchise
+  - Trademarked group / organization names (The Avengers, Justice League,
+    Jedi Order, Lantern Corps as such)
+
+Coach Claw is not affiliated with or endorsed by any franchise owner.
+"""
+from __future__ import annotations
+
+# L1-L8 preserved from the original ladder for backwards-compat with
+# existing XP totals. L9-L50 follow the technical-mastery arc:
+# recognized excellence → mastery → cosmic → transcendent.
+THEME_CRAFT = [
+    "Drafter", "Iterator", "Builder", "Shipper", "Craftsman",
+    "Architect", "Virtuoso", "Sensei", "Luminary", "Legend",
+    "Mythic", "Ascendant", "Pioneer", "Vanguard", "Savant",
+    "Prodigy", "Visionary", "Oracle", "Sage", "Paragon",
+    "Archmage", "Grandmaster", "Elder", "Progenitor", "Sovereign",
+    "Titan", "Colossus", "Zenith", "Overmind", "Transcendent",
+    "Celestial", "Cosmic", "Stellar", "Nebula", "Supernova",
+    "Singularity", "Primordial", "Aether", "Eldritch", "Eternal",
+    "Immortal", "Divine", "Demiurge", "Alpha", "Omega",
+    "Apex", "Ultima", "Infinite", "Genesis", "Origin",
+]
+
+# Blacksmithing arc — apprentice → master smith → primal forge.
+THEME_FORGE = [
+    "Apprentice", "Striker", "Smith", "Forger", "Hammerhand",
+    "Bladesmith", "Toolsmith", "Mastersmith", "Forgemaster", "Anvilkeeper",
+    "Furnacekeeper", "Quenchmaster", "Edgewright", "Steelwright", "Ironwright",
+    "Bellowsmith", "Crucible", "Tempersworn", "Hardener", "Foundrylord",
+    "Smelter", "Blastsmith", "Damascus", "Foldweaver", "Patternsmith",
+    "Runesmith", "Soulforger", "Starsmith", "Voidwright", "Worldforger",
+    "Spiritsmith", "Lightsmith", "Flamewarden", "Inferno", "Cinder",
+    "Ember", "Glow", "Furnacecore", "Magmaheart", "Sunsmith",
+    "Forgekin", "Coresoul", "Eternalflame", "Worldhammer", "Anvilheart",
+    "Pillar", "Bedrock", "Forgefather", "Primalforge", "Genesis",
+]
+
+# Cosmological arc — spark of matter → galaxy → cosmic inflation.
+THEME_COSMIC = [
+    "Spark", "Mote", "Particle", "Atom", "Element",
+    "Crystal", "Mineral", "Aerolith", "Asteroid", "Meteor",
+    "Comet", "Moon", "Planet", "Star", "Pulsar",
+    "Quasar", "Magnetar", "Nebula", "Nova", "Supernova",
+    "Hypernova", "Galaxy", "Constellation", "Cluster", "Spiral",
+    "Filament", "Wormhole", "Horizon", "Singularity", "Universe",
+    "Multiverse", "Cosmosphere", "Plenum", "Continuum", "Aether",
+    "Ether", "Void", "Abyssum", "Eonkeeper", "Timeweaver",
+    "Spaceforger", "Lightspeed", "Causal", "Quantum", "Primordial",
+    "Genesis", "Inflation", "Eternity", "Infinity", "Origin",
+]
+
+# Marine-depth arc — lobster mascot tribute. Hatchling → leviathan → origin.
+THEME_OCEAN = [
+    "Hatchling", "Larva", "Wriggler", "Postlarva", "Juvenile",
+    "Forager", "Burrower", "Reefer", "Hunter", "Patroller",
+    "Stalker", "Predator", "Tidewalker", "Currentrider", "Wavecrest",
+    "Reefking", "Tidemaster", "Deepswimmer", "Sandstrider", "Coralweaver",
+    "Stormbringer", "Squallchaser", "Tidelord", "Reeflord", "Abyssal",
+    "Deepkeeper", "Trenchwalker", "Voidswimmer", "Leviathan", "Kraken",
+    "Reefshaper", "Oceanic", "Saltkin", "Pearlborn", "Deepforger",
+    "Mariner", "Tideborn", "Foamprince", "Wavekeeper", "Tidesage",
+    "Cosmic", "Primordial", "Oceanmind", "Worldsea", "Eternalshore",
+    "Tideborne", "Currentlord", "Genesis", "Source", "Origin",
+]
+
+# === POP-CULTURE THEMES ===================================================
+# All entries below are public-domain mythology, real historical titles,
+# or genre-generic terminology. No franchise-coined neologisms or named
+# characters. See module docstring "Brand safety" for the policy.
+
+# Skyrim-inspired — Norse / Anglo-Saxon hierarchy + generic fantasy.
+# Bandit → Whelp/Initiate paths → Companion / Listener / Greybeard tier
+# → Wyrmkin → Norse pantheon. No Bethesda-coined words (no Dovahkiin,
+# Daedra, Aedra, Talos, Alduin, etc.).
+THEME_SKYRIM = [
+    "Pauper", "Citizen", "Footpad", "Bandit", "Adventurer",
+    "Whelp", "Initiate", "Pupil", "Apprentice", "Sellsword",
+    "Adept", "Skald", "Drengr", "Berserker", "Conjurer",
+    "Burglar", "Mercenary", "Slayer", "Wizard", "Centurion",
+    "Praefect", "Warlock", "Guildmaster", "Master", "Legate",
+    "Archmage", "Companion", "Speaker", "General", "Blade",
+    "Harbinger", "Listener", "Greybeard", "Tongue", "Thane",
+    "Jarl", "Stormcaller", "Konung", "Champion", "Voidwalker",
+    "Wyrmkin", "Wyrmblood", "Dragonkin", "Highking", "Highlord",
+    "Worldwarden", "Vanir", "Aesir", "Asgardian", "Anu",
+]
+
+# Marvel-inspired — comics power-tier classification, no character names
+# or trademarked group names. Civilian → Hero → cosmic → abstract.
+THEME_MARVEL = [
+    "Civilian", "Witness", "Bystander", "Cadet", "Operative",
+    "Agent", "Vigilante", "Sidekick", "Hero", "Defender",
+    "Mutant", "Mystic", "Sorcerer", "Specialist", "Captain",
+    "Knight", "Crusader", "Sentinel", "Watchman", "Champion",
+    "Speedster", "Telepath", "Telekinetic", "Pyromancer", "Cryomancer",
+    "Channeler", "Berserker", "Behemoth", "Phoenix", "Avatar",
+    "Cosmic", "Celestial", "Eternal", "Galactic", "Stellar",
+    "Universal", "Multiversal", "Dimensional", "Astral", "Beyond",
+    "Eternity", "Infinity", "Tribunal", "Allfather", "Existence",
+    "Sovereign", "Above", "Origin", "Apex", "Source",
+]
+
+# DC-inspired — vigilante / detective angle, Justice / Trinity / New Gods
+# cosmology. Differentiated from Marvel by Detective+Justicer flavor and
+# Highfather/Spectre/Presence top tiers.
+THEME_DC = [
+    "Civilian", "Bystander", "Witness", "Patrolman", "Detective",
+    "Operative", "Agent", "Vigilante", "Sidekick", "Hero",
+    "Crusader", "Justicer", "Defender", "Watchman", "Sentinel",
+    "Captain", "Knight", "Centurion", "Champion", "Specialist",
+    "Speedster", "Telepath", "Sorcerer", "Mystic", "Lantern",
+    "Wonder", "Founder", "Council", "Trinity", "Avatar",
+    "Demigod", "Eternal", "Stellar", "Cosmic", "Galactic",
+    "Universal", "Multiversal", "Beyond", "Aspect", "Spirit",
+    "Spectre", "Phantom", "Highfather", "Endless", "Highest",
+    "Sovereign", "Crisis", "Presence", "Origin", "Source",
+]
+
+# Final Fantasy-inspired — generic JRPG job classes + summon-type terms.
+# Specific FF characters / Onion Knight / Cetra / Esper-as-named-summon
+# excluded; mythological summon types (Aeon, Eidolon, Primal) are public
+# domain (Greek "eidolon", broader use), so retained.
+THEME_FINALFANTASY = [
+    "Squire", "Page", "Cadet", "Apprentice", "Initiate",
+    "Adept", "Knight", "Warrior", "Crusader", "Paladin",
+    "Berserker", "Monk", "Lancer", "Dragoon", "Samurai",
+    "Ninja", "Bard", "Dancer", "Geomancer", "Cleric",
+    "Warlock", "Spellsword", "Mystic", "Scholar", "Astrologer",
+    "Necromancer", "Alchemist", "Engineer", "Reaper", "Viper",
+    "Mediator", "Channeler", "Summoner", "Hero", "Champion",
+    "Lightbringer", "Crystal", "Aeon", "Eidolon", "Esper",
+    "Familiar", "Primal", "Avatar", "Sovereign", "Worldwarden",
+    "Skywarden", "Source", "Origin", "Singularity", "Genesis",
+]
+
+# Military hierarchy — US enlisted/officer ranks + Roman + Asian + mythic
+# war archetypes. All real historical titles (Caesar, Khan, Shogun) or
+# generic English military terms.
+THEME_MILITARY = [
+    "Recruit", "Private", "Specialist", "Corporal", "Sergeant",
+    "Staffsergeant", "Mastersergeant", "Sergeantmajor", "Ensign", "Cadet",
+    "Lieutenant", "Captain", "Major", "Colonel", "Brigadier",
+    "General", "Fieldmarshal", "Commander", "Commodore", "Admiral",
+    "Viceadmiral", "Fleetadmiral", "Marshal", "Airmarshal", "Highmarshal",
+    "Ranger", "Beret", "Seal", "Marine", "Paratrooper",
+    "Sniper", "Operative", "Aviator", "Pilot", "Centurion",
+    "Optio", "Tribune", "Legate", "Praetor", "Consul",
+    "Imperator", "Caesar", "Augustus", "Samurai", "Daimyo",
+    "Khan", "Shogun", "Conqueror", "Generalissimo", "Polemarch",
+]
+
+# LOTR-inspired — Anglo-Saxon / generic medieval high-fantasy. None of:
+# Hobbit, Maiar, Valar, Eru, Numenor, Mordor, Shire, Gondor, Rohan, or
+# named characters. "Halfling" is pre-Tolkien (in 1860s English use).
+THEME_LOTR = [
+    "Pauper", "Cottar", "Wanderer", "Squire", "Apprentice",
+    "Halfling", "Footsoldier", "Pikeman", "Outrider", "Greenrider",
+    "Knight", "Esquire", "Ranger", "Scout", "Hunter",
+    "Marshal", "Captain", "Bannerman", "Reeve", "Thegn",
+    "Champion", "Crusader", "Sentinel", "Warden", "Guardian",
+    "Watchman", "Liegelord", "Lord", "Highlord", "Steward",
+    "Regent", "King", "Highking", "Sage", "Loremaster",
+    "Wizard", "Conjurer", "Mage", "Archmage", "Highmage",
+    "Mystic", "Oracle", "Visionary", "Wraith", "Spectre",
+    "Shade", "Avatar", "Forefather", "Source", "Origin",
+]
+
+# Star Wars-inspired — generic monk-knight + Light/Dark hierarchy. None
+# of: Jedi, Sith, Padawan, Lightsaber, Force, Mandalorian, or named
+# characters. Initiate → Apprentice → Knight → Master → Lord progression
+# is broadly monastic, predates SW.
+THEME_STARWARS = [
+    "Civilian", "Cadet", "Recruit", "Initiate", "Acolyte",
+    "Apprentice", "Disciple", "Adept", "Pupil", "Trainee",
+    "Squire", "Knight", "Crusader", "Champion", "Hunter",
+    "Tracker", "Warrior", "Sentinel", "Guardian", "Defender",
+    "Captain", "Master", "Council", "Sovereign", "Lord",
+    "Highlord", "Warlord", "Darklord", "Commander", "Chancellor",
+    "Emperor", "Mystic", "Sage", "Seer", "Oracle",
+    "Shadowmaster", "Lightbearer", "Voidwalker", "Starwarden", "Skywarden",
+    "Voidlord", "Galactic", "Stellar", "Cosmic", "Eternal",
+    "Astral", "Celestial", "Origin", "Source", "Above",
+]
+
+# Hacker / dev-culture — mainstream dev hierarchy + system-internals
+# folklore. No company names, no trademarked product names. "Linux",
+# "Unix", "Bell Labs", "Knuth" intentionally absent — using them as
+# rank names is gimmicky and risks association.
+THEME_HACKER = [
+    "Lurker", "Reader", "Newbie", "Scriptkiddie", "Tinkerer",
+    "Coder", "Programmer", "Hacker", "Junior", "Engineer",
+    "Developer", "Senior", "Lead", "Architect", "Principal",
+    "Distinguished", "Fellow", "Maintainer", "Reviewer", "Mentor",
+    "Wizard", "Sorcerer", "Guru", "Sensei", "Sage",
+    "Oracle", "Veteran", "Greybeard", "Founder", "Pioneer",
+    "Daemon", "Compiler", "Linker", "Kernel", "Hypervisor",
+    "Bootloader", "Firmware", "Microservice", "Distributed", "Quantum",
+    "Specter", "Phantom", "Ghost", "Demon", "Druid",
+    "Phreaker", "Legend", "Source", "Genesis", "Singularity",
+]
+
+THEMES: dict[str, list[str]] = {
+    "craft":        THEME_CRAFT,
+    "forge":        THEME_FORGE,
+    "cosmic":       THEME_COSMIC,
+    "ocean":        THEME_OCEAN,
+    "skyrim":       THEME_SKYRIM,
+    "marvel":       THEME_MARVEL,
+    "dc":           THEME_DC,
+    "finalfantasy": THEME_FINALFANTASY,
+    "military":     THEME_MILITARY,
+    "lotr":         THEME_LOTR,
+    "starwars":     THEME_STARWARS,
+    "hacker":       THEME_HACKER,
+}
+
+DEFAULT_THEME = "craft"
+
+
+def get_ladder(theme: str) -> list[str]:
+    """Return the 50-element name list for `theme`. Falls back to default
+    on unknown themes — the caller never sees a KeyError."""
+    return THEMES.get(theme, THEMES[DEFAULT_THEME])
+
+
+def list_themes() -> list[str]:
+    """Stable list of available theme keys, default first for `/config`."""
+    return [DEFAULT_THEME] + sorted(k for k in THEMES if k != DEFAULT_THEME)