docs: split README into component docs, update jobkit dep

- Break README into README.md (overview), docs/daemon.md (pipeline
  stages, diagnostics, common issues), docs/notifications.md
  (notification daemon, IRC/Telegram modules)
- Update jobkit dependency from local path to git URL

Co-Authored-By: ProofOfConcept <poc@bcachefs.org>
This commit is contained in:
Kent Overstreet 2026-03-07 13:56:09 -05:00
parent 45335de220
commit 908f8c9e52
5 changed files with 228 additions and 129 deletions

103
docs/notifications.md Normal file
View file

@ -0,0 +1,103 @@
# Notification daemon
`poc-daemon` routes messages from communication modules and internal
events through a hierarchical, activity-aware delivery system.
## Architecture
```
Communication modules Hooks
+-----------------+ +-------------+
| IRC (native) |--+ | poc-hook |
| Telegram | | mpsc | (all events|
+-----------------+ +------+ +------+------+
| | |
v | capnp-rpc
+----------+ |
| poc-daemon |
| |
| NotifyState <---------+
| +-- type registry
| +-- pending queue
| +-- threshold lookup
| +-- activity-aware delivery
|
| idle::State
| +-- presence detection
| +-- sleep/wake/dream modes
| +-- tmux prompt injection
+--------------------------
```
## Notification types and urgency
Types are free-form hierarchical strings: `irc.mention.nick`,
`irc.channel.bcachefs`, `telegram.kent`. Each has an urgency level:
| Level | Name | Meaning |
|-------|---------|--------------------------------------|
| 0 | ambient | Include in idle context only |
| 1 | low | Deliver on next check |
| 2 | normal | Deliver on next user interaction |
| 3 | urgent | Interrupt immediately |
Per-type thresholds walk up the hierarchy: `irc.channel.bcachefs-ai`
-> `irc.channel` -> `irc` -> default. Effective thresholds adjust by
activity state: raised when focused, lowered when idle, only urgent
when sleeping.
## Communication modules
**IRC** — native async TLS connection (tokio-rustls). Connects,
joins channels, parses messages, generates notifications. Runtime
commands: join, leave, send, status, log, nick. Per-channel logs
at `~/.claude/irc/logs/`.
**Telegram** — native async HTTP long-polling (reqwest). Downloads
media (photos, voice, documents). Chat ID filtering for security.
Runtime commands: send, status, log.
Both modules persist config changes to `~/.claude/daemon.toml`
channel joins and nick changes survive restarts.
## Commands
```bash
poc-daemon # Start daemon
poc-daemon status # State summary
poc-daemon irc status # IRC module status
poc-daemon irc send TARGET MSG # Send IRC message
poc-daemon irc join CHANNEL # Join (persists to config)
poc-daemon irc leave CHANNEL # Leave
poc-daemon irc log [N] # Last N messages
poc-daemon telegram status # Telegram module status
poc-daemon telegram send MSG # Send Telegram message
poc-daemon telegram log [N] # Last N messages
poc-daemon notify TYPE URG MSG # Submit notification
poc-daemon notifications [URG] # Get + drain pending
poc-daemon notify-types # List all types
poc-daemon notify-threshold T L # Set per-type threshold
poc-daemon sleep / wake / quiet # Session management
poc-daemon stop # Shut down
```
## Configuration
Config: `~/.claude/daemon.toml`
```toml
[irc]
enabled = true
server = "irc.oftc.net"
port = 6697
tls = true
nick = "MyBot"
user = "bot"
realname = "My Bot"
channels = ["#mychannel"]
[telegram]
enabled = true
token = "bot-token-here"
chat_id = 123456789
```