Padreug
8f83d8df5e
New maubot plugin that points at any Quartz-rendered docs site and answers chat queries by full-text searching its emitted /static/contentIndex.json. Default config targets docs.ariege.io (castle-docs). Commands: !ask <query> search corpus; top-N hits with snippet + link !doc <slug-or-title> open a specific page (fuzzy title match) !wiki / !wiki refresh status / force re-index Architecture: - Periodic fetch (default 10 min) of /static/contentIndex.json - In-memory inverted-ish scoring: title hit 5pt, content hit 1pt + freq - No LLM — pure deterministic keyword search; RAG is future Phase 2b - No DB — index is upstream-derived cache, repopulates on bot restart Deployment posture: docs.ariege.io is served from cfaun alongside maubot, so the bot hits it over the host's internal network — works during WAN outages. base-config.yaml exposes docs_url + index_path for adopters pointing at their own site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# maubot-plugins
|
|
|
|
Umbrella for [maubot](https://github.com/maubot/maubot) plugins used by
|
|
the aiolabs / Château du Faune Matrix stack. The maubot daemon itself
|
|
is provisioned via `server-deploy/modules/services/maubot.nix` on the
|
|
castle hosts; the actual plugin code lives here.
|
|
|
|
## Plugins
|
|
|
|
| Plugin | Purpose |
|
|
|---|---|
|
|
| [`journal/`](./journal/) | Farm-journal bot. `!journal <text>` records what you did, scoped per-user/room/timestamp. `!journal show [@user]` and `!journal today` query back. |
|
|
| [`tracker/`](./tracker/) | Community-organizer bot. `!add` / `!task` / `!sidequest` / `!remind` / `!done` / `!list` / `!setup`. Implements the [Community Organizer spec](./docs/community-organizer-spec.md) — per-room shortcuts, 5-level priority, rules-based inbox classifier. |
|
|
| [`wiki/`](./wiki/) | Docs-lookup bot. `!ask <query>` / `!doc <slug-or-title>` / `!wiki [refresh\|status]`. Points at any Quartz-rendered docs site (default: `docs.ariege.io`), full-text searches the corpus, replies with snippets + links. Internal-network deployment posture — works during WAN outages. |
|
|
|
|
## Community Organizer protocol
|
|
|
|
`docs/community-organizer-spec.md` defines the protocol the plugins in
|
|
this repo (and companion renderers like
|
|
[`inky-impression`](https://git.atitlan.io/aiolabs/inky-impression)) use
|
|
to coordinate community life — tasks, journals, reminders, shopping
|
|
lists — over Matrix capture + Nostr storage. Designed to be adopted by
|
|
other communities; reuses NIP-52 + NIP-72 instead of inventing new
|
|
event kinds. Read it before changing verb behavior or event shapes in
|
|
any plugin.
|
|
|
|
## Building a plugin
|
|
|
|
A `.mbp` is just a zip containing `maubot.yaml` + the plugin's Python
|
|
modules at the root. No special tooling needed:
|
|
|
|
```sh
|
|
cd <plugin>/
|
|
zip -j ../<plugin>.mbp maubot.yaml *.py
|
|
```
|
|
|
|
(`-j` strips the directory prefix so files land at the zip root.)
|
|
|
|
## Uploading / iterating
|
|
|
|
1. Open the maubot UI (e.g. `https://maubot.<domain>/_matrix/maubot/`).
|
|
2. **Plugins → +** (first time) or click the existing plugin → upload
|
|
the new `.mbp`. Maubot keys plugins by `id`; uploading a new
|
|
`version` of the same `id` replaces the old one.
|
|
3. **Hit Save** on the affected instance after upload — toggling
|
|
Enabled without Save will revert. Easy facepalm.
|
|
|
|
Bump `version:` in `maubot.yaml` for every meaningful change so the
|
|
maubot UI surfaces it cleanly and old `.mbp` files in
|
|
`/var/lib/maubot/plugins/` aren't ambiguous.
|
|
|
|
## Bot account convention
|
|
|
|
Each plugin attaches to a Matrix client (a regular Matrix user account
|
|
controlled by maubot). For the journal bot: `@journalbot:ariege.io`.
|
|
Bot accounts are created the same way as any user — issue a
|
|
registration token from the Continuwuity admin room
|
|
(`!admin token issue --once`) and register through Element, then add
|
|
the client in the maubot UI.
|
|
|
|
Invite the bot to whichever rooms it should serve via `/invite
|
|
@<bot>:<domain>` — maubot's autojoin handles new invites that arrive
|
|
after the client's sync loop is up.
|
|
|
|
## Patterns + gotchas
|
|
|
|
Maubot-specific patterns (command decorators, multi-line caveats,
|
|
`database_type` in `maubot.yaml`, etc.) live in `~/dev/CLAUDE.md`
|
|
under "Maubot plugin development". Read that before writing a new
|
|
plugin — there are several footguns that look fine but silently lose
|
|
data.
|