sow-nodebb-theme/AGENTS.md

AGENTS.md

Project

This repository is nodebb-theme-westgate, a NodeBB theme for the Shadows Over Westgate forum and website.

It is forked from nodebb-theme-quickstart and should remain a small, focused NodeBB child theme rather than a full replacement for NodeBB or Harmony.

Shadows Over Westgate (SoW) is a Neverwinter Nights persistent-world project. Its community forum and wiki run on NodeBB (a Node.js forum platform). This theme is the visual layer for that forum. It is consumed by sow-nodebb (https://git.westgate.pw/ShadowsOverWestgate/sow-nodebb), which pins this repo by exact commit in plugins.lock and compiles it into the production forum image at image-build time. Switching themes in the Admin Control Panel does nothing in production; only the theme pinned and activated in sow-nodebb is compiled in.

How It Is Used

There is no build step in this repo; NodeBB compiles the SCSS. To see changes live, use the docker-compose.dev.yml dev loop in sow-nodebb (see How To Test below). Release: merge here, re-pin the commit SHA in sow-nodebb's plugins.lock, rebuild and publish the image there.

How To Test

Fast checks, no forum needed:

• node tests/<name>.test.js — contract tests (topbar, footer, icons, wiki tables). There is no npm test script; run each file directly.
• node scripts/check-emails.js — when working on email templates.

Live visual check against a real forum — always possible, never skip it. Every change in this repo can be seen in a browser before it ships; there is no theme change that can only be checked in production. A unit test cannot tell you that a colour is unreadable, so look at the page.

Use the sibling checkout at ../sow-nodebb:

1. cd ../sow-nodebb && cp .env.example .env, then uncomment the "Theme development" block so this working tree is the mounted package: PLUGIN_PATH=../sow-nodebb-theme, PLUGIN_ID=nodebb-theme-westgate, EXTRA_PLUGINS=nodebb-plugin-westgate-wiki nodebb-plugin-westgate-pages.
2. nix develop --command make dev — the forum comes up at http://localhost:4567 (or HTTP_PORT) with this theme already active. Dev admin login: admin / Admin12345! (defaults; dev-only).
3. NodeBB compiles this theme's SCSS and templates at build time, so a browser reload alone is not enough after editing them: make dev-build, then reload. make dev-restart if changes still don't show.
4. make dev-reset wipes everything; required after changing PLUGIN_* or EXTRA_PLUGINS in .env.

A fresh database is empty, so pages that render content (wiki, categories, topics) need seeding first. ../sow-nodebb/AGENTS.md has the recipes for seeding over the REST API, for writing plugin settings straight to Redis, and for driving a headless browser on this NixOS box (the Playwright MCP server does not work here). Point any browser tooling at http://localhost:4567 to load pages, take screenshots, and compare before/after.

Assume the stack is dirty when you arrive, and leave it clean. Reset it (make dev-reset) before the first boot of a testing session and tear it down after every cycle, including a failed one; a stack carrying the last session's data is the usual reason a screenshot shows something that no longer exists in the code. Full hygiene rules live in ../sow-nodebb/AGENTS.md. Two things that bite here in particular:

• Templates and client JS are compiled, so a browser reload alone proves nothing after editing them. make dev-build — and note the build marker lives on the container filesystem, so a plain restart skips the rebuild.
• Playwright login on this forum: the form is #username / #password with a #login submit button, and a successful login lands on /?loggedin=true, which page.waitForURL('**/') never matches. Wait on page.waitForLoadState('networkidle') instead.

Design Context

• PRODUCT.md: strategic design context — register, users, purpose, positioning, brand personality, anti-references, design principles, accessibility target (WCAG AA). Read it before design work.
• DESIGN.md: the visual system — palette ("The Velvet Ledger"), typography, elevation, components, and do's/don'ts, with machine-readable tokens in its frontmatter and .impeccable/design.json.

Guidance Map

• README.md and GAME_ICONS.md: repo intro and icon usage notes.
• theme.json, plugin.json: theme metadata, hooks, static dirs.
• theme.scss (imports-only) and scss/: all styling; scss/overrides.scss holds pre-Bootstrap variable overrides.
• templates/: Harmony template overrides (same relative paths as Harmony).
• custom_pages/: source content and mockups for custom-pages surfaces.
• lib/, public/client.js: server hooks and client behavior.
• tests/: contract tests for topbar, footer, icons, wiki table rendering, and the Bootstrap dark-repaint variables. Plain assert scripts: run each with node tests/<name>.test.js; there is no npm test script.

Theme Direction

The visual target is black velvet silk, darkness, vampirism, decadence, and decay.

Use this palette direction:

• Plum and near-black as the dominant base.
• Muted gold for accents, borders, small highlights, and important affordances.
• Red only sparingly, preferably as a subtle detail or state color.
• Avoid bright, playful, clinical, or flat SaaS-style treatment.
• Favor depth, restraint, texture, and rich contrast over loud ornament.

NodeBB Theme Rules

Follow the current NodeBB theme model:

• theme.json defines theme metadata and the base theme.
• This project uses baseTheme: "nodebb-theme-harmony".
• Keep this as a child theme unless the user explicitly asks for a larger rewrite.
• theme.scss is the theme entry point and must stay imports-only.
• Do not append substantive CSS/SCSS directly to theme.scss.
• Do not add new root-level theme styling files.
• Put substantive Westgate-specific style overrides under focused files in scss/.
• Keep scss/overrides.scss focused on Bootstrap/Harmony variable overrides that must load before Bootstrap.
• Template overrides belong under templates/ and must preserve the same relative path as the Harmony template they replace.
• Do not copy or redefine Harmony templates unless an actual override is needed.
• If a template does not exist here, NodeBB inherits it from the configured base theme.
• In the Westgate topbar, notification, chat, draft, and navigation count bubbles must honor NodeBB/Harmony's hidden class and only display when there is an actual count to check.

NodeBB theme documentation: https://docs.nodebb.org/development/themes/

Current Files Of Interest

• theme.json: theme metadata and baseTheme.
• plugin.json: hooks, scripts, modules, template path, and static dirs.
• theme.scss: NodeBB SCSS entry point.
• scss/overrides.scss: current Westgate override layer.
• lib/theme.js and lib/controllers.js: server-side theme hooks/controllers.
• public/client.js: client-side theme behavior.
• templates/: local template overrides and admin templates.

Working Practices

• Keep edits scoped to the theme package unless the task explicitly names the NodeBB install.
• Prefer existing NodeBB, Harmony, Bootstrap, and local theme patterns over introducing new frameworks.
• Keep selectors maintainable and avoid broad global overrides unless they are intentional theme-wide tokens or resets.
• Avoid unrelated formatting churn.
• Before overriding a template, inspect the corresponding Harmony template and copy only what is necessary.
• Preserve accessibility: readable contrast, visible focus states, usable hover/active states, and no text hidden purely for visual effect unless there is an accessible alternative.

Tests

Tests must survive harmless changes to constants, defaults, wording, ordering, fixture data, and internal implementation details. A test that fails merely because a basic value changed is usually a bad test. Only assert exact values when the value is part of a documented public contract, external protocol, compatibility requirement, security rule, migration, or business rule.

Agent skills

Issue tracker

Issues live in Gitea at git.westgate.pw (ShadowsOverWestgate/sow-nodebb-theme), managed with the tea CLI. Issues follow ownership — file work in the repo that owns it, not the one you happen to be standing in. See docs/agents/issue-tracker.md.

Triage labels

Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/agents/triage-labels.md.

Domain docs

Single-context: CONTEXT.md at the repo root plus docs/adr/. See docs/agents/domain.md.

Where work lives

Markdown here is reference, law, or an ADR — nothing else (sow-codebase ADR-0001). Live work -> wayfinder maps + Gitea issues (closeable, assignable, queryable). Settled decisions -> ADR files in docs/adr/ (immutable, never closed, only superseded). Standing law -> DOCTRINE.md / AGENTS.md / CONTEXT.md. Current-state reference -> docs describing what the code does now. Everything else — plans, specs, concepts, handoffs, trackers — is process: it belongs in a Gitea issue, not a file. Harvest unfinished intent to an issue before deleting a process doc. sow-docs is deprecated and read-only.