archvillainetteandClaude Fable 5
896c5048d0
Add guidance map, purpose, and usage sections to AGENTS.md; replace sibling-repository paths with repo name + Gitea URL. Includes pending working-tree changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
92 lines
4.9 KiB
Markdown
92 lines
4.9 KiB
Markdown
# 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. Local check:
|
|
`node scripts/check-emails.js` (if working on email templates). To see changes
|
|
live, use the `docker-compose.dev.yml` dev loop in sow-nodebb with this repo
|
|
as an extra mounted package. Release: merge here, re-pin the commit SHA in
|
|
sow-nodebb's `plugins.lock`, rebuild and publish the image there.
|
|
|
|
## 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, and wiki table
|
|
rendering. 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.
|