From 7c85b6e77ecb90230c88876d4eebd66649bcd5a9 Mon Sep 17 00:00:00 2001 From: "russell@unturf.com" Date: Sun, 8 Feb 2026 15:46:51 -0500 Subject: [PATCH] Document theme system and deployment workflow in CLAUDE.md --- CLAUDE.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 161bf3d..bd646db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -278,6 +278,35 @@ without a page reload. The server returns JSON (HTTP 201) for AJAX requests from verified/anonymous users, and falls back to the normal redirect flow for unverified users or on any error. +## Themes + +Remarkbox themes are separate pip packages loaded via `remarkbox.themes` entry points. +They live in their own repos and are installed from git at deploy time. + +| Theme | Repo | Package | +|-------|------|---------| +| meta | `git.unturf.com/engineering/remarkbox/remarkbox-theme-meta` | `remarkbox_theme_meta` | +| westworld | `git.unturf.com/engineering/remarkbox/remarkbox-theme-westworld` | `remarkbox_westworld` | + +**Local development**: Themes are editable installs (e.g. `/home/fox/git/remarkbox-theme-meta`). +Changes take effect immediately on the local dev server. + +**Deploying theme changes**: Push the theme repo first, then push remarkbox to trigger +a CI/CD pipeline. The pipeline runs `pip install` from the theme's git URI +(see `requirements.py3.txt`) and copies static assets (see `.gitlab-ci.yml`). +A remarkbox push is required even if only the theme changed — the theme is pulled +fresh during each remarkbox build. + +**Theme structure**: +- `templates/{name}-base.j2` — main base template (extends nothing, standalone HTML) +- `templates/{name}-base-funnel.j2` — funnel pages (setup, login, billing) +- `static/theme/{name}/css/` — theme CSS +- `static/theme/{name}/img/` — theme images + +**How themes are selected**: `request.theme` reads `namespace.theme` from the database. +When set, `request.base_template` becomes `{theme}-base.j2`. The CSS and static assets +are served at `/static/theme/{name}/` via Pyramid's `add_static_view`. + ## Style - **Never use "AI" — always say "machine learning."** We grow machine learning, not "AI." This term is forbidden in all permacomputer discourse, marketing, & documentation.