Rabbot — guide for AI and contributors

Start here before editing. Rabbot is an IRC bot platform (Undernet, mIRC-class clients) built on Cinch with ~120 plugins and a flat lib/ of shared helpers.

Repo layout

rabbot.rb              → process entry (loads config, starts bot)
lib/rabbot_app.rb      → Cinch::Bot factory, plugin resolution, DB path
plugins/*.rb           → thin Cinch::Plugin handlers (# Help: = metadata)
lib/*.rb               → testable logic (prefer shared libs in lib/)
config/bots/*.yml      → per-persona bot config (nick, channels, plugins)
test/plugins/          → mirrors plugins/
test/lib/              → mirrors lib/
test/fixtures/         → offline API payloads for tests
data/                  → runtime files, PostgreSQL socket (tmp/), bot console logs (gitignored)

Rule: plugins wire IRC → lib. Business logic, HTTP, parsing, and formatting belong in lib/, not duplicated in plugins.

Multi-bot personas

Config	Nick	Role
`config/bots/rabbot.yml`	Rabbot	Full plugin host; `!rabbot plugin` builds new plugins
`config/bots/steve.yml`	Steve	Room reader; coordinates build ideas, `!chat`, `!veto`
`config/bots/dr_weird.yml`	Dr_Weird	Proposes plugin ideas in channel
`config/bots/happy_time_harry.yml`	HappyTimeHarry	Character / mention replies

Build flow: Dr_Weird (idea) → Steve (veto window) → human admin runs !rabbot plugin on Rabbot.

See docs/architecture.md for flow diagrams.

Subsystem index

`Domain`	Plugin(s)	Lib entry points	Detail
Shared infra	(all)	`IrcFormat`, `RabbotHttp`, `RabbotDb`, `FloodSafe`, `AsyncJob`, `BotIdentity`	LIB_INDEX § IRC / HTTP / DB
AI chat	plugins/ai.rb	`AiAccess`, `AiChatCore`, `AiAgent`	LIB_INDEX § AI
AI plan	plugins/aip.rb	`AiPlanSession`, `AiPlanAgent`	CONTRACTS § AI plan
Plugin generation	plugins/rabbot_meta.rb	`RabbotMetaAgent`, `RabbotMetaBuild`, `RabbotMetaQueue`	architecture.md
`Directchat`	plugins/directchat.rb	`DirectchatSession`, `DirectchatWire`, `DirectchatMesh`	CONTRACTS § Directchat
Catalogue search	`auslib`, `qldlibrary`, `qldmuseum`	`*Search.lookup`, `SearchQuery`, `SearchReport`	CONTRACTS § Search
Events / cinemas	`whatson`, `theatres`	`WhatsonSearch`, `TheatresSearch` + `*_report`	PLUGIN_INDEX
QLD / `Sunbus`	`qld`, `sunbus`	`qld_`, `sunbus_`	QLD_APIS.md
Gov / open data	`govau`, `abs`, `aec`, `fuel`, `tm`, `rba`	`govau_`, `abs_`, etc.	AU_APIS.md
Games	`blackjack`, `poker`, `*_game` plugins	`Game`, `lib/*_game.rb`	CONTRACTS § Games
`Bot` runtime	`bot`, rabbot_user	`RabbotApp`, `bot_console/`	LIB_INDEX § Bot runtime

Full plugin → lib wiring: docs/PLUGIN_INDEX.md.

How to change behaviour

Command text, matching, gating → plugins/<name>.rb (match, execute, BotIdentity, AiAccess)
Parsing, HTTP, domain logic → lib/<domain>_*.rb
IRC colours and card layout → lib/irc_format.rb, lib/irc_reply.rb, lib/CONVENTIONS.md
Persistence → lib/rabbot_db.rb, lib/RABBOT_DB.md
External APIs / env keys → lib/AU_APIS.md, lib/QLD_APIS.md, README.md secrets table
Return hash shapes → lib/CONTRACTS.md — do not invent new keys without updating tests

Before adding a helper, check lib/LIB_INDEX.md and the shared-lib table in lib/CONVENTIONS.md.

Testing (summary)

Full detail: test/README.md.

bundle exec rake test
ruby -Itest test/lib/auslib_search_test.rb   # single file

No live HTTP — pass fetch: lambdas into search/lookup methods.
Temp DB — RabbotDb::TestSupport.reset!(bot_id: "test") in tests (see test/README.md).
Read tests first — test/lib/<module>_test.rb before editing lib/<module>.rb.
Fixtures — add under test/fixtures/<domain>/ when introducing new HTTP-backed libs.

Documentation index

Doc	Purpose
AGENTS.md	This file — orientation
lib/LIB_INDEX.md	`Domain` → lib files, naming conventions
lib/CONTRACTS.md	Hash/struct return shapes
lib/CONVENTIONS.md	IRC style, shared libs, plugin checklist
docs/PLUGIN_INDEX.md	Command → plugin → lib → secrets
docs/architecture.md	Mermaid subsystem flows
docs/NEXT_STEPS.md	Backlog — splits, subdirs, remaining DRY
test/README.md	Test layout and fixtures
lib/RABBOT_DB.md	PostgreSQL schema and API
lib/AU_APIS.md	Australian API env vars
lib/QLD_APIS.md	Queensland API env vars
README.md	Quick start, secrets, key commands

Do not edit

lib/vendor/ — generated protobuf (Translink GTFS realtime)
data/ — runtime PostgreSQL data dir (use RabbotDb API)