The agent itself: a Bun project at agent/mcp/seed-cli-mcp/ wrapping seed-cli as MCP tools.

• Read tools: seed_search, seed_get_document, seed_get_comment_thread, seed_site_sync_status, seed_get_governance.

• Write tools (gated by governance + rate limits): seed_create_comment, seed_reply_comment. Document writes via cadence driver only.

• Three-pass polling driver (poll-cli.ts): pass A discovers mentions and posts placeholder comments within ~2s; pass B drafts the real reply via DeepSeek and edits the placeholder in place; pass C handles thread-reply mentions (see below) with direct-reply posting. Stateless deduplication by mention ID.

• Thread-reply trigger: walks the replyParent chain (up to 30 hops, with cycle guard and per-cycle cache) to detect comments replying to a thread where KM already participated. Uses a pure helper (detectThreadReplyToKm) with injected fetcher for testability. Thread-replies skip the placeholder→edit flow and post the final answer directly (pass C) to work around a seed-cli --reply bug (see "Rabbit holes"). Mention type carries a triggerSource: 'mention' | 'thread-reply' discriminator for audit logs.

• Cadence driver (cadence-cli.ts): three LAFH outputs — boletin (weekly), gap (weekly), health (monthly). One DeepSeek call per task, deterministic output path.

• Telegram operator bot (telegram-bot.ts): long-running poller, allowlisted by Telegram user ID.

• XState v5 lifecycle (machines/mention-machine.ts + supervisor.ts): per-mention state machine, snapshotted to jsonl, replayable on crash. Behind feature flag KM_USE_STATE_MACHINE.

• Bounded tool-call agent loop (agent/mastra-agent.ts): ≤30 tool calls then forced final_answer. Lets the model dynamically expand context instead of running one deterministic prompt. Behind feature flag KM_USE_MASTRA_AGENT.

• Governance loader (governance.ts): fetches the four governance docs, parses the machine-readable YAML in rules and allowlist, caches 60 seconds.

• Audit + redaction (audit.ts, redact.ts): per-run directories with meta.json (summary), trace.jsonl (events), llm.jsonl (DeepSeek calls), seed-cli.jsonl (commands). Secrets redacted on disk.

• Skill + templates: SKILL.md documents the seven capabilities; templates/{synthesis-document, boletin-periodico, gap-report, onboarding-capsule, network-health}.md shape the outputs; references/lafh-framework.md carries the theoretical grounding.

• Infrastructure: Docker compose.yaml (seed-daemon + seed-web), systemd user units and timers (km-poll, km-boletin, km-gap, km-health, km-reconcile, km-telegram), idempotent install scripts (install-phase1.sh, bootstrap-subscription.sh), secret-tool-shim (file-backed keyring replacement), km-log (log browser).

New subcommands to manage subscriptions and force convergence from the CLI:

• seed-cli site subscribe <id> [--recursive] [--wait]

• seed-cli site unsubscribe <id>

• seed-cli site list-subscriptions

• seed-cli site sync-status <id> [--writer <accountId>] — reports whether the local daemon has cached a given WRITER capability.

• seed-cli site reconcile — forces hot discovery via fan-out over entities.discoverEntity.

Shared API helpers: frontend/packages/shared/src/api-subscriptions.ts, frontend/packages/shared/src/api-force-sync.ts. Used by the agent's preflight gate — the polling driver refuses to run unless sync-status confirms the writer capability is locally cached.

Two-tier discovery queue:

• tierHot (priority 0) preempts tierCold (priority 1).

• hotDeadline heartbeat TTL (~40s); expired hot tasks demote or drop.

• Hot tasks preempt running subscriptions and oldest in-flight hot tasks when workers saturate.

• New config flag Syncing.SubscriptionHotTier (backend/config/config.go:312): when on, subscription tasks ride the hot tier so writer-capability blobs converge in ~hotTTL instead of the next polling interval.

• PRAGMA busy_timeout = 5000 in backend/storage/sqlite.go:33 — wait 5 seconds on a writer lock instead of returning SQLITE_BUSY immediately. Protects reconcile transactions from being starved by peer-store writes on small VMs.

Without this, an agent that subscribes to a community sees the WRITER capability only after a multi-minute polling sweep — long enough that "subscribe then run" doesn't work in practice. With it, subscribe --wait converges in seconds.

Single Ubuntu 24.04 host. User km with linger + docker group.

                 ┌───────────────────────┐
   :55000 P2P →  │   seed-daemon         │ ← Docker
   :55001 HTTP   │   (seedhypermedia/    │
   :55002 gRPC   │    site:latest)       │
                 └─────────┬─────────────┘
                           │ seed-cli
                           ▼
              ┌──────────────────────────┐
              │  seed-cli-mcp (Bun)      │ ─── DeepSeek API
              │  + governance cache      │
              │  + audit                 │
              └──┬────────┬──────────┬───┘
                 │        │          │
        invoked by each timer / service
                 │        │          │
                 ▼        ▼          ▼
            km-poll   km-{boletin,  km-telegram
            (15-30s)   gap,health}  (long-running)
                 │
                 ▼
         posts comments / docs to
         oc.hyper.media (seed-web :3000)

Governance flow. On every action point the agent reads the four docs at hm://oc.hyper.media/agents/knowledge-manager/{charter,rules,runbook,allowlist} (cache TTL 60s). The rules doc carries a YAML block with caps (max_docs_per_run, max_comments_per_run, max_comments_per_day), mention triggers, invoker source (WRITER capability or allowlist doc), and a draft_only kill switch. Toggling draft_only: true stops document writes within 60 seconds; comments continue.

Hardcoded denylist. Regardless of permissions, limits.ts refuses to write to the four governance paths. Operators can edit governance; the agent cannot.

Feature flags (default off, ready to ship on):

• KM_USE_LOCAL_DAEMON — talk to the local daemon instead of a public gateway. Required for self-contained operation.

• KM_USE_STATE_MACHINE — XState lifecycle with snapshot/replay across crashes.

• KM_USE_MASTRA_AGENT — bounded tool-call loop instead of single-shot prompt.

• Mention @knowledge-manager in any comment to get a grounded answer with hm:// citations.

• Reply to KM's answers directly — no need to re-mention. KM continues the conversation as a follow-up turn.

• Read the auto-published cadence docs under hm://oc.hyper.media/agents/knowledge-manager/.

• Edit …/rules to change caps, set draft_only: true, or restrict invokers.

• Edit …/runbook to change tone, citation style, or escalation policy.

• Edit …/allowlist to whitelist mentioners (when invoker_source: allowlist-doc; default is WRITER capability).

• Edit …/charter to redefine scope.

• /status, /last-runs, /show-rules, /poll-now, /ask <question>.

Behind feature flag KM_USE_STATE_MACHINE. One XState v5 machine definition with a supervisor layer for persistence and crash recovery.