brain-of-reese/.agent/phases/complete/62_ui_customization/04_docs.md

Task 04 — Document the customization surface (.env.example + README)

Phase: 62_ui_customization · Source: TODO.md:3 — "Allow UI customization. This is brain of reese, but I want anyone to be able to deploy it with their name…" Story: n/a (TODO-derived)

Objective

A deployer who has never seen the codebase can find, understand, and apply all four customization vars (name, placeholder, footer, theme) from the docs alone — the house standard set by the phase-39 BOR_APP_NAME documentation.

Work

1. .env.example — in the # --- App --- block, right after the BOR_APP_NAME comment line (~L9), add (same comment style, phase-cited):

   # BOR_INPUT_PLACEHOLDER=Ask me anything…   # composer placeholder, chat page (phase 62)
   # BOR_FOOTER_TEXT=Powered by self-hosted models   # footer line on every page (phase 62)
   # BOR_THEME=            # filename under frontend/assets/themes/ (e.g. indigo.css) — overrides the built-in palette; empty = built-in (phase 62)
   

2. README.md — two edits:
   • The env-var table (the BOR_APP_NAME row sits ~L734): add three rows immediately after it, matching that row's column style — what it affects, the default, the no-op-when-unset contract:
     • BOR_INPUT_PLACEHOLDER | Ask me anything… | the chat composer placeholder; applied by assets/brand.js from GET /api/config; unset ⇒ the template default
     • BOR_FOOTER_TEXT | Powered by self-hosted models | the footer line on all 9 pages (the .footer-text spans); same mechanism
     • BOR_THEME | (empty) | a filename under frontend/assets/themes/ (e.g. indigo.css) — a :root palette override injected after styles.css; the server refuses a malformed name at startup (bare ^[a-z0-9_-]+\.css$ filename); a missing file degrades to the built-in theme; unset ⇒ built-in dark-tech palette
   • A short "Customizing the look" subsection (3–6 sentences) placed directly above or below the env table (mirror the placement of the nearest feature section — the executor picks the spot that reads best and notes it in the task report): the app ships as "Brain of Reese" but every identity string is an env var (BOR_APP_NAME / BOR_INPUT_PLACEHOLDER / BOR_FOOTER_TEXT), themes are plain CSS variable overrides (frontend/assets/themes/README.md is the authoring guide, indigo.css the example), and everything unset renders the defaults byte-identically.
3. No code changes in this task.

Testing & Quality

• Docs-only; uv run pytest green unchanged; uv run ruff check . && uv run pyright clean.
• Coverage: >90% on app/ (validate.sh gate).

Completion Criteria

• .env.example carries the three new commented vars in the App block with the exact default values (so copy-paste of the example reproduces the defaults).
• README env table has the three rows + the "Customizing the look" subsection; the README builds/reads cleanly (no broken table rows, links resolve — frontend/assets/themes/README.md exists from task 03).
• Full suite green, lint + types clean.