Documentation
Getting it running, and getting it good.
Two separate jobs. The first takes about twenty minutes and is mostly copying environment variables. The second never quite finishes, and is where the value is.
Five minutes to something working
- 1
Add the bot
The invite asks for eleven permissions and never Administrator. Two privileged intents — Message Content and Server Members — have to be switched on in the Discord developer portal, or the bot cannot read ticket messages or check staff roles.
- 2
Run /setup
Four questions: where tickets go, who counts as staff, where logs go, and where the panel is posted. A new server is seeded with three categories, working forms and 25 example answers, so there is something to try immediately.
- 3
Type /faq
Start typing a question and watch the suggestions. This is the cheapest deflection in the system — a lot of people stop here and never open a ticket.
- 4
Come back in a week
Open Unanswered questions in the dashboard. It lists exactly what people asked that the bot could not answer, sorted by how often. Writing those answers is the whole job.
The guides
SETUP.md
Discord application, intents, OAuth redirects, PostgreSQL extensions, migrations, and a table of every environment variable with where to get it.
PI-DEPLOYMENT.md
Node without touching the system install, the systemd unit, the Cloudflare Tunnel, log rotation, swap, and the update script.
SEARCH-TUNING.md
When to add a question variant, when a synonym, when a trigger keyword — and how to read match_events to tell which one you actually need.
ARCHITECTURE.md
Why the database is the only source of truth, how the dashboard reaches a Raspberry Pi, and what happens when the tunnel is down.
All four ship in the repository, in docs/.
The one thing worth knowing up front
A knowledge base does not get good because you sat down and wrote it. It gets good because the bot tells you what it could not answer and you write that. Two things follow from this:
- Add question variants, not entries. One entry with six real phrasings beats six entries competing for the same question — and the dashboard warns you before you create the second one.
- A synonym beats an entry. Teaching the search that “refund” and “money back” are the same thing improves every existing answer at once, with nothing new to maintain.