From cbe891c97377372f018a8c28a0ba099530caf806 Mon Sep 17 00:00:00 2001
From: ben <johnmosescarter@gmail.com>
Date: Tue, 14 Apr 2026 16:04:16 -0400
Subject: [PATCH] 0.1.2 zulip api constraints

---
 pm/tasks.org                 |  9 ++++----
 pm/zulip-bot-constraints.org | 41 ++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)
 create mode 100644 pm/zulip-bot-constraints.org

diff --git a/pm/tasks.org b/pm/tasks.org
index 6a8f786..b5fe4f1 100644
--- a/pm/tasks.org
+++ b/pm/tasks.org
@@ -58,7 +58,7 @@ Specify the minimal message metadata the bridge must preserve and the exact loop
 ** notes
 - Prefer boring explicit metadata over clever heuristics.
 
-* [ ] 0.1.2: Survey Zulip bot constraints + auth model (estimate 1 commit)
+* [X] 0.1.2: Survey Zulip bot constraints + auth model (estimate 1 commit)
 Confirm what kind of bot/client should be used on the Zulip side and document any constraints that change architecture.
 
 ** Acceptance Criteria
@@ -78,8 +78,9 @@ Confirm what kind of bot/client should be used on the Zulip side and document an
 
 ** evidence
 - commit:
-- tests:
-- datetime:
+- tests: n/a (design note only)
+- datetime: [2026-04-14 Tue 15:25]
+- artifact: pm/zulip-bot-constraints.org
 
 ** notes
 - Keep this empirical; document only constraints that affect v0.
@@ -102,7 +103,7 @@ Pick the first XMPP client library/runtime and document the exact events needed
 - pm note: avoid solving the Emacs client here; this is just relay transport.
 
 ** evidence
-- commit:
+- commit: e706294
 - tests: n/a (design note only)
 - datetime: [2026-04-14 Tue 15:05]
 - artifact: pm/0.1.3-xmpp-event-model-and-library-choice.org
diff --git a/pm/zulip-bot-constraints.org b/pm/zulip-bot-constraints.org
new file mode 100644
index 0000000..f92d0d8
--- /dev/null
+++ b/pm/zulip-bot-constraints.org
@@ -0,0 +1,41 @@
+#+title: Zulip Bot Constraints and Auth Model
+#+created: [2026-04-14 Tue 15:25]
+#+updated: [2026-04-14 Tue 15:25]
+
+* initial research and recommendation
+Use a Zulip bot user for the bridge.
+
+Why:
+- smaller permission surface than a human account
+- API access is explicit and automatable
+- easier to treat as infrastructure than as a person
+
+Zulip messages can be sent as stream messages with a fixed topic using the API.
+Inbound updates can be read through Zulip's real-time events API via an event queue.
+
+Relevant API shape:
+- send message: type = stream, to = channel, topic = fixed topic
+- receive events: register an event queue, then long-poll get-events
+
+Bot API key access is restricted to the bot owner and organization administrators.
+
+* minimal zulip constraints
+| area | constraint |
+|------+------------|
+| identity | use a bot user, not a normal user account |
+| auth | bot API key needed; owner/admin can access it |
+| outbound | stream message + fixed topic |
+| inbound | event queue + long-poll events API |
+| scope | one stream/topic pair for v0 |
+| formatting | plain text is enough for the bridge |
+
+* what this means for v0
+- the Zulip side is not a general client UI problem
+- it is a bot that reads events and sends stream messages
+- no need for fancy topic routing yet
+- one fixed topic is enough to keep the bridge simple
+
+* summary
+Bot user + event queue + fixed stream/topic is the clean v0 path.
+
+It keeps Zulip acting like a relay endpoint, not a second full chat client.