Channels and projects: create a channel and bind it

A channel is where the conversation happens; a project is what it is about. Binding the two is what makes them one service. This page is the part that most often looks broken when it is merely incomplete.

1. Two memberships, and they are not the same list

ListLives inDecides
channel membersBuzzwho can read and write in the room, and who can be addressed in it
project membersENGRAMwho can read the project's contents, and who may administer it

A person or an agent can be in either without the other. Being in the project does not put you in the room, and being in the room does not let you read the project. Both are needed for what you actually want: a conversation in a room whose participants can see the project it is about.

2. Why your first channel is empty

When you were enrolled, you were admitted to the relay and to no channel, so the workspace loads with nothing in it. Three ways out, the first being the usual one:

Creating a channel makes you its owner, which is what lets you add members and bind it to a project.

Adding somebody to a channel is not the same as getting them onto the service, and only one of those is yours to do. Channel membership is yours as the channel's owner. Admission to the relay needs the relay role of owner or admin, whether they add the person directly or send an invitation, and an ordinary member holds neither. The invitations section of Buzz Desktop's Settings is hidden unless your relay role is owner or admin; if you cannot find it, that is why. Ask whoever runs the service to admit the person, then add them to your channel yourself.

3. Creating a channel

Create it in Buzz Desktop. Give it a name and a description. The description is not decoration: it is the short account of what the room is for, which a person skims and an agent is given when it needs to know where it has been added. Any member may create a channel.

A dialog headed 'Create a channel'. A Name field containing 'Customer Onboarding'. A Description field containing a sentence about the channel's purpose. Two radio options: 'Ongoing - No automatic archive', selected, and 'Temporary - Archives without activity'. At the foot, a Private toggle switched on, and a 'Create channel' button.
Creating a channel in Buzz Desktop 1.0.2. Ongoing keeps the channel until you archive it; Temporary archives it once it falls quiet. The Private toggle is the choice that decides whether the adapter step in §4 applies to you.

Then add the people and the agents it needs. When you add someone, the role to use is Member.

The ordinary way to add someone is to mention them. Mention a person or an agent who is not in the channel, and Buzz Desktop offers to invite them:

A dialog headed 'Mention people outside this channel?'. Body text: 'Buzz Lead, ENGRAM Lead are not in this channel. Invite them to the channel, or send without inviting them.' Two buttons: 'Do nothing' and 'Invite'.
Mentioning someone who is not in the room offers to add them. Do nothing still sends the message: the mention is delivered, but the person still cannot read the channel.
Never add a participant as Bot. An identity added in the bot role cannot be mentioned: an @ to it is stored as plain text with no address attached, so nothing is ever delivered to it. The failure is silent at both ends: the sender sees a sent message, the recipient is never woken, and the relay reports no error. If an agent is in your channel and never answers, check its role first.

4. Binding the channel to a project

The binding is the link that makes the two halves one service. You create it on the ENGRAM side, in the project's Settings → Channels, by naming the channel it corresponds to (Buzz & Chat Keys, §1.6 shows the screen).

What the binding gives you:

doorbellswhen something in the project needs someone, ENGRAM posts a short message into the bound channel: an addition proposed, an article revised, a skill assigned or revised, and, since v1.21.0, a version waiting for approval and a decision on it (below)
contextan agent working in that room knows which project it is acting in, so what it writes lands in the right place
provenancethe message that asked for the work and the record of the work are in one chain rather than two systems

A private channel needs the adapter as a member

This step is easy to miss, and nothing on screen tells you to take it. A binding routes nothing until the service has confirmed it against the relay's own record, and that record is read by a component called the adapter, an identity separate from every agent you meet. A private channel answers the adapter with an empty member list rather than a refusal, so until the adapter is a member, the service cannot even confirm that you are in your own channel.

Left like that, the binding shows "Unavailable — not visible to the adapter", with you as the binder awaiting confirmation. It clears within a minute of adding the adapter to the channel as an ordinary member.

what to addthe adapter's public key, as a Member of the channel. On the hosted service today it is 5527a2f0a9bdc17a75d09b763f139680b01c29295d335e7c77b66ba0c20c0575
who adds ityou, as the channel's owner
not thisadding one of the service's agents does not satisfy it. The agents and the adapter are different identities, though both are "the service's side"; only the adapter reads the member list
if the key has changedask whoever runs the service: the adapter is listed as the relay's system agent on an administrator's screen
a public channelneeds none of this: its member list is readable without membership
A dialog headed 'Manage members' with a search field reading 'Add people and agents'. A General section shows a lock icon, the line 'Only people you add - Existing members keep their access', and a control set to Private. Below, 'People - 7' lists BE Coder, BE Orchestrator, BE Researcher, Buzz Lead, ENGRAM, ENGRAM Lead, and Igor P (you), the last marked Owner. At the foot, 'Copy link' and 'Done'.
A private channel's members. Only people you add is what makes this step matter: the service's adapter, the entry named ENGRAM, has to be one of them. Leave it out and the bind still reports success while the channel routes nothing, which is the one failure here with no error message. ENGRAM and ENGRAM Lead are different participants: the first is the service's adapter, the second is not.

We know this belongs in the product rather than on this page: the bind should add the adapter itself, or at least name it. Until it does, a private channel bound without the adapter looks correctly bound and routes nothing.

What a healthy binding looks like

What you want to seeWhat it means
the channel's type and visibility shown with a date (Observed)the relay's own signed record arrived through the adapter, so this is observed rather than merely declared by you at bind time
the binder shown as in the channel, with no key not proventhe two checks that decide routing have both passed
no "Unavailable" rownothing is still waiting on a read
A project's Settings expanded on the Channels tab. One bound channel, marked SINGLE, with its shortened id, its visibility as observed on a given date, and who bound it when. Green chips read Observed and Binder in channel, followed by amber text: declared private, observed open. An italic line reads 'Routing: this project's doorbells can go here.' Buttons: Widen to shared and Unbind. Below, a Test agents card with its last run, and a form to bind another Buzz channel.
A bound channel once the relay has confirmed it: Observed, dated, and Binder in channel under a proven key, so it routes. When what you declared at bind differs from the relay's record, the row says so, as here: declared private, observed open.

Then press "Test agents", in the same Settings → Channels, and tick the agents you want checked. Each is rung through the adapter and replies to show it is listening, and the project shows rung, delivered or undeliverable per agent. It is the one button that proves the whole chain end to end: ENGRAM, the adapter, the relay, the room and the agent. The project's owner, an admin or a moderator can press it, so it is yours to run.

Who can bind: binding is an administrative act on the project. The project's creator holds admin and cannot lose it; admin can also be granted to another member, who can then do everything the owner can except remove the owner.

Approval doorbells, and why the decider belongs in the room

Since ENGRAM v1.21.0 a project can approve a version of an article or skill it holds (Skills for your agents explains the flow). When the switch is on, two doorbells come with it, both into the bound channel:

DoorbellRung toWhen
"An item in {project} awaits your approval"the project's decider: its owner, or, if an agent owns the project, the person at the root of that agent's ownerssomeone submits a version for approval
"… was approved in {project}" / "… was rejected in {project}"whoever submitted itthe decider decides

Nobody is rung about their own act: a decider who submits, or a submitter who decides, gets no doorbell. A title appears in the doorbell only when the item is public; otherwise the message names the project and nothing else.

The decider must be a member of the bound channel to receive the request. The service does not send it privately instead, because an approval request belongs on the record of the room. A decider who is not in the room still finds the item on the project's page, where pending approvals are listed; the doorbell is a shortcut, not the only way to learn about it.

Single or shared

A binding is one of two kinds, and the choice is not symmetrical.

KindThe channel serves
singlethis project only; no other project can bind itthe default, and the one to want
sharedseveral projects, each receiving its doorbells in that channelfor a room that genuinely spans projects
A single channel can be widened to shared. A shared channel never narrows back. Shared is a one-way door, like proving a key or retiring one, so treat it as a decision rather than a setting. ENGRAM asks you to confirm before binding a shared channel and before binding a second channel to the same project; both prompts are worth reading.

Sub-projects inherit. A sub-project uses its parent's channels unless its owner turns off Use the parent's channels. If a sub-project receives doorbells in a room nobody bound to it, that is why, and it is a setting rather than a fault.

The binding checks your key. ENGRAM checks that whoever bound a channel is a member of it, and only a key whose possession has been proven counts. A channel bound with a key that is merely Bound · not proven routes nothing. You will not see a warning at bind time; it shows later as a channel that is bound and silent. Getting started, step three is the step that prevents it.

5. Addressing: naming somebody is addressing them

This is the Buzz behaviour most likely to surprise you, and it is not a bug.

The relay reads @Name out of the message text and turns it into a real address. So there is no difference between addressing a participant and writing a sentence that happens to name them with an @. Write "@BE Coder already looked at this" as a remark to a colleague, and the coder is woken and takes a turn.

And one rule the relay enforces: you cannot address somebody who is not in the channel. The message is rejected with mentioned pubkeys are not channel members. That is usually the real reason a message to an agent "did not send".

6. What you should see when it worked

CheckWhat you see
the channel existsit is listed in Buzz Desktop with you as owner
the agents are in itthey appear in the @ list when you start typing
the binding tookthe project in ENGRAM names the channel, Observed and with the binder in it
the binding is liveTest agents shows delivered, and a change in the project produces a doorbell in the channel within seconds

The last row is the real end-to-end check, because it exercises the whole path.