fixed box-shadow attr on token equip assignation to .token-panel instead of .token-rails, where it belonged

CARTE type, User.equipped_trinket FK, Token.slots_claimed field; post_save signal sets
equipped_trinket=COIN for new users, PASS for staff; kit bag now shows only the equipped
trinket in Trinkets section; Game Kit applet mini tooltip portal shows Equipped or Equip
Trinket per token; AJAX POST equip-trinket id updates equippedId in-place; equip btn
now works for COIN, PASS, and CARTE (data-token-id added to all three); Gatekeeper CARTE
flow: drop_token sets current_room (no slot reserved); each empty slot up to
slots_claimed+1 gets a drop-token-btn; slots_claimed high-water mark advances on fill,
never decrements; highest CARTE-filled slot gets NVM (release_slot); token_return_btn
resets current_room + slots_claimed + un-fills all CARTE slots; gate_status always returns
full template so launch-game-btn persists via HTMX when gate_status == OPEN; room.html
includes gatekeeper when GATHERING or OPEN; new FT test_trinket_carte_blanche.py (2
tests, both passing); 299 tests green

.gitignore

@@ -10,9 +10,8 @@
 *.pyc
 __pycache__/
 local_settings.py
-db.sqlite3
+*.sqlite3
-db.sqlite3-journal
+*.sqlite3-journal
-container.db.sqlite3
 media
 
 # If your build process includes running collectstatic, then you probably don't need or want to include staticfiles/

.woodpecker.yaml

@@ -6,31 +6,48 @@ services:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
 
+  - name: redis
+    image: redis:7
+
 steps:
   - name: test-UTs-n-ITs
     image: python:3.13-slim
     environment:
       DATABASE_URL: postgresql://postgres:postgres@postgres/python_tdd_test
+      CELERY_BROKER_URL: redis://redis:6379/0
+      REDIS_URL: redis://redis:6379/1
     commands:
       - pip install -r requirements.txt
       - cd ./src
       - python manage.py test apps
+    when:
+      - event: push
 
   - name: test-FTs
     image: gitea.earthmanrpg.me/discoman/python-tdd-ci:latest
     environment:
       HEADLESS: 1
+      CELERY_BROKER_URL: redis://redis:6379/0
+      REDIS_URL: redis://redis:6379/1
+      STRIPE_SECRET_KEY:
+        from_secret: stripe_secret_key
+      STRIPE_PUBLISHABLE_KEY:
+        from_secret: stripe_publishable_key
     commands:
+      - pip install -r requirements.txt
       - cd ./src
       - python manage.py collectstatic --noinput
       - python manage.py test functional_tests
+    when:
+      - event: push
 
   - name: screendumps
     image: gitea.earthmanrpg.me/discoman/python-tdd-ci:latest
-    when:
-      - status: failure
     commands:
       - cat ./src/functional_tests/screendumps/*.html || echo "No screendumps found"
+    when:
+      - event: push
+        status: failure
 
   - name: build-and-push
     image: docker:cli
@@ -43,7 +60,7 @@ steps:
       - docker push gitea.earthmanrpg.me/discoman/gamearray:latest
     when:
       - branch: main
-      - event: push
+        event: push
 
   - name: deploy
     image: alpine
@@ -58,5 +75,5 @@ steps:
       - ssh -o StrictHostKeyChecking=no discoman@staging.earthmanrpg.me /opt/gamearray/deploy.sh
     when:
       - branch: main
-      - event: push
+        event: push
     

Dockerfile

@@ -15,6 +15,8 @@ RUN python manage.py collectstatic --noinput
 
 ENV DJANGO_DEBUG_FALSE=1
 
+RUN DJANGO_SECRET_KEY=build-dummy DJANGO_ALLOWED_HOST=localhost python manage.py compress
+
 RUN adduser --uid 1234 nonroot
 
 USER nonroot

infra/deploy-playbook.yaml

@@ -114,6 +114,15 @@
           POSTGRES_USER: gamearray
           POSTGRES_PASSWORD: "{{ postgres_password }}"
 
+    - name: Start Redis container
+      community.docker.docker_container:
+        name: gamearray_redis
+        image: redis:7
+        state: started
+        restart_policy: unless-stopped
+        networks:
+          - name: gamearray_net
+
     - name: Run container
       community.docker.docker_container:
         name: gamearray
@@ -124,13 +133,36 @@
           DJANGO_DEBUG_FALSE: "1"
           DJANGO_SECRET_KEY: "{{ secret_key.content | b64decode }}"
           DJANGO_ALLOWED_HOST: "{{ django_allowed_host }}"
+          DJANGO_SUPERUSER_EMAIL: "{{ django_superuser_email }}"
+          DJANGO_SUPERUSER_PASSWORD: "{{ django_superuser_password }}"
           DATABASE_URL: "postgresql://gamearray:{{ postgres_password }}@gamearray_postgres/gamearray"
           MAILGUN_API_KEY: "{{  mailgun_api_key }}"
+          CELERY_BROKER_URL: "redis://gamearray_redis:6379/0"
+          REDIS_URL: "redis://gamearray_redis:6379/1"
         networks:
           - name: gamearray_net
         ports:
           127.0.0.1:8888:8888
 
+    - name: Start Celery worker container
+      community.docker.docker_container:
+        name: gamearray_celery
+        image: gitea.earthmanrpg.me/discoman/gamearray:latest
+        state: started
+        recreate: true
+        env:
+          DJANGO_DEBUG_FALSE: "1"
+          DJANGO_SECRET_KEY: "{{ secret_key.content | b64decode }}"
+          DJANGO_ALLOWED_HOST: "{{ django_allowed_host }}"
+          DATABASE_URL: "postgresql://gamearray:{{ postgres_password }}@gamearray_postgres/gamearray"
+          MAILGUN_API_KEY: "{{  mailgun_api_key }}"
+          CELERY_BROKER_URL: "redis://gamearray_redis:6379/0"
+          REDIS_URL: "redis://gamearray_redis:6379/1"
+        networks:
+          - name: gamearray_net
+        command: "python -m celery -A core worker -l info"
+
+
     - name: Create static files directory
       ansible.builtin.file:
         path: /var/www/gamearray/static
@@ -149,6 +181,11 @@
         container: gamearray
         command: python manage.py migrate
 
+    - name: Ensure superuser exists
+      community.docker.docker_container_exec:
+        container: gamearray
+        command: python manage.py ensure_superuser
+
   handlers:
     - name: Restart nginx
       ansible.builtin.service:

infra/deploy.sh.j2

@@ -17,9 +17,22 @@ docker run -d --name gamearray \
     -p 127.0.0.1:8888:8888 \
     "$IMAGE"
 
+echo "==> Stopping old celery worker..."
+docker stop gamearray_celery 2>/dev/null || true
+docker rm gamearray_celery 2>/dev/null || true
+
+echo "==> Starting new celery worker..."
+docker run -d --name gamearray_celery \
+    --env-file /opt/gamearray/gamearray.env \
+    --network gamearray_net \
+    "$IMAGE" python -m celery -A core worker -l info
+
 echo "==> Running migrations..."
 docker exec gamearray python ./manage.py migrate
 
+echo "==> Ensuring superuser exists..."
+docker exec gamearray python manage.py ensure_superuser
+
 echo "==> Copying static files..."
 sudo docker cp gamearray:/src/static/. /var/www/gamearray/static/
 

infra/gamearray.env.j2

@@ -1,5 +1,12 @@
 DJANGO_DEBUG_FALSE=1
 DJANGO_SECRET_KEY={{ secret_key.content | b64decode }}
 DJANGO_ALLOWED_HOST={{ django_allowed_host }}
+DJANGO_SUPERUSER_EMAIL={{ django_superuser_email }}
+DJANGO_SUPERUSER_PASSWORD={{ django_superuser_password }}
 DATABASE_URL=postgresql://gamearray:{{ postgres_password }}@gamearray_postgres/gamearray
 MAILGUN_API_KEY={{ mailgun_api_key }}
+STRIPE_PUBLISHABLE_KEY={{ stripe_publishable_key }}
+STRIPE_SECRET_KEY={{ stripe_secret_key }}
+CELERY_BROKER_URL=redis://gamearray_redis:6379/0
+REDIS_URL=redis://gamearray_redis:6379/1
+

infra/group_vars/staging/vault.yaml

@@ -1,23 +1,42 @@
 $ANSIBLE_VAULT;1.1;AES256
-33616230376431343735626631623932393166343538653732383533323436326335343463646664
+38383061343764656262613934313230656462366163363263653462333338333863326338343838
-6565373531623465613661613533376231373837326438300a393665613839646231633737313938
+3664646437643462346636623231633639396239333532340a363338313839353734326238643735
-64633035336663313163333634623732323537326363646132313136376131636666636538323066
+39343237396433336436366430626332343666666461613636656433363838613432393539386266
-3037373930303537320a313062646166353862633836373466316261363939633433663039323866
+3237336434346333350a663530623334633438616135376437666631313064333735653633396461
-62333739303662343836306538393734343830366336323265393138343438363533353166383031
+31306163343838336465626663373661343839653037333235313361633335646337353339616333
-32313461313137643039376237346633316466646136353038633861333031663164656233366634
+35343233346562346236636364316265313936646235373866636333353866623161663935626637
-38303363383130376264373861393863623330623733643135643461383132613339376633353031
+31633864366339653930626365373237326531366632626337636163333266656434323063333365
-32313863323039646534633733383661333361313832333830383066633130396239626661643264
+38373437383261613439306666373764633737623466626235356465636365646337306534326535
-65636335303339613432326533343337366261356632313639623634386633383836333733663536
+36633866663161613632613434666134343465383663633165663330376535653537333763376232
-39383361353530646166643531333535356636326535383534326237666638326137616162646261
+61653265303134656338393033303834663630653064666134633638393235346631346461633030
-65316466323335653932636338653565383038313531383638393839313736643739363037353230
+35343332393961363361613661633633613262663231366236396663636239326534373134623762
-35653632353531656435396663316537333133653632366437613339303033333536643937353166
+30653139333134616236666238616466633733656633326331386138363839653566333434346534
-64363037653733303332643931343362303261643432366531326262383465313965633064356338
+63326539333461383265316332336333656365386531393630663537363365643061363263313738
-31336333373665373035656533633864316139303934623030383934393434356334643962666163
+37633564363533633762393736636333306433306534393539636231656162343562383232663932
-33343739366336613263333764306365333566363536616662383733616237396563346132336633
+62646339363266303564383438636636373661656465666663613863396639633732636635326166
-38663239613339376335386233386330396634323033343332366130616162666339393861306336
+39323738303338373466366236623665633538363134616565326665386564613735393638656630
-35383566383831356530633130313732356331616164646132626665646235396635386237313538
+31326431316163376132623064376634643737313864336464623431333834663361336133353838
-38656631336261646530303761643334303937613036363766303637376262373466316431323731
+32303635663261333732306137383133623134373363613837306637663566303634653863343766
-38666462313639353131303134646434646135366136343361353932326165626666306361393431
+33613936626362653466333537666462373633313038376565623363666631353162643634653730
-62646238323265346263386363373462313766616333326366366461346436383064336535376339
+30323532623261643136666237316561353038323265303930336364633731333533386563623133
-31356566356336386262393831616631666233633930393263623563386265343237323133313832
+31343965643336613933663431626435333235366639363334653065303434386165333739336632
-3430363635363332303963316530663765613666306233376463
+61363030376664643638653365626365623936623864666663326534343863613962616431376666
+39363837386639393235316339323932326466616330303165613032663637616232656162653335
+61613266376262626234383135306238313366346330656333383465383861663962653638303362
+34353833646461383839386238626661346263363131643438343461393739336132386466373665
+32646238633161363064666335626639653335306236613866333934646366323564306133396131
+36343032623964316138386538333863363530396330646431373466646538663063326330663639
+32323762356632336364333162336133336335623865323861663131626232633066643238333237
+32343938353166353037316162653832663433343534626331633936633866356666653932656665
+38396533356131326262633431653435306362633966383531356236396639376437396333616130
+35666435393461316232323234653865346338326330623065373461323961393663306262313066
+30313430353065616230356135333565333338373663643434353561363438656233383739663233
+35653832353062396634613832353837333835636461616234343462626239636634613430373931
+31656534343764643065643733326637343631356633653531313062633362663461313732633331
+35626364393563373339636466346339383032383635303865306636623737343237333863353238
+63306132396262656365323833323635633563653735366630313363386236613231346339643430
+63396230353566633830383932666335373665356434656438336338633035653465613665613862
+31663565653338376662323866613538363566306635333735646363363730646331306234353839
+30346363393231623563646439623261643634663831313338393761343865303930373133633733
+31656466303365316164396463373335396464643130643337656361333339653238333633373662
+6539

infra/inventory.ini

@@ -1,5 +1,5 @@
 [staging]
-staging.earthmanrpg.me ansible_user=discoman ansible_ssh_private_key_file=~/.ssh/id_ed25519_wsl_python-tdd
+staging.earthmanrpg.me ansible_user=discoman ansible_ssh_private_key_file=~/.ssh/id_ed25519_wsl_python-tdd letsencrypt_domain=staging.earthmanrpg.me
 
 [production]
 www.earthmanrpg.me ansible_user=discoman ansible_ssh_private_key_file=~/.ssh/id_ed25519_wsl_python-tdd

infra/nginx.conf.j2

@@ -1,6 +1,15 @@
 server {
     listen 80;
     server_name {{ django_allowed_host | replace(',', ' ')}};
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name {{ django_allowed_host | replace(',', ' ') }};
+
+    ssl_certificate /etc/letsencrypt/live/{{ letsencrypt_domain }}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{ letsencrypt_domain }}/privkey.pem;
 
     location /static/ {
         alias /var/www/gamearray/static/;
@@ -11,6 +20,6 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto https;
     }
 }

requirements.dev.txt

@@ -2,13 +2,20 @@ asgiref==3.11.0
 attrs==25.4.0
 certifi==2025.11.12
 cffi==2.0.0
+channels
+channels-redis
 charset-normalizer==3.4.4
 coverage
 cssselect==1.3.0
+daphne
 dj-database-url
 Django==6.0
+django-compressor
+django-htmx
+django-libsass
 django-stubs==5.2.8
 django-stubs-ext==5.2.8
+djangorestframework
 gunicorn==23.0.0
 h11==0.16.0
 idna==3.11
@@ -17,17 +24,21 @@ outcome==1.3.0.post0
 packaging==25.0
 pycparser==2.23
 PySocks==1.7.1
+python-dotenv
 requests==2.32.5
+scipy
 selenium==4.39.0
 sniffio==1.3.1
 sortedcontainers==2.4.0
 sqlparse==0.5.5
+stripe
 trio==0.32.0
 trio-websocket==0.12.2
 types-PyYAML==6.0.12.20250915
 typing_extensions==4.15.0
 tzdata==2025.3
 urllib3==2.6.2
+uvicorn[standard]
 websocket-client==1.9.0
 whitenoise==6.11.0
 wsproto==1.3.2

requirements.txt

@@ -1,10 +1,22 @@
+celery
+channels
+channels-redis
 cssselect==1.3.0
+daphne
 Django==6.0
 dj-database-url
+django-compressor
+django-htmx
+django-libsass
 django-stubs==5.2.8
 django-stubs-ext==5.2.8
+djangorestframework
 gunicorn==23.0.0
 lxml==6.0.2
 psycopg2-binary
+redis
 requests==2.31.0
+scipy
+stripe
 whitenoise==6.11.0
+uvicorn[standard]

src/.coveragerc

@@ -3,6 +3,7 @@ source = apps
 omit =
     */migrations/*
     */tests/*
+    */routing.py
 
 [report]
 show_missing = true

src/apps/api/serializers.py

@@ -0,0 +1,32 @@
+from rest_framework import serializers
+
+from apps.dashboard.models import Item, Note
+from apps.lyric.models import User
+
+
+class ItemSerializer(serializers.ModelSerializer):
+    text = serializers.CharField()
+
+    def validate_text(self, value):
+        note = self.context["note"]
+        if note.item_set.filter(text=value).exists():
+            raise serializers.ValidationError("duplicate")
+        return value
+
+    class Meta:
+        model = Item
+        fields = ["id", "text"]
+
+class NoteSerializer(serializers.ModelSerializer):
+    name = serializers.ReadOnlyField()
+    url = serializers.CharField(source="get_absolute_url", read_only=True)
+    items = ItemSerializer(many=True, read_only=True, source="item_set")
+
+    class Meta:
+        model = Note
+        fields = ["id", "name", "url", "items"]
+
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["id", "username"]

src/apps/api/tests/integrated/test_views.py

@@ -0,0 +1,115 @@
+from django.test import TestCase
+from rest_framework.test import APIClient
+
+from apps.dashboard.models import Item, Note
+from apps.lyric.models import User
+
+class BaseAPITest(TestCase):
+    # Helper fns
+    def setUp(self):
+        self.client = APIClient()
+        self.user = User.objects.create_user("test@example.com")
+        self.client.force_authenticate(user=self.user)
+
+class NoteDetailAPITest(BaseAPITest):
+    def test_returns_note_with_items(self):
+        note = Note.objects.create(owner=self.user)
+        Item.objects.create(text="item 1", note=note)
+        Item.objects.create(text="item 2", note=note)
+
+        response = self.client.get(f"/api/notes/{note.id}/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["id"], str(note.id))
+        self.assertEqual(len(response.data["items"]), 2)
+
+class NoteItemsAPITest(BaseAPITest):
+    def test_can_add_item_to_note(self):
+        note = Note.objects.create(owner=self.user)
+
+        response = self.client.post(
+            f"/api/notes/{note.id}/items/",
+            {"text": "a new item"},
+        )
+
+        self.assertEqual(response.status_code, 201)
+        self.assertEqual(Item.objects.count(), 1)
+        self.assertEqual(Item.objects.first().text, "a new item")
+
+    def test_cannot_add_empty_item_to_note(self):
+        note = Note.objects.create(owner=self.user)
+
+        response = self.client.post(
+            f"/api/notes/{note.id}/items/",
+            {"text": ""},
+        )
+
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(Item.objects.count(), 0)
+
+    def test_cannot_add_duplicate_item_to_note(self):
+        note = Note.objects.create(owner=self.user)
+        Item.objects.create(text="note item", note=note)
+        duplicate_response = self.client.post(
+            f"/api/notes/{note.id}/items/",
+            {"text": "note item"},
+        )
+
+        self.assertEqual(duplicate_response.status_code, 400)
+        self.assertEqual(Item.objects.count(), 1)
+
+class NotesAPITest(BaseAPITest):
+    def test_get_returns_only_users_notes(self):
+        note1 = Note.objects.create(owner=self.user)
+        Item.objects.create(text="item 1", note=note1)
+        other_user = User.objects.create_user("other@example.com")
+        Note.objects.create(owner=other_user)
+
+        response = self.client.get("/api/notes/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.data), 1)
+        self.assertEqual(response.data[0]["id"], str(note1.id))
+
+    def test_post_creates_note_with_item(self):
+        response = self.client.post(
+            "/api/notes/",
+            {"text": "first item"},
+        )
+
+        self.assertEqual(response.status_code, 201)
+        self.assertEqual(Note.objects.count(), 1)
+        self.assertEqual(Note.objects.first().owner, self.user)
+        self.assertEqual(Item.objects.first().text, "first item")
+
+class UserSearchAPITest(BaseAPITest):
+    def test_returns_users_matching_username(self):
+        disco = User.objects.create_user("disco@example.com")
+        disco.username = "discoman"
+        disco.searchable = True
+        disco.save()
+
+        response = self.client.get("/api/users/?q=disc")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.data), 1)
+        self.assertEqual(response.data[0]["username"], "discoman")
+
+    def test_non_searchable_users_are_excluded(self):
+        alice = User.objects.create_user("alice@example.com")
+        alice.username = "princessAli"
+        alice.save() # searchable defaults to False
+
+        response = self.client.get("/api/users/?q=prin")
+
+        self.assertEqual(response.data, [])
+
+    def test_response_does_not_include_email(self):
+        alice = User.objects.create_user("alice@example.com")
+        alice.username = "princessAli"
+        alice.searchable = True
+        alice.save()
+
+        response = self.client.get("/api/users/?q=prin")
+
+        self.assertNotIn("email", response.data[0])

src/apps/api/tests/unit/test_serializers.py

@@ -0,0 +1,19 @@
+from django.test import SimpleTestCase
+from apps.api.serializers import ItemSerializer, NoteSerializer
+
+
+class ItemSerializerTest(SimpleTestCase):
+    def test_fields(self):
+        serializer = ItemSerializer()
+        self.assertEqual(
+            set(serializer.fields.keys()),
+            {"id", "text"},
+        )
+
+class NoteSerializerTest(SimpleTestCase):
+    def test_fields(self):
+        serializer = NoteSerializer()
+        self.assertEqual(
+            set(serializer.fields.keys()),
+            {"id", "name", "url", "items"},
+        )

src/apps/api/urls.py

@@ -0,0 +1,11 @@
+from django.urls import path
+
+from . import views
+
+
+urlpatterns = [
+    path('notes/', views.NotesAPI.as_view(), name='api_notes'),
+    path('notes/<uuid:note_id>/', views.NoteDetailAPI.as_view(), name='api_note_detail'),
+    path('notes/<uuid:note_id>/items/', views.NoteItemsAPI.as_view(), name='api_note_items'),
+    path('users/', views.UserSearchAPI.as_view(), name='api_users'),
+]

src/apps/api/views.py

@@ -0,0 +1,45 @@
+from django.shortcuts import get_object_or_404
+from rest_framework.views import APIView
+from rest_framework.response import Response
+
+from apps.api.serializers import ItemSerializer, NoteSerializer, UserSerializer
+from apps.dashboard.models import Item, Note
+from apps.lyric.models import User
+
+
+class NoteDetailAPI(APIView):
+    def get(self, request, note_id):
+        note = get_object_or_404(Note, id=note_id)
+        serializer = NoteSerializer(note)
+        return Response(serializer.data)
+
+class NoteItemsAPI(APIView):
+    def post(self, request, note_id):
+        note = get_object_or_404(Note, id=note_id)
+        serializer = ItemSerializer(data=request.data, context={"note": note})
+        if serializer.is_valid():
+            serializer.save(note=note)
+            return Response(serializer.data, status=201)
+        return Response(serializer.errors, status=400)
+
+class NotesAPI(APIView):
+    def get(self, request):
+        notes = Note.objects.filter(owner=request.user)
+        serializer = NoteSerializer(notes, many=True)
+        return Response(serializer.data)
+
+    def post(self, request):
+        note = Note.objects.create(owner=request.user)
+        item = Item.objects.create(text=request.data.get("text", ""), note=note)
+        serializer = NoteSerializer(note)
+        return Response(serializer.data, status=201)
+
+class UserSearchAPI(APIView):
+    def get(self, request):
+        q = request.query_params.get("q", "")
+        users = User.objects.filter(
+            username__icontains=q,
+            searchable=True,
+        )
+        serializer = UserSerializer(users, many=True)
+        return Response(serializer.data)

src/apps/applets/admin.py

@@ -0,0 +1,11 @@
+from django.contrib import admin
+
+from apps.applets.models import Applet, UserApplet
+
+
+@admin.register(Applet)
+class AppletAdmin(admin.ModelAdmin):
+    list_display = ['slug', 'name', 'default_visible', 'grid_cols', 'grid_rows']
+    list_editable = ['grid_cols', 'grid_rows']
+
+admin.site.register(UserApplet)

src/apps/applets/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class AppletsConfig(AppConfig):
+    name = 'apps.applets'

src/apps/applets/migrations/0001_initial.py

@@ -0,0 +1,36 @@
+import django.db.models.deletion
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Applet',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('slug', models.SlugField(unique=True)),
+                ('name', models.CharField(max_length=100)),
+                ('context', models.CharField(choices=[('dashboard', 'Dashboard'), ('gameboard', 'Gameboard')], default='dashboard', max_length=20)),
+                ('default_visible', models.BooleanField(default=True)),
+                ('grid_cols', models.PositiveSmallIntegerField(default=12)),
+                ('grid_rows', models.PositiveSmallIntegerField(default=3)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='UserApplet',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('visible', models.BooleanField(default=True)),
+                ('applet', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='applets.applet')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='user_applets', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={'unique_together': {('user', 'applet')}},
+        ),
+    ]

src/apps/applets/migrations/0002_seed_applets.py

@@ -0,0 +1,29 @@
+from django.db import migrations
+
+
+def seed_applets(apps, schema_editor):
+    Applet = apps.get_model('applets', 'Applet')
+    for slug, name, cols, rows, context in [
+        ('wallet', 'Wallet', 12, 3, 'dashboard'),
+        ('new-list', 'New List', 9, 3, 'dashboard'),
+        ('my-lists', 'My Lists', 3, 3, 'dashboard'),
+        ('username', 'Username', 6, 3, 'dashboard'),
+        ('palette', 'Palette', 6, 3, 'dashboard'),
+        ('new-game', 'New Game', 4, 2, 'gameboard'),
+        ('my-games', 'My Games', 4, 4, 'gameboard'),
+        ('game-kit', 'Game Kit', 4, 2, 'gameboard'),
+    ]:
+        Applet.objects.get_or_create(
+            slug=slug,
+            defaults={'name': name, 'grid_cols': cols, 'grid_rows': rows, 'context': context},
+        )
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('applets', '0001_initial')
+    ]
+
+    operations = [
+        migrations.RunPython(seed_applets, migrations.RunPython.noop)
+    ]

src/apps/applets/migrations/0003_wallet_applets.py

@@ -0,0 +1,37 @@
+from django.db import migrations, models
+
+
+def seed_wallet_applets(apps, schema_editor):
+    Applet = apps.get_model('applets', 'Applet')
+    for slug, name, cols, rows in [
+        ('wallet-balances', 'Wallet Balances', 3, 3),
+        ('wallet-tokens',   'Wallet Tokens',   3, 3),
+        ('wallet-payment',  'Payment Methods', 6, 2),
+    ]:
+        Applet.objects.get_or_create(
+            slug=slug,
+            defaults={'name': name, 'grid_cols': cols, 'grid_rows': rows, 'context': 'wallet'},
+        )
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('applets', '0002_seed_applets'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='applet',
+            name='context',
+            field=models.CharField(
+                choices=[
+                    ('dashboard', 'Dashboard'),
+                    ('gameboard', 'Gameboard'),
+                    ('wallet', 'Wallet'),
+                ],
+                default='dashboard',
+                max_length=20,
+            ),
+        ),
+        migrations.RunPython(seed_wallet_applets, migrations.RunPython.noop),
+    ]

src/apps/applets/migrations/0004_rename_list_applet_slugs.py

@@ -0,0 +1,24 @@
+from django.db import migrations
+
+
+def rename_list_slugs(apps, schema_editor):
+    Applet = apps.get_model('applets', 'Applet')
+    Applet.objects.filter(slug='new-list').update(slug='new-note', name='New Note')
+    Applet.objects.filter(slug='my-lists').update(slug='my-notes', name='My Notes')
+
+
+def reverse_rename_list_slugs(apps, schema_editor):
+    Applet = apps.get_model('applets', 'Applet')
+    Applet.objects.filter(slug='new-note').update(slug='new-list', name='New List')
+    Applet.objects.filter(slug='my-notes').update(slug='my-lists', name='My Lists')
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('applets', '0003_wallet_applets'),
+    ]
+
+    operations = [
+        migrations.RunPython(rename_list_slugs, reverse_rename_list_slugs),
+    ]

src/apps/applets/models.py

@@ -0,0 +1,36 @@
+from django.db import models
+
+class Applet(models.Model):
+    DASHBOARD = "dashboard"
+    GAMEBOARD = "gameboard"
+    WALLET = "wallet"
+    CONTEXT_CHOICES = [
+        (DASHBOARD, "Dashboard"),
+        (GAMEBOARD, "Gameboard"),
+        (WALLET, "Wallet"),
+    ]
+
+    slug = models.SlugField(unique=True)
+    name = models.CharField(max_length=100)
+    context = models.CharField(max_length=20, choices=CONTEXT_CHOICES, default=DASHBOARD)
+    default_visible = models.BooleanField(default=True)
+    grid_cols = models.PositiveSmallIntegerField(default=12)
+    grid_rows = models.PositiveSmallIntegerField(default=3)
+
+    def __str__(self):
+        return self.name
+    
+class UserApplet(models.Model):
+    user = models.ForeignKey(
+        "lyric.User",
+        related_name="user_applets",
+        on_delete=models.CASCADE,
+    )
+    applet = models.ForeignKey(
+        Applet,
+        on_delete=models.CASCADE,
+    )
+    visible = models.BooleanField(default=True)
+
+    class Meta:
+        unique_together = ("user", "applet")

src/apps/applets/static/apps/applets/applets.js

@@ -0,0 +1,41 @@
+const initGearMenus = () => {
+    document.querySelectorAll('.gear-btn').forEach(gear => {
+        const menuId = gear.dataset.menuTarget;
+
+        gear.addEventListener('click', (e) => {
+            e.stopPropagation();
+            const menu = document.getElementById(menuId);
+            if (!menu) return;
+            const opening = menu.style.display === 'none' || menu.style.display === '';
+            menu.style.display = opening ? 'block' : 'none';
+            gear.classList.toggle('active', opening);
+        });
+
+        document.addEventListener('click', (e) => {
+            const menu = document.getElementById(menuId);
+            if (!menu || menu.style.display === 'none') return;
+            if (e.target.closest('.applet-menu-cancel') || !menu.contains(e.target)) {
+                menu.style.display = 'none';
+                gear.classList.remove('active');
+            }
+        });
+    })
+
+};
+
+document.addEventListener('DOMContentLoaded', initGearMenus);
+
+const appletContainerIds = new Set([
+    'id_applets_container',
+    'id_game_applets_container',
+    'id_wallet_applets_container',
+]);
+
+document.body.addEventListener('htmx:afterSwap', (e) => {
+    if (!e.detail.target || !appletContainerIds.has(e.detail.target.id)) return;
+    document.querySelectorAll('.gear-btn').forEach(gear => {
+        const menu = document.getElementById(gear.dataset.menuTarget);
+        if (menu) menu.style.display = 'none';
+        gear.classList.remove('active');
+    });
+});

src/apps/applets/tests/integrated/test_models.py

@@ -0,0 +1,65 @@
+from django.db.utils import IntegrityError
+from django.test import TestCase
+
+from apps.applets.models import Applet, UserApplet
+from apps.applets.utils import applet_context
+from apps.lyric.models import User
+
+
+class AppletModelTest(TestCase):
+    def setUp(self):
+        self.applet = Applet.objects.create(
+            slug="my-applet", name="My Applet", default_visible=True
+        )
+
+    def test_applet_can_be_created(self):
+        self.assertEqual(Applet.objects.get(slug="my-applet"), self.applet)
+
+    def test_applet_slug_is_unique(self):
+        with self.assertRaises(IntegrityError):
+            Applet.objects.create(slug="my-applet", name="Second")
+
+    def test_applet_str(self):
+        self.assertEqual(str(self.applet), "My Applet")
+
+    def test_applet_grid_defaults(self):
+        self.assertEqual(self.applet.grid_cols, 12)
+        self.assertEqual(self.applet.grid_rows, 3)
+
+
+class UserAppletModelTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="a@b.cde")
+        self.applet, _ = Applet.objects.get_or_create(slug="username", defaults={"name": "Username"})
+
+    def test_user_applet_links_user_to_applet(self):
+        ua = UserApplet.objects.create(user=self.user, applet=self.applet, visible=True)
+        self.assertIn(ua, self.user.user_applets.all())
+
+    def test_user_applet_unique_per_user_and_applet(self):
+        UserApplet.objects.create(user=self.user, applet=self.applet, visible=True)
+        with self.assertRaises(IntegrityError):
+            UserApplet.objects.create(user=self.user, applet=self.applet, visible=False)
+
+class AppletContextTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="a@b.cde")
+        self.dash_applet, _ = Applet.objects.get_or_create(slug="username", defaults={"name": "Username", "context": "dashboard"})
+        self.game_applet, _ = Applet.objects.get_or_create(slug="new-game", defaults={"name": "New Game", "context": "gameboard"})
+    
+    def test_filters_by_context(self):
+        result = applet_context(self.user, "dashboard")
+        slugs = [e["applet"].slug for e in result]
+        self.assertIn("username", slugs)
+        self.assertNotIn("new-game", slugs)
+
+    def test_defaults_to_applet_default_visible(self):
+        result = applet_context(self.user, "dashboard")
+        [entry] = [e for e in result if e["applet"].slug == "username"]
+        self.assertTrue(entry["visible"])
+
+    def test_respects_user_applet_visible_false(self):
+        UserApplet.objects.create(user=self.user, applet=self.dash_applet, visible=False)
+        result = applet_context(self.user, "dashboard")
+        [entry] = [e for e in result if e["applet"].slug == "username"]
+        self.assertFalse(entry["visible"])

src/apps/applets/utils.py

@@ -0,0 +1,11 @@
+from apps.applets.models import Applet, UserApplet
+
+
+def applet_context(user, context):
+    ua_map = {ua.applet_id: ua.visible for ua in user.user_applets.all()}
+    applets = {a.slug: a for a in Applet.objects.filter(context=context)}
+    return [
+        {"applet": applets[slug], "visible": ua_map.get(applets[slug].pk, applets[slug].default_visible)}
+        for slug in applets
+        if slug in applets
+    ]

src/apps/dashboard/admin.py

@@ -1,3 +1 @@
 from django.contrib import admin
-
-# Register your models here.

src/apps/dashboard/forms.py

@@ -2,8 +2,8 @@ from django import forms
 from django.core.exceptions import ValidationError
 from .models import Item
 
-DUPLICATE_ITEM_ERROR = "You've already logged this to your list"
+DUPLICATE_ITEM_ERROR = "You've already logged this to your note"
-EMPTY_ITEM_ERROR = "You can't have an empty list item"
+EMPTY_ITEM_ERROR = "You can't have an empty note item"
 
 class ItemForm(forms.Form):
     text = forms.CharField(
@@ -11,22 +11,22 @@ class ItemForm(forms.Form):
         required=True,
     )
 
-    def save(self, for_list):
+    def save(self, for_note):
         return Item.objects.create(
-            list=for_list,
+            note=for_note,
             text=self.cleaned_data["text"],
         )
 
-class ExistingListItemForm(ItemForm):
+class ExistingNoteItemForm(ItemForm):
-    def __init__(self, for_list, *args, **kwargs):
+    def __init__(self, for_note, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        self._for_list = for_list
+        self._for_note = for_note
 
     def clean_text(self):
         text = self.cleaned_data["text"]
-        if self._for_list.item_set.filter(text=text).exists():
+        if self._for_note.item_set.filter(text=text).exists():
             raise forms.ValidationError(DUPLICATE_ITEM_ERROR)
         return text
-    
+
     def save(self):
-        return super().save(for_list=self._for_list)
+        return super().save(for_note=self._for_note)

src/apps/dashboard/migrations/0001_initial.py

@@ -1,6 +1,8 @@
-# Generated by Django 6.0 on 2026-02-08 01:19
+# Generated by Django 6.0 on 2026-02-23 04:30
 
 import django.db.models.deletion
+import uuid
+from django.conf import settings
 from django.db import migrations, models
 
 
@@ -9,13 +11,16 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
     operations = [
         migrations.CreateModel(
             name='List',
             fields=[
-                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('owner', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='lists', to=settings.AUTH_USER_MODEL)),
+                ('shared_with', models.ManyToManyField(blank=True, related_name='shared_lists', to=settings.AUTH_USER_MODEL)),
             ],
         ),
         migrations.CreateModel(

src/apps/dashboard/migrations/0002_list_owner.py

@@ -1,21 +0,0 @@
-# Generated by Django 6.0 on 2026-02-09 03:29
-
-import django.db.models.deletion
-from django.conf import settings
-from django.db import migrations, models
-
-
-class Migration(migrations.Migration):
-
-    dependencies = [
-        ('dashboard', '0001_initial'),
-        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
-    ]
-
-    operations = [
-        migrations.AddField(
-            model_name='list',
-            name='owner',
-            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='lists', to=settings.AUTH_USER_MODEL),
-        ),
-    ]

src/apps/dashboard/migrations/0002_rename_list_to_note.py

@@ -0,0 +1,20 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dashboard', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.RenameModel(
+            old_name='List',
+            new_name='Note',
+        ),
+        migrations.RenameField(
+            model_name='Item',
+            old_name='list',
+            new_name='note',
+        ),
+    ]

src/apps/dashboard/migrations/0003_alter_note_owner_alter_note_shared_with.py

@@ -0,0 +1,26 @@
+# Generated by Django 6.0 on 2026-03-12 19:30
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dashboard', '0002_rename_list_to_note'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='note',
+            name='owner',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='notes', to=settings.AUTH_USER_MODEL),
+        ),
+        migrations.AlterField(
+            model_name='note',
+            name='shared_with',
+            field=models.ManyToManyField(blank=True, related_name='shared_notes', to=settings.AUTH_USER_MODEL),
+        ),
+    ]

src/apps/dashboard/migrations/0003_list_shared_with.py

@@ -1,20 +0,0 @@
-# Generated by Django 6.0 on 2026-02-18 18:13
-
-from django.conf import settings
-from django.db import migrations, models
-
-
-class Migration(migrations.Migration):
-
-    dependencies = [
-        ('dashboard', '0002_list_owner'),
-        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
-    ]
-
-    operations = [
-        migrations.AddField(
-            model_name='list',
-            name='shared_with',
-            field=models.ManyToManyField(blank=True, related_name='shared_lists', to=settings.AUTH_USER_MODEL),
-        ),
-    ]

src/apps/dashboard/models.py

@@ -1,10 +1,14 @@
+import uuid
+
 from django.db import models
 from django.urls import reverse
 
-class List(models.Model):
+
+class Note(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     owner = models.ForeignKey(
         "lyric.User",
-        related_name="lists",
+        related_name="notes",
         blank=True,
         null=True,
         on_delete=models.CASCADE,
@@ -12,7 +16,7 @@ class List(models.Model):
 
     shared_with = models.ManyToManyField(
         "lyric.User",
-        related_name="shared_lists",
+        related_name="shared_notes",
         blank=True,
     )
 
@@ -21,16 +25,15 @@ class List(models.Model):
         return self.item_set.first().text
 
     def get_absolute_url(self):
-        return reverse("view_list", args=[self.id])
+        return reverse("view_note", args=[self.id])
 
 class Item(models.Model):
     text = models.TextField(default="")
-    list = models.ForeignKey(List, default=None, on_delete=models.CASCADE)
+    note = models.ForeignKey(Note, default=None, on_delete=models.CASCADE)
 
     class Meta:
         ordering = ("id",)
-        unique_together = ("list", "text")
+        unique_together = ("note", "text")
 
     def __str__(self):
         return self.text
-    

src/apps/dashboard/static/apps/dashboard/dashboard.js

@@ -2,8 +2,9 @@
 const initialize = (inputSelector) => {
     // console.log("initialize called!");
     const textInput = document.querySelector(inputSelector);
+    if (!textInput) return;
     textInput.oninput = () => {
         // console.log("oninput triggered");
         textInput.classList.remove("is-invalid");
     };
-};
+};

src/apps/dashboard/static/apps/dashboard/game-kit.js

@@ -0,0 +1,91 @@
+(function () {
+    var btn = document.getElementById('id_kit_btn');
+    var dialog = document.getElementById('id_kit_bag_dialog');
+    if (!btn || !dialog) return;
+
+    btn.addEventListener('click', function () {
+        if (dialog.hasAttribute('open')) {
+            dialog.removeAttribute('open');
+            btn.classList.remove('active');
+            return;
+        }
+        fetch(btn.dataset.kitUrl, {
+            headers: { 'X-Requested-With': 'XMLHttpRequest' },
+        })
+            .then(function (r) { return r.text(); })
+            .then(function (html) {
+                dialog.innerHTML = html;
+                attachCardListeners();
+                btn.classList.add('active');
+                dialog.setAttribute('open', '');
+            })
+            .catch(function () {
+                btn.classList.remove('active');
+            });
+    });
+
+    // Escape key
+    document.addEventListener('keydown', function (e) {
+        if (e.key === 'Escape' && dialog.hasAttribute('open')) {
+            dialog.removeAttribute('open');
+            btn.classList.remove('active');
+        }
+    });
+
+    // Click outside (but not on the rails button — let that flow through)
+    document.addEventListener('click', function (e) {
+        if (!dialog.hasAttribute('open')) return;
+        if (dialog.contains(e.target)) return;
+        if (e.target === btn || btn.contains(e.target)) return;
+        if (e.target.closest('button.token-rails')) return;
+        dialog.removeAttribute('open');
+        btn.classList.remove('active');
+    });
+
+    // Inject token_id before token-rails form submits
+    document.addEventListener('click', function (e) {
+        var rails = e.target.closest('button.token-rails');
+        if (!rails || !window._kitTokenId) return;
+        var form = rails.closest('form');
+        if (!form) return;
+        var existing = form.querySelector('input[name="token_id"]');
+        if (existing) existing.remove();
+        var hidden = document.createElement('input');
+        hidden.type = 'hidden';
+        hidden.name = 'token_id';
+        hidden.value = window._kitTokenId;
+        form.appendChild(hidden);
+        if (dialog.hasAttribute('open')) dialog.removeAttribute('open');
+    });
+
+    function attachCardListeners() {
+        dialog.querySelectorAll('.token[data-token-id]').forEach(function (card) {
+            card.addEventListener('click', function () {
+                dialog.querySelectorAll('.token[data-token-id].selected').forEach(function (c) {
+                    c.classList.remove('selected');
+                });
+                card.classList.add('selected');
+                window._kitTokenId = card.dataset.tokenId;
+                var slot = document.querySelector('.token-slot');
+                if (slot) slot.classList.add('ready');
+            });
+
+            card.addEventListener('mouseenter', function () {
+                var tooltip = card.querySelector('.token-tooltip');
+                if (!tooltip) return;
+                var rect = card.getBoundingClientRect();
+                tooltip.style.position = 'fixed';
+                tooltip.style.bottom = (window.innerHeight - rect.top + 8) + 'px';
+                tooltip.style.left = rect.left + 'px';
+                tooltip.style.display = 'block';
+            });
+
+            card.addEventListener('mouseleave', function () {
+                var tooltip = card.querySelector('.token-tooltip');
+                if (tooltip) tooltip.style.display = '';
+            });
+        });
+    }
+
+
+}());

src/apps/dashboard/static/apps/dashboard/wallet.js

@@ -0,0 +1,116 @@
+const initWallet = () => {
+    let stripe, elements;
+
+    const addBtn = document.getElementById('id_add_payment_method');
+    const saveBtn = document.getElementById('id_save_payment_method');
+    const cancelBtn = document.getElementById('id_cancel_payment_method');
+    if (!addBtn) return;
+
+    const getCsrf = () => document.cookie.match(/csrftoken=([^;]+)/)[1];
+
+    addBtn.addEventListener('click', async () => {
+        const res = await fetch('/dashboard/wallet/setup-intent', {
+            method: 'POST',
+            headers: {'X-CSRFToken': getCsrf()},
+        });
+        const {client_secret, publishable_key} = await res.json();
+        stripe = Stripe(publishable_key);
+        elements = stripe.elements({clientSecret: client_secret});
+        const paymentEl = elements.create('payment');
+        paymentEl.mount('#id_stripe_payment_element');
+        saveBtn.hidden = false;
+        cancelBtn.hidden = false;
+        const section = addBtn.closest('section');
+        const rowPx = 3 * parseFloat(getComputedStyle(document.documentElement).fontSize);
+        const updateRows = () => {
+            const sectionTop = section.getBoundingClientRect().top;
+            let maxBottom = sectionTop;
+            for (const child of section.children) {
+                if (child.hidden) continue;
+                maxBottom = Math.max(maxBottom, child.getBoundingClientRect().bottom);
+            }
+            const padBot = parseFloat(getComputedStyle(section).paddingBottom);
+            const rows = Math.ceil((maxBottom - sectionTop + padBot) / rowPx) + 1;
+            section.style.setProperty('--applet-rows', String(rows));
+        };
+        paymentEl.on('ready', () => {
+            updateRows();
+            const stripeContainer = document.getElementById('id_stripe_payment_element');
+            if (stripeContainer) {
+                const obs = new ResizeObserver(updateRows);
+                obs.observe(stripeContainer);
+                section._stripeObs = obs;
+            }
+        });
+    });
+
+    saveBtn.addEventListener('click', async () => {
+        const {error, setupIntent} = await stripe.confirmSetup({
+            elements,
+            redirect: 'if_required',
+        });
+        if (error) { console.error(error); return; }
+        const res = await fetch('/dashboard/wallet/save-payment-method', {
+            method: 'POST',
+            headers: {
+                'X-CSRFToken': getCsrf(),
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: `payment_method_id=${setupIntent.payment_method}`,
+        });
+        const {last4, brand} = await res.json();
+        const pm = document.createElement('div');
+        pm.textContent = `${brand} ····${last4}`;
+        document.getElementById('id_payment_methods').appendChild(pm);
+        elements.getElement('payment').unmount();
+        elements = null;
+        stripe = null;
+        saveBtn.hidden = true;
+        cancelBtn.hidden = true;
+        const section = cancelBtn.closest('section');
+        section.style.setProperty('--applet-rows', '2');
+        if (section._stripeObs) { section._stripeObs.disconnect(); section._stripeObs = null; }
+    });
+
+    cancelBtn.addEventListener('click', () => {
+        if (elements) {
+            elements.getElement('payment').unmount();
+            elements = null;
+            stripe = null;
+        }
+        saveBtn.hidden = true;
+        cancelBtn.hidden = true;
+        const section = cancelBtn.closest('section');
+        section.style.setProperty('--applet-rows', '2');
+        if (section._stripeObs) { section._stripeObs.disconnect(); section._stripeObs = null; }
+    });
+};
+
+function initWalletTooltips() {
+    const portal = document.getElementById('id_tooltip_portal');
+    if (!portal) return;
+
+    document.querySelectorAll('.wallet-tokens .token').forEach(token => {
+        const tooltip = token.querySelector('.token-tooltip');
+        if (!tooltip) return;
+
+        token.addEventListener('mouseenter', () => {
+            const rect = token.getBoundingClientRect();
+            portal.innerHTML = tooltip.innerHTML;
+            portal.classList.add('active');
+            const halfW = portal.offsetWidth / 2;
+            const rawLeft = rect.left + rect.width / 2;
+            const clampedLeft = Math.max(halfW + 8, Math.min(rawLeft, window.innerWidth - halfW - 8));
+            portal.style.left = Math.round(clampedLeft) + 'px';
+            portal.style.top = Math.round(rect.top) + 'px';
+            portal.style.transform = 'translate(-50%, calc(-100% - 0.5rem))';
+        });
+
+        token.addEventListener('mouseleave', () => {
+            portal.classList.remove('active');
+        });
+    });
+}
+
+document.addEventListener('DOMContentLoaded', initWallet);
+document.addEventListener('DOMContentLoaded', initWalletTooltips);

src/apps/dashboard/tests/integrated/test_forms.py

@@ -3,39 +3,39 @@ from django.test import TestCase
 from apps.dashboard.forms import (
     DUPLICATE_ITEM_ERROR,
     EMPTY_ITEM_ERROR,
-    ExistingListItemForm,
+    ExistingNoteItemForm,
     ItemForm,
 )
-from apps.dashboard.models import Item, List
+from apps.dashboard.models import Item, Note
 
 
 class ItemFormTest(TestCase):
-    def test_form_save_handles_saving_to_a_list(self):
+    def test_form_save_handles_saving_to_a_note(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
         form = ItemForm(data={"text": "do re mi"})
         self.assertTrue(form.is_valid())
-        new_item = form.save(for_list=mylist)
+        new_item = form.save(for_note=mynote)
         self.assertEqual(new_item, Item.objects.get())
         self.assertEqual(new_item.text, "do re mi")
-        self.assertEqual(new_item.list, mylist)
+        self.assertEqual(new_item.note, mynote)
 
-class ExistingListItemFormTest(TestCase):
+class ExistingNoteItemFormTest(TestCase):
     def test_form_validation_for_blank_items(self):
-        list_ = List.objects.create()
+        note = Note.objects.create()
-        form = ExistingListItemForm(for_list=list_, data={"text": ""})
+        form = ExistingNoteItemForm(for_note=note, data={"text": ""})
         self.assertFalse(form.is_valid())
         self.assertEqual(form.errors["text"], [EMPTY_ITEM_ERROR])
 
     def test_form_validation_for_duplicate_items(self):
-        list_ = List.objects.create()
+        note = Note.objects.create()
-        Item.objects.create(list=list_, text="twins, basil")
+        Item.objects.create(note=note, text="twins, basil")
-        form = ExistingListItemForm(for_list=list_, data={"text": "twins, basil"})
+        form = ExistingNoteItemForm(for_note=note, data={"text": "twins, basil"})
         self.assertFalse(form.is_valid())
         self.assertEqual(form.errors["text"], [DUPLICATE_ITEM_ERROR])
 
     def test_form_save(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
-        form = ExistingListItemForm(for_list=mylist, data={"text": "howdy"})
+        form = ExistingNoteItemForm(for_note=mynote, data={"text": "howdy"})
         self.assertTrue(form.is_valid())
         new_item = form.save()
         self.assertEqual(new_item, Item.objects.get())

src/apps/dashboard/tests/integrated/test_models.py

@@ -2,69 +2,69 @@ from django.core.exceptions import ValidationError
 from django.db.utils import IntegrityError
 from django.test import TestCase
 
-from apps.dashboard.models import Item, List
+from apps.dashboard.models import Item, Note
 from apps.lyric.models import User
 
 
 class ItemModelTest(TestCase):
-    def test_item_is_related_to_list(self):
+    def test_item_is_related_to_note(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
         item = Item()
-        item.list = mylist
+        item.note = mynote
         item.save()
-        self.assertIn(item, mylist.item_set.all())
+        self.assertIn(item, mynote.item_set.all())
 
-    def test_cannot_save_null_list_items(self):
+    def test_cannot_save_null_note_items(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
-        item = Item(list=mylist, text=None)
+        item = Item(note=mynote, text=None)
         with self.assertRaises(IntegrityError):
             item.save()
 
-    def test_cannot_save_empty_list_items(self):
+    def test_cannot_save_empty_note_items(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
-        item = Item(list=mylist, text="")
+        item = Item(note=mynote, text="")
         with self.assertRaises(ValidationError):
             item.full_clean()
 
     def test_duplicate_items_are_invalid(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
-        Item.objects.create(list=mylist, text="jklol")
+        Item.objects.create(note=mynote, text="jklol")
         with self.assertRaises(ValidationError):
-            item = Item(list=mylist, text="jklol")
+            item = Item(note=mynote, text="jklol")
             item.full_clean()
 
-    def test_still_can_save_same_item_to_different_lists(self):
+    def test_still_can_save_same_item_to_different_notes(self):
-        list1 = List.objects.create()
+        note1 = Note.objects.create()
-        list2 = List.objects.create()
+        note2 = Note.objects.create()
-        Item.objects.create(list=list1, text="nojk")
+        Item.objects.create(note=note1, text="nojk")
-        item = Item(list=list2, text="nojk")
+        item = Item(note=note2, text="nojk")
         item.full_clean() # should not raise
 
-class ListModelTest(TestCase):
+class NoteModelTest(TestCase):
         def test_get_absolute_url(self):
-            mylist = List.objects.create()
+            mynote = Note.objects.create()
-            self.assertEqual(mylist.get_absolute_url(), f"/apps/dashboard/{mylist.id}/")
+            self.assertEqual(mynote.get_absolute_url(), f"/dashboard/note/{mynote.id}/")
 
-        def test_list_items_order(self):
+        def test_note_items_order(self):
-            list1 = List.objects.create()
+            note1 = Note.objects.create()
-            item1 = Item.objects.create(list=list1, text="i1")
+            item1 = Item.objects.create(note=note1, text="i1")
-            item2 = Item.objects.create(list=list1, text="item 2")
+            item2 = Item.objects.create(note=note1, text="item 2")
-            item3 = Item.objects.create(list=list1, text="3")
+            item3 = Item.objects.create(note=note1, text="3")
             self.assertEqual(
-                list(list1.item_set.all()),
+                list(note1.item_set.all()),
                 [item1, item2, item3],
             )
 
-        def test_lists_can_have_owners(self):
+        def test_notes_can_have_owners(self):
             user = User.objects.create(email="a@b.cde")
-            mylist = List.objects.create(owner=user)
+            mynote = Note.objects.create(owner=user)
-            self.assertIn(mylist, user.lists.all())
+            self.assertIn(mynote, user.notes.all())
 
-        def test_list_owner_is_optional(self):
+        def test_note_owner_is_optional(self):
-            List.objects.create()
+            Note.objects.create()
 
-        def test_list_name_is_first_item_text(self):
+        def test_note_name_is_first_item_text(self):
-            list_ = List.objects.create()
+            note = Note.objects.create()
-            Item.objects.create(list=list_, text="first item")
+            Item.objects.create(note=note, text="first item")
-            Item.objects.create(list=list_, text="second item")
+            Item.objects.create(note=note, text="second item")
-            self.assertEqual(list_.name, "first item")
+            self.assertEqual(note.name, "first item")

src/apps/dashboard/tests/integrated/test_stripe_views.py

@@ -0,0 +1,79 @@
+from unittest import mock
+from django.test import TestCase
+
+from apps.lyric.models import PaymentMethod, User
+
+
+class SetupIntentViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="capman@test.io")
+        self.client.force_login(self.user)
+
+    def test_setup_intent_requires_login(self):
+        self.client.logout()
+        response = self.client.post("/dashboard/wallet/setup-intent")
+        self.assertRedirects(
+            response, "/?next=/dashboard/wallet/setup-intent",
+            fetch_redirect_response=False,
+        )
+
+    @mock.patch("apps.dashboard.views.stripe")
+    def test_returns_client_secret(self, mock_stripe):
+        mock_stripe.Customer.create.return_value = mock.Mock(id="cus_test123")
+        mock_stripe.SetupIntent.create.return_value = mock.Mock(client_secret="seti_secret")
+        response = self.client.post("/dashboard/wallet/setup-intent")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["client_secret"], "seti_secret")
+        self.assertIn("publishable_key", response.json())
+
+    @mock.patch("apps.dashboard.views.stripe")
+    def test_reuses_existing_stripe_customer(self, mock_stripe):
+        self.user.stripe_customer_id = "cus_existing"
+        self.user.save()
+        mock_stripe.SetupIntent.create.return_value = mock.Mock(client_secret="seti_secret")
+        self.client.post("/dashboard/wallet/setup-intent")
+        mock_stripe.Customer.create.assert_not_called()
+        mock_stripe.SetupIntent.create.assert_called_once_with(customer="cus_existing")
+
+class SavePaymentMethodViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="capman@test.io")
+        self.user.stripe_customer_id = "cus_test123"
+        self.user.save()
+        self.client.force_login(self.user)
+
+    def test_save_payment_method_requires_login(self):
+        self.client.logout()
+        response = self.client.post(
+            "/dashboard/wallet/save-payment-method", {"payment_method_id": "pm_test"}
+        )
+        self.assertRedirects(
+            response, "/?next=/dashboard/wallet/save-payment-method",
+            fetch_redirect_response=False,
+        )
+
+    @mock.patch("apps.dashboard.views.stripe")
+    def test_creates_payment_method_record(self, mock_stripe):
+        mock_stripe.PaymentMethod.retrieve.return_value = mock.Mock(
+            card=mock.Mock(last4="4242", brand="visa")
+        )
+        self.client.post(
+            "/dashboard/wallet/save-payment-method",
+            {"payment_method_id": "pm_test123"},
+        )
+        pm = PaymentMethod.objects.get(user=self.user)
+        self.assertEqual(pm.last4, "4242")
+        self.assertEqual(pm.brand, "visa")
+
+    @mock.patch("apps.dashboard.views.stripe")
+    def test_returns_json_with_last4_and_brand(self, mock_stripe):
+        mock_stripe.PaymentMethod.retrieve.return_value = mock.Mock(
+            card=mock.Mock(last4="4242", brand="visa")
+        )
+        response = self.client.post(
+            "/dashboard/wallet/save-payment-method",
+            {"payment_method_id": "pm_test123"},
+        )
+        data = response.json()
+        self.assertEqual(data["last4"], "4242")
+        self.assertEqual(data["brand"], "visa")

src/apps/dashboard/tests/integrated/test_views.py

@@ -1,18 +1,25 @@
 import lxml.html
-from unittest import skip
 
-from django.test import TestCase
+from django.contrib.messages import get_messages
+from django.test import override_settings, TestCase
+from django.urls import reverse
 from django.utils import html
 
+from apps.applets.models import Applet, UserApplet
 from apps.dashboard.forms import (
     DUPLICATE_ITEM_ERROR,
     EMPTY_ITEM_ERROR,
 )
-from apps.dashboard.models import Item, List
+from apps.dashboard.models import Item, Note
 from apps.lyric.models import User
 
 
 class HomePageTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="disco@test.io")
+        self.client.force_login(self.user)
+        Applet.objects.get_or_create(slug="new-note", defaults={"name": "New Note"})
+
     def test_uses_home_template(self):
         response = self.client.get('/')
         self.assertTemplateUsed(response, 'apps/dashboard/home.html')
@@ -21,32 +28,36 @@ class HomePageTest(TestCase):
         response = self.client.get('/')
         parsed = lxml.html.fromstring(response.content)
         forms = parsed.cssselect('form[method=POST]')
-        self.assertIn("/apps/dashboard/new_list", [form.get("action") for form in forms])
+        self.assertIn("/dashboard/new_note", [form.get("action") for form in forms])
-        [form] = [form for form in forms if form.get("action") == "/apps/dashboard/new_list"]
+        [form] = [form for form in forms if form.get("action") == "/dashboard/new_note"]
         inputs = form.cssselect("input")
         self.assertIn("text", [input.get("name") for input in inputs])
 
-class NewListTest(TestCase):
+class NewNoteTest(TestCase):
+    def setUp(self):
+        user = User.objects.create(email="disco@test.io")
+        self.client.force_login(user)
+
     def test_can_save_a_POST_request(self):
-        self. client.post("/apps/dashboard/new_list", data={"text": "A new list item"})
+        self.client.post("/dashboard/new_note", data={"text": "A new note item"})
         self.assertEqual(Item.objects.count(), 1)
         new_item = Item.objects.get()
-        self.assertEqual(new_item.text, "A new list item")
+        self.assertEqual(new_item.text, "A new note item")
 
     def test_redirects_after_POST(self):
-        response = self.client.post("/apps/dashboard/new_list", data={"text": "A new list item"})
+        response = self.client.post("/dashboard/new_note", data={"text": "A new note item"})
-        new_list = List.objects.get()
+        new_note = Note.objects.get()
-        self.assertRedirects(response, f"/apps/dashboard/{new_list.id}/")
+        self.assertRedirects(response, f"/dashboard/note/{new_note.id}/")
 
     # Post invalid input helper
     def post_invalid_input(self):
-        return self.client.post("/apps/dashboard/new_list", data={"text": ""})
+        return self.client.post("/dashboard/new_note", data={"text": ""})
 
     def test_for_invalid_input_nothing_saved_to_db(self):
         self.post_invalid_input()
         self.assertEqual(Item.objects.count(), 0)
 
-    def test_for_invalid_input_renders_list_template(self):
+    def test_for_invalid_input_renders_home_template(self):
         response = self.post_invalid_input()
         self.assertEqual(response.status_code, 200)
         self.assertTemplateUsed(response, "apps/dashboard/home.html")
@@ -55,15 +66,16 @@ class NewListTest(TestCase):
         response = self.post_invalid_input()
         self.assertContains(response, html.escape(EMPTY_ITEM_ERROR))
 
-class ListViewTest(TestCase):
+@override_settings(COMPRESS_ENABLED=False)
-    def test_uses_list_template(self):
+class NoteViewTest(TestCase):
-        mylist = List.objects.create()
+    def test_uses_note_template(self):
-        response = self.client.get(f"/apps/dashboard/{mylist.id}/")
+        mynote = Note.objects.create()
-        self.assertTemplateUsed(response, "apps/dashboard/list.html")
+        response = self.client.get(f"/dashboard/note/{mynote.id}/")
+        self.assertTemplateUsed(response, "apps/dashboard/note.html")
 
     def test_renders_input_form(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
-        url = f"/apps/dashboard/{mylist.id}/"
+        url = f"/dashboard/note/{mynote.id}/"
         response = self.client.get(url)
         parsed = lxml.html.fromstring(response.content)
         forms = parsed.cssselect("form[method=POST]")
@@ -72,58 +84,58 @@ class ListViewTest(TestCase):
         inputs = form.cssselect("input")
         self.assertIn("text", [input.get("name") for input in inputs])
 
-    def test_displays_only_items_for_that_list(self):
+    def test_displays_only_items_for_that_note(self):
         # Given/Arrange
-        correct_list = List.objects.create()
+        correct_note = Note.objects.create()
-        Item.objects.create(text="itemey 1", list=correct_list)
+        Item.objects.create(text="itemey 1", note=correct_note)
-        Item.objects.create(text="itemey 2", list=correct_list)
+        Item.objects.create(text="itemey 2", note=correct_note)
-        other_list = List.objects.create()
+        other_note = Note.objects.create()
-        Item.objects.create(text="other list item", list=other_list)
+        Item.objects.create(text="other note item", note=other_note)
         # When/Act
-        response = self.client.get(f"/apps/dashboard/{correct_list.id}/")
+        response = self.client.get(f"/dashboard/note/{correct_note.id}/")
         # Then/Assert
         self.assertContains(response, "itemey 1")
         self.assertContains(response, "itemey 2")
-        self.assertNotContains(response, "other list item")
+        self.assertNotContains(response, "other note item")
 
-    def test_can_save_a_POST_request_to_an_existing_list(self):
+    def test_can_save_a_POST_request_to_an_existing_note(self):
-        other_list = List.objects.create()
+        other_note = Note.objects.create()
-        correct_list = List.objects.create()
+        correct_note = Note.objects.create()
 
         self.client.post(
-            f"/apps/dashboard/{correct_list.id}/",
+            f"/dashboard/note/{correct_note.id}/",
-            data={"text": "A new item for an existing list"},
+            data={"text": "A new item for an existing note"},
         )
 
         self.assertEqual(Item.objects.count(), 1)
         new_item = Item.objects.get()
-        self.assertEqual(new_item.text, "A new item for an existing list")
+        self.assertEqual(new_item.text, "A new item for an existing note")
-        self.assertEqual(new_item.list, correct_list)
+        self.assertEqual(new_item.note, correct_note)
 
-    def test_POST_redirects_to_list_view(self):
+    def test_POST_redirects_to_note_view(self):
-        other_list = List.objects.create()
+        other_note = Note.objects.create()
-        correct_list = List.objects.create()
+        correct_note = Note.objects.create()
 
         response = self.client.post(
-            f"/apps/dashboard/{correct_list.id}/",
+            f"/dashboard/note/{correct_note.id}/",
-            data={"text": "A new item for an existing list"},
+            data={"text": "A new item for an existing note"},
         )
 
-        self.assertRedirects(response, f"/apps/dashboard/{correct_list.id}/")
+        self.assertRedirects(response, f"/dashboard/note/{correct_note.id}/")
 
     # Post invalid input helper
     def post_invalid_input(self):
-        mylist = List.objects.create()
+        mynote = Note.objects.create()
-        return self.client.post(f"/apps/dashboard/{mylist.id}/", data={"text": ""})
+        return self.client.post(f"/dashboard/note/{mynote.id}/", data={"text": ""})
 
     def test_for_invalid_input_nothing_saved_to_db(self):
         self.post_invalid_input()
         self.assertEqual(Item.objects.count(), 0)
 
-    def test_for_invalid_input_renders_list_template(self):
+    def test_for_invalid_input_renders_note_template(self):
         response = self.post_invalid_input()
         self.assertEqual(response.status_code, 200)
-        self.assertTemplateUsed(response, "apps/dashboard/list.html")
+        self.assertTemplateUsed(response, "apps/dashboard/note.html")
 
     def test_for_invalid_input_shows_error_on_page(self):
         response = self.post_invalid_input()
@@ -135,78 +147,320 @@ class ListViewTest(TestCase):
         [input] = parsed.cssselect("input[name=text]")
         self.assertIn("is-invalid", set(input.classes))
 
-    def test_duplicate_item_validation_errors_end_up_on_lists_page(self):
+    def test_duplicate_item_validation_errors_end_up_on_note_page(self):
-        list1 = List.objects.create()
+        note1 = Note.objects.create()
-        Item.objects.create(list=list1, text="lorem ipsum")
+        Item.objects.create(note=note1, text="lorem ipsum")
 
         response = self.client.post(
-            f"/apps/dashboard/{list1.id}/",
+            f"/dashboard/note/{note1.id}/",
             data={"text": "lorem ipsum"},
         )
 
         expected_error = html.escape(DUPLICATE_ITEM_ERROR)
         self.assertContains(response, expected_error)
-        self.assertTemplateUsed(response, "apps/dashboard/list.html")
+        self.assertTemplateUsed(response, "apps/dashboard/note.html")
         self.assertEqual(Item.objects.all().count(), 1)
 
-class MyListsTest(TestCase):
+class MyNotesTest(TestCase):
-    def test_my_lists_url_renders_my_lists_template(self):
+    def test_my_notes_url_renders_my_notes_template(self):
         user = User.objects.create(email="a@b.cde")
         self.client.force_login(user)
-        response = self.client.get(f"/apps/dashboard/users/{user.id}/")
+        response = self.client.get(f"/dashboard/users/{user.id}/")
-        self.assertTemplateUsed(response, "apps/dashboard/my_lists.html")
+        self.assertTemplateUsed(response, "apps/dashboard/my_notes.html")
 
     def test_passes_correct_owner_to_template(self):
         User.objects.create(email="wrongowner@example.com")
         correct_user = User.objects.create(email="a@b.cde")
         self.client.force_login(correct_user)
-        response = self.client.get(f"/apps/dashboard/users/{correct_user.id}/")
+        response = self.client.get(f"/dashboard/users/{correct_user.id}/")
         self.assertEqual(response.context["owner"], correct_user)
 
-    def test_list_owner_is_saved_if_user_is_authenticated(self):
+    def test_note_owner_is_saved_if_user_is_authenticated(self):
         user = User.objects.create(email="a@b.cde")
         self.client.force_login(user)
-        self.client.post("/apps/dashboard/new_list", data={"text": "new item"})
+        self.client.post("/dashboard/new_note", data={"text": "new item"})
-        new_list = List.objects.get()
+        new_note = Note.objects.get()
-        self.assertEqual(new_list.owner, user)
+        self.assertEqual(new_note.owner, user)
 
-    def test_my_lists_redirects_if_not_logged_in(self):
+    def test_my_notes_redirects_if_not_logged_in(self):
         user  = User.objects.create(email="a@b.cde")
-        response = self.client.get(f"/apps/dashboard/users/{user.id}/")
+        response = self.client.get(f"/dashboard/users/{user.id}/")
         self.assertRedirects(response, "/")
 
-    def test_my_lists_returns_403_for_wrong_user(self):
+    def test_my_notes_returns_403_for_wrong_user(self):
-        # create two users, login as user_a, request user_b's my_lists url
+        # create two users, login as user_a, request user_b's my_notes url
         user1 = User.objects.create(email="a@b.cde")
         user2 = User.objects.create(email="wrongowner@example.com")
         self.client.force_login(user2)
-        response = self.client.get(f"/apps/dashboard/users/{user1.id}/")
+        response = self.client.get(f"/dashboard/users/{user1.id}/")
         # assert 403
         self.assertEqual(response.status_code, 403)
 
-class ShareListTest(TestCase):
+class ShareNoteTest(TestCase):
-    def test_post_to_share_list_url_redirects_to_list(self):
+    def test_post_to_share_note_url_redirects_to_note(self):
-        our_list = List.objects.create()
+        our_note = Note.objects.create()
         alice = User.objects.create(email="alice@example.com")
         response = self.client.post(
-            f"/apps/dashboard/{our_list.id}/share_list",
+            f"/dashboard/note/{our_note.id}/share_note",
             data={"recipient": "alice@example.com"},
         )
-        self.assertRedirects(response, f"/apps/dashboard/{our_list.id}/")
+        self.assertRedirects(response, f"/dashboard/note/{our_note.id}/")
 
     def test_post_with_email_adds_user_to_shared_with(self):
-        our_list = List.objects.create()
+        our_note = Note.objects.create()
         alice = User.objects.create(email="alice@example.com")
         self.client.post(
-            f"/apps/dashboard/{our_list.id}/share_list",
+            f"/dashboard/note/{our_note.id}/share_note",
             data={"recipient": "alice@example.com"},
         )
-        self.assertIn(alice, our_list.shared_with.all())
+        self.assertIn(alice, our_note.shared_with.all())
 
-    def test_post_with_nonexistent_email_redirects_to_list(self):
+    def test_post_with_nonexistent_email_redirects_to_note(self):
-        our_list = List.objects.create()
+        our_note = Note.objects.create()
         response = self.client.post(
-            f"/apps/dashboard/{our_list.id}/share_list",
+            f"/dashboard/note/{our_note.id}/share_note",
             data={"recipient": "nobody@example.com"},
         )
-        self.assertRedirects(response, f"/apps/dashboard/{our_list.id}/")
+        self.assertRedirects(
+            response,
+            f"/dashboard/note/{our_note.id}/",
+            fetch_redirect_response=False,
+        )
+
+    def test_share_note_does_not_add_owner_as_recipient(self):
+        owner = User.objects.create(email="owner@example.com")
+        our_note = Note.objects.create(owner=owner)
+        self.client.force_login(owner)
+        self.client.post(reverse("share_note", args=[our_note.id]),
+                         data={"recipient": "owner@example.com"})
+        self.assertNotIn(owner, our_note.shared_with.all())
+
+    @override_settings(MESSAGE_STORAGE='django.contrib.messages.storage.session.SessionStorage')
+    def test_share_note_shows_privacy_safe_message(self):
+        our_note = Note.objects.create()
+        response = self.client.post(
+            f"/dashboard/note/{our_note.id}/share_note",
+            data={"recipient": "nobody@example.com"},
+            follow=True,
+        )
+        messages = list(get_messages(response.wsgi_request))
+        self.assertEqual(
+            str(messages[0]),
+            "An invite has been sent if that address is registered.",
+        )
+
+class ViewAuthNoteTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="disco@example.com")
+        self.our_note = Note.objects.create(owner=self.owner)
+
+    def test_anonymous_user_is_redirected(self):
+        response = self.client.get(reverse("view_note", args=[self.our_note.id]))
+        self.assertRedirects(response, "/", fetch_redirect_response=False)
+
+    def test_non_owner_non_shared_user_gets_403(self):
+        stranger = User.objects.create(email="stranger@example.com")
+        self.client.force_login(stranger)
+        response = self.client.get(reverse("view_note", args=[self.our_note.id]))
+        self.assertEqual(response.status_code, 403)
+
+    def test_shared_with_user_can_access_note(self):
+        guest = User.objects.create(email="guest@example.com")
+        self.our_note.shared_with.add(guest)
+        self.client.force_login(guest)
+        response = self.client.get(reverse("view_note", args=[self.our_note.id]))
+        self.assertEqual(response.status_code, 200)
+
+@override_settings(COMPRESS_ENABLED=False)
+class SetPaletteTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="a@b.cde")
+        self.client.force_login(self.user)
+        self.url = reverse("home")
+        Applet.objects.get_or_create(slug="palette", defaults={"name": "Palette"})
+
+    def test_anonymous_user_is_redirected_home(self):
+        response = self.client.post("/dashboard/set_palette")
+        self.assertRedirects(response, "/", fetch_redirect_response=False)
+
+    def test_set_palette_updates_user_palette(self):
+        User.objects.filter(pk=self.user.pk).update(palette="palette-sheol")
+        self.client.post("/dashboard/set_palette", data={"palette": "palette-default"})
+        self.user.refresh_from_db()
+        self.assertEqual(self.user.palette, "palette-default")
+
+    def test_locked_palette_is_rejected(self):
+        response = self.client.post("/dashboard/set_palette", data={"palette": "palette-nirvana"})
+        self.user.refresh_from_db()
+        self.assertEqual(self.user.palette, "palette-default")
+        self.assertRedirects(response, "/", fetch_redirect_response=False)
+
+    def test_set_palette_redirects_home(self):
+        response = self.client.post("/dashboard/set_palette", data={"palette": "palette-default"})
+        self.assertRedirects(response, "/", fetch_redirect_response=False)
+
+    def test_dashboard_contains_set_palette_form(self):
+        response = self.client.get(self.url)
+        parsed = lxml.html.fromstring(response.content)
+        forms = parsed.cssselect('form[action="/dashboard/set_palette"]')
+        unlocked = [p for p in response.context["palettes"] if not p["locked"]]
+        self.assertEqual(len(forms), len(unlocked))
+
+    def test_active_palette_swatch_has_active_class(self):
+        response = self.client.get(self.url)
+        parsed = lxml.html.fromstring(response.content)
+        [active] = parsed.cssselect(".swatch.active")
+        self.assertIn("palette-default", active.classes)
+
+    def test_locked_palettes_are_not_forms(self):
+        response = self.client.get(self.url)
+        parsed = lxml.html.fromstring(response.content)
+        locked = parsed.cssselect(".swatch.locked")
+        expected_locked = [p for p in response.context["palettes"] if p["locked"]]
+        self.assertEqual(len(locked), len(expected_locked))
+        # they mustn't be button els
+        for swatch in locked:
+            self.assertNotEqual(swatch.tag, "button")
+
+    def test_palette_picker_count_matches_context(self):
+        response = self.client.get(self.url)
+        parsed = lxml.html.fromstring(response.content)
+        swatches = parsed.cssselect(".swatch")
+        self.assertEqual(len(swatches), len(response.context["palettes"]))
+
+@override_settings(COMPRESS_ENABLED=False)
+class ProfileViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="discoman@example.com")
+        self.client.force_login(self.user)
+
+    def test_post_username_saves_to_user(self):
+        self.client.post("/dashboard/set_profile", data={"username": "discoman"})
+        self.user.refresh_from_db()
+        self.assertEqual(self.user.username, "discoman")
+
+    def test_post_username_requires_login(self):
+        self.client.logout()
+        response = self.client.post("/dashboard/set_profile", data={"username": "somnambulist"})
+        self.assertRedirects(response, "/?next=/dashboard/set_profile", fetch_redirect_response=False)
+
+    def test_dash_renders_username_applet(self):
+        response = self.client.get("/")
+        parsed = lxml.html.fromstring(response.content)
+        [applet] = parsed.cssselect("#id_applet_username")
+        self.assertIn("@", applet.text_content())
+        [input_el] = parsed.cssselect("#id_new_username")
+        self.assertEqual("", input_el.get("value"))
+
+    def test_dash_shows_display_name_in_applet(self):
+        self.user.username = "discoman"
+        self.user.save()
+        response = self.client.get("/")
+        parsed = lxml.html.fromstring(response.content)
+        [username_input] = parsed.cssselect("#id_new_username")
+        self.assertEqual("discoman", username_input.get("value"))
+
+class ToggleDashAppletsViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="disco@test.io")
+        self.client.force_login(self.user)
+        self.username_applet, _ = Applet.objects.get_or_create(slug="username", defaults={"name": "Username"})
+        self.palette_applet, _ = Applet.objects.get_or_create(slug="palette", defaults={"name": "Palette"})
+        self.url = reverse("toggle_applets")
+
+    def test_unauthenticated_user_is_redirected(self):
+        self.client.logout()
+        response = self.client.post(self.url)
+        self.assertRedirects(
+            response, f"/?next={self.url}", fetch_redirect_response=False
+        )
+
+    def test_unchecked_applet_gets_user_applet_with_visible_false(self):
+        self.client.post(self.url, {"applets": ["username"]})
+        ua = UserApplet.objects.get(user=self.user, applet=self.palette_applet)
+        self.assertFalse(ua.visible)
+
+    def test_redirects_on_normal_post(self):
+        response = self.client.post(
+            self.url, {"applets": ["username", "palette"]}
+        )
+        self.assertRedirects(response, reverse("home"), fetch_redirect_response=False)
+
+    def test_returns_200_on_htmx_post(self):
+        response = self.client.post(
+            self.url,
+            {"applets": ["username", "palette"]},
+            HTTP_HX_REQUEST="true",
+        )
+        self.assertEqual(response.status_code, 200)
+
+    def test_htmx_post_renders_visible_applets_only(self):
+        response = self.client.post(
+            self.url,
+            {"applets": ["username"]},
+            HTTP_HX_REQUEST="true",
+        )
+        parsed = lxml.html.fromstring(response.content)
+        self.assertEqual(len(parsed.cssselect("#id_applet_username")), 1)
+        self.assertEqual(len(parsed.cssselect("#id_applet_palette")), 0)
+
+    def test_toggle_applets_does_not_affect_gameboard_applets(self):
+        game_applet, _ = Applet.objects.get_or_create(
+            slug="new-game", defaults={"name": "New Game", "context": "gameboard"}
+        )
+        self.client.post(self.url, {"applets": ["username", "palette"]})
+        self.assertFalse(UserApplet.objects.filter(user=self.user, applet=game_applet). exists())
+
+class AppletVisibilityContextTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="disco@test.io")
+        self.client.force_login(self.user)
+        self.username_applet, _ = Applet.objects.get_or_create(slug="username", defaults={"name": "Username"})
+        self.palette_applet, _ = Applet.objects.get_or_create(slug="palette", defaults={"name": "Palette"})
+        UserApplet.objects.create(user=self.user, applet=self.palette_applet, visible=False)
+
+    def test_dash_reflects_user_applet_visibility(self):
+        response = self.client.get("/")
+        applet_map = {entry["applet"].slug: entry["visible"] for entry in response.context["applets"]}
+        self.assertFalse(applet_map["palette"])
+        self.assertTrue(applet_map["username"])
+
+class FooterNavTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="disco@test.io")
+        self.client.force_login(self.user)
+
+    def test_footer_nav_present_on_dashboard(self):
+        response = self.client.get("/")
+        parsed = lxml.html.fromstring(response.content)
+        [nav] = parsed.cssselect("#id_footer_nav")
+        self.assertIsNotNone(nav)
+
+    def test_footer_nav_has_dashboard_link(self):
+        response = self.client.get("/")
+        parsed = lxml.html.fromstring(response.content)
+        [nav] = parsed.cssselect("#id_footer_nav")
+        links = [a.get("href") for a in nav.cssselect("a")]
+        self.assertIn("/", links)
+
+    def test_footer_nav_has_gameboard_link(self):
+        response = self.client.get("/")
+        parsed = lxml.html.fromstring(response.content)
+        [nav] = parsed.cssselect("#id_footer_nav")
+        links = [a.get("href") for a in nav.cssselect("a")]
+        self.assertIn("/gameboard/", links)
+
+class WalletAppletTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="disco@test.io")
+        self.client.force_login(self.user)
+        Applet.objects.get_or_create(slug="wallet", defaults={"name": "Wallet"})
+        response = self.client.get("/")
+        self.parsed = lxml.html.fromstring(response.content)
+
+    def test_wallet_applet_present_on_dash(self):
+        [_] = self.parsed.cssselect("#id_applet_wallet")
+
+    def test_wallet_applet_has_manage_link(self):
+        [link] = self.parsed.cssselect("#id_applet_wallet a.wallet-manage-link")
+        self.assertEqual(link.get("href"), "/dashboard/wallet/")

src/apps/dashboard/tests/integrated/test_wallet_views.py

@@ -0,0 +1,139 @@
+import lxml.html
+
+from django.test import TestCase
+
+from apps.applets.models import Applet, UserApplet
+from apps.lyric.models import Token, User, Wallet
+
+
+class WalletViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="capman@test.io")
+        self.client.force_login(self.user)
+        response = self.client.get("/dashboard/wallet/")
+        self.parsed = lxml.html.fromstring(response.content)
+
+    def test_wallet_page_requires_login(self):
+        self.client.logout()
+        response = self.client.get("/dashboard/wallet/")
+        self.assertRedirects(
+            response, "/?next=/dashboard/wallet/", fetch_redirect_response=False
+        )
+
+    def test_wallet_page_renders(self):
+        [el] = self.parsed.cssselect("#id_writs_balance")
+        self.assertEqual(el.text_content().strip(), "144")
+
+    def test_wallet_page_shows_esteem_balance(self):
+        [el] = self.parsed.cssselect("#id_esteem_balance")
+        self.assertEqual(el.text_content().strip(), "0")
+
+    def test_wallet_page_shows_coin_on_a_string(self):
+        [_] = self.parsed.cssselect("#id_coin_on_a_string")
+        
+    def test_wallet_page_shows_free_token(self):
+        [_] = self.parsed.cssselect("#id_free_token")
+
+    def test_wallet_page_shows_payment_methods_section(self):
+        [_] = self.parsed.cssselect("#id_add_payment_method")
+
+    def test_wallet_page_shows_stripe_payment_element(self):
+        [_] = self.parsed.cssselect("#id_stripe_payment_element")
+
+    def test_wallet_page_shows_tithe_token_shop(self):
+        [_] = self.parsed.cssselect("#id_tithe_token_shop")
+
+    def test_tithe_token_shop_shows_bundle(self):
+        bundles = self.parsed.cssselect("#id_tithe_token_shop .token-bundle")
+        self.assertGreater(len(bundles), 0)
+
+
+class WalletViewAppletContextTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="walletctx@test.io")
+        Applet.objects.get_or_create(
+            slug="wallet-balances",
+            defaults={"name": "Wallet Balances", "grid_cols": 3, "grid_rows": 3, "context": "wallet"},
+        )
+        Applet.objects.get_or_create(
+            slug="wallet-tokens",
+            defaults={"name": "Wallet Tokens", "grid_cols": 3, "grid_rows": 3, "context": "wallet"},
+        )
+        Applet.objects.get_or_create(
+            slug="wallet-payment",
+            defaults={"name": "Payment Methods", "grid_cols": 6, "grid_rows": 2, "context": "wallet"},
+        )
+        self.client.force_login(self.user)
+
+    def test_wallet_view_passes_applets_context(self):
+        response = self.client.get("/dashboard/wallet/")
+        slugs = [e["applet"].slug for e in response.context["applets"]]
+        self.assertIn("wallet-balances", slugs)
+        self.assertIn("wallet-tokens", slugs)
+        self.assertIn("wallet-payment", slugs)
+
+    def test_wallet_page_renders_applets_container(self):
+        response = self.client.get("/dashboard/wallet/")
+        parsed = lxml.html.fromstring(response.content)
+        [_] = parsed.cssselect("#id_wallet_applets_container")
+
+    def test_wallet_page_renders_gear_button(self):
+        response = self.client.get("/dashboard/wallet/")
+        parsed = lxml.html.fromstring(response.content)
+        [_] = parsed.cssselect(".gear-btn")
+
+
+class ToggleWalletAppletsTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="wallettoggle@test.io")
+        self.balances = Applet.objects.get_or_create(
+            slug="wallet-balances",
+            defaults={"name": "Wallet Balances", "grid_cols": 3, "grid_rows": 3, "context": "wallet"},
+        )[0]
+        self.tokens = Applet.objects.get_or_create(
+            slug="wallet-tokens",
+            defaults={"name": "Wallet Tokens", "grid_cols": 3, "grid_rows": 3, "context": "wallet"},
+        )[0]
+        Applet.objects.get_or_create(
+            slug="wallet-payment",
+            defaults={"name": "Payment Methods", "grid_cols": 6, "grid_rows": 2, "context": "wallet"},
+        )
+        self.client.force_login(self.user)
+
+    def test_toggle_requires_login(self):
+        self.client.logout()
+        response = self.client.post("/dashboard/wallet/toggle-applets", {})
+        self.assertRedirects(
+            response, "/?next=/dashboard/wallet/toggle-applets",
+            fetch_redirect_response=False,
+        )
+
+    def test_toggle_redirects_to_wallet(self):
+        response = self.client.post(
+            "/dashboard/wallet/toggle-applets", {"applets": ["wallet-balances"]}
+        )
+        self.assertRedirects(response, "/dashboard/wallet/", fetch_redirect_response=False)
+
+    def test_toggle_hides_unchecked_applet(self):
+        self.client.post(
+            "/dashboard/wallet/toggle-applets", {"applets": ["wallet-balances"]}
+        )
+        ua = UserApplet.objects.get(user=self.user, applet=self.tokens)
+        self.assertFalse(ua.visible)
+
+    def test_toggle_shows_checked_applet(self):
+        UserApplet.objects.create(user=self.user, applet=self.balances, visible=False)
+        self.client.post(
+            "/dashboard/wallet/toggle-applets", {"applets": ["wallet-balances"]}
+        )
+        ua = UserApplet.objects.get(user=self.user, applet=self.balances)
+        self.assertTrue(ua.visible)
+
+    def test_toggle_htmx_returns_container_partial(self):
+        response = self.client.post(
+            "/dashboard/wallet/toggle-applets",
+            {"applets": ["wallet-balances"]},
+            HTTP_HX_REQUEST="true",
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "id_wallet_applets_container")

src/apps/dashboard/tests/unit/test_templates.py

@@ -0,0 +1,9 @@
+from datetime import date
+from django.test import SimpleTestCase
+from django.template.loader import render_to_string
+
+
+class FooterTemplateTest(SimpleTestCase):
+    def test_footer_shows_current_year(self):
+        rendered = render_to_string("core/_partials/_footer.html")
+        self.assertIn(str(date.today().year), rendered)

src/apps/dashboard/urls.py

@@ -2,8 +2,16 @@ from django.urls import path
 from . import views
 
 urlpatterns = [
-    path('new_list', views.new_list, name='new_list'),
+    path('new_note', views.new_note, name='new_note'),
-    path('<int:list_id>/', views.view_list, name='view_list'),
+    path('note/<uuid:note_id>/', views.view_note, name='view_note'),
-    path('users/<uuid:user_id>/', views.my_lists, name='my_lists'),
+    path('note/<uuid:note_id>/share_note', views.share_note, name="share_note"),
-    path('<int:list_id>/share_list', views.share_list, name="share_list"),
+    path('set_palette', views.set_palette, name='set_palette'),
+    path('set_profile', views.set_profile, name='set_profile'),
+    path('users/<uuid:user_id>/', views.my_notes, name='my_notes'),
+    path('toggle_applets', views.toggle_applets, name="toggle_applets"),
+    path('wallet/', views.wallet, name='wallet'),
+    path('wallet/toggle-applets', views.toggle_wallet_applets, name='toggle_wallet_applets'),
+    path('wallet/setup-intent', views.setup_intent, name='setup_intent'),
+    path('wallet/save-payment-method', views.save_payment_method, name='save_payment_method'),
+    path('kit-bag/', views.kit_bag, name='kit_bag'),
 ]

src/apps/dashboard/views.py

@@ -1,48 +1,235 @@
-from django.http import HttpResponseForbidden
+import stripe
+
+from django.conf import settings
+from django.contrib import messages
+from django.contrib.auth.decorators import login_required
+from django.db.models import Max, Q
+from django.http import HttpResponse, HttpResponseForbidden, JsonResponse
 from django.shortcuts import redirect, render
-from .forms import ExistingListItemForm, ItemForm
+from django.utils import timezone
-from .models import Item, List
+from django.views.decorators.csrf import ensure_csrf_cookie
-from apps.lyric.models import User
+
+from apps.applets.models import Applet, UserApplet
+from apps.applets.utils import applet_context
+from apps.dashboard.forms import ExistingNoteItemForm, ItemForm
+from apps.dashboard.models import Item, Note
+from apps.lyric.models import PaymentMethod, Token, User, Wallet
+
+
+APPLET_ORDER = ["wallet", "new-note", "my-notes", "username", "palette"]
+UNLOCKED_PALETTES = frozenset([
+    "palette-default",
+    "palette-sepia",
+    "palette-monochrome-light",
+    "palette-monochrome-dark",
+])
+PALETTES = [
+    {"name": "palette-default", "label": "Earthman", "locked": False},
+    {"name": "palette-sepia", "label": "Sepia", "locked": False},
+    {"name": "palette-monochrome-light", "label": "Monochrome (Light)", "locked": False},
+    {"name": "palette-monochrome-dark", "label": "Monochrome (Dark)", "locked": False},
+    {"name": "palette-nirvana", "label": "Nirvana", "locked": True},
+    {"name": "palette-sheol", "label": "Sheol", "locked": True},
+    {"name": "palette-inferno", "label": "Inferno", "locked": True},
+    {"name": "palette-terrestre", "label": "Terrestre", "locked": True},
+    {"name": "palette-celestia", "label": "Celestia", "locked": True},
+]
+
+
+def _recent_notes(user, limit=3):
+    return (
+        Note
+            .objects
+            .filter(Q(owner=user) | Q(shared_with=user))
+            .annotate(last_item=Max('item__id'))
+            .order_by('-last_item')
+            .distinct()[:limit]
+    )
 
 def home_page(request):
-    return render(request, "apps/dashboard/home.html", {"form": ItemForm()})
+    context = {
+        "form": ItemForm(),
+        "palettes": PALETTES,
+        "page_class": "page-dashboard",
+    }
+    if request.user.is_authenticated:
+        context["applets"] = applet_context(request.user, "dashboard")
+        context["recent_notes"] = _recent_notes(request.user)
+    return render(request, "apps/dashboard/home.html", context)
 
-def new_list(request):
+def new_note(request):
     form = ItemForm(data=request.POST)
     if form.is_valid():
-        nulist = List.objects.create()
+        nunote = Note.objects.create()
         if request.user.is_authenticated:
-            nulist.owner = request.user
+            nunote.owner = request.user
-            nulist.save()
+            nunote.save()
-        form.save(for_list=nulist)
+        form.save(for_note=nunote)
-        return redirect(nulist)
+        return redirect(nunote)
     else:
-        return render(request, "apps/dashboard/home.html", {"form": form})
+        context = {
+            "form": form,
+            "palettes": PALETTES,
+            "page_class": "page-dashboard",
+        }
+        if request.user.is_authenticated:
+            context["applets"] = applet_context(request.user, "dashboard")
+            context["recent_notes"] = _recent_notes(request.user)
+        return render(request, "apps/dashboard/home.html", context)
 
-def view_list(request, list_id):
+def view_note(request, note_id):
-    our_list = List.objects.get(id=list_id)
+    our_note = Note.objects.get(id=note_id)
-    form = ExistingListItemForm(for_list=our_list)
+
+    if our_note.owner:
+        if not request.user.is_authenticated:
+            return redirect("/")
+        if request.user != our_note.owner and request.user not in our_note.shared_with.all():
+            return HttpResponseForbidden()
+
+    form = ExistingNoteItemForm(for_note=our_note)
 
     if request.method == "POST":
-        form = ExistingListItemForm(for_list=our_list, data=request.POST)
+        form = ExistingNoteItemForm(for_note=our_note, data=request.POST)
         if form.is_valid():
             form.save()
-            return redirect(our_list)
+            return redirect(our_note)
-    return render(request, "apps/dashboard/list.html", {"list": our_list, "form": form})
+    return render(request, "apps/dashboard/note.html", {"note": our_note, "form": form})
-            
+
-def my_lists(request, user_id):
+def my_notes(request, user_id):
     owner = User.objects.get(id=user_id)
     if not request.user.is_authenticated:
         return redirect("/")
     if request.user.id != owner.id:
         return HttpResponseForbidden()
-    return render(request, "apps/dashboard/my_lists.html", {"owner": owner})
+    return render(request, "apps/dashboard/my_notes.html", {"owner": owner})
 
-def share_list(request, list_id):
+def share_note(request, note_id):
-    our_list = List.objects.get(id=list_id)
+    our_note = Note.objects.get(id=note_id)
     try:
         recipient = User.objects.get(email=request.POST["recipient"])
-        our_list.shared_with.add(recipient)
+        if recipient == request.user:
+            return redirect(our_note)
+        our_note.shared_with.add(recipient)
     except User.DoesNotExist:
         pass
-    return redirect(our_list)
+    messages.success(request, "An invite has been sent if that address is registered.")
+    return redirect(our_note)
+
+@login_required(login_url="/")
+def set_palette(request):
+    if request.method == "POST":
+        palette = request.POST.get("palette", "")
+        if palette in UNLOCKED_PALETTES:
+            request.user.palette = palette
+            request.user.save(update_fields=["palette"])
+    return redirect("home")
+
+@login_required(login_url="/")
+def set_profile(request):
+    if request.method == "POST":
+        username = request.POST.get("username", "")
+        request.user.username = username
+        request.user.save(update_fields=["username"])
+    return redirect("/")
+
+@login_required(login_url="/")
+def toggle_applets(request):
+    checked = request.POST.getlist("applets")
+    for applet in Applet.objects.filter(context="dashboard"):
+        UserApplet.objects.update_or_create(
+            user=request.user,
+            applet=applet,
+            defaults={"visible": applet.slug in checked},
+        )
+    if request.headers.get("HX-Request"):
+        return render(request, "apps/dashboard/_partials/_applets.html", {
+            "applets": applet_context(request.user, "dashboard"),
+            "palettes": PALETTES,
+            "form": ItemForm(),
+            "recent_notes": _recent_notes(request.user),
+        })
+    return redirect("home")
+
+@login_required(login_url="/")
+@ensure_csrf_cookie
+def wallet(request):
+    return render(request, "apps/dashboard/wallet.html", {
+        "wallet": request.user.wallet,
+        "pass_token": request.user.tokens.filter(token_type=Token.PASS).first(),
+        "coin": request.user.tokens.filter(token_type=Token.COIN).first(),
+        "free_tokens": list(request.user.tokens.filter(
+            token_type=Token.FREE, expires_at__gt=timezone.now()
+        ).order_by("expires_at")),
+        "tithe_tokens": list(request.user.tokens.filter(token_type=Token.TITHE)),
+        "free_count": request.user.tokens.filter(
+            token_type=Token.FREE, expires_at__gt=timezone.now()
+        ).count(),
+        "tithe_count": request.user.tokens.filter(token_type=Token.TITHE).count(),
+        "applets": applet_context(request.user, "wallet"),
+        "page_class": "page-wallet",
+    })
+
+
+@login_required(login_url="/")
+def kit_bag(request):
+    tokens = list(request.user.tokens.all())
+    free_tokens = sorted(
+        [t for t in tokens if t.token_type == Token.FREE and t.expires_at and t.expires_at > timezone.now()],
+        key=lambda t: t.expires_at,
+    )
+    tithe_tokens = [t for t in tokens if t.token_type == Token.TITHE]
+    return render(request, "core/_partials/_kit_bag_panel.html", {
+        "equipped_trinket": request.user.equipped_trinket,
+        "free_token": free_tokens[0] if free_tokens else None,
+        "free_count": len(free_tokens),
+        "tithe_token": tithe_tokens[0] if tithe_tokens else None,
+        "tithe_count": len(tithe_tokens),
+    })
+
+@login_required(login_url="/")
+def toggle_wallet_applets(request):
+    checked = request.POST.getlist("applets")
+    for applet in Applet.objects.filter(context="wallet"):
+        UserApplet.objects.update_or_create(
+            user=request.user,
+            applet=applet,
+            defaults={"visible": applet.slug in checked},
+        )
+    if request.headers.get("HX-Request"):
+        return render(request, "apps/wallet/_partials/_applets.html", {
+            "applets": applet_context(request.user, "wallet"),
+            "wallet": request.user.wallet,
+            "pass_token": request.user.tokens.filter(token_type=Token.PASS).first(),
+            "coin": request.user.tokens.filter(token_type=Token.COIN).first(),
+            "free_tokens": list(request.user.tokens.filter(token_type=Token.FREE)),
+            "tithe_tokens": list(request.user.tokens.filter(token_type=Token.TITHE)),
+        })
+    return redirect("wallet")
+
+@login_required(login_url="/")
+def setup_intent(request):
+    stripe.api_key = settings.STRIPE_SECRET_KEY
+    user = request.user
+    if not user.stripe_customer_id:
+        customer = stripe.Customer.create(email=user.email)
+        user.stripe_customer_id = customer.id
+        user.save(update_fields=["stripe_customer_id"])
+    intent = stripe.SetupIntent.create(customer=user.stripe_customer_id)
+    return JsonResponse({
+        "client_secret": intent.client_secret,
+        "publishable_key": settings.STRIPE_PUBLISHABLE_KEY,
+    })
+
+@login_required(login_url="/")
+def save_payment_method(request):
+    stripe.api_key = settings.STRIPE_SECRET_KEY
+    pm_id = request.POST.get("payment_method_id")
+    pm = stripe.PaymentMethod.retrieve(pm_id)
+    stripe.PaymentMethod.attach(pm_id, customer=request.user.stripe_customer_id)
+    PaymentMethod.objects.create(
+        user=request.user,
+        stripe_pm_id=pm_id,
+        last4=pm.card.last4,
+        brand=pm.card.brand,
+    )
+    return JsonResponse({"last4": pm.card.last4, "brand": pm.card.brand})

src/apps/epic/admin.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.

src/apps/epic/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class EpicConfig(AppConfig):
+    name = 'apps.epic'

src/apps/epic/consumers.py

@@ -0,0 +1,27 @@
+from channels.generic.websocket import AsyncJsonWebsocketConsumer
+
+
+class RoomConsumer(AsyncJsonWebsocketConsumer):
+    async def connect(self):
+        self.room_id = self.scope["url_route"]["kwargs"]["room_id"]
+        self.group_name = f"room_{self.room_id}"
+        await self.channel_layer.group_add(self.group_name, self.channel_name)
+        await self.accept()
+
+    async def disconnect(self, close_code):
+        await self.channel_layer.group_discard(self.group_name, self.channel_name)
+
+    async def receive_json(self, content):
+        pass # handlers added as events introduced
+
+    async def gate_update(self, event):
+        await self.send_json(event)
+
+    async def role_select_start(self, event):
+        await self.send_json(event)
+
+    async def turn_changed(self, event):
+        await self.send_json(event)
+
+    async def roles_revealed(self, event):
+        await self.send_json(event)

src/apps/epic/migrations/0001_initial.py

@@ -0,0 +1,45 @@
+# Generated by Django 6.0 on 2026-03-12 19:46
+
+import django.db.models.deletion
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Room',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('name', models.CharField(max_length=200)),
+                ('visibility', models.CharField(choices=[('PRIVATE', 'Private'), ('PUBLIC', 'Public'), ('INVITE ONLY', 'Invite Only')], default='PRIVATE', max_length=20)),
+                ('gate_status', models.CharField(choices=[('GATHERING', 'Gathering'), ('OPEN', 'Open'), ('RENEWAL_DUE', 'Renewal Due')], default='GATHERING', max_length=20)),
+                ('renewal_period', models.DurationField(blank=True, null=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('board_state', models.JSONField(default=dict)),
+                ('seed_count', models.IntegerField(default=12)),
+                ('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='owned_rooms', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='GateSlot',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('slot_number', models.IntegerField()),
+                ('status', models.CharField(choices=[('EMPTY', 'Empty'), ('RESERVED', 'Reserved'), ('FILLED', 'Filled')], default='EMPTY', max_length=10)),
+                ('reserved_at', models.DateTimeField(blank=True, null=True)),
+                ('filled_at', models.DateTimeField(blank=True, null=True)),
+                ('funded_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='funded_slots', to=settings.AUTH_USER_MODEL)),
+                ('gamer', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='gate_slots', to=settings.AUTH_USER_MODEL)),
+                ('room', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='gate_slots', to='epic.room')),
+            ],
+        ),
+    ]

src/apps/epic/migrations/0002_alter_room_renewal_period.py

@@ -0,0 +1,19 @@
+# Generated by Django 6.0 on 2026-03-13 20:32
+
+import datetime
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('epic', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='room',
+            name='renewal_period',
+            field=models.DurationField(blank=True, default=datetime.timedelta(days=7), null=True),
+        ),
+    ]

src/apps/epic/migrations/0003_roominvite.py

@@ -0,0 +1,27 @@
+# Generated by Django 6.0 on 2026-03-13 22:19
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('epic', '0002_alter_room_renewal_period'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='RoomInvite',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('invitee_email', models.EmailField(max_length=254)),
+                ('status', models.CharField(choices=[('PENDING', 'Pending'), ('ACCEPTED', 'Accepted'), ('DECLINED', 'Declined')], default='PENDING', max_length=10)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('inviter', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='sent_invites', to=settings.AUTH_USER_MODEL)),
+                ('room', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='invites', to='epic.room')),
+            ],
+        ),
+    ]

src/apps/epic/migrations/0004_alter_room_gate_status.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0 on 2026-03-15 00:32
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('epic', '0003_roominvite'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='room',
+            name='gate_status',
+            field=models.CharField(choices=[('GATHERING', 'GATHERING GAMERS'), ('OPEN', 'Open'), ('RENEWAL_DUE', 'Renewal Due')], default='GATHERING', max_length=20),
+        ),
+    ]

src/apps/epic/migrations/0005_gateslot_debited_token_fields.py

@@ -0,0 +1,21 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('epic', '0004_alter_room_gate_status'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='gateslot',
+            name='debited_token_type',
+            field=models.CharField(max_length=8, null=True, blank=True),
+        ),
+        migrations.AddField(
+            model_name='gateslot',
+            name='debited_token_expires_at',
+            field=models.DateTimeField(null=True, blank=True),
+        ),
+    ]

src/apps/epic/migrations/0006_table_status_and_table_seat.py

@@ -0,0 +1,33 @@
+# Generated by Django 6.0 on 2026-03-17 00:14
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('epic', '0005_gateslot_debited_token_fields'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='room',
+            name='table_status',
+            field=models.CharField(blank=True, choices=[('ROLE_SELECT', 'Role Select'), ('SIG_SELECT', 'Significator Select'), ('IN_GAME', 'In Game')], max_length=20, null=True),
+        ),
+        migrations.CreateModel(
+            name='TableSeat',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('slot_number', models.IntegerField()),
+                ('role', models.CharField(blank=True, choices=[('PC', 'Player'), ('BC', 'Builder'), ('SC', 'Shepherd'), ('AC', 'Alchemist'), ('NC', 'Narrator'), ('EC', 'Economist')], max_length=2, null=True)),
+                ('role_revealed', models.BooleanField(default=False)),
+                ('seat_position', models.IntegerField(blank=True, null=True)),
+                ('gamer', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='table_seats', to=settings.AUTH_USER_MODEL)),
+                ('room', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='table_seats', to='epic.room')),
+            ],
+        ),
+    ]

src/apps/epic/models.py

@@ -0,0 +1,175 @@
+import uuid
+
+from datetime import timedelta
+from django.db import models
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+from django.conf import settings
+from django.utils import timezone
+
+from apps.lyric.models import Token
+
+
+class Room(models.Model):
+    GATHERING = "GATHERING"
+    OPEN = "OPEN"
+    RENEWAL_DUE = "RENEWAL_DUE"
+    GATE_STATUS_CHOICES = [
+        (GATHERING, "GATHERING GAMERS"),
+        (OPEN, "Open"),
+        (RENEWAL_DUE, "Renewal Due"),
+    ]
+
+    PRIVATE = "PRIVATE"
+    PUBLIC = "PUBLIC"
+    INVITE_ONLY = "INVITE ONLY"
+    VISIBILITY_CHOICES = [
+        (PRIVATE, "Private"),
+        (PUBLIC, "Public"),
+        (INVITE_ONLY, "Invite Only"),
+    ]
+
+    ROLE_SELECT = "ROLE_SELECT"
+    SIG_SELECT = "SIG_SELECT"
+    IN_GAME = "IN_GAME"
+    TABLE_STATUS_CHOICES = [
+        (ROLE_SELECT, "Role Select"),
+        (SIG_SELECT, "Significator Select"),
+        (IN_GAME, "In Game"),
+    ]
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=200)
+    owner = models.ForeignKey(
+        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="owned_rooms"
+    )
+    visibility = models.CharField(max_length=20, choices=VISIBILITY_CHOICES, default=PRIVATE)
+    gate_status = models.CharField(max_length=20, choices=GATE_STATUS_CHOICES, default=GATHERING)
+    table_status = models.CharField(
+        max_length=20, choices=TABLE_STATUS_CHOICES, null=True, blank=True
+    )
+    renewal_period = models.DurationField(null=True, blank=True, default=timedelta(days=7))
+    created_at = models.DateTimeField(auto_now_add=True)
+    board_state = models.JSONField(default=dict)
+    seed_count = models.IntegerField(default=12)
+
+
+class GateSlot(models.Model):
+    EMPTY = "EMPTY"
+    RESERVED = "RESERVED"
+    FILLED = "FILLED"
+    STATUS_CHOICES = [
+        (EMPTY, "Empty"),
+        (RESERVED, "Reserved"),
+        (FILLED, "Filled"),
+    ]
+
+    room = models.ForeignKey(Room, on_delete=models.CASCADE, related_name="gate_slots")
+    slot_number = models.IntegerField()
+    gamer = models.ForeignKey(
+        settings.AUTH_USER_MODEL, null=True, blank=True,
+        on_delete=models.SET_NULL, related_name="gate_slots"
+    )
+    funded_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL, null=True, blank=True,
+        on_delete=models.SET_NULL, related_name="funded_slots"
+    )
+    status = models.CharField(max_length=10, choices=STATUS_CHOICES, default=EMPTY)
+    reserved_at = models.DateTimeField(null=True, blank=True)
+    filled_at = models.DateTimeField(null=True, blank=True)
+    debited_token_type = models.CharField(max_length=8, null=True, blank=True)
+    debited_token_expires_at = models.DateTimeField(null=True, blank=True)
+
+
+class RoomInvite(models.Model):
+    PENDING = "PENDING"
+    ACCEPTED = "ACCEPTED"
+    DECLINED = "DECLINED"
+    STATUS_CHOICES = [
+        (PENDING, "Pending"),
+        (ACCEPTED, "Accepted"),
+        (DECLINED, "Declined"),
+    ]
+
+    room = models.ForeignKey(Room, on_delete=models.CASCADE, related_name="invites")
+    inviter = models.ForeignKey(
+        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="sent_invites"
+    )
+    invitee_email = models.EmailField()
+    status = models.CharField(max_length=10, choices=STATUS_CHOICES, default=PENDING)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+
+@receiver(post_save, sender=Room)
+def create_gate_slots(sender, instance, created, **kwargs):
+    if created:
+        for i in range(1, 7):
+            GateSlot.objects.create(room=instance, slot_number=i)
+
+
+def select_token(user):
+    if user.is_staff:
+        pass_token = user.tokens.filter(token_type=Token.PASS).first()
+        if pass_token:
+            return pass_token
+    coin = user.tokens.filter(token_type=Token.COIN, current_room__isnull=True).first()
+    if coin:
+        return coin
+    free = user.tokens.filter(
+        token_type=Token.FREE,
+        expires_at__gt=timezone.now(),
+    ).order_by("expires_at").first()
+    if free:
+        return free
+    return user.tokens.filter(token_type=Token.TITHE).first()
+
+
+def debit_token(user, slot, token):
+    slot.debited_token_type = token.token_type
+    if token.token_type == Token.COIN:
+        token.current_room = slot.room
+        period = slot.room.renewal_period or timedelta(days=7)
+        token.next_ready_at = timezone.now() + period
+        token.save()
+    elif token.token_type == Token.CARTE:
+        pass  # current_room already set in drop_token; token not consumed
+    elif token.token_type != Token.PASS:
+        slot.debited_token_expires_at = token.expires_at
+        token.delete()
+    slot.gamer = user
+    slot.status = GateSlot.FILLED
+    slot.filled_at = timezone.now()
+    slot.save()
+
+    room = slot.room
+    if not room.gate_slots.filter(status=GateSlot.EMPTY).exists():
+        room.gate_status = Room.OPEN
+        room.save()
+
+
+class TableSeat(models.Model):
+    PC = "PC"
+    BC = "BC"
+    SC = "SC"
+    AC = "AC"
+    NC = "NC"
+    EC = "EC"
+    ROLE_CHOICES = [
+        (PC, "Player"),
+        (BC, "Builder"),
+        (SC, "Shepherd"),
+        (AC, "Alchemist"),
+        (NC, "Narrator"),
+        (EC, "Economist"),
+    ]
+    PARTNER_MAP = {PC: BC, BC: PC, SC: AC, AC: SC, NC: EC, EC: NC}
+
+    room = models.ForeignKey(Room, on_delete=models.CASCADE, related_name="table_seats")
+    gamer = models.ForeignKey(
+        settings.AUTH_USER_MODEL, null=True, blank=True,
+        on_delete=models.SET_NULL, related_name="table_seats"
+    )
+    slot_number = models.IntegerField()
+    role = models.CharField(max_length=2, choices=ROLE_CHOICES, null=True, blank=True)
+    role_revealed = models.BooleanField(default=False)
+    seat_position = models.IntegerField(null=True, blank=True)

src/apps/epic/routing.py

@@ -0,0 +1,8 @@
+from django.urls import path
+
+from . import consumers
+
+
+websocket_urlpatterns = [
+    path('ws/room/<uuid:room_id>/', consumers.RoomConsumer.as_asgi()),
+]

src/apps/epic/static/apps/epic/gatekeeper.js

@@ -0,0 +1,12 @@
+(function () {
+    window.addEventListener('room:gate_update', function () {
+        const wrapper = document.getElementById('id_gate_wrapper');
+        if (!wrapper) return;
+
+        fetch(wrapper.dataset.gateStatusUrl)
+            .then(function (r) { return r.text(); })
+            .then(function (html) {
+                wrapper.outerHTML = html;
+            });
+    });
+}());

src/apps/epic/static/apps/epic/role-select.js

@@ -0,0 +1,163 @@
+var RoleSelect = (function () {
+    var ROLES = [
+        { code: "PC", name: "Player",     element: "Fire"  },
+        { code: "BC", name: "Builder",    element: "Stone" },
+        { code: "SC", name: "Shepherd",   element: "Air"   },
+        { code: "AC", name: "Alchemist",  element: "Water" },
+        { code: "NC", name: "Narrator",   element: "Time"  },
+        { code: "EC", name: "Economist",  element: "Space" },
+    ];
+
+    function getSelectRoleUrl() {
+        var el = document.querySelector("[data-select-role-url]");
+        return el ? el.dataset.selectRoleUrl : null;
+    }
+
+    function getCsrf() {
+        var m = document.cookie.match(/csrftoken=([^;]+)/);
+        return m ? m[1] : "";
+    }
+
+    function closeFan() {
+        var backdrop = document.querySelector(".role-select-backdrop");
+        if (backdrop) backdrop.remove();
+    }
+
+    function selectRole(roleCode, cardEl) {
+        var invCard = cardEl.cloneNode(true);
+        invCard.classList.add("flipped");
+        // strip old event listeners from the clone by replacing with a clean copy
+        var clean = invCard.cloneNode(true);
+
+        closeFan();
+
+        var invSlot = document.getElementById("id_inv_role_card");
+        if (invSlot) invSlot.appendChild(clean);
+
+        // Update the stack's taken-roles so the next openFan() filters correctly
+        var stack = document.querySelector(".card-stack[data-taken-roles]");
+        if (stack) {
+            var current = stack.dataset.takenRoles;
+            stack.dataset.takenRoles = current ? current + "," + roleCode : roleCode;
+        }
+
+        var url = getSelectRoleUrl();
+        if (!url) return;
+        fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                "X-CSRFToken": getCsrf(),
+            },
+            body: "role=" + encodeURIComponent(roleCode),
+        });
+    }
+
+    function getTakenRoles() {
+        var stack = document.querySelector(".card-stack[data-taken-roles]");
+        if (!stack) return [];
+        var raw = stack.dataset.takenRoles;
+        return raw ? raw.split(",").map(function (s) { return s.trim(); }) : [];
+    }
+
+    function openFan() {
+        if (document.querySelector(".role-select-backdrop")) return;
+
+        var taken = getTakenRoles();
+        var available = ROLES.filter(function (r) { return taken.indexOf(r.code) === -1; });
+
+        var backdrop = document.createElement("div");
+        backdrop.className = "role-select-backdrop";
+
+        var modal = document.createElement("div");
+        modal.id = "id_role_select";
+
+        available.forEach(function (role) {
+            var card = document.createElement("div");
+            card.className = "card";
+            card.dataset.role = role.code;
+
+            var back = document.createElement("div");
+            back.className = "card-back";
+            back.textContent = "?";
+
+            var front = document.createElement("div");
+            front.className = "card-front";
+            front.innerHTML = '<div class="card-role-name">' + role.name + "</div>";
+
+            card.appendChild(back);
+            card.appendChild(front);
+
+            card.addEventListener("mouseenter", function () {
+                card.classList.add("flipped");
+            });
+            card.addEventListener("mouseleave", function () {
+                card.classList.remove("flipped");
+            });
+            card.addEventListener("click", function (e) {
+                e.stopPropagation();
+                selectRole(role.code, card);
+            });
+
+            modal.appendChild(card);
+        });
+
+        backdrop.appendChild(modal);
+        backdrop.addEventListener("click", closeFan);
+        document.body.appendChild(backdrop);
+    }
+
+    function init() {
+        var stack = document.querySelector(".card-stack[data-state='eligible']");
+        if (!stack) return;
+        stack.addEventListener("click", openFan);
+    }
+
+    var _reload = function () { window.location.reload(); };
+
+    function handleRolesRevealed() {
+        _reload();
+    }
+
+    function handleTurnChanged(event) {
+        var active = String(event.detail.active_slot);
+
+        // Update card-stack eligibility
+        var stack = document.querySelector(".card-stack[data-user-slots]");
+        if (stack) {
+            var userSlots = stack.dataset.userSlots
+                ? stack.dataset.userSlots.split(",") : [];
+            if (userSlots.indexOf(active) !== -1) {
+                stack.dataset.state = "eligible";
+                stack.removeEventListener("click", openFan);
+                stack.addEventListener("click", openFan);
+            } else {
+                stack.dataset.state = "ineligible";
+                stack.removeEventListener("click", openFan);
+            }
+        }
+
+        // Move .active to the newly active seat
+        document.querySelectorAll(".table-seat.active").forEach(function (s) {
+            s.classList.remove("active");
+        });
+        var activeSeat = document.querySelector(".table-seat[data-slot='" + active + "']");
+        if (activeSeat) activeSeat.classList.add("active");
+    }
+
+    window.addEventListener("room:role_select_start", init);
+    window.addEventListener("room:turn_changed", handleTurnChanged);
+    window.addEventListener("room:roles_revealed", handleRolesRevealed);
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", init);
+    } else {
+        init();
+    }
+
+    return {
+        openFan: openFan,
+        closeFan: closeFan,
+        setReload: function (fn) { _reload = fn; },
+    };
+}());

src/apps/epic/static/apps/epic/room.js

@@ -0,0 +1,17 @@
+(function () {
+    const roomPage = document.querySelector('.room-page');
+    if (!roomPage) return;
+
+    const roomId = roomPage.dataset.roomId;
+    const wsScheme = window.location.protocol === 'https:' ? 'wss' : 'ws';
+    const ws = new WebSocket(`${wsScheme}://${window.location.host}/ws/room/${roomId}/`);
+
+    ws.onmessage = function (event) {
+        const data = JSON.parse(event.data);
+        window.dispatchEvent(new CustomEvent('room:' + data.type, { detail: data }));
+    };
+
+    ws.onclose = function () {
+        console.warn('Room WebSocket closed');
+    };
+}());

src/apps/epic/tests/integrated/test_consumers.py

@@ -0,0 +1,85 @@
+from channels.testing.websocket import WebsocketCommunicator
+from channels.layers import get_channel_layer
+from django.test import SimpleTestCase, override_settings
+
+from core.asgi import application
+
+
+TEST_CHANNEL_LAYERS = {
+    "default": {
+        "BACKEND": "channels.layers.InMemoryChannelLayer",
+    }
+}
+
+
+@override_settings(CHANNEL_LAYERS=TEST_CHANNEL_LAYERS)
+class RoomConsumerTest(SimpleTestCase):
+    async def test_can_connect_and_disconnect(self):
+        communicator = WebsocketCommunicator(application, "/ws/room/00000000-0000-0000-0000-000000000001/")
+        connected, _ = await communicator.connect()
+        self.assertTrue(connected)
+        await communicator.disconnect()
+
+    async def test_receives_role_select_start_broadcast(self):
+        communicator = WebsocketCommunicator(application, "/ws/room/00000000-0000-0000-0000-000000000001/")
+        await communicator.connect()
+
+        channel_layer = get_channel_layer()
+        await channel_layer.group_send(
+            "room_00000000-0000-0000-0000-000000000001",
+            {"type": "role_select_start", "slot_order": [1, 2, 3, 4, 5, 6]},
+        )
+
+        response = await communicator.receive_json_from()
+        self.assertEqual(response["type"], "role_select_start")
+        self.assertEqual(response["slot_order"], [1, 2, 3, 4, 5, 6])
+
+        await communicator.disconnect()
+
+    async def test_receives_turn_changed_broadcast(self):
+        communicator = WebsocketCommunicator(application, "/ws/room/00000000-0000-0000-0000-000000000001/")
+        await communicator.connect()
+
+        channel_layer = get_channel_layer()
+        await channel_layer.group_send(
+            "room_00000000-0000-0000-0000-000000000001",
+            {"type": "turn_changed", "active_slot": 2},
+        )
+
+        response = await communicator.receive_json_from()
+        self.assertEqual(response["type"], "turn_changed")
+        self.assertEqual(response["active_slot"], 2)
+
+        await communicator.disconnect()
+
+    async def test_receives_roles_revealed_broadcast(self):
+        communicator = WebsocketCommunicator(application, "/ws/room/00000000-0000-0000-0000-000000000001/")
+        await communicator.connect()
+
+        channel_layer = get_channel_layer()
+        await channel_layer.group_send(
+            "room_00000000-0000-0000-0000-000000000001",
+            {"type": "roles_revealed", "assignments": {"1": "PC", "2": "BC"}},
+        )
+
+        response = await communicator.receive_json_from()
+        self.assertEqual(response["type"], "roles_revealed")
+        self.assertIn("assignments", response)
+
+        await communicator.disconnect()
+
+    async def test_receives_gate_update_broadcast(self):
+        communicator = WebsocketCommunicator(application, "/ws/room/00000000-0000-0000-0000-000000000001/")
+        await communicator.connect()
+
+        channel_layer = get_channel_layer()
+        await channel_layer.group_send(
+            "room_00000000-0000-0000-0000-000000000001",
+            {"type": "gate_update", "gate_state": "some_state"},
+        )
+
+        response = await communicator.receive_json_from()
+        self.assertEqual(response["type"], "gate_update")
+        self.assertEqual(response["gate_state"], "some_state")
+
+        await communicator.disconnect()

src/apps/epic/tests/integrated/test_models.py

@@ -0,0 +1,216 @@
+from datetime import timedelta
+from django.db.models import Q
+from django.test import TestCase
+from django.urls import reverse
+from django.utils import timezone
+
+from apps.lyric.models import Token, User
+from apps.epic.models import GateSlot, Room, RoomInvite, TableSeat, debit_token, select_token
+
+
+class RoomCreationTest(TestCase):
+    def test_creating_a_room_generates_six_gate_slots(self):
+        owner = User.objects.create(email="founder@example.com")
+        room = Room.objects.create(name="Test Room", owner=owner)
+        self.assertEqual(GateSlot.objects.filter(room=room).count(), 6)
+
+
+class DebitTokenTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="founder@example.com")
+        self.room = Room.objects.create(
+            name="Test Room",
+            owner=self.owner,
+            renewal_period=timedelta(days=7)
+        )
+        self.slot = self.room.gate_slots.get(slot_number=1)
+
+    def test_debit_free_token_consumes_token_and_fills_slot(self):
+        free_token = Token.objects.get(user=self.owner, token_type=Token.FREE)
+        debit_token(self.owner, self.slot, free_token)
+        self.assertFalse(Token.objects.filter(pk=free_token.pk).exists())
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, GateSlot.FILLED)
+        self.assertEqual(self.slot.gamer, self.owner)
+
+    def test_debit_coin_does_not_consume_token(self):
+        coin_token = Token.objects.get(user=self.owner, token_type=Token.COIN)
+        debit_token(self.owner, self.slot, coin_token)
+        self.assertTrue(Token.objects.filter(pk=coin_token.pk).exists())
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, GateSlot.FILLED)
+        self.assertEqual(self.slot.gamer, self.owner)
+
+    def test_debit_fills_last_slot_and_opens_gate(self):
+        for i in range(2, 7):
+            gamer = User.objects.create(email=f"g{i}@test.io")
+            slot = self.room.gate_slots.get(slot_number=i)
+            slot.gamer = gamer
+            slot.status = GateSlot.FILLED
+            slot.save()
+        free_token = Token.objects.get(user=self.owner, token_type=Token.FREE)
+        debit_token(self.owner, self.slot, free_token)
+        self.room.refresh_from_db()
+        self.assertEqual(self.room.gate_status, Room.OPEN)
+
+
+class CoinTokenInUseTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="founder@example.com")
+        self.room = Room.objects.create(
+            name="Dragon's Den",
+            owner=self.owner,
+            renewal_period=timedelta(days=7),
+        )
+        self.slot = self.room.gate_slots.get(slot_number=1)
+        self.coin = Token.objects.get(user=self.owner, token_type=Token.COIN)
+        debit_token(self.owner, self.slot, self.coin)
+        self.coin.refresh_from_db()
+
+    def test_coin_tooltip_expiry_shows_next_ready_date(self):
+        expected_date = self.coin.next_ready_at.strftime("%Y-%m-%d")
+        self.assertIn(expected_date, self.coin.tooltip_expiry())
+
+    def test_coin_tooltip_room_html_contains_anchor(self):
+        room_url = reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        html = self.coin.tooltip_room_html()
+        self.assertIn(f'href="{room_url}"', html)
+        self.assertIn(self.room.name, html)
+
+
+class SelectTokenTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="gamer@test.io")
+        self.other_room = Room.objects.create(name="Other Room", owner=self.user)
+        self.coin = Token.objects.get(user=self.user, token_type=Token.COIN)
+
+    def test_returns_coin_when_available(self):
+        token = select_token(self.user)
+        self.assertEqual(token.token_type, Token.COIN)
+
+    def test_returns_free_token_when_coin_in_use(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        token = select_token(self.user)
+        self.assertEqual(token.token_type, Token.FREE)
+
+    def test_free_token_selection_is_fefo(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        Token.objects.filter(user=self.user, token_type=Token.FREE).delete()
+        soon = Token.objects.create(
+            user=self.user, token_type=Token.FREE,
+            expires_at=timezone.now() + timedelta(days=2),
+        )
+        Token.objects.create(
+            user=self.user, token_type=Token.FREE,
+            expires_at=timezone.now() + timedelta(days=6),
+        )
+        token = select_token(self.user)
+        self.assertEqual(token.pk, soon.pk)
+
+    def test_returns_tithe_when_coin_in_use_and_no_free_tokens(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        Token.objects.filter(user=self.user, token_type=Token.FREE).delete()
+        tithe = Token.objects.create(user=self.user, token_type=Token.TITHE)
+        token = select_token(self.user)
+        self.assertEqual(token.pk, tithe.pk)
+
+    def test_returns_none_when_all_depleted(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        Token.objects.filter(user=self.user, token_type=Token.FREE).delete()
+        token = select_token(self.user)
+        self.assertIsNone(token)
+
+    def test_returns_pass_for_staff(self):
+        self.user.is_staff = True
+        self.user.save()
+        pass_token = Token.objects.create(user=self.user, token_type=Token.PASS)
+        token = select_token(self.user)
+        self.assertEqual(token.token_type, Token.PASS)
+
+
+class RoomTableStatusTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="founder@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=self.owner)
+
+    def test_table_status_defaults_to_blank(self):
+        self.room.refresh_from_db()
+        self.assertFalse(self.room.table_status)
+
+    def test_room_has_role_select_constant(self):
+        self.assertEqual(Room.ROLE_SELECT, "ROLE_SELECT")
+
+    def test_room_has_sig_select_constant(self):
+        self.assertEqual(Room.SIG_SELECT, "SIG_SELECT")
+
+    def test_room_has_in_game_constant(self):
+        self.assertEqual(Room.IN_GAME, "IN_GAME")
+
+    def test_table_status_accepts_role_select(self):
+        self.room.table_status = Room.ROLE_SELECT
+        self.room.save()
+        self.room.refresh_from_db()
+        self.assertEqual(self.room.table_status, Room.ROLE_SELECT)
+
+
+class TableSeatModelTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="founder@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=self.owner)
+
+    def test_table_seat_can_be_created(self):
+        seat = TableSeat.objects.create(
+            room=self.room,
+            gamer=self.owner,
+            slot_number=1,
+        )
+        self.assertEqual(seat.slot_number, 1)
+        self.assertIsNone(seat.role)
+        self.assertFalse(seat.role_revealed)
+        self.assertIsNone(seat.seat_position)
+
+    def test_table_seat_role_choices_cover_all_six(self):
+        role_codes = [c[0] for c in TableSeat.ROLE_CHOICES]
+        for code in ["PC", "BC", "SC", "AC", "NC", "EC"]:
+            self.assertIn(code, role_codes)
+
+    def test_partner_map_pairs_are_mutual(self):
+        for a, b in [(TableSeat.PC, TableSeat.BC), (TableSeat.SC, TableSeat.AC), (TableSeat.NC, TableSeat.EC)]:
+            self.assertEqual(TableSeat.PARTNER_MAP[a], b)
+            self.assertEqual(TableSeat.PARTNER_MAP[b], a)
+
+    def test_room_table_seats_reverse_relation(self):
+        TableSeat.objects.create(room=self.room, gamer=self.owner, slot_number=1)
+        self.assertEqual(self.room.table_seats.count(), 1)
+
+
+class RoomInviteTest(TestCase):
+    def setUp(self):
+        self.founder = User.objects.create(email="founder@example.com")
+        self.room = Room.objects.create(name="Dragon's Den", owner=self.founder)
+
+    def test_founder_can_invite_by_email(self):
+        invite = RoomInvite.objects.create(
+            room=self.room,
+            inviter=self.founder,
+            invitee_email="friend@example.com",
+        )
+        self.assertEqual(invite.status, RoomInvite.PENDING)
+
+    def test_invited_room_appears_in_my_games_queryset(self):
+        friend = User.objects.create(email="friend@example.com")
+        RoomInvite.objects.create(
+            room=self.room,
+            inviter=self.founder,
+            invitee_email=friend.email,
+        )
+        rooms = Room.objects.filter(
+            Q(owner=friend) |
+            Q(gate_slots__gamer=friend) |
+            Q(invites__invitee_email=friend.email, invites__status=RoomInvite.PENDING)
+        ).distinct()
+        self.assertIn(self.room, rooms)

src/apps/epic/tests/integrated/test_views.py

@@ -0,0 +1,695 @@
+from datetime import timedelta
+from unittest.mock import patch
+
+from django.test import TestCase
+from django.urls import reverse
+from django.utils import timezone
+
+from apps.lyric.models import Token, User
+from apps.epic.models import GateSlot, Room, RoomInvite, TableSeat
+
+
+class RoomCreationViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="founder@test.io")
+        self.client.force_login(self.user)
+
+    def test_post_creates_room_and_redirects_to_gatekeeper(self):
+        response = self.client.post(
+            reverse("epic:create_room"),
+            data={"name": "Test Room"},
+        )
+        room = Room.objects.get(owner=self.user)
+        self.assertRedirects(
+            response, reverse(
+                "epic:gatekeeper",
+                args=[room.id],
+            )
+        )
+
+    def test_post_requires_login(self):
+        self.client.logout()
+        response = self.client.post(
+            reverse("epic:create_room"),
+            data={"name": "Test Room"},
+        )
+
+    def test_create_room_get_redirects_to_gameboard(self):
+        response = self.client.get(reverse("epic:create_room"))
+        self.assertRedirects(response, "/gameboard/")
+
+
+class MyGamesContextTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="gamer@example.com")
+        self.client.force_login(self.user)
+
+    def test_gameboard_context_includes_owned_rooms(self):
+        room = Room.objects.create(name="Durango", owner=self.user)
+        response = self.client.get("/gameboard/")
+        self.assertIn(room, response.context["my_games"])
+
+    def test_gameboard_context_includes_rooms_with_filled_slot(self):
+        other = User.objects.create(email="friend@example.com")
+        room = Room.objects.create(name="Their Room", owner=other)
+        slot = room.gate_slots.get(slot_number=2)
+        slot.gamer = self.user
+        slot.status = "FILLED"
+        slot.save()
+        response = self.client.get("/gameboard/")
+        self.assertIn(room, response.context["my_games"])
+
+
+class GateStatusViewTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="founder@test.io")
+        self.client.force_login(self.owner)
+        self.room = Room.objects.create(name="Test Room", owner=self.owner)
+
+    def test_gate_status_returns_launch_btn_when_open(self):
+        self.room.gate_status = Room.OPEN
+        self.room.save()
+        response = self.client.get(reverse("epic:gate_status", kwargs={"room_id": self.room.id}))
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "launch-game-btn")
+
+    def test_gate_status_returns_partial_when_gathering(self):
+        response = self.client.get(
+            reverse("epic:gate_status", kwargs={"room_id": self.room.id})
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "gate-modal")
+
+
+class DropTokenViewTest(TestCase):
+    def setUp(self):
+        self.gamer = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.gamer)
+        owner = User.objects.create(email="owner@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=owner)
+
+    def test_drop_token_reserves_lowest_empty_slot(self):
+        self.client.post(reverse("epic:drop_token", kwargs={"room_id": self.room.id}))
+        slot = self.room.gate_slots.get(slot_number=1)
+        self.assertEqual(slot.status, GateSlot.RESERVED)
+        self.assertEqual(slot.gamer, self.gamer)
+
+    def test_drop_token_skips_already_filled_slots(self):
+        other = User.objects.create(email="other@test.io")
+        slot1 = self.room.gate_slots.get(slot_number=1)
+        slot1.gamer = other
+        slot1.status = GateSlot.FILLED
+        slot1.save()
+        self.client.post(reverse("epic:drop_token", kwargs={"room_id": self.room.id}))
+        slot2 = self.room.gate_slots.get(slot_number=2)
+        self.assertEqual(slot2.status, GateSlot.RESERVED)
+        self.assertEqual(slot2.gamer, self.gamer)
+
+    def test_drop_token_blocked_when_another_slot_reserved(self):
+        other = User.objects.create(email="other@test.io")
+        slot1 = self.room.gate_slots.get(slot_number=1)
+        slot1.gamer = other
+        slot1.status = GateSlot.RESERVED
+        slot1.reserved_at = timezone.now()
+        slot1.save()
+        self.client.post(reverse("epic:drop_token", kwargs={"room_id": self.room.id}))
+        # Slot 2 should remain EMPTY — lock held by other user
+        slot2 = self.room.gate_slots.get(slot_number=2)
+        self.assertEqual(slot2.status, GateSlot.EMPTY)
+
+    def test_drop_token_blocked_when_user_already_has_filled_slot(self):
+        slot1 = self.room.gate_slots.get(slot_number=1)
+        slot1.gamer = self.gamer
+        slot1.status = GateSlot.FILLED
+        slot1.save()
+        self.client.post(reverse("epic:drop_token", kwargs={"room_id": self.room.id}))
+        slot2 = self.room.gate_slots.get(slot_number=2)
+        self.assertEqual(slot2.status, GateSlot.EMPTY)
+
+    def test_drop_token_sets_reserved_at(self):
+        self.client.post(reverse("epic:drop_token", kwargs={"room_id": self.room.id}))
+        slot = self.room.gate_slots.get(slot_number=1)
+        self.assertIsNotNone(slot.reserved_at)
+
+    def test_drop_token_redirects_to_gatekeeper(self):
+        response = self.client.post(
+            reverse("epic:drop_token", kwargs={"room_id": self.room.id})
+        )
+        self.assertRedirects(
+            response, reverse("epic:gatekeeper", args=[self.room.id])
+        )
+
+
+class ConfirmTokenViewTest(TestCase):
+    def setUp(self):
+        self.gamer = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.gamer)
+        owner = User.objects.create(email="owner@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=owner)
+        self.slot = self.room.gate_slots.get(slot_number=1)
+        self.slot.gamer = self.gamer
+        self.slot.status = GateSlot.RESERVED
+        self.slot.reserved_at = timezone.now()
+        self.slot.save()
+        Token.objects.create(user=self.gamer, token_type=Token.FREE)
+
+    def test_confirm_marks_slot_filled(self):
+        self.client.post(
+            reverse("epic:confirm_token", kwargs={"room_id": self.room.id})
+        )
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, GateSlot.FILLED)
+
+    def test_confirm_sets_gate_open_when_all_slots_filled(self):
+        # Fill slots 2–6 via ORM
+        for i in range(2, 7):
+            other = User.objects.create(email=f"g{i}@test.io")
+            s = self.room.gate_slots.get(slot_number=i)
+            s.gamer = other
+            s.status = GateSlot.FILLED
+            s.save()
+        self.client.post(
+            reverse("epic:confirm_token", kwargs={"room_id": self.room.id})
+        )
+        self.room.refresh_from_db()
+        self.assertEqual(self.room.gate_status, Room.OPEN)
+
+    def test_confirm_redirects_to_gatekeeper(self):
+        response = self.client.post(
+            reverse("epic:confirm_token", kwargs={"room_id": self.room.id})
+        )
+        self.assertRedirects(
+            response, reverse("epic:gatekeeper", args=[self.room.id])
+        )
+
+    def test_confirm_does_nothing_without_reserved_slot(self):
+        self.slot.status = GateSlot.EMPTY
+        self.slot.gamer = None
+        self.slot.save()
+        self.client.post(
+            reverse("epic:confirm_token", kwargs={"room_id": self.room.id})
+        )
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, GateSlot.EMPTY)
+
+
+class ReturnTokenViewTest(TestCase):
+    def setUp(self):
+        self.gamer = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.gamer)
+        owner = User.objects.create(email="owner@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=owner)
+        self.slot = self.room.gate_slots.get(slot_number=1)
+        self.slot.gamer = self.gamer
+        self.slot.status = GateSlot.RESERVED
+        self.slot.reserved_at = timezone.now()
+        self.slot.save()
+
+    def test_return_clears_reserved_slot(self):
+        self.client.post(
+            reverse("epic:return_token", kwargs={"room_id": self.room.id})
+        )
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, GateSlot.EMPTY)
+        self.assertIsNone(self.slot.gamer)
+        self.assertIsNone(self.slot.reserved_at)
+
+    def test_return_after_confirm_clears_filled_slot(self):
+        self.slot.status = GateSlot.FILLED
+        self.slot.save()
+        self.client.post(
+            reverse("epic:return_token", kwargs={"room_id": self.room.id})
+        )
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, GateSlot.EMPTY)
+        self.assertIsNone(self.slot.gamer)
+
+    def test_return_redirects_to_gatekeeper(self):
+        response = self.client.post(
+            reverse("epic:return_token", kwargs={"room_id": self.room.id})
+        )
+        self.assertRedirects(
+            response, reverse("epic:gatekeeper", args=[self.room.id])
+        )
+
+    def test_return_restores_coin_token(self):
+        coin = Token.objects.get(user=self.gamer, token_type=Token.COIN)
+        coin.current_room = self.room
+        coin.next_ready_at = timezone.now() + timedelta(days=7)
+        coin.save()
+        self.slot.status = GateSlot.FILLED
+        self.slot.debited_token_type = Token.COIN
+        self.slot.save()
+        self.client.post(
+            reverse("epic:return_token", kwargs={"room_id": self.room.id})
+        )
+        coin.refresh_from_db()
+        self.assertIsNone(coin.current_room)
+        self.assertIsNone(coin.next_ready_at)
+
+    def test_return_restores_free_token(self):
+        Token.objects.filter(user=self.gamer, token_type=Token.FREE).delete()
+        expires = timezone.now() + timedelta(days=3)
+        self.slot.status = GateSlot.FILLED
+        self.slot.debited_token_type = Token.FREE
+        self.slot.debited_token_expires_at = expires
+        self.slot.save()
+        self.client.post(
+            reverse("epic:return_token", kwargs={"room_id": self.room.id})
+        )
+        restored = Token.objects.filter(user=self.gamer, token_type=Token.FREE).first()
+        self.assertIsNotNone(restored)
+        self.assertEqual(restored.expires_at, expires)
+
+    def test_return_restores_tithe_token(self):
+        self.slot.status = GateSlot.FILLED
+        self.slot.debited_token_type = Token.TITHE
+        self.slot.save()
+        self.client.post(
+            reverse("epic:return_token", kwargs={"room_id": self.room.id})
+        )
+        self.assertTrue(
+            Token.objects.filter(user=self.gamer, token_type=Token.TITHE).exists()
+        )
+
+
+class DropTokenAvailabilityViewTest(TestCase):
+    def setUp(self):
+        self.gamer = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.gamer)
+        owner = User.objects.create(email="owner@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=owner)
+        self.other_room = Room.objects.create(name="Other Room", owner=owner)
+        self.coin = Token.objects.get(user=self.gamer, token_type=Token.COIN)
+
+    def test_drop_reserves_slot_when_tokens_available(self):
+        self.client.post(reverse("epic:drop_token", kwargs={"room_id": self.room.id}))
+        slot = self.room.gate_slots.get(slot_number=1)
+        self.assertEqual(slot.status, GateSlot.RESERVED)
+        # token not debited yet — that happens at confirm
+        self.coin.refresh_from_db()
+        self.assertIsNone(self.coin.current_room)
+
+    def test_drop_returns_402_when_all_tokens_depleted(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        Token.objects.filter(user=self.gamer, token_type=Token.FREE).delete()
+        response = self.client.post(
+            reverse("epic:drop_token", kwargs={"room_id": self.room.id})
+        )
+        self.assertEqual(response.status_code, 402)
+
+
+class ConfirmTokenPriorityViewTest(TestCase):
+    def setUp(self):
+        self.gamer = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.gamer)
+        owner = User.objects.create(email="owner@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=owner)
+        self.other_room = Room.objects.create(name="Other Room", owner=owner)
+        self.slot = self.room.gate_slots.get(slot_number=1)
+        self.slot.gamer = self.gamer
+        self.slot.status = GateSlot.RESERVED
+        self.slot.reserved_at = timezone.now()
+        self.slot.save()
+        self.coin = Token.objects.get(user=self.gamer, token_type=Token.COIN)
+
+    def test_confirm_leases_coin_to_room(self):
+        self.client.post(reverse("epic:confirm_token", kwargs={"room_id": self.room.id}))
+        self.coin.refresh_from_db()
+        self.assertEqual(self.coin.current_room, self.room)
+        self.assertTrue(Token.objects.filter(pk=self.coin.pk).exists())
+
+    def test_confirm_uses_free_token_when_coin_in_use(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        self.client.post(reverse("epic:confirm_token", kwargs={"room_id": self.room.id}))
+        self.assertEqual(
+            Token.objects.filter(user=self.gamer, token_type=Token.FREE).count(), 0
+        )
+        self.coin.refresh_from_db()
+        self.assertEqual(self.coin.current_room, self.other_room)
+
+    def test_confirm_uses_tithe_when_free_tokens_exhausted(self):
+        self.coin.current_room = self.other_room
+        self.coin.save()
+        Token.objects.filter(user=self.gamer, token_type=Token.FREE).delete()
+        tithe = Token.objects.create(user=self.gamer, token_type=Token.TITHE)
+        self.client.post(reverse("epic:confirm_token", kwargs={"room_id": self.room.id}))
+        self.assertFalse(Token.objects.filter(pk=tithe.pk).exists())
+
+    def test_pass_not_consumed_and_coin_not_leased(self):
+        self.gamer.is_staff = True
+        self.gamer.save()
+        pass_token = Token.objects.create(user=self.gamer, token_type=Token.PASS)
+        self.client.post(reverse("epic:confirm_token", kwargs={"room_id": self.room.id}))
+        self.assertTrue(Token.objects.filter(pk=pass_token.pk).exists())
+        self.coin.refresh_from_db()
+        self.assertIsNone(self.coin.current_room)
+
+
+class RoleSelectRenderingTest(TestCase):
+    def setUp(self):
+        self.founder = User.objects.create(email="founder@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=self.founder)
+        self.gamers = [self.founder]
+        for i in range(2, 7):
+            self.gamers.append(User.objects.create(email=f"g{i}@test.io"))
+        for i, gamer in enumerate(self.gamers, start=1):
+            slot = self.room.gate_slots.get(slot_number=i)
+            slot.gamer = gamer
+            slot.status = GateSlot.FILLED
+            slot.save()
+        self.room.gate_status = Room.OPEN
+        self.room.table_status = Room.ROLE_SELECT
+        self.room.save()
+        for i, gamer in enumerate(self.gamers, start=1):
+            TableSeat.objects.create(room=self.room, gamer=gamer, slot_number=i)
+
+    def test_room_view_includes_card_stack_when_role_select(self):
+        self.client.force_login(self.founder)
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, "card-stack")
+
+    def test_card_stack_eligible_for_slot1_gamer(self):
+        self.client.force_login(self.founder)
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, 'data-state="eligible"')
+
+    def test_card_stack_ineligible_for_slot2_gamer(self):
+        self.client.force_login(self.gamers[1])
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, 'data-state="ineligible"')
+
+    def test_card_stack_ineligible_shows_fa_ban(self):
+        self.client.force_login(self.gamers[1])
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, "fa-ban")
+
+    def test_card_stack_eligible_omits_fa_ban(self):
+        self.client.force_login(self.founder)
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertNotContains(response, "fa-ban")
+
+    def test_gatekeeper_overlay_absent_when_role_select(self):
+        self.client.force_login(self.founder)
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertNotContains(response, "gate-overlay")
+
+    def test_six_table_seats_rendered(self):
+        self.client.force_login(self.founder)
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, "table-seat", count=6)
+
+    def test_active_table_seat_has_active_class(self):
+        self.client.force_login(self.founder)  # slot 1 is active
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, 'class="table-seat active"')
+
+    def test_inactive_table_seat_lacks_active_class(self):
+        self.client.force_login(self.founder)
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        # Slots 2–6 are not active, so at least one plain table-seat exists
+        self.assertContains(response, 'class="table-seat"')
+
+    def test_card_stack_has_data_user_slots_for_eligible_gamer(self):
+        self.client.force_login(self.founder)  # founder is slot 1 only
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, 'data-user-slots="1"')
+
+    def test_card_stack_has_data_user_slots_for_ineligible_gamer(self):
+        self.client.force_login(self.gamers[1])  # slot 2 gamer
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, 'data-user-slots="2"')
+
+
+class PickRolesViewTest(TestCase):
+    def setUp(self):
+        self.founder = User.objects.create(email="founder@test.io")
+        self.client.force_login(self.founder)
+        self.room = Room.objects.create(name="Test Room", owner=self.founder)
+        for i in range(1, 7):
+            gamer = self.founder if i == 1 else User.objects.create(email=f"g{i}@test.io")
+            slot = self.room.gate_slots.get(slot_number=i)
+            slot.gamer = gamer
+            slot.status = GateSlot.FILLED
+            slot.save()
+        self.room.gate_status = Room.OPEN
+        self.room.save()
+
+    def test_pick_roles_transitions_room_to_role_select(self):
+        self.client.post(reverse("epic:pick_roles", kwargs={"room_id": self.room.id}))
+        self.room.refresh_from_db()
+        self.assertEqual(self.room.table_status, Room.ROLE_SELECT)
+
+    def test_pick_roles_creates_one_table_seat_per_filled_slot(self):
+        self.client.post(reverse("epic:pick_roles", kwargs={"room_id": self.room.id}))
+        self.assertEqual(TableSeat.objects.filter(room=self.room).count(), 6)
+
+    def test_pick_roles_table_seats_carry_gamer_and_slot_number(self):
+        self.client.post(reverse("epic:pick_roles", kwargs={"room_id": self.room.id}))
+        seat = TableSeat.objects.get(room=self.room, slot_number=1)
+        self.assertEqual(seat.gamer, self.founder)
+
+    def test_only_open_room_can_start_role_select(self):
+        self.room.gate_status = Room.GATHERING
+        self.room.save()
+        self.client.post(reverse("epic:pick_roles", kwargs={"room_id": self.room.id}))
+        self.room.refresh_from_db()
+        self.assertIsNone(self.room.table_status)
+
+    def test_pick_roles_requires_login(self):
+        self.client.logout()
+        response = self.client.post(
+            reverse("epic:pick_roles", kwargs={"room_id": self.room.id})
+        )
+        self.assertEqual(response.status_code, 302)
+        self.assertIn("/accounts/login/", response.url)
+
+    def test_pick_roles_redirects_to_room(self):
+        response = self.client.post(
+            reverse("epic:pick_roles", kwargs={"room_id": self.room.id})
+        )
+        self.assertRedirects(
+            response, reverse("epic:gatekeeper", args=[self.room.id])
+        )
+
+    def test_pick_roles_notifies_channel_layer(self):
+        with patch("apps.epic.views._notify_role_select_start") as mock_notify:
+            self.client.post(reverse("epic:pick_roles", kwargs={"room_id": self.room.id}))
+            mock_notify.assert_called_once_with(self.room.id)
+
+
+class SelectRoleViewTest(TestCase):
+    def setUp(self):
+        self.founder = User.objects.create(email="founder@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=self.founder)
+        self.gamers = [self.founder]
+        for i in range(2, 7):
+            self.gamers.append(User.objects.create(email=f"g{i}@test.io"))
+        for i, gamer in enumerate(self.gamers, start=1):
+            slot = self.room.gate_slots.get(slot_number=i)
+            slot.gamer = gamer
+            slot.status = GateSlot.FILLED
+            slot.save()
+        self.room.gate_status = Room.OPEN
+        self.room.table_status = Room.ROLE_SELECT
+        self.room.save()
+        for i, gamer in enumerate(self.gamers, start=1):
+            TableSeat.objects.create(room=self.room, gamer=gamer, slot_number=i)
+        self.client.force_login(self.founder)
+
+    def test_select_role_records_choice(self):
+        self.client.post(
+            reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+            data={"role": "PC"},
+        )
+        seat = TableSeat.objects.get(room=self.room, slot_number=1)
+        self.assertEqual(seat.role, "PC")
+
+    def test_select_role_wrong_turn_makes_no_change(self):
+        self.client.force_login(self.gamers[1])  # slot 2 — not their turn
+        self.client.post(
+            reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+            data={"role": "BC"},
+        )
+        seat = TableSeat.objects.get(room=self.room, slot_number=2)
+        self.assertIsNone(seat.role)
+
+    def test_turn_advances_after_selection(self):
+        self.client.post(
+            reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+            data={"role": "PC"},
+        )
+        next_active = TableSeat.objects.filter(
+            room=self.room, role__isnull=True
+        ).order_by("slot_number").first()
+        self.assertEqual(next_active.slot_number, 2)
+
+    def test_all_selected_sets_sig_select(self):
+        roles = ["PC", "BC", "SC", "AC", "NC"]
+        for i, role in enumerate(roles):
+            seat = TableSeat.objects.get(room=self.room, slot_number=i + 1)
+            seat.role = role
+            seat.save()
+        self.client.force_login(self.gamers[5])  # slot 6 — last
+        self.client.post(
+            reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+            data={"role": "EC"},
+        )
+        self.room.refresh_from_db()
+        self.assertEqual(self.room.table_status, Room.SIG_SELECT)
+
+    def test_select_role_notifies_turn_changed(self):
+        with patch("apps.epic.views._notify_turn_changed") as mock_notify:
+            self.client.post(
+                reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+                data={"role": "PC"},
+            )
+            mock_notify.assert_called_once_with(self.room.id)
+
+    def test_select_role_notifies_roles_revealed_when_last(self):
+        roles = ["PC", "BC", "SC", "AC", "NC"]
+        for i, role in enumerate(roles):
+            seat = TableSeat.objects.get(room=self.room, slot_number=i + 1)
+            seat.role = role
+            seat.save()
+        self.client.force_login(self.gamers[5])
+        with patch("apps.epic.views._notify_roles_revealed") as mock_notify:
+            self.client.post(
+                reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+                data={"role": "EC"},
+            )
+            mock_notify.assert_called_once_with(self.room.id)
+
+    def test_select_role_requires_login(self):
+        self.client.logout()
+        response = self.client.post(
+            reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+            data={"role": "PC"},
+        )
+        self.assertEqual(response.status_code, 302)
+        self.assertIn("/accounts/login/", response.url)
+
+    def test_select_role_redirects_to_room(self):
+        response = self.client.post(
+            reverse("epic:select_role", kwargs={"room_id": self.room.id}),
+            data={"role": "PC"},
+        )
+        self.assertRedirects(
+            response, reverse("epic:gatekeeper", args=[self.room.id])
+        )
+
+
+class RevealPhaseRenderingTest(TestCase):
+    def setUp(self):
+        self.founder = User.objects.create(email="founder@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=self.founder)
+        gamers = [self.founder]
+        for i in range(2, 7):
+            gamers.append(User.objects.create(email=f"g{i}@test.io"))
+        roles = ["PC", "BC", "SC", "AC", "NC", "EC"]
+        for i, (gamer, role) in enumerate(zip(gamers, roles), start=1):
+            TableSeat.objects.create(
+                room=self.room, gamer=gamer, slot_number=i,
+                role=role, role_revealed=True,
+            )
+        self.room.gate_status = Room.OPEN
+        self.room.table_status = Room.SIG_SELECT
+        self.room.save()
+        self.client.force_login(self.founder)
+
+    def test_face_up_role_cards_rendered_when_sig_select(self):
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, "face-up")
+
+    def test_inv_role_card_slot_present(self):
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, "id_inv_role_card")
+
+    def test_partner_indicator_present_when_sig_select(self):
+        response = self.client.get(
+            reverse("epic:gatekeeper", kwargs={"room_id": self.room.id})
+        )
+        self.assertContains(response, "partner-indicator")
+
+
+class RoomActionsViewTest(TestCase):
+    def setUp(self):
+        self.owner = User.objects.create(email="owner@test.io")
+        self.gamer = User.objects.create(email="gamer@test.io")
+        self.room = Room.objects.create(name="Test Room", owner=self.owner)
+        self.slot = self.room.gate_slots.get(slot_number=2)
+        self.slot.gamer = self.gamer
+        self.slot.status = "FILLED"
+        self.slot.save()
+        RoomInvite.objects.create(
+            room=self.room, inviter=self.owner,
+            invitee_email=self.gamer.email
+        )
+
+    def test_owner_delete_removes_room(self):
+        self.client.force_login(self.owner)
+        self.client.post(reverse("epic:delete_room", kwargs={"room_id": self.room.id}))
+        self.assertFalse(Room.objects.filter(pk=self.room.pk).exists())
+
+    def test_non_owner_delete_does_not_remove_room(self):
+        self.client.force_login(self.gamer)
+        self.client.post(reverse("epic:delete_room", kwargs={"room_id": self.room.id}))
+        self.assertTrue(Room.objects.filter(pk=self.room.pk).exists())
+
+    def test_delete_redirects_to_gameboard(self):
+        self.client.force_login(self.owner)
+        response = self.client.post(
+            reverse("epic:delete_room", kwargs={"room_id": self.room.id})
+        )
+        self.assertRedirects(response, "/gameboard/")
+
+    def test_abandon_clears_slot(self):
+        self.client.force_login(self.gamer)
+        self.client.post(reverse("epic:abandon_room", kwargs={"room_id": self.room.id}))
+        self.slot.refresh_from_db()
+        self.assertEqual(self.slot.status, "EMPTY")
+        self.assertIsNone(self.slot.gamer)
+
+    def test_abandon_deletes_pending_invite(self):
+        self.client.force_login(self.gamer)
+        self.client.post(reverse("epic:abandon_room", kwargs={"room_id": self.room.id}))
+        self.assertFalse(
+            RoomInvite.objects.filter(
+                room=self.room, invitee_email=self.gamer.email
+            ).exists()
+        )
+
+    def test_abandon_redirects_to_gameboard(self):
+        self.client.force_login(self.gamer)
+        response = self.client.post(
+            reverse("epic:abandon_room", kwargs={"room_id": self.room.id})
+        )
+        self.assertRedirects(response, "/gameboard/")

src/apps/epic/urls.py

@@ -0,0 +1,20 @@
+from django.urls import path
+from . import views
+
+
+app_name = 'epic'
+
+urlpatterns = [
+    path('rooms/create_room', views.create_room, name='create_room'),
+    path('room/<uuid:room_id>/gate/', views.gatekeeper, name='gatekeeper'),
+    path('room/<uuid:room_id>/gate/drop_token', views.drop_token, name='drop_token'),
+    path('room/<uuid:room_id>/gate/confirm_token', views.confirm_token, name='confirm_token'),
+    path('room/<uuid:room_id>/gate/return_token', views.return_token, name='return_token'),
+    path('room/<uuid:room_id>/gate/release_slot', views.release_slot, name='release_slot'),
+    path('room/<uuid:room_id>/pick-roles', views.pick_roles, name='pick_roles'),
+    path('room/<uuid:room_id>/select-role', views.select_role, name='select_role'),
+    path('room/<uuid:room_id>/gate/invite', views.invite_gamer, name='invite_gamer'),
+    path('room/<uuid:room_id>/gate/status', views.gate_status, name='gate_status'),
+    path('room/<uuid:room_id>/delete', views.delete_room, name='delete_room'),
+    path('room/<uuid:room_id>/abandon', views.abandon_room, name='abandon_room'),
+]

src/apps/epic/views.py

@@ -0,0 +1,445 @@
+from datetime import timedelta
+
+from asgiref.sync import async_to_sync
+from channels.layers import get_channel_layer
+from django.contrib.auth.decorators import login_required
+from django.http import HttpResponse
+from django.shortcuts import redirect, render
+from django.utils import timezone
+
+from apps.epic.models import GateSlot, Room, RoomInvite, TableSeat, debit_token, select_token
+from apps.lyric.models import Token
+
+
+RESERVE_TIMEOUT = timedelta(seconds=60)
+
+
+def _notify_gate_update(room_id):
+    async_to_sync(get_channel_layer().group_send)(
+        f'room_{room_id}',
+        {'type': 'gate_update'},
+    )
+
+
+def _notify_turn_changed(room_id):
+    active_seat = TableSeat.objects.filter(
+        room_id=room_id, role__isnull=True
+    ).order_by("slot_number").first()
+    active_slot = active_seat.slot_number if active_seat else None
+    async_to_sync(get_channel_layer().group_send)(
+        f'room_{room_id}',
+        {'type': 'turn_changed', 'active_slot': active_slot},
+    )
+
+
+def _notify_roles_revealed(room_id):
+    assignments = {
+        str(seat.slot_number): seat.role
+        for seat in TableSeat.objects.filter(room_id=room_id).order_by("slot_number")
+    }
+    async_to_sync(get_channel_layer().group_send)(
+        f'room_{room_id}',
+        {'type': 'roles_revealed', 'assignments': assignments},
+    )
+
+
+def _notify_role_select_start(room_id):
+    slot_order = list(
+        GateSlot.objects.filter(room_id=room_id, status=GateSlot.FILLED)
+        .order_by("slot_number")
+        .values_list("slot_number", flat=True)
+    )
+    async_to_sync(get_channel_layer().group_send)(
+        f'room_{room_id}',
+        {'type': 'role_select_start', 'slot_order': slot_order},
+    )
+
+
+def _expire_reserved_slots(room):
+    cutoff = timezone.now() - RESERVE_TIMEOUT
+    room.gate_slots.filter(
+        status=GateSlot.RESERVED,
+        reserved_at__lt=cutoff,
+    ).update(status=GateSlot.EMPTY, gamer=None, reserved_at=None)
+
+
+def _gate_context(room, user):
+    _expire_reserved_slots(room)
+    slots = room.gate_slots.order_by("slot_number")
+    pending_slot = slots.filter(status=GateSlot.RESERVED).first()
+    user_reserved_slot = None
+    user_filled_slot = None
+    carte_token = None
+    carte_slots_claimed = 0
+    carte_nvm_slot_number = None
+    carte_next_slot_number = None
+    if user.is_authenticated:
+        user_reserved_slot = slots.filter(gamer=user, status=GateSlot.RESERVED).first()
+        user_filled_slot = slots.filter(gamer=user, status=GateSlot.FILLED).first()
+        carte_token = user.tokens.filter(
+            token_type=Token.CARTE, current_room=room
+        ).first()
+        if carte_token:
+            carte_slots_claimed = carte_token.slots_claimed
+            # NVM shown on the highest-numbered slot this user filled via CARTE
+            nvm_slot = slots.filter(
+                debited_token_type=Token.CARTE, gamer=user, status=GateSlot.FILLED
+            ).order_by("-slot_number").first()
+            if nvm_slot:
+                carte_nvm_slot_number = nvm_slot.slot_number
+            # Only the very next empty slot gets an OK button
+            next_slot = slots.filter(status=GateSlot.EMPTY).order_by("slot_number").first()
+            if next_slot:
+                carte_next_slot_number = next_slot.slot_number
+    carte_active = carte_token is not None
+    eligible = (
+        user.is_authenticated
+        and pending_slot is None
+        and user_reserved_slot is None
+        and user_filled_slot is None
+        and not carte_active
+    )
+    token_depleted = eligible and select_token(user) is None
+    can_drop = eligible and not token_depleted
+    is_last_slot = (
+        user_reserved_slot is not None
+        and slots.filter(status=GateSlot.EMPTY).count() == 0
+    )
+    user_can_reject = user_reserved_slot is not None or user_filled_slot is not None or carte_active
+    return {
+        "slots": slots,
+        "pending_slot": pending_slot,
+        "user_reserved_slot": user_reserved_slot,
+        "user_filled_slot": user_filled_slot,
+        "can_drop": can_drop,
+        "token_depleted": token_depleted,
+        "is_last_slot": is_last_slot,
+        "user_can_reject": user_can_reject,
+        "carte_active": carte_active,
+        "carte_slots_claimed": carte_slots_claimed,
+        "carte_nvm_slot_number": carte_nvm_slot_number,
+        "carte_next_slot_number": carte_next_slot_number,
+    }
+
+
+def _role_select_context(room, user):
+    user_seat = None
+    active_seat = None
+    unassigned = room.table_seats.filter(role__isnull=True).order_by("slot_number")
+    if unassigned.exists():
+        # Normal path — TableSeats present
+        active_seat = unassigned.first()
+        user_seat = None
+        if user.is_authenticated:
+            user_seat = room.table_seats.filter(gamer=user, role__isnull=True).order_by("slot_number").first()
+        if user_seat and user_seat.slot_number == active_seat.slot_number:
+            card_stack_state = "eligible"
+        else:
+            card_stack_state = "ineligible"
+    else:
+        # Fallback — no TableSeats yet; use GateSlot drop order
+        active_slot = room.gate_slots.filter(
+            status=GateSlot.FILLED
+        ).order_by("slot_number").first()
+        if active_slot is None:
+            card_stack_state = None
+        elif user.is_authenticated and active_slot.gamer == user:
+            card_stack_state = "eligible"
+        else:
+            card_stack_state = "ineligible"
+    taken_roles = list(
+        room.table_seats.exclude(role__isnull=True).values_list("role", flat=True)
+    )
+    _action_order = {r: i for i, r in enumerate(["PC", "NC", "EC", "SC", "AC", "BC"])}
+    assigned_seats = (
+        sorted(
+            room.table_seats.filter(gamer=user, role__isnull=False),
+            key=lambda s: _action_order.get(s.role, 99),
+        )
+        if user.is_authenticated else []
+    )
+    active_slot = active_seat.slot_number if active_seat else None
+    ctx = {
+        "card_stack_state": card_stack_state,
+        "taken_roles": taken_roles,
+        "assigned_seats": assigned_seats,
+        "user_seat": user_seat,
+        "user_slots": list(
+            room.table_seats.filter(gamer=user, role__isnull=True)
+            .order_by("slot_number")
+            .values_list("slot_number", flat=True)
+        ) if user.is_authenticated else [],
+        "active_slot": active_slot,
+    }
+    if room.table_status == Room.SIG_SELECT:
+        user_seat = room.table_seats.filter(gamer=user).first() if user.is_authenticated else None
+        partner_role = TableSeat.PARTNER_MAP.get(user_seat.role) if user_seat and user_seat.role else None
+        partner_seat = room.table_seats.filter(role=partner_role).first() if partner_role else None
+        ctx["user_seat"] = user_seat
+        ctx["partner_seat"] = partner_seat
+        ctx["revealed_seats"] = room.table_seats.filter(role_revealed=True).order_by("slot_number")
+    return ctx
+
+
+@login_required
+def create_room(request):
+    if request.method == "POST":
+        name = request.POST.get("name", "").strip()
+        if name:
+            room = Room.objects.create(name=name, owner=request.user)
+            return redirect("epic:gatekeeper", room_id=room.id)
+    return redirect("/gameboard/")
+
+
+def gatekeeper(request, room_id):
+    room = Room.objects.get(id=room_id)
+    if room.table_status:
+        ctx = _role_select_context(room, request.user)
+    else:
+        ctx = _gate_context(room, request.user)
+    ctx["room"] = room
+    return render(request, "apps/gameboard/room.html", ctx)
+
+
+@login_required
+def drop_token(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        token_id = request.POST.get("token_id")
+        if token_id:
+            token = request.user.tokens.filter(id=token_id).first()
+        else:
+            token = select_token(request.user)
+        if token is None:
+            return HttpResponse(status=402)
+        if token.token_type == Token.CARTE:
+            # CARTE enters the machine without reserving a slot — all slots
+            # become individually claimable via .drop-token-btn
+            token.current_room = room
+            token.save()
+            request.session["kit_token_id"] = str(token.id)
+            _notify_gate_update(room_id)
+            return redirect("epic:gatekeeper", room_id=room_id)
+        if room.gate_slots.filter(status=GateSlot.RESERVED).exists():
+            return redirect("epic:gatekeeper", room_id=room_id)
+        if room.gate_slots.filter(gamer=request.user, status=GateSlot.FILLED).exists():
+            return redirect("epic:gatekeeper", room_id=room_id)
+        slot = room.gate_slots.filter(
+            status=GateSlot.EMPTY
+        ).order_by("slot_number").first()
+        if slot:
+            slot.gamer = request.user
+            slot.status = GateSlot.RESERVED
+            slot.reserved_at = timezone.now()
+            slot.save()
+            request.session["kit_token_id"] = str(token.id)
+            _notify_gate_update(room_id)
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def confirm_token(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        slot_number = request.POST.get("slot_number")
+        if slot_number:
+            # CARTE per-slot fill: directly fill the requested slot
+            carte = request.user.tokens.filter(
+                token_type=Token.CARTE, current_room=room
+            ).first()
+            if carte:
+                slot = room.gate_slots.filter(
+                    slot_number=slot_number, status=GateSlot.EMPTY
+                ).first()
+                if slot:
+                    debit_token(request.user, slot, carte)
+                    # slots_claimed is the high-water mark — advance if beyond current
+                    if int(slot_number) > carte.slots_claimed:
+                        carte.slots_claimed = int(slot_number)
+                        carte.save()
+                    _notify_gate_update(room_id)
+        else:
+            slot = room.gate_slots.filter(
+                gamer=request.user, status=GateSlot.RESERVED
+            ).first()
+            if slot:
+                token_id = request.session.pop("kit_token_id", None)
+                token = None
+                if token_id:
+                    token = request.user.tokens.filter(id=token_id).first()
+                if not token:
+                    token = select_token(request.user)
+                if token:
+                    debit_token(request.user, slot, token)
+                    _notify_gate_update(room_id)
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def return_token(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        # CARTE full return: reset token + all CARTE-debited slots
+        carte = request.user.tokens.filter(
+            token_type=Token.CARTE, current_room=room
+        ).first()
+        if carte:
+            room.gate_slots.filter(
+                debited_token_type=Token.CARTE, gamer=request.user
+            ).update(
+                gamer=None, status=GateSlot.EMPTY, filled_at=None,
+                debited_token_type=None, debited_token_expires_at=None,
+            )
+            carte.current_room = None
+            carte.slots_claimed = 0
+            carte.save()
+            request.session.pop("kit_token_id", None)
+            _notify_gate_update(room_id)
+            return redirect("epic:gatekeeper", room_id=room_id)
+        slot = room.gate_slots.filter(
+            gamer=request.user,
+            status__in=[GateSlot.RESERVED, GateSlot.FILLED],
+        ).first()
+        if slot:
+            if slot.status == GateSlot.FILLED:
+                if slot.debited_token_type == Token.COIN:
+                    coin = request.user.tokens.filter(
+                        token_type=Token.COIN, current_room=room
+                    ).first()
+                    if coin:
+                        coin.current_room = None
+                        coin.next_ready_at = None
+                        coin.save()
+                elif slot.debited_token_type in (Token.FREE, Token.TITHE):
+                    Token.objects.create(
+                        user=request.user,
+                        token_type=slot.debited_token_type,
+                        expires_at=slot.debited_token_expires_at,
+                    )
+            request.session.pop("kit_token_id", None)
+            slot.gamer = None
+            slot.status = GateSlot.EMPTY
+            slot.reserved_at = None
+            slot.filled_at = None
+            slot.debited_token_type = None
+            slot.debited_token_expires_at = None
+            slot.save()
+            _notify_gate_update(room_id)
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def release_slot(request, room_id):
+    """Un-fill a single CARTE-claimed slot without returning the CARTE itself."""
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        slot_number = request.POST.get("slot_number")
+        if slot_number:
+            slot = room.gate_slots.filter(
+                slot_number=slot_number,
+                debited_token_type=Token.CARTE,
+                gamer=request.user,
+                status=GateSlot.FILLED,
+            ).first()
+            if slot:
+                slot.gamer = None
+                slot.status = GateSlot.EMPTY
+                slot.filled_at = None
+                slot.debited_token_type = None
+                slot.debited_token_expires_at = None
+                slot.save()
+                if room.gate_status == Room.OPEN:
+                    room.gate_status = Room.GATHERING
+                    room.save()
+                _notify_gate_update(room_id)
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def select_role(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        if room.table_status != Room.ROLE_SELECT:
+            return redirect("epic:gatekeeper", room_id=room_id)
+        active_seat = room.table_seats.filter(
+            role__isnull=True
+        ).order_by("slot_number").first()
+        if not active_seat or active_seat.gamer != request.user:
+            return redirect("epic:gatekeeper", room_id=room_id)
+        role = request.POST.get("role")
+        valid_roles = [code for code, _ in TableSeat.ROLE_CHOICES]
+        if not role or role not in valid_roles:
+            return redirect("epic:gatekeeper", room_id=room_id)
+        if room.table_seats.filter(role=role).exists():
+            return redirect("epic:gatekeeper", room_id=room_id)
+        active_seat.role = role
+        active_seat.save()
+        if room.table_seats.filter(role__isnull=True).exists():
+            _notify_turn_changed(room_id)
+        else:
+            room.table_status = Room.SIG_SELECT
+            room.save()
+            _notify_roles_revealed(room_id)
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def pick_roles(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        if room.gate_status == Room.OPEN:
+            room.table_status = Room.ROLE_SELECT
+            room.save()
+            for slot in room.gate_slots.filter(status=GateSlot.FILLED).order_by("slot_number"):
+                TableSeat.objects.create(
+                    room=room,
+                    gamer=slot.gamer,
+                    slot_number=slot.slot_number,
+                )
+            _notify_role_select_start(room_id)
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def invite_gamer(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        email = request.POST.get("invitee_email", "").strip()
+        if email:
+            RoomInvite.objects.get_or_create(
+                room=room,
+                inviter=request.user,
+                invitee_email=email,
+                defaults={"status": RoomInvite.PENDING}
+            )
+    return redirect("epic:gatekeeper", room_id=room_id)
+
+
+@login_required
+def delete_room(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        if request.user == room.owner:
+            room.delete()
+    return redirect("/gameboard/")
+
+
+@login_required
+def abandon_room(request, room_id):
+    if request.method == "POST":
+        room = Room.objects.get(id=room_id)
+        room.gate_slots.filter(gamer=request.user).update(
+            gamer=None, status="EMPTY", filled_at=None
+        )
+        room.invites.filter(
+            invitee_email=request.user.email,
+            status=RoomInvite.PENDING
+        ).delete()
+    return redirect("/gameboard/")
+
+
+def gate_status(request, room_id):
+    room = Room.objects.get(id=room_id)
+    ctx = _gate_context(room, request.user)
+    ctx["room"] = room
+    return render(request, "apps/gameboard/_partials/_gatekeeper.html", ctx)

src/apps/epic/voronoi.py

@@ -0,0 +1 @@
+# TODO: toroidal topology (tile seeds across boundary before computing)

src/apps/gameboard/admin.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.

src/apps/gameboard/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class GameboardConfig(AppConfig):
+    name = 'apps.gameboard'

src/apps/gameboard/models.py

@@ -0,0 +1,3 @@
+from django.db import models
+
+# Create your models here.

src/apps/gameboard/static/apps/gameboard/gameboard.js

@@ -0,0 +1,130 @@
+function getCsrfToken() {
+    const match = document.cookie.match(/csrftoken=([^;]+)/)
+    return match ? match[1] : '';
+}
+
+function initGameKitTooltips() {
+    const portal = document.getElementById('id_tooltip_portal');
+    const miniPortal = document.getElementById('id_mini_tooltip_portal');
+    const gameKit = document.getElementById('id_game_kit');
+    if (!portal || !miniPortal || !gameKit) return;
+
+    let equippedId = gameKit.dataset.equippedId || '';
+    let activeToken = null;
+    let equipping = false;
+
+    function inRect(x, y, r) {
+        return x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+    }
+
+    function closePortals() {
+        portal.classList.remove('active');
+        miniPortal.classList.remove('active');
+        miniPortal.style.display = '';
+        activeToken = null;
+    }
+
+    document.addEventListener('mousemove', (e) => {
+        if (portal.classList.contains('active') && activeToken) {
+            const rects = [activeToken.getBoundingClientRect(), portal.getBoundingClientRect()];
+            if (miniPortal.classList.contains('active')) rects.push(miniPortal.getBoundingClientRect());
+            const left   = Math.min(...rects.map(r => r.left));
+            const top    = Math.min(...rects.map(r => r.top));
+            const right  = Math.max(...rects.map(r => r.right));
+            const bottom = Math.max(...rects.map(r => r.bottom));
+            if (!inRect(e.clientX, e.clientY, { left, top, right, bottom })) closePortals();
+        } else if (!portal.classList.contains('active')) {
+            for (const tokenEl of gameKit.querySelectorAll('.token')) {
+                if (!tokenEl.querySelector('.token-tooltip')) continue;
+                if (inRect(e.clientX, e.clientY, tokenEl.getBoundingClientRect())) {
+                    showPortals(tokenEl);
+                    break;
+                }
+            }
+        }
+    });
+
+    function buildMiniContent(tokenId) {
+        if (equippedId && tokenId === equippedId) {
+            miniPortal.textContent = 'Equipped';
+        } else {
+            const btn = document.createElement('button');
+            btn.className = 'equip-trinket-btn';
+            btn.dataset.tokenId = tokenId;
+            btn.textContent = 'Equip Trinket?';
+            btn.addEventListener('click', (e) => {
+                e.stopPropagation();
+                equipping = true;
+                equippedId = tokenId;
+                gameKit.dataset.equippedId = equippedId;
+                fetch(`/gameboard/equip-trinket/${tokenId}/`, {
+                    method: 'POST',
+                    headers: {'X-CSRFToken': getCsrfToken()},
+                }).then(r => {
+                    if (r.ok && equipping) {
+                        equipping = false;
+                        closePortals();
+                    } else {
+                        equipping = false;
+                    }
+                });
+            });
+            miniPortal.innerHTML = '';
+            miniPortal.appendChild(btn);
+        }
+    }
+
+    function showPortals(token) {
+        equipping = false;
+        activeToken = token;
+        const tooltip = token.querySelector('.token-tooltip');
+        portal.innerHTML = tooltip.innerHTML;
+        portal.classList.add('active');
+
+        const isEquippable = !!token.dataset.tokenId;
+        let miniHeight = 0;
+
+        if (isEquippable) {
+            buildMiniContent(token.dataset.tokenId);
+            miniPortal.classList.add('active');
+            miniPortal.style.display = 'block';
+            miniHeight = miniPortal.offsetHeight + 4;
+        } else {
+            miniPortal.classList.remove('active');
+            miniPortal.style.display = '';
+        }
+
+        const tokenRect = token.getBoundingClientRect();
+        const halfW = portal.offsetWidth / 2;
+        const rawLeft = tokenRect.left + tokenRect.width / 2;
+        const clampedLeft = Math.max(halfW + 8, Math.min(rawLeft, window.innerWidth - halfW - 8));
+        portal.style.left = Math.round(clampedLeft) + 'px';
+        portal.style.top = Math.round(tokenRect.top) + 'px';
+        portal.style.transform = `translate(-50%, calc(-100% - 0.5rem - ${miniHeight}px))`;
+
+        if (isEquippable) {
+            const mainRect = portal.getBoundingClientRect();
+            miniPortal.style.left = (mainRect.right - miniPortal.offsetWidth) + 'px';
+            miniPortal.style.top = (mainRect.bottom + 4) + 'px';
+        }
+    }
+
+    document.addEventListener('mouseover', (e) => {
+        const tokenEl = e.target.closest('#id_game_kit .token');
+        if (!tokenEl || !tokenEl.querySelector('.token-tooltip')) return;
+        if (!portal.classList.contains('active') || activeToken !== tokenEl) {
+            showPortals(tokenEl);
+        }
+    });
+
+    gameKit.querySelectorAll('.token').forEach(tokenEl => {
+        if (!tokenEl.querySelector('.token-tooltip')) return;
+        tokenEl.addEventListener('mouseenter', () => {
+            if (!portal.classList.contains('active') || activeToken !== tokenEl) {
+                showPortals(tokenEl);
+            }
+        });
+    });
+}
+
+document.addEventListener('DOMContentLoaded', initGameKitTooltips);

src/apps/gameboard/tests/integrated/test_views.py

@@ -0,0 +1,103 @@
+import lxml.html
+
+from django.test import TestCase
+from django.urls import reverse
+
+from apps.applets.models import Applet, UserApplet
+from apps.lyric.models import User
+
+
+class GameboardViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.user)
+        Applet.objects.get_or_create(slug="new-game", defaults={"name": "New Game", "context": "gameboard"})
+        Applet.objects.get_or_create(slug="my-games", defaults={"name": "My Games", "context": "gameboard"})
+        Applet.objects.get_or_create(slug="game-kit", defaults={"name": "Game Kit", "context": "gameboard"})
+        response = self.client.get("/gameboard/")
+        self.parsed = lxml.html.fromstring(response.content)
+
+    def test_gameboard_requires_login(self):
+        self.client.logout()
+        response = self.client.get("/gameboard/")
+        self.assertRedirects(
+            response, "/?next=/gameboard/", fetch_redirect_response=False
+        )
+    
+    def test_gameboard_renders(self):
+        response = self.client.get("/gameboard/")
+        self.assertEqual(response.status_code, 200)
+
+    def test_gameboard_shows_my_games_applet(self):
+        [_] = self.parsed.cssselect("#id_applet_my_games")
+
+    def test_gameboard_shows_new_game_applet(self):
+        [_] = self.parsed.cssselect("#id_applet_new_game")
+    
+    def test_gameboard_shows_game_kit(self):
+        [_] = self.parsed.cssselect("#id_game_kit")
+
+    def test_gameboard_shows_game_gear(self):
+        [_] = self.parsed.cssselect(".gear-btn")
+
+    def test_my_games_has_no_game_items_for_new_user(self):
+        game_items = self.parsed.cssselect("#id_applet_my_games .game-item")
+        self.assertEqual(len(game_items), 0)
+
+    def test_game_kit_has_coin_on_a_string(self):
+        [_] = self.parsed.cssselect("#id_game_kit #id_kit_coin_on_a_string")
+
+    def test_game_kit_has_free_token(self):
+        [_] = self.parsed.cssselect("#id_game_kit #id_kit_free_token")
+
+    def test_game_kit_has_card_deck_placeholder(self):
+        [_] = self.parsed.cssselect("#id_game_kit #id_kit_card_deck")
+
+    def test_game_kit_has_dice_set_placeholder(self):
+        [_] = self.parsed.cssselect("#id_game_kit #id_kit_dice_set")
+
+
+class ToggleGameAppletsViewTest(TestCase):
+    def setUp(self):
+        self.user = User.objects.create(email="gamer@test.io")
+        self.client.force_login(self.user)
+        self.new_game, _ = Applet.objects.get_or_create(
+            slug="new-game", defaults={"name": "New Game", "context": "gameboard"}
+        )
+        self.my_games, _ = Applet.objects.get_or_create(
+            slug="my-games", defaults={"name": "My Games", "context": "gameboard"}
+        )
+        self.url = reverse("toggle_game_applets")
+    
+    def test_unauthenticated_user_is_redirected(self):
+        self.client.logout()
+        response = self.client.post(self.url)
+        self.assertRedirects(
+            response, f"/?next={self.url}", fetch_redirect_response=False
+        )
+
+    def test_unchecked_applet_gets_user_applet_with_visible_false(self):
+        self.client.post(self.url, {"applets": ["new-game"]})
+        ua = UserApplet.objects.get(user=self.user, applet=self.my_games)
+        self.assertFalse(ua.visible)
+
+    def test_redirects_on_normal_post(self):
+        response = self.client.post(self.url, {"applets": ["new-game", "my-games"]})
+        self.assertRedirects(
+            response, reverse("gameboard"), fetch_redirect_response=False
+        )
+
+    def test_returns_200_on_htmx_post(self):
+        response = self.client.post(
+            self.url,
+            {"applets": ["new-game", "my-games"]},
+            HTTP_HX_REQUEST="true",
+        )
+        self.assertEqual(response.status_code, 200)
+
+    def test_does_not_affect_dash_applets(self):
+        dash_applet, _ = Applet.objects.get_or_create(
+            slug="username", defaults={"name": "Username", "context": "dashboard"}
+        )
+        self.client.post(self.url, {"applets": ["new-game", "my-games"]})
+        self.assertFalse(UserApplet.objects.filter(user=self.user, applet=dash_applet).exists())

src/apps/gameboard/urls.py

@@ -0,0 +1,11 @@
+from django.urls import path
+
+from . import views
+
+
+urlpatterns = [
+    path('', views.gameboard, name='gameboard'),
+    path('toggle-applets', views.toggle_game_applets, name='toggle_game_applets'),
+    path('equip-trinket/<int:token_id>/', views.equip_trinket, name='equip_trinket'),
+]
+

src/apps/gameboard/views.py

@@ -0,0 +1,88 @@
+from django.contrib.auth.decorators import login_required
+from django.db.models import Q
+from django.http import HttpResponse
+from django.shortcuts import get_object_or_404, redirect, render
+from django.utils import timezone
+
+from apps.applets.utils import applet_context
+from apps.applets.models import Applet, UserApplet
+from apps.epic.models import Room, RoomInvite
+from apps.lyric.models import Token
+
+
+GAMEBOARD_APPLET_ORDER = [
+    "new-game",
+    "my-games",
+    "game-kit",
+]
+
+
+@login_required(login_url="/")
+def gameboard(request):
+    pass_token = request.user.tokens.filter(token_type=Token.PASS).first() if request.user.is_staff else None
+    coin = request.user.tokens.filter(token_type=Token.COIN).first()
+    carte = request.user.tokens.filter(token_type=Token.CARTE).first()
+    free_tokens = list(request.user.tokens.filter(
+        token_type=Token.FREE, expires_at__gt=timezone.now()
+    ).order_by("expires_at"))
+    return render(
+        request, "apps/gameboard/gameboard.html", {
+            "pass_token": pass_token,
+            "coin": coin,
+            "carte": carte,
+            "equipped_trinket_id": str(request.user.equipped_trinket_id or ""),
+            "free_tokens": free_tokens,
+            "free_count": len(free_tokens),
+            "applets": applet_context(request.user, "gameboard"),
+            "page_class": "page-gameboard",
+            "my_games": Room.objects.filter(
+                Q(owner=request.user) |
+                Q(gate_slots__gamer=request.user) |
+                Q(invites__invitee_email=request.user.email, invites__status=RoomInvite.PENDING)
+            ).distinct(),
+        }
+    )
+
+@login_required(login_url="/")
+def toggle_game_applets(request):
+    checked = request.POST.getlist("applets")
+    for applet in Applet.objects.filter(context="gameboard"):
+        UserApplet.objects.update_or_create(
+            user=request.user,
+            applet=applet,
+            defaults={"visible": applet.slug in checked},
+        )
+    if request.headers.get("HX-Request"):
+        return render(request, "apps/gameboard/_partials/_applets.html", {
+            "applets": applet_context(request.user, "gameboard"),
+            "pass_token": request.user.tokens.filter(token_type=Token.PASS).first() if request.user.is_staff else None,
+            "coin": request.user.tokens.filter(token_type=Token.COIN).first(),
+            "carte": request.user.tokens.filter(token_type=Token.CARTE).first(),
+            "equipped_trinket_id": str(request.user.equipped_trinket_id or ""),
+            "free_tokens": list(request.user.tokens.filter(
+                token_type=Token.FREE, expires_at__gt=timezone.now()
+            ).order_by("expires_at")),
+            "free_count": request.user.tokens.filter(
+                token_type=Token.FREE, expires_at__gt=timezone.now()
+            ).count(),
+            "my_games": Room.objects.filter(
+                Q(owner=request.user) |
+                Q(gate_slots__gamer=request.user) |
+                Q(invites__invitee_email=request.user.email, invites__status=RoomInvite.PENDING)
+            ).distinct(),
+        })
+    return redirect("gameboard")
+
+
+@login_required(login_url="/")
+def equip_trinket(request, token_id):
+    token = get_object_or_404(Token, pk=token_id, user=request.user)
+    if request.method == "POST":
+        request.user.equipped_trinket = token
+        request.user.save(update_fields=["equipped_trinket"])
+        return HttpResponse(status=204)
+    return render(
+        request,
+        "apps/gameboard/_partials/_equip_trinket_btn.html",
+        {"token": token},
+    )

src/apps/lyric/admin.py

@@ -1,6 +1,30 @@
+from django import forms
 from django.contrib import admin
-from .models import Token, User
+
+from .models import LoginToken, Token, User
 
 
-admin.site.register(User)
+class UserAdmin(admin.ModelAdmin):
-admin.site.register(Token)
+    list_display = ["email"]
+    search_fields = ["email"]
+
+
+class TokenAdminForm(forms.ModelForm):
+    class Meta:
+        model = Token
+        fields = "__all__"
+
+    def clean(self):
+        cleaned_data = super().clean()
+        if cleaned_data.get("token_type") == Token.FREE and not cleaned_data.get("expires_at"):
+            raise forms.ValidationError("Free Tokens must have an expiration date.")
+        return cleaned_data
+
+
+class TokenAdmin(admin.ModelAdmin):
+    form = TokenAdminForm
+
+
+admin.site.register(User, UserAdmin)
+admin.site.register(LoginToken)
+admin.site.register(Token, TokenAdmin)

src/apps/lyric/authentication.py

@@ -1,5 +1,5 @@
 from django.core.exceptions import ValidationError
-from .models import Token, User
+from .models import LoginToken, User
 
 
 class PasswordlessAuthenticationBackend:
@@ -7,13 +7,13 @@ class PasswordlessAuthenticationBackend:
         if uid is None:
             return None
         try:
-            token = Token.objects.get(uid=uid)
+            login_token = LoginToken.objects.get(uid=uid)
-        except (Token.DoesNotExist, ValidationError):
+        except (LoginToken.DoesNotExist, ValidationError):
             return None
         try:
-            return User.objects.get(email=token.email)
+            return User.objects.get(email=login_token.email)
         except User.DoesNotExist:
-            return User.objects.create_user(email=token.email)
+            return User.objects.create_user(email=login_token.email)
 
     def get_user(self, user_id):
         try:

src/apps/lyric/management/commands/ensure_superuser.py

@@ -0,0 +1,21 @@
+import os
+
+from django.core.management.base import BaseCommand
+
+from apps.lyric.models import User
+
+
+class Command(BaseCommand):
+    help = "Create a superuser if none exists"
+
+    def handle(self, *args, **options):
+        if User.objects.filter(is_superuser=True).exists():
+            self.stdout.write("Superuser already exists!")
+            return
+        email = os.environ.get('DJANGO_SUPERUSER_EMAIL')
+        password = os.environ.get('DJANGO_SUPERUSER_PASSWORD')
+        if not email or not password:
+            self.stdout.write("Superuser credentials not set!—skipping")
+            return
+        User.objects.create_superuser(email=email, password=password)
+        self.stdout.write("Superuser created!")

src/apps/lyric/migrations/0002_user_searchable_user_username.py

@@ -0,0 +1,23 @@
+# Generated by Django 6.0 on 2026-03-02 01:32
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('lyric', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='user',
+            name='searchable',
+            field=models.BooleanField(default=False),
+        ),
+        migrations.AddField(
+            model_name='user',
+            name='username',
+            field=models.CharField(blank=True, max_length=35, null=True, unique=True),
+        ),
+    ]

src/apps/lyric/migrations/0003_user_theme.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0 on 2026-03-02 04:15
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('lyric', '0002_user_searchable_user_username'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='user',
+            name='theme',
+            field=models.CharField(default='theme-default', max_length=32),
+        ),
+    ]

src/apps/lyric/migrations/0004_remove_user_theme_user_palette.py

@@ -0,0 +1,22 @@
+# Generated by Django 6.0 on 2026-03-05 19:01
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('lyric', '0003_user_theme'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='user',
+            name='theme',
+        ),
+        migrations.AddField(
+            model_name='user',
+            name='palette',
+            field=models.CharField(default='palette-default', max_length=32),
+        ),
+    ]

src/apps/lyric/migrations/0005_rename_logintoken.py

@@ -0,0 +1,14 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('lyric', '0004_remove_user_theme_user_palette'),
+    ]
+
+    operations = [
+        migrations.RenameModel(
+            old_name="Token",
+            new_name="LoginToken",
+        ),
+    ]