@volter/twin-telegram 1.0.0

package/journeys/customer-life.outline.md

@@ -0,0 +1,99 @@
+# Tide Labs on Telegram: the outline
+
+**The customer.** Tide Labs, a two-person software studio in Lisbon. Ana Ribeiro, its founder, runs an agent on Volter
+Harness that she and the team talk to on Telegram, and publishes the studio's news to its Telegram channel with
+Postiz. Bruno Costa, its engineer, is on the team chat. The story runs from Monday 5 January to Friday 27 February
+2026: two bots made, the agent at work in a private chat and a group, a news channel connected to Postiz and posted to
+for six weeks, the agent's group retired and, at the end, the agent's token revoked. The channel and its bot stay.
+
+## Who acts, and with what
+
+- **Ana** and **Bruno**: Telegram accounts, acting in the Telegram app (the World's doors stand in for the app: an
+  account, a chat made, a member added or removed, a message posted). An account holds no API credential.
+- **BotFather**, Telegram's bot for making bots (https://core.telegram.org/bots/features#botfather): Ana makes each
+  bot there and is given its token; at the end she makes one again there, which revokes the one before (the World's
+  bot doors stand in for /newbot and /token).
+- **The agent bot**, @tidelabs_agent_bot, token A: Volter Harness's Telegram channel (the Chat SDK's adapter, polling).
+  Its grant is the bot's: it reads the updates sent to it and writes in chats it is in. Privacy mode is on, as every
+  bot's is by default, so in a group where it is a plain member it receives only commands meant for it, replies to it
+  and service messages (https://core.telegram.org/bots/features#privacy-mode); an administrator bot is sent every
+  message, which is why Ana, once the agent misses the team's messages, makes it an administrator of the team group.
+  Harness's board, where the agent files work as cards, tells a chat subscribed to a card when it is done, the card's
+  files attached; the Chat SDK sends a message with files as MarkdownV2 (supercode board/dispatch.mjs notifyChats,
+  @chat-adapter/telegram's resolveParseMode).
+- **The news bot**, @tidelabs_news_bot, token N: the bot Postiz posts with. Postiz's Telegram integration calls with
+  the one bot its deployment configures, its TELEGRAM_TOKEN (postiz-app telegram.provider.ts), so Ana runs Postiz
+  herself (docker compose, local storage) and sets its TELEGRAM_TOKEN to token N. She makes the bot an administrator of
+  the channel allowed to post and to delete messages.
+
+A bot can write to a person in private only after the person has started it, and to a group or channel only while it
+is a member; a bot deletes another's message in a channel only with the right to delete messages.
+
+## Acts
+
+1. **Monday 5 January, 10:00. Two people, one bot.** Ana and Bruno have Telegram accounts. Ana makes the agent bot
+   with BotFather and is given token A. In Telegram she opens the bot, presses Start (/start) and writes: "Hi! I'm Ana
+   from Tide Labs. Can you keep notes of our standups?" (doors: people, bots, a private message twice).
+2. **10:05. The agent comes up.** Ana puts token A in her Harness profile and starts Harness. Its adapter reads the
+   bot itself (getMe), removes any webhook so it can poll (deleteWebhook, keeping pending updates), and polls
+   (getUpdates, timeout 30): Ana's /start and her message come back at once. For her message it shows the bot typing in
+   her private chat (sendChatAction) and posts the agent's answer there (sendMessage, plain text).
+3. **11:00. The team chat.** Ana makes the group "Tide Labs team" with Bruno and the agent bot, which the app adds as
+   a plain member (door). Harness's poll, from the update after the last it read (offset), receives the bot's own
+   membership change (my_chat_member) and the service message that the group was created, which privacy mode lets
+   through. At 11:10 Bruno tells the team standups are at 9:00 on Tuesdays from tomorrow, items posted in the group, and
+   asks "@tidelabs_agent_bot what did Ana ask you to track?"; privacy mode sends a plain member neither (a plain
+   mention is no command and no reply to it), so no answer comes. At 11:25 Ana reads why and makes the agent an
+   administrator of the group (door), and Bruno asks again with the standup time. Harness's next poll receives the
+   bot's promotion and Bruno's second question, and nothing of his first two messages; the agent answers in the group
+   that it will post the digest at 9:15 (no typing indicator outside a private chat). Ana makes the group the
+   profile's home chat in Harness (no Telegram call).
+4. **Tuesday 6 January, 09:00. The first standup and its digest.** Ana posts her items in the group, and Harness's poll,
+   held open, returns with them as she posts; at 09:02 Bruno posts his (blocked on staging credentials) and Harness's
+   next poll, from the update after hers, returns with them. At 09:15 Harness's scheduled job posts the digest of
+   exactly those items to the home chat (sendMessage to the group).
+5. **Wednesday 7 January, 14:00. The news channel.** Ana makes the public channel "Tide Labs News" (@tidelabs_news)
+   with the studio's logo as its photo (door). She makes the news bot with BotFather (token N) and adds it to the
+   channel as an administrator that may post and delete messages (door). In the Postiz she runs herself (docker compose,
+   local storage) she sets TELEGRAM_TOKEN to token N, and then chooses to add Telegram; Postiz
+   shows the command to post, "/connect" and a word, and she posts it in the channel (door). Postiz's connect screen
+   polls (getUpdates, its library sending allowed_updates as the fields allowed_updates[0]=message and
+   allowed_updates[1]=channel_post, which the Bot API does not read as its JSON-serialized list, so every update type
+   comes back): the bot's own membership change and her post come back. Postiz reads its bot (getMe), checks the bot
+   may delete messages there (getChatMember: an administrator with can_delete_messages), deletes her /connect post
+   (deleteMessage), posts "Connection Successful. Message will be deleted in 10 seconds." (sendMessage) and, ten
+   seconds later, deletes that too (deleteMessage). It then reads the channel (getChat), the photo's file (getFile), and copies the photo into its
+   storage from the file's link (the file download).
+6. **Thursday 8 January, 10:00. The launch post, and the release notes.** Postiz publishes Ana's announcement, bold title and two paragraphs
+   (sendMessage, parse_mode HTML).
+   At 11:00 Ana asks the agent in her private chat for the 0.9 release notes by Friday; Harness's poll receives it,
+   it shows the bot typing, and the agent answers that the work is card t_7c1e9a04 on its board and that this chat
+   will get the notes when it is done (it subscribes the chat to the card on the board; no Telegram call). **Friday 9
+   January, 15:00**: the card is done with its notes file, and Harness's board tells the chat: the notice "card … done
+   — Draft the 0.9 release notes" and its summary as the caption of the file (sendDocument, the file uploaded, the
+   caption in MarkdownV2 as the Chat SDK escapes it).
+7. **Monday 12 January, 10:00. A release with screenshots.** Postiz publishes the release post with three screenshots
+   as one album, the text on the first (sendMediaGroup, the images uploaded). At 11:00 it publishes the post's comment,
+   the changelog, as a reply to the album's first message (sendMessage with reply_to_message_id).
+8. **Monday 12 January, 18:00. The standups move.** The team moves its standups to a video call and Ana removes the
+   agent bot from "Tide Labs team" (door), but leaves the digest job on. Tuesday 13 January at 09:15 the job posts its
+   digest to the home chat, which says no standup items were posted this week (that morning's standup was on the
+   call), and Telegram refuses: "Forbidden: bot was kicked from the group chat". Ana deletes the job in Harness (no
+   Telegram call).
+9. **Wednesday 14 January, 16:00. A caption too long.** Ana's next post is one product photo with a 1,091-character
+   story. Postiz sends it (sendPhoto) and Telegram refuses it: a photo's caption holds at most 1,024 characters
+   ("Bad Request: message caption is too long"); Postiz shows "Telegram rejected the post". At 16:20 she cuts the story
+   to a paragraph and Postiz sends it again, which posts.
+10. **Monday 19 January, 11:00. A demo and a paper.** Postiz publishes the product demo video (sendVideo, uploaded) and,
+   at 15:00, the white paper as a PDF (sendDocument, uploaded).
+11. **Friday 27 February, 17:00. The agent retired.** Ana stops using the agent on Telegram and, in BotFather, makes a new
+    token for it (/token), which revokes token A. Harness, still running on her laptop, polls with it and is refused ("Unauthorized"); she stops it. The
+    news channel, its posts and the news bot stay with Postiz.
+
+## What the story reaches
+
+getMe (both bots), deleteWebhook, getUpdates (held, a long poll; with allowed_updates sent as form fields the Bot API does not read; with offset),
+privacy mode (a plain member bot sent a service message and not a plain mention; an administrator bot sent every
+message), sendChatAction, sendMessage (plain, HTML, a reply; refused for a removed bot), getChatMember, deleteMessage
+(twice), getChat, getFile, the file download, sendPhoto (refused for its caption, then sent), sendVideo, sendDocument
+(Postiz's PDF; Harness's notes with a MarkdownV2 caption), sendMediaGroup; and a revoked token's refusal.

package/journeys/customer-life.outline.verdict.json

@@ -0,0 +1,76 @@
+{
+  "judge": {
+    "agent": "Claude Code (Claude Agent SDK), model claude-opus-5-5",
+    "name": "Contributor 106"
+  },
+  "authors": [
+    "Contributor 173"
+  ],
+  "bar": "829132787d94a2d4",
+  "sha256": "267e4ae00d8d6bd435831be1a5b9dc741a7003bd0a43641ea7c4c000ee974e20",
+  "judgedAt": "2026-10-02",
+  "plausible": true,
+  "rulings": [
+    {
+      "id": "three-tuesdays-skipped",
+      "steps": [
+        "act 3",
+        "act 4",
+        "act 7",
+        "act 8",
+        "act 9",
+        "act 10"
+      ],
+      "barItem": "a stated cause that never happens, and a promise never kept",
+      "reason": "Act 3 sets the standup weekly on Tuesdays and makes the agent an administrator, which is sent every group message (https://core.telegram.org/bots/features#privacy-mode). Act 4 runs the first standup and digest on 6 January. The standups move to the call only on Monday 2 February (act 10). Tuesdays 13, 20 and 27 January fall within acts 7-9 with no standup, no poll and no digest. Act 10's digest then says that no items were posted \"this week\", as if earlier weeks had them.",
+      "correction": "Move act 10 to Monday 12 January, 18:00, so that the refused digest is Tuesday 13 January's. Or tell the three January Tuesdays' standups and digests."
+    },
+    {
+      "id": "postiz-never-given-token-n",
+      "steps": [
+        "Who acts",
+        "act 5"
+      ],
+      "barItem": "the wrong actor or credential for an act",
+      "reason": "Postiz posts to Telegram through the one bot its deployment configures, process.env.TELEGRAM_TOKEN (postiz-app e0a08a7, libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:19). In hosted Postiz, that bot is Postiz's own. The outline calls @tidelabs_news_bot, token N, \"Postiz's Telegram integration\", and in act 5 Ana makes the bot and Postiz then calls with it. The outline never says that she runs Postiz herself or that token N becomes its TELEGRAM_TOKEN.",
+      "correction": "In 'Who acts' and act 5, say that Ana self-hosts Postiz (docker compose, local storage) and sets its TELEGRAM_TOKEN to token N before she adds Telegram."
+    }
+  ],
+  "applied": {
+    "from": "7f1802b57b256e32061a52ede0d2972060c725a7550b068ac1ae23f131c63c6c",
+    "wasPlausible": false,
+    "steps": [
+      "0",
+      "5",
+      "8",
+      "9",
+      "10"
+    ],
+    "rulings": [
+      {
+        "id": "three-tuesdays-skipped",
+        "steps": [
+          "act 3",
+          "act 4",
+          "act 7",
+          "act 8",
+          "act 9",
+          "act 10"
+        ],
+        "barItem": "a stated cause that never happens, and a promise never kept",
+        "reason": "Act 3 sets the standup weekly on Tuesdays and makes the agent an administrator, which is sent every group message (https://core.telegram.org/bots/features#privacy-mode). Act 4 runs the first standup and digest on 6 January. The standups move to the call only on Monday 2 February (act 10). Tuesdays 13, 20 and 27 January fall within acts 7-9 with no standup, no poll and no digest. Act 10's digest then says that no items were posted \"this week\", as if earlier weeks had them.",
+        "correction": "Move act 10 to Monday 12 January, 18:00, so that the refused digest is Tuesday 13 January's. Or tell the three January Tuesdays' standups and digests."
+      },
+      {
+        "id": "postiz-never-given-token-n",
+        "steps": [
+          "Who acts",
+          "act 5"
+        ],
+        "barItem": "the wrong actor or credential for an act",
+        "reason": "Postiz posts to Telegram through the one bot its deployment configures, process.env.TELEGRAM_TOKEN (postiz-app e0a08a7, libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:19). In hosted Postiz, that bot is Postiz's own. The outline calls @tidelabs_news_bot, token N, \"Postiz's Telegram integration\", and in act 5 Ana makes the bot and Postiz then calls with it. The outline never says that she runs Postiz herself or that token N becomes its TELEGRAM_TOKEN.",
+        "correction": "In 'Who acts' and act 5, say that Ana self-hosts Postiz (docker compose, local storage) and sets its TELEGRAM_TOKEN to token N before she adds Telegram."
+      }
+    ]
+  }
+}

package/journeys/customer-life.verdict.json

@@ -0,0 +1,134 @@
+{
+  "judge": {
+    "agent": "Claude Code (Claude Agent SDK), model claude-opus-5-5",
+    "name": "Contributor 106"
+  },
+  "authors": [
+    "Contributor 173"
+  ],
+  "bar": "829132787d94a2d4",
+  "sha256": "f58ee4db9e9c90c0f87f6018cf370f00963898ae16e0d4e7069e6afca17a6cf3",
+  "judgedAt": "2026-10-02",
+  "plausible": true,
+  "rulings": [
+    {
+      "id": "three-tuesdays-skipped",
+      "steps": [
+        16,
+        20,
+        22,
+        30,
+        58,
+        62,
+        66,
+        70,
+        73
+      ],
+      "barItem": "a stated cause that never happens, and a promise never kept",
+      "reason": "Steps 16, 20 and 22 set the standup for 9:00 every Tuesday, with items posted in the group, and the agent promises the digest at 9:15. From step 19 the agent is an administrator, and an administrator is sent every group message (https://core.telegram.org/bots/features#privacy-mode, \"bot admins always receive all messages\"). The job runs once, Tuesday 6 January (step 30). The team keeps the group standup until Monday 2 February (step 70: \"the standups move to a video call\"), yet Tuesdays 13, 20 and 27 January pass inside steps 58-70 with no items posted, no poll and no digest. Step 73's digest then says \"No standup items were posted this week\", which implies the earlier weeks had items. Three of the four weekly runs the story promises never happen, and nothing in the story explains why.",
+      "correction": "Move the standups' move and the bot's removal to Monday 12 January, 18:00, after step 61. The job's next run, Tuesday 13 January at 09:15, is then the refused one, and the waits to Wednesday 14 January 16:00 and onward are adjusted. Alternatively, show the Tuesday standups of 13, 20 and 27 January: items posted, a poll, and a digest each week."
+    },
+    {
+      "id": "postiz-never-given-token-n",
+      "steps": [
+        33,
+        37,
+        40,
+        41,
+        42,
+        43,
+        45,
+        46,
+        47,
+        48,
+        50,
+        59,
+        61,
+        63,
+        65,
+        67,
+        69
+      ],
+      "barItem": "the wrong actor or credential for an act",
+      "reason": "Postiz's Telegram provider calls with one bot, the one its deployment configures: `new TelegramBot(process.env.TELEGRAM_TOKEN!)` (libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:19, postiz-app e0a08a7; demand.json, Postiz's client: \"TELEGRAM_TOKEN\"). In hosted Postiz, that is Postiz's own bot and not one a customer makes. Step 33 has Ana make @tidelabs_news_bot \"for Postiz\", and from step 37 on Postiz calls with {news_token}. But no step or name says that Ana runs Postiz herself, or that token N is set as its TELEGRAM_TOKEN. The life never shows how the credential Postiz uses reaches it, and as written it reads as the hosted product calling with a bot that belongs to the customer.",
+      "correction": "In step 33 or a step beside it, say that Ana runs Postiz herself (docker compose, local storage, as demand.json reads it) and sets TELEGRAM_TOKEN to the news bot's token before she adds Telegram. Use the same wording in the outline."
+    },
+    {
+      "id": "running-harness-polls-without-offset",
+      "steps": [
+        76
+      ],
+      "barItem": "content that does not bear out the step's name",
+      "reason": "Step 76 is Harness \"still running on her laptop\". The adapter it runs keeps its offset in its polling loop and sends it on every poll: `offset = update.update_id + 1` (@chat-adapter/telegram 4.39.0, dist/index.js:3327-3345, pollingLoop; demand.json: \"confirming the last with offset\"). The life last confirmed one at step 53. Step 76's body, {\"limit\": 100, \"timeout\": 30}, is the request a freshly started adapter sends (step 9), not the request of the process the step names.",
+      "correction": "Step 76's body: {\"offset\": \"{agent_next}\", \"limit\": 100, \"timeout\": 30}."
+    }
+  ],
+  "applied": {
+    "from": "1248e944117c27955453a626f8ed5a44ff07ad520f525feaa0a7a6dc53399963",
+    "wasPlausible": false,
+    "steps": [
+      "33",
+      "36",
+      "62",
+      "70",
+      "71",
+      "72",
+      "73",
+      "74",
+      "76"
+    ],
+    "rulings": [
+      {
+        "id": "three-tuesdays-skipped",
+        "steps": [
+          16,
+          20,
+          22,
+          30,
+          58,
+          62,
+          66,
+          70,
+          73
+        ],
+        "barItem": "a stated cause that never happens, and a promise never kept",
+        "reason": "Steps 16, 20 and 22 set the standup for 9:00 every Tuesday, with items posted in the group, and the agent promises the digest at 9:15. From step 19 the agent is an administrator, and an administrator is sent every group message (https://core.telegram.org/bots/features#privacy-mode, \"bot admins always receive all messages\"). The job runs once, Tuesday 6 January (step 30). The team keeps the group standup until Monday 2 February (step 70: \"the standups move to a video call\"), yet Tuesdays 13, 20 and 27 January pass inside steps 58-70 with no items posted, no poll and no digest. Step 73's digest then says \"No standup items were posted this week\", which implies the earlier weeks had items. Three of the four weekly runs the story promises never happen, and nothing in the story explains why.",
+        "correction": "Move the standups' move and the bot's removal to Monday 12 January, 18:00, after step 61. The job's next run, Tuesday 13 January at 09:15, is then the refused one, and the waits to Wednesday 14 January 16:00 and onward are adjusted. Alternatively, show the Tuesday standups of 13, 20 and 27 January: items posted, a poll, and a digest each week."
+      },
+      {
+        "id": "postiz-never-given-token-n",
+        "steps": [
+          33,
+          37,
+          40,
+          41,
+          42,
+          43,
+          45,
+          46,
+          47,
+          48,
+          50,
+          59,
+          61,
+          63,
+          65,
+          67,
+          69
+        ],
+        "barItem": "the wrong actor or credential for an act",
+        "reason": "Postiz's Telegram provider calls with one bot, the one its deployment configures: `new TelegramBot(process.env.TELEGRAM_TOKEN!)` (libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:19, postiz-app e0a08a7; demand.json, Postiz's client: \"TELEGRAM_TOKEN\"). In hosted Postiz, that is Postiz's own bot and not one a customer makes. Step 33 has Ana make @tidelabs_news_bot \"for Postiz\", and from step 37 on Postiz calls with {news_token}. But no step or name says that Ana runs Postiz herself, or that token N is set as its TELEGRAM_TOKEN. The life never shows how the credential Postiz uses reaches it, and as written it reads as the hosted product calling with a bot that belongs to the customer.",
+        "correction": "In step 33 or a step beside it, say that Ana runs Postiz herself (docker compose, local storage, as demand.json reads it) and sets TELEGRAM_TOKEN to the news bot's token before she adds Telegram. Use the same wording in the outline."
+      },
+      {
+        "id": "running-harness-polls-without-offset",
+        "steps": [
+          76
+        ],
+        "barItem": "content that does not bear out the step's name",
+        "reason": "Step 76 is Harness \"still running on her laptop\". The adapter it runs keeps its offset in its polling loop and sends it on every poll: `offset = update.update_id + 1` (@chat-adapter/telegram 4.39.0, dist/index.js:3327-3345, pollingLoop; demand.json: \"confirming the last with offset\"). The life last confirmed one at step 53. Step 76's body, {\"limit\": 100, \"timeout\": 30}, is the request a freshly started adapter sends (step 9), not the request of the process the step names.",
+        "correction": "Step 76's body: {\"offset\": \"{agent_next}\", \"limit\": 100, \"timeout\": 30}."
+      }
+    ]
+  }
+}

package/journeys/decisions.json

@@ -0,0 +1,95 @@
+{
+ "about": "telegram's decision table (the P3 procedure: demand, then this table, then the code): each method the pack serves, the demand it answers (journeys/demand.json, or the manifest's refresh scope) and the mechanism that serves it. The Bot API is an RPC wire (POST /bot<token>/<method>, every answer {ok, result}), so no method is a create, read, update or delete the derived core could serve: each is a handler over the bot the token names (./src/semantics/around.ts resolves it, before routing, as the Bot API server does). Every other method of the page answers the server's unknown method (the manifest's gap), the URL-media sends only an opt-in Postiz storage makes (demand.json's optional) included: a URL the World cannot reach is refused as Telegram refuses one it cannot download. People, bots and chats are made through the World's doors (the Telegram app and BotFather, which no Bot API method stands for).",
+ "decisions": [
+  {
+   "operation": "getMe",
+   "demand": "Volter Harness's adapter reads its bot as it starts; Postiz reads its bot's id when the /connect message is found",
+   "mechanism": "handler",
+   "why": "a computed read: the bot the token names, its User with the bot-only fields (can_join_groups, can_read_all_group_messages for privacy mode, supports_inline_queries, …)"
+  },
+  {
+   "operation": "deleteWebhook",
+   "demand": "Volter Harness's adapter removes any webhook before it polls (drop_pending_updates false)",
+   "mechanism": "handler",
+   "why": "an action on the bot: its webhook URL cleared (none was set: 'Webhook is already deleted'), and its waiting updates dropped when asked"
+  },
+  {
+   "operation": "getUpdates",
+   "demand": "Volter Harness's adapter polls in a loop (timeout 30, limit 100); Postiz's connect screen polls with allowed_updates [message, channel_post] and an offset",
+   "mechanism": "handler",
+   "why": "an action: the bot's queue read from the offset (confirming, and so deleting, every update below it), filtered by the allowed_updates in force when each was made, at most limit; with nothing waiting and a timeout, the read held until an update is written (the kernel's held read)"
+  },
+  {
+   "operation": "sendChatAction",
+   "demand": "Volter Harness's adapter shows its bot typing when a person writes in private",
+   "mechanism": "handler",
+   "why": "an action that stores nothing: the chat's access checked as the server checks it, True"
+  },
+  {
+   "operation": "sendMessage",
+   "demand": "Volter Harness posts its answers and its scheduled reports; Postiz posts a text (HTML), its connect notices and a comment as a reply",
+   "mechanism": "handler",
+   "why": "a message made in a chat the bot may write in: its message_id counted per chat, its text parsed for the parse_mode's entities (HTML, MarkdownV2 or Markdown), checked for length (1-4096 after parsing), a reply resolved; it writes no update for its own bot (bots do not receive their own messages)",
+   "sourceRules": [
+    {
+     "source": "https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp",
+     "means": "Unsupported parse_mode"
+    }
+   ]
+  },
+  {
+   "operation": "sendPhoto",
+   "demand": "Postiz posts one image with its caption (HTML), uploaded",
+   "mechanism": "handler",
+   "why": "a message with a photo: the upload's bytes stored as a file (its width and height read from the image), the caption parsed and checked (0-1024); a URL the World cannot reach is refused as the server refuses one it cannot download"
+  },
+  {
+   "operation": "sendVideo",
+   "demand": "Postiz posts one video with its caption, uploaded",
+   "mechanism": "handler",
+   "why": "a message with a video: the bytes stored, its width, height and duration read from the file's own header where it is an MP4"
+  },
+  {
+   "operation": "sendDocument",
+   "demand": "Postiz posts one file that is neither an image nor a video, uploaded; Volter Harness's board sends a done card's artifact with its notice as a MarkdownV2 caption",
+   "mechanism": "handler",
+   "why": "a message with a document: the bytes stored with its name and media type; its caption parsed as sendMessage's text is (HTML, MarkdownV2 or Markdown) and checked (0-1024)"
+  },
+  {
+   "operation": "sendMediaGroup",
+   "demand": "Postiz posts several images or videos as one album, the caption on the first, uploaded (attach://<name>); Volter Harness's board sends a done card's several artifacts as one album of documents",
+   "mechanism": "handler",
+   "why": "2-10 messages sharing one media_group_id, each its own file; the array of sent messages answered"
+  },
+  {
+   "operation": "deleteMessage",
+   "demand": "Postiz deletes the /connect message and its own success notice",
+   "mechanism": "handler",
+   "why": "a message deleted where the bot may delete it: its own, or another's in a channel or group where it is an administrator with can_delete_messages; 'message to delete not found' for one that is not there"
+  },
+  {
+   "operation": "getChat",
+   "demand": "Postiz reads the channel it is connecting (id, title, username, photo); the vendor-backed refresh reads each chat again (the manifest's refresh of chat)",
+   "mechanism": "handler",
+   "why": "a computed read: the chat as ChatFullInfo, its access checked as the server checks a read"
+  },
+  {
+   "operation": "getChatMember",
+   "demand": "Postiz checks its bot is an administrator that can delete messages in the channel",
+   "mechanism": "handler",
+   "why": "a computed read: the member's status and rights with its user"
+  },
+  {
+   "operation": "getFile",
+   "demand": "Postiz reads the chat photo's file to make its link",
+   "mechanism": "handler",
+   "why": "an action: the file's download path issued (file_path), valid for the bot that asked"
+  },
+  {
+   "operation": "downloadFile",
+   "demand": "Postiz copies the chat photo into its storage from the file's link",
+   "mechanism": "handler",
+   "why": "the stored bytes of the file a getFile path names, for the bot whose token is in the path"
+  }
+ ]
+}

package/journeys/demand.json

@@ -0,0 +1,152 @@
+{
+  "measured": "Application calls and optional settings are recorded below at the cited commits.",
+  "applications": [
+    {
+      "name": "volter-ai/supercode (Volter Harness)",
+      "commit": "62620578c014",
+      "client": "the Chat SDK's Telegram adapter (@chat-adapter/telegram 4.39.0 under chat 4.39.0, fetch POST https://api.telegram.org/bot<token>/<method> with a JSON body, multipart form data for a file; rows marked @chat-adapter/telegram@4.39.0: are its published dist), botToken TELEGRAM_BOT_TOKEN from the Hermes profile's .env, mode polling; configuration read at sdk/orchestrator/adapters/chat-sdk.mjs:10,80,209",
+      "backend": [
+        {
+          "call": "the sidecar starts the Chat SDK: the adapter reads the bot's own user (its id and username, which a mention names)",
+          "operation": "getMe",
+          "evidence": "sdk/orchestrator/adapters/chat-sdk.mjs:331",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:1088"
+        },
+        {
+          "call": "...and, polling, removes any webhook first (pending updates kept)",
+          "operation": "deleteWebhook",
+          "evidence": "sdk/orchestrator/adapters/chat-sdk.mjs:80",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:1293"
+        },
+        {
+          "call": "...then asks for updates in a loop, each request held up to 30 seconds, confirming the last with offset",
+          "operation": "getUpdates",
+          "evidence": "sdk/orchestrator/adapters/chat-sdk.mjs:80",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:3327"
+        },
+        {
+          "call": "a person writes to the bot in private: the adapter shows it typing",
+          "operation": "sendChatAction",
+          "evidence": "sdk/orchestrator/adapters/chat-sdk.mjs:323",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:1945"
+        },
+        {
+          "call": "the agent's answer posted in the chat it came from, in parts of 4096 characters at most",
+          "operation": "sendMessage",
+          "evidence": "sdk/orchestrator/adapters/chat-sdk.mjs:449",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:3246"
+        },
+        {
+          "call": "a scheduled job's report to the profile's home chat (TELEGRAM_HOME_CHANNEL)",
+          "operation": "sendMessage",
+          "evidence": "sdk/orchestrator/adapters/chat-sdk.mjs:453",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:1790"
+        },
+        {
+          "call": "a card the chat is subscribed to is done: the board's notice with the card's artifact, the notice the file's caption in MarkdownV2",
+          "operation": "sendDocument",
+          "evidence": "sdk/orchestrator/board/dispatch.mjs:1663",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:2645"
+        },
+        {
+          "call": "...a card done with several artifacts: the files as one album of documents, the notice the first's caption in MarkdownV2",
+          "operation": "sendMediaGroup",
+          "evidence": "sdk/orchestrator/board/dispatch.mjs:1663",
+          "client": "@chat-adapter/telegram@4.39.0:dist/index.js:2802"
+        }
+      ]
+    },
+    {
+      "commit": "e0a08a7d9592fdc1ef1e82cb7cb781489fceade3",
+      "client": "node-telegram-bot-api 0.66.0 (POST https://api.telegram.org/bot<token>/<method>, form-urlencoded, multipart for a file; rows marked node-telegram-bot-api@0.66.0: are its published src), TELEGRAM_TOKEN",
+      "backend": [
+        {
+          "call": "the connect screen polls for the person's /connect message (allowed_updates message and channel_post, from the last offset)",
+          "operation": "getUpdates",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:87",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:849"
+        },
+        {
+          "call": "found: the bot's own id",
+          "operation": "getMe",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:105",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:931"
+        },
+        {
+          "call": "...whether it is an administrator that can delete messages there",
+          "operation": "getChatMember",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:356",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1966"
+        },
+        {
+          "call": "an administrator: the /connect message deleted, a success notice posted and deleted ten seconds later",
+          "operation": "deleteMessage",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:120",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:3093"
+        },
+        {
+          "call": "the success notice (or, without the right to delete, the notice asking the person to remove the messages)",
+          "operation": "sendMessage",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:122",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:970"
+        },
+        {
+          "call": "the channel added: its chat read (id, title, username, photo)",
+          "operation": "getChat",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:62",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1924"
+        },
+        {
+          "call": "...and its photo's file, whose path makes the channel's picture link",
+          "operation": "getFile",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:71",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1522"
+        },
+        {
+          "call": "...and Postiz copies the picture into its own storage from that link",
+          "operation": "downloadFile",
+          "evidence": "libraries/nestjs-libraries/src/database/prisma/integrations/integration.service.ts:119",
+          "client": "libraries/nestjs-libraries/src/upload/local.storage.ts:62"
+        },
+        {
+          "call": "a post with no media: its text, parse_mode HTML",
+          "operation": "sendMessage",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:224",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:970"
+        },
+        {
+          "call": "a post with one image: the photo uploaded with the text as its caption",
+          "operation": "sendPhoto",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:247",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1075"
+        },
+        {
+          "call": "a post with one video",
+          "operation": "sendVideo",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:240",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1164"
+        },
+        {
+          "call": "a post with one file that is neither",
+          "operation": "sendDocument",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:253",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1136"
+        },
+        {
+          "call": "a post with several media: an album of up to ten, the text on the first",
+          "operation": "sendMediaGroup",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:272",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:1296"
+        },
+        {
+          "call": "a comment: the next post sent as a reply to the last (reply_to_message_id)",
+          "operation": "sendMessage",
+          "evidence": "libraries/nestjs-libraries/src/integrations/social/telegram.provider.ts:226",
+          "client": "node-telegram-bot-api@0.66.0:src/telegram.js:970"
+        }
+      ],
+      "name": "gitroomhq/postiz-app"
+    }
+  ],
+  "optional": []
+}