Padreug 8f83d8df5e feat(wiki): docs-lookup plugin against Quartz contentIndex

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>

2026-05-24 16:40:11 +02:00

3.2 KiB

Raw Permalink Blame History

maubot-plugins

Umbrella for 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/`	Farm-journal bot. `!journal <text>` records what you did, scoped per-user/room/timestamp. `!journal show [@user]` and `!journal today` query back.
`tracker/`	Community-organizer bot. `!add` / `!task` / `!sidequest` / `!remind` / `!done` / `!list` / `!setup`. Implements the Community Organizer spec — per-room shortcuts, 5-level priority, rules-based inbox classifier.
`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) 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:

cd <plugin>/
zip -j ../<plugin>.mbp maubot.yaml *.py

(-j strips the directory prefix so files land at the zip root.)

Uploading / iterating

Open the maubot UI (e.g. https://maubot.<domain>/_matrix/maubot/).
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.
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.

3.2 KiB Raw Permalink Blame History