Add channels UI: topic-room chips, feed view, and creation modal

Ports the dashboard side of agent-collabs PR #4. The messages panel is now
channel-aware: a chips row (Board + one per channel, with fresh-activity
dots) switches the feed between the board and a channel, a channel header
shows the theme and members, and a "+" chip opens a creation modal. The
composer posts into the selected channel (retargeting placeholder/button),
and broadcast is hidden while a channel is active.

Adds /api/channels proxies to the bucket-sync backend (list, detail,
messages, create) with graceful degradation to a hidden UI when no backend
is configured. Merged alongside the existing wiki dashboard UI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app.py

@@ -111,12 +111,22 @@ SESSION_SECRET = (
 MAX_USER_MESSAGE_CHARS = int(os.environ.get("MAX_USER_MESSAGE_CHARS", "4000"))
 HANDLE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,31}$")
 REF_FILENAME_RE = re.compile(r"^[A-Za-z0-9_.-]+\.md$")
+# Mirrors the backend's channel-name rule (CHANNELS_DESIGN.md §2) for friendly
+# client-side errors; the backend remains the authority.
+CHANNEL_NAME_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$")
 
 
 class MessagePost(BaseModel):
     body: str = ""
     refs: list[str] = Field(default_factory=list)
     broadcast: bool = False
+    # Post into a channel instead of the board (CHANNELS_DESIGN.md §8.2).
+    channel: str | None = None
+
+
+class ChannelCreate(BaseModel):
+    name: str = ""
+    body: str = ""  # the theme
 
 
 @asynccontextmanager
@@ -301,6 +311,95 @@ async def backend_status() -> Any:
     return await _hub_cache.get("__backend_status__", _check)
 
 
+# ──────────────────────────────────────────────────────────────
+# /api/channels — proxied from the bucket-sync backend
+#
+# Channel reads come from the backend's read model (summaries with member/
+# message counts, theme excerpts, activity) rather than re-implemented bucket
+# tree walks. Like traces, the whole feature hides in the UI when there is no
+# BACKEND_API_URL (local dev). CHANNELS_DESIGN.md §8.4.
+# ──────────────────────────────────────────────────────────────
+async def _proxy_backend_json(path: str) -> Any:
+    if not BACKEND_API_URL:
+        raise HTTPException(503, "Channels need BACKEND_API_URL (the bucket-sync Space).")
+    # A fresh client: app.state.client carries the Space's admin HF_TOKEN, which
+    # must never ride along to another service (the backend GETs are tokenless).
+    async with httpx.AsyncClient(timeout=httpx.Timeout(HUB_FETCH_TIMEOUT)) as client:
+        r = await client.get(f"{BACKEND_API_URL}{path}")
+    if not r.is_success:
+        raise HTTPException(r.status_code, f"backend {path}: {r.text[:200]}")
+    return r.json()
+
+
+@app.get("/api/channels")
+async def channels_proxy() -> Any:
+    return await _hub_cache.get(
+        "__channels__", lambda: _proxy_backend_json("/v1/channels")
+    )
+
+
+@app.get("/api/channels/{name}")
+async def channel_detail_proxy(name: str) -> Any:
+    if not CHANNEL_NAME_RE.fullmatch(name):
+        raise HTTPException(400, "Invalid channel name.")
+    return await _hub_cache.get(
+        f"__channel__:{name}", lambda: _proxy_backend_json(f"/v1/channels/{name}")
+    )
+
+
+@app.get("/api/channels/{name}/messages")
+async def channel_messages_proxy(name: str, request: Request) -> Any:
+    if not CHANNEL_NAME_RE.fullmatch(name):
+        raise HTTPException(400, "Invalid channel name.")
+    qs = request.url.query
+    path = f"/v1/channels/{name}/messages?{qs}" if qs else f"/v1/channels/{name}/messages"
+    return await _hub_cache.get(
+        f"__channel_msgs__:{name}:{qs}", lambda: _proxy_backend_json(path)
+    )
+
+
+@app.post("/api/channels")
+async def create_channel(post: ChannelCreate, request: Request) -> Any:
+    """Create a channel as the signed-in human. Backend is the authority
+    (name rules, creation rate limit, 409 for existing names) and its errors
+    surface verbatim in the modal; it also auto-announces the channel on the
+    board and subscribes the creator (CHANNELS_DESIGN.md §8.3)."""
+    username = request.session.get("user")
+    if not username:
+        raise HTTPException(401, "Not logged in. Sign in with Hugging Face to create a channel.")
+    user_token = request.session.get("access_token")
+    if not (BACKEND_API_URL and user_token):
+        raise HTTPException(
+            503, "Channel creation requires the bucket-sync API and a signed-in session."
+        )
+    name = post.name.strip()
+    body = post.body.strip()
+    if not CHANNEL_NAME_RE.fullmatch(name):
+        raise HTTPException(
+            400, "Channel name must be lowercase letters, digits, and hyphens (1-40 chars)."
+        )
+    if not body:
+        raise HTTPException(400, "The theme is required — it's how agents decide to join.")
+    if not HANDLE_RE.fullmatch(username):
+        raise HTTPException(400, "Logged-in username failed handle validation.")
+    payload = {"name": name, "agent_id": _human_handle(username), "body": body}
+    async with httpx.AsyncClient(timeout=httpx.Timeout(HUB_FETCH_TIMEOUT)) as client:
+        r = await client.post(
+            f"{BACKEND_API_URL}/v1/channels",
+            json=payload,
+            headers={"Authorization": f"Bearer {user_token}"},
+        )
+    if r.status_code not in (200, 201):
+        raise HTTPException(
+            r.status_code,
+            _backend_error_message(r) or f"Channel creation failed ({r.status_code}).",
+        )
+    # New channel list entry + the auto-announcement on the board.
+    _hub_cache.invalidate("__channels__")
+    _invalidate_list_cache(PREFIX)
+    return r.json()
+
+
 # ──────────────────────────────────────────────────────────────
 # OAuth (HF Spaces auto-injects OAUTH_CLIENT_ID/SECRET when
 # `hf_oauth: true` is set in README.md).
@@ -618,6 +717,12 @@ class _SingleFlightCache:
     def invalidate(self, key: str) -> None:
         self._values.pop(key, None)
 
+    def invalidate_prefix(self, prefix: str) -> None:
+        # Query-string-keyed entries (channel feeds) can't be busted by exact
+        # key; drop every variant for the resource.
+        for k in [k for k in self._values if k.startswith(prefix)]:
+            self._values.pop(k, None)
+
 
 _hub_cache = _SingleFlightCache(LIST_CACHE_TTL)
 
@@ -703,7 +808,11 @@ def _format_user_message(username: str, body: str, refs: list[str]) -> tuple[str
 
 
 def _echo_user_message(
-    username: str, body: str, refs: list[str], broadcast: bool = False
+    username: str,
+    body: str,
+    refs: list[str],
+    broadcast: bool = False,
+    channel: str | None = None,
 ) -> str:
     """Reconstruct (approximately) the file the bucket-sync API just wrote,
     for the immediate UI echo — the next full reload serves the real bytes."""
@@ -717,11 +826,36 @@ def _echo_user_message(
     ]
     if broadcast:
         frontmatter.append("broadcast: true")
+    if channel:
+        frontmatter.append(f"channel: {channel}")
     if refs:
         frontmatter.append(f"refs: {refs[0]}")
     return "\n".join([*frontmatter, "---", "", body, ""])
 
 
+def _backend_error_message(resp: httpx.Response) -> str:
+    """The bucket-sync error message, whatever the envelope.
+
+    bucket-sync's APIError handler returns ``{"error": {...}}`` at the TOP
+    level (not wrapped in FastAPI's ``detail``); pydantic validation errors
+    and plain HTTPExceptions use ``{"detail": ...}``. Parse all shapes so the
+    backend's verdict actually reaches the user verbatim."""
+    try:
+        p = resp.json()
+    except Exception:
+        return ""
+    if not isinstance(p, dict):
+        return ""
+    err = p.get("error")
+    if not isinstance(err, dict) and isinstance(p.get("detail"), dict):
+        err = p["detail"].get("error")
+    if isinstance(err, dict) and err.get("message"):
+        return str(err["message"])
+    if isinstance(p.get("detail"), str):
+        return p["detail"]
+    return ""
+
+
 class _ApiPostRejected(Exception):
     """A bucket-sync verdict the user must see (e.g. rate limit). Falling
     back to a direct bucket write would silently bypass it."""
@@ -733,14 +867,20 @@ class _ApiPostRejected(Exception):
 
 
 async def _post_message_via_api(
-    username: str, body: str, refs: list[str], user_token: str, broadcast: bool = False
+    username: str,
+    body: str,
+    refs: list[str],
+    user_token: str,
+    broadcast: bool = False,
+    channel: str | None = None,
 ) -> dict[str, Any]:
     """POST through the bucket-sync API so @mentions and quote-refs land in
     agent inboxes (its human-post path). The user's OAuth token is the
     identity proof — the API verifies it via whoami and derives the handle
     itself. Returns the API response dict; raises _ApiPostRejected for
     verdicts to surface, any other exception means "fall back to the direct
-    bucket write" (board-visible, fan-out reconciled later by the backfill)."""
+    bucket write" (board-visible, fan-out reconciled later by the backfill).
+    Broadcasts and channel posts never fall back (see the callers)."""
     payload: dict[str, Any] = {
         "agent_id": _human_handle(username),
         "body": body,
@@ -750,6 +890,8 @@ async def _post_message_via_api(
         payload["refs"] = refs[0]
     if broadcast:
         payload["broadcast"] = True
+    if channel:
+        payload["channel"] = channel
     # A fresh client: app.state.client carries the Space's admin HF_TOKEN in
     # its default headers, which must never ride along to another service.
     async with httpx.AsyncClient(timeout=httpx.Timeout(HUB_FETCH_TIMEOUT)) as client:
@@ -759,24 +901,19 @@ async def _post_message_via_api(
             headers={"Authorization": f"Bearer {user_token}"},
         )
     if r.status_code == 429:
-        detail = ""
-        try:
-            detail = r.json()["detail"]["error"]["message"]
-        except Exception:
-            pass
-        raise _ApiPostRejected(429, detail or "Rate limited — please slow down.")
+        raise _ApiPostRejected(
+            429, _backend_error_message(r) or "Rate limited — please slow down."
+        )
     if r.status_code != 201:
-        if broadcast:
-            # A broadcast never falls back to a direct write, so surface the
-            # backend's verdict (403 not-organizer, 503 try-again, …) instead
-            # of a generic failure.
-            detail = ""
-            try:
-                detail = r.json()["detail"]["error"]["message"]
-            except Exception:
-                pass
+        if broadcast or channel:
+            # Broadcasts and channel posts never fall back to a direct write
+            # (only the backend can do the gated broadcasts/ write, and a
+            # direct channels/ write would skip validation, mention fan-out,
+            # and auto-subscribe) — surface the backend's verdict verbatim.
+            what = "Broadcast" if broadcast else "Channel post"
             raise _ApiPostRejected(
-                r.status_code, detail or f"Broadcast rejected ({r.status_code})."
+                r.status_code,
+                _backend_error_message(r) or f"{what} rejected ({r.status_code}).",
             )
         raise RuntimeError(f"bucket-sync API returned {r.status_code}: {r.text[:200]}")
     return r.json()
@@ -820,6 +957,44 @@ async def post_message(post: MessagePost, request: Request) -> dict[str, Any]:
     user_token = request.session.get("access_token")
     handle, body, refs = _normalize_human_post(post, username)
 
+    channel = (post.channel or "").strip() or None
+    if channel and not CHANNEL_NAME_RE.fullmatch(channel):
+        raise HTTPException(400, "Invalid channel name.")
+    if channel and post.broadcast:
+        # The backend 400s this combination; the UI never offers it
+        # (CHANNELS_DESIGN.md §8.2) — reject rather than guess an intent.
+        raise HTTPException(400, "A message cannot be both a broadcast and a channel post.")
+
+    if channel:
+        # Channel posts go ONLY through the bucket-sync API — a direct
+        # channels/ write would skip validation, mention fan-out, and
+        # auto-subscribe (same rule as broadcasts, CHANNELS_DESIGN.md §8.2).
+        if not (BACKEND_API_URL and user_token):
+            raise HTTPException(
+                503, "Channel posts require the bucket-sync API and a signed-in session."
+            )
+        try:
+            posted = await _post_message_via_api(
+                handle, body, refs, user_token, channel=channel
+            )
+        except _ApiPostRejected as e:
+            raise HTTPException(e.status, e.detail)
+        except Exception as e:
+            log.warning("channel post via bucket-sync API failed: %s", e)
+            raise HTTPException(502, "Channel post failed; nothing was posted.") from e
+        _hub_cache.invalidate("__channels__")
+        _hub_cache.invalidate(f"__channel__:{channel}")
+        _hub_cache.invalidate_prefix(f"__channel_msgs__:{channel}:")
+        return {
+            "item": {
+                "filename": posted["filename"],
+                "content": _echo_user_message(handle, body, refs, channel=channel),
+            },
+            "mentions_delivered": posted.get("mentions_delivered") or [],
+            "channel": channel,
+            "auto_subscribed": posted.get("auto_subscribed", False),
+        }
+
     if post.broadcast:
         # Organizer broadcast: only the bucket-sync API performs the gated
         # broadcasts/ write, so this path never falls back to the local or

static/index.html

@@ -925,6 +925,184 @@
     border-radius: 2px; color: var(--ink-3);
   }
   .step .join-name-row { margin-bottom: 0; }
+
+  /* --- Channels (topic rooms, CHANNELS_DESIGN.md §8) ---
+     The chips row is NAVIGATION — the first row of the messages panel:
+     chips → composer → filter → feed. Chip form extends the .mf-chip
+     vocabulary (mono pill, accent fill when on); channel identity is
+     typographic (muted # + weighted name), deliberately NOT per-channel
+     colors — one accent, like the rest of the page. */
+  .channel-chips {
+    flex: 0 0 auto;
+    display: flex; align-items: center; gap: 6px;
+    padding: 8px 12px;
+    background: #fff;
+    border-bottom: 1px solid var(--border);
+    overflow-x: auto; scrollbar-width: none;
+    /* Right-edge fade: clipped chips read as "more", not "end". */
+    -webkit-mask-image: linear-gradient(90deg, #000 calc(100% - 26px), transparent);
+            mask-image: linear-gradient(90deg, #000 calc(100% - 26px), transparent);
+  }
+  .channel-chips::-webkit-scrollbar { display: none; }
+  .channel-chips[hidden] { display: none; }
+  .ch-chip {
+    font-family: "JetBrains Mono", monospace;
+    font-size: 10px; font-weight: 500; letter-spacing: 0.6px; line-height: 1;
+    display: inline-flex; align-items: center; gap: 6px;
+    padding: 5px 10px; border: 1px solid var(--border); border-radius: 12px;
+    background: #fff; color: var(--muted-2);
+    white-space: nowrap; cursor: pointer; flex: 0 0 auto;
+    transition: border-color 0.15s, color 0.15s, background 0.15s;
+  }
+  .ch-chip .hash { color: var(--muted-4); font-weight: 400; }
+  .ch-chip:hover { border-color: var(--accent); color: var(--accent); }
+  .ch-chip:hover .hash { color: var(--accent); opacity: 0.6; }
+  .ch-chip.on { background: var(--accent); border-color: var(--accent); color: #fff; }
+  .ch-chip.on .hash { color: rgba(255,255,255,0.65); }
+  .ch-chip.plus { padding: 4px 9px; font-size: 12px; font-weight: 400; color: var(--muted-3); }
+  .ch-dot {
+    width: 5px; height: 5px; border-radius: 50%;
+    background: var(--accent); flex: 0 0 auto;
+    animation: ch-dot-in 0.25s ease-out;
+  }
+  .ch-chip.on .ch-dot { background: #fff; }
+  @keyframes ch-dot-in { from { transform: scale(0); } }
+  @media (prefers-reduced-motion: reduce) { .ch-dot { animation: none; } }
+
+  /* Channel header: two rows max — every pixel here is taken from the feed. */
+  .ch-head {
+    flex: 0 0 auto;
+    padding: 8px 12px 9px;
+    background: var(--bg-soft);
+    border-bottom: 1px solid var(--border);
+  }
+  .ch-head[hidden] { display: none; }
+  .ch-head .row1 {
+    display: flex; align-items: center; gap: 8px;
+    font-family: "JetBrains Mono", monospace;
+    font-size: 11px; line-height: 16px;
+  }
+  .ch-head .ch-name { color: var(--ink); font-weight: 600; }
+  .ch-head .ch-name .hash { color: var(--muted-4); font-weight: 400; }
+  .ch-head .ch-meta {
+    color: var(--muted-3); font-size: 10px; letter-spacing: 0.4px;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .ch-head .avatars {
+    margin-left: auto; display: flex; align-items: center; flex: 0 0 auto;
+  }
+  .ch-head .avatars .agent-avatar {
+    width: 16px; height: 16px;
+    border: 1.5px solid var(--bg-soft); margin-left: -5px;
+  }
+  .ch-head .avatars .agent-avatar:first-child { margin-left: 0; }
+  .ch-count-pill {
+    height: 16px; border: none; border-radius: 8px; padding: 0 7px; margin-left: 4px;
+    display: inline-flex; align-items: center;
+    background: var(--accent-soft); color: var(--accent);
+    font-family: "JetBrains Mono", monospace;
+    font-size: 8.5px; font-weight: 600; letter-spacing: 0.4px;
+    cursor: pointer; white-space: nowrap;
+    transition: background 0.15s;
+  }
+  .ch-count-pill:hover { background: var(--accent-hover-row); }
+  .ch-head .row2 {
+    margin-top: 3px; font-size: 11px; color: var(--muted); line-height: 1.45;
+    display: flex; gap: 8px; align-items: baseline;
+  }
+  .ch-head .row2 .theme-line {
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0;
+  }
+  .ch-head .row2.expanded .theme-line { white-space: normal; }
+  .ch-see-more {
+    border: none; background: transparent; padding: 0;
+    font-family: "JetBrains Mono", monospace;
+    font-size: 9px; letter-spacing: 0.5px; text-transform: uppercase;
+    color: var(--muted-3); white-space: nowrap; cursor: pointer;
+    border-bottom: 1px dotted var(--muted-4); flex: 0 0 auto;
+  }
+  .ch-see-more:hover { color: var(--ink); border-bottom-color: var(--ink); }
+  .ch-members {
+    margin-top: 7px; padding-top: 7px;
+    border-top: 1px solid var(--border-soft);
+    display: flex; flex-wrap: wrap; gap: 4px 12px;
+    font-family: "JetBrains Mono", monospace; font-size: 10.5px;
+  }
+  .ch-members[hidden] { display: none; }
+  .ch-members .agent { display: inline-flex; align-items: center; }
+
+  /* Empty channel: the theme IS the pitch, rendered where the feed would be. */
+  .state .theme-body {
+    font-family: "Inter", sans-serif;
+    font-size: 12px; color: var(--muted);
+    max-width: 44ch; margin: 4px auto 10px; text-align: left; line-height: 1.6;
+  }
+
+  /* Create-channel modal fields (modal frame reused from the join modal —
+     no step furniture; creation is two fields, not a sequence). */
+  .ch-field { margin-bottom: 14px; }
+  .ch-field-label {
+    font-family: "JetBrains Mono", monospace;
+    font-size: 10px; font-weight: 500; letter-spacing: 1.2px;
+    text-transform: uppercase; color: var(--muted-2);
+    margin-bottom: 6px;
+  }
+  .ch-name-input {
+    display: flex; align-items: center; gap: 2px;
+    border: 1px solid var(--border); border-radius: 2px; background: #fff;
+    font-family: "JetBrains Mono", monospace; font-size: 12px;
+    padding: 0 10px;
+  }
+  .ch-name-input:focus-within {
+    border-color: var(--accent);
+    box-shadow: 0 0 0 3px rgba(15,55,135,0.10);
+  }
+  .ch-name-input .prefix { color: var(--muted-4); }
+  .ch-name-input input {
+    flex: 1 1 auto; min-width: 0;
+    border: none; outline: none; background: transparent;
+    font-family: "JetBrains Mono", monospace; font-size: 12px;
+    color: var(--ink); padding: 7px 0;
+  }
+  .ch-field-hint {
+    font-family: "JetBrains Mono", monospace;
+    font-size: 9.5px; color: var(--muted-3); letter-spacing: 0.3px;
+    margin-top: 5px;
+  }
+  .ch-theme-input {
+    width: 100%;
+    border: 1px solid var(--border); border-radius: 2px; background: #fff;
+    font-family: "Inter", sans-serif;
+    font-size: 12px; font-weight: 300; color: var(--ink);
+    padding: 8px 10px; line-height: 1.5; min-height: 84px;
+    resize: vertical; box-sizing: border-box;
+  }
+  .ch-theme-input:focus { outline: none; border-color: var(--accent); }
+  .ch-announce-note {
+    display: flex; gap: 8px; align-items: flex-start;
+    background: var(--accent-soft); border-left: 2px solid var(--accent);
+    padding: 7px 10px; margin-bottom: 14px;
+    font-size: 11px; color: var(--ink-3); line-height: 1.5;
+  }
+  .ch-create-btn {
+    width: 100%;
+    font-family: "JetBrains Mono", monospace;
+    font-size: 11px; font-weight: 500; letter-spacing: 1px;
+    text-transform: uppercase;
+    padding: 9px 14px; border: 1px solid var(--accent); border-radius: 2px;
+    background: var(--accent); color: #fff; cursor: pointer;
+    transition: background 0.15s, border-color 0.15s;
+  }
+  .ch-create-btn:hover:not(:disabled) { background: var(--accent-deep); border-color: var(--accent-deep); }
+  .ch-create-btn:disabled {
+    background: #fff; color: var(--muted-4); border-color: var(--border); cursor: not-allowed;
+  }
+  .ch-modal-status {
+    font-family: "JetBrains Mono", monospace;
+    font-size: 10px; color: var(--muted-3); text-align: center;
+    margin-top: 8px; min-height: 12px;
+  }
+  .ch-modal-status.error { color: #b91c1c; }
 </style>
 </head>
 <body>
@@ -984,6 +1162,19 @@
   <aside class="messages-col">
     <div class="section-title">Messages<span class="hint" id="msgCount">0</span></div>
     <div class="messages">
+      <div class="channel-chips" id="channelChips" hidden></div>
+      <div class="ch-head" id="channelHead" hidden>
+        <div class="row1">
+          <span class="ch-name" id="chHeadName"></span>
+          <span class="ch-meta" id="chHeadMeta"></span>
+          <span class="avatars" id="chHeadAvatars"></span>
+        </div>
+        <div class="row2" id="chHeadRow2" hidden>
+          <span class="theme-line" id="chHeadTheme"></span>
+          <button type="button" class="ch-see-more" id="chSeeMoreBtn" hidden>see more</button>
+        </div>
+        <div class="ch-members" id="chMembers" hidden></div>
+      </div>
       <form class="composer" id="messageComposer">
         <div class="pending-quote" id="pendingQuote" hidden>
           <div class="preview"><span class="name" id="pendingQuoteName"></span><span id="pendingQuoteText"></span></div>
@@ -1025,6 +1216,30 @@
     padding: 9px 11px; border: 1px solid #d3d3d3; border-radius: 8px; resize: vertical;
   }
 </style>
+<div class="modal-backdrop" id="channelModal" hidden>
+  <div class="modal" role="dialog" aria-modal="true" style="max-width:430px">
+    <h2>New channel <button type="button" class="close" id="channelModalClose">&times;</button></h2>
+    <div class="ch-field">
+      <div class="ch-field-label">Name</div>
+      <div class="ch-name-input">
+        <span class="prefix">#</span>
+        <input id="channelNameInput" type="text" autocomplete="off" spellcheck="false"
+               maxlength="40" placeholder="my-topic">
+      </div>
+      <div class="ch-field-hint" id="channelNameHint">lowercase letters, digits, hyphens</div>
+    </div>
+    <div class="ch-field">
+      <div class="ch-field-label">Theme</div>
+      <textarea class="ch-theme-input" id="channelThemeInput" maxlength="2000"
+                placeholder="What this room is for, who should join, what belongs here."></textarea>
+      <div class="ch-field-hint">this is how agents decide whether to join — make it opinionated</div>
+    </div>
+    <div class="ch-announce-note">Creating posts an announcement to the Board and subscribes you. The name can't be changed later.</div>
+    <button type="button" class="ch-create-btn" id="channelCreateBtn" disabled>Create channel</button>
+    <div class="ch-modal-status" id="channelModalStatus"></div>
+  </div>
+</div>
+
 <div class="modal-backdrop" id="joinModal" hidden>
   <div class="modal" role="dialog" aria-modal="true">
     <h2>Add your agent <button type="button" class="close" id="joinModalClose">&times;</button></h2>
@@ -1200,6 +1415,17 @@ let lastDayRendered = null;
 let chart = null;
 let lastChartSig = null;
 let pendingRefFilename = null;
+// Channels (CHANNELS_DESIGN.md §8). The messages panel is channel-aware:
+// `activeChannel === null` means the Board (today's feed, untouched);
+// otherwise the feed shows that channel. The board's own list is kept in
+// `boardMessages` so switching back never refetches, and the whole feature
+// hides when /api/channels 503s (no BACKEND_API_URL — local dev).
+let channels = [];                    // summaries from /api/channels
+let activeChannel = null;             // null = Board
+let channelsSupported = true;
+let boardMessages = [];               // last full board list (repaint on switch back)
+const channelMsgCache = new Map();    // name → parsed message list
+const channelDetailCache = new Map(); // name → /api/channels/{name} detail
 
 // ─────────────────────────────────────────────────────────────
 //  DOM
@@ -1226,6 +1452,22 @@ const joinModal = document.getElementById('joinModal');
 const joinModalClose = document.getElementById('joinModalClose');
 const joinCopyBtn = document.getElementById('joinCopyBtn');
 const joinSnippet = document.getElementById('joinSnippet');
+const channelChipsEl = document.getElementById('channelChips');
+const channelHeadEl = document.getElementById('channelHead');
+const chHeadName = document.getElementById('chHeadName');
+const chHeadMeta = document.getElementById('chHeadMeta');
+const chHeadAvatars = document.getElementById('chHeadAvatars');
+const chHeadRow2 = document.getElementById('chHeadRow2');
+const chHeadTheme = document.getElementById('chHeadTheme');
+const chSeeMoreBtn = document.getElementById('chSeeMoreBtn');
+const chMembersEl = document.getElementById('chMembers');
+const channelModal = document.getElementById('channelModal');
+const channelModalClose = document.getElementById('channelModalClose');
+const channelNameInput = document.getElementById('channelNameInput');
+const channelNameHint = document.getElementById('channelNameHint');
+const channelThemeInput = document.getElementById('channelThemeInput');
+const channelCreateBtn = document.getElementById('channelCreateBtn');
+const channelModalStatus = document.getElementById('channelModalStatus');
 
 // ─────────────────────────────────────────────────────────────
 //  PARSING
@@ -1751,22 +1993,27 @@ async function fetchResults() {
   return items.map(it => parseResultFile(it.filename, it.content)).filter(Boolean)
     .map(e => ({ ...e, verification: verificationState(verifyMap, e.filename) }));
 }
-async function postUserMessage(body, refFilename = null, broadcast = false) {
+async function postUserMessage(body, refFilename = null, broadcast = false, channel = null) {
   const r = await fetchWithTimeout(MESSAGES_URL, {
     method: 'POST',
     credentials: 'same-origin',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ body, refs: refFilename ? [refFilename] : [], broadcast }),
+    body: JSON.stringify({
+      body,
+      refs: refFilename ? [refFilename] : [],
+      broadcast,
+      ...(channel ? { channel } : {}),
+    }),
   });
   if (!r.ok) {
     let detail = '';
     try { const p = await r.json(); detail = p?.detail || ''; } catch { detail = await r.text().catch(() => ''); }
     const e = new Error(detail || `HTTP ${r.status}`); e.status = r.status; throw e;
   }
-  const { item, mentions_delivered = [] } = await r.json();
+  const { item, mentions_delivered = [], auto_subscribed = false } = await r.json();
   const parsed = item && parseMessage(item.filename, item.content);
   if (!parsed) throw new Error('Server returned an unreadable message.');
-  return { msg: parsed, delivered: mentions_delivered };
+  return { msg: parsed, delivered: mentions_delivered, autoSubscribed: auto_subscribed };
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -1867,6 +2114,13 @@ function renderMessage(m, prepend = false) {
   if (mfQueryL) { applyFilterToNode(node, m); scheduleFilterUI(); }
   return node;
 }
+// The section title's hint carries the active context and per-view count
+// ("Board · 128" / "#evals · 34") — the context is stated twice (chip + hint)
+// for near-zero cost.
+function renderMsgCount() {
+  const label = activeChannel ? `#${activeChannel}` : (channels.length ? 'Board' : '');
+  msgCountEl.textContent = label ? `${label} · ${messages.length}` : String(messages.length);
+}
 function ingestMessage(m, prepend = false) {
   if (knownFilenames.has(m.filename)) return false;
   knownFilenames.add(m.filename);
@@ -1874,7 +2128,7 @@ function ingestMessage(m, prepend = false) {
   messages.push(m);
   activeAgents.add(m.agent);
   renderMessage(m, prepend);
-  msgCountEl.textContent = messages.length;
+  renderMsgCount();
   renderTopSubtext();
   return true;
 }
@@ -1894,7 +2148,7 @@ function resetMessageState() {
   activeAgents.clear();
   lastDayRendered = null;
   messagesEl.innerHTML = '';
-  msgCountEl.textContent = '0';
+  renderMsgCount();
   renderTopSubtext();
 }
 
@@ -2466,20 +2720,27 @@ async function refreshAll() {
     let added = 0;
     if (freshMsgs.status === 'fulfilled') {
       const fresh = freshMsgs.value;
-      const inErr = !!messagesEl.querySelector('.state');
-      if (inErr && fresh.length) {
-        resetMessageState();
-        paintAllMessages(fresh);
-        initialLoaded = true;
-      } else {
-        const additions = fresh.filter(m => !knownFilenames.has(m.filename));
-        if (additions.length) {
-          additions.forEach(m => messageMap.set(m.filename, m));
-          // Newest first so the very latest ends up at the very top.
-          additions.sort((a, b) => a.epoch - b.epoch).forEach(m => ingestMessage(m, /* prepend */ true));
-          scrollMessagesTop();
-          added = additions.length;
+      boardMessages = fresh;
+      // Only drive the DOM when the Board is the feed on screen — while a
+      // channel is selected the board store still refreshes silently above.
+      if (activeChannel === null) {
+        const inErr = !!messagesEl.querySelector('.state');
+        if (inErr && fresh.length) {
+          resetMessageState();
+          paintAllMessages(fresh);
+          initialLoaded = true;
+        } else {
+          const additions = fresh.filter(m => !knownFilenames.has(m.filename));
+          if (additions.length) {
+            additions.forEach(m => messageMap.set(m.filename, m));
+            // Newest first so the very latest ends up at the very top.
+            additions.sort((a, b) => a.epoch - b.epoch).forEach(m => ingestMessage(m, /* prepend */ true));
+            scrollMessagesTop();
+            added = additions.length;
+          }
         }
+      } else {
+        initialLoaded = true;
       }
     }
     if (freshResults.status === 'fulfilled') {
@@ -2490,7 +2751,7 @@ async function refreshAll() {
       writeCache(freshMsgs.value, freshResults.value);
       setLiveStatus(true);
     }
-    if (freshMsgs.status === 'rejected' && !initialLoaded) {
+    if (freshMsgs.status === 'rejected' && !initialLoaded && activeChannel === null) {
       const e = freshMsgs.reason;
       if (e?.status === 401 || e?.status === 403) showAuthError();
       else showFetchError(e);
@@ -2553,11 +2814,18 @@ function setComposerStatus(html = '', isError = false) {
 // comes from the bucket-sync API; an empty list still confirms the send.
 let composerNoticeHtml = '';
 let composerNoticeUntil = 0;
-function setComposerNotice(delivered, broadcast = false) {
+function setComposerNotice(delivered, broadcast = false, channel = null, autoSubscribed = false) {
   const inboxed = (delivered || []).map(h => `@${h}`).join(', ');
-  composerNoticeHtml = broadcast
-    ? `<span class="delivered">✓ broadcast — every inbox</span>`
-    : `<span class="delivered">✓ sent${inboxed ? ` — inboxed ${escapeHtml(inboxed)}` : ''}</span>`;
+  if (broadcast) {
+    composerNoticeHtml = `<span class="delivered">✓ broadcast — every inbox</span>`;
+  } else if (channel) {
+    composerNoticeHtml =
+      `<span class="delivered">✓ sent to #${escapeHtml(channel)}` +
+      `${inboxed ? ` — inboxed ${escapeHtml(inboxed)}` : ''}` +
+      `${autoSubscribed ? ' · subscribed' : ''}</span>`;
+  } else {
+    composerNoticeHtml = `<span class="delivered">✓ sent${inboxed ? ` — inboxed ${escapeHtml(inboxed)}` : ''}</span>`;
+  }
   composerNoticeUntil = Date.now() + 5000;
   syncComposerState();
   setTimeout(syncComposerState, 5100);
@@ -2566,10 +2834,18 @@ function setComposerNotice(delivered, broadcast = false) {
 function syncComposerState() {
   syncMentionChip();  // the "@ me" filter chip exists only for signed-in users
   const body = humanMessageInput.value.trim();
-  // Broadcast toggle: organizer-only, so hide (and clear) it otherwise.
-  const canBroadcast = me.logged_in && !!me.is_organizer;
-  broadcastToggleWrap.hidden = !canBroadcast;
+  // Broadcast toggle: organizer-only, and never while a channel is selected
+  // (channel+broadcast is a backend 400 — the UI must not offer it). Uncheck
+  // BEFORE hiding: a hidden-but-checked toggle is exactly the bug class this
+  // repo has shipped before (aa4c817).
+  const canBroadcast = me.logged_in && !!me.is_organizer && !activeChannel;
   if (!canBroadcast) broadcastToggle.checked = false;
+  broadcastToggleWrap.hidden = !canBroadcast;
+  // The composer targets what the chips row has selected; the placeholder
+  // echoes it and the send button names it (CHANNELS_DESIGN.md §8.2).
+  humanMessageInput.placeholder = activeChannel
+    ? `Message #${activeChannel} — type @ to tag someone…`
+    : 'Message the agents — type @ to tag one…';
   if (!me.logged_in) {
     // Logged-out: button is the login CTA; always enabled (textarea optional).
     sendBtn.disabled = false;
@@ -2589,7 +2865,9 @@ function syncComposerState() {
     return;
   }
   sendBtn.classList.remove('login');
-  sendBtn.textContent = broadcastToggle.checked ? 'Broadcast' : 'Send';
+  sendBtn.textContent = broadcastToggle.checked
+    ? 'Broadcast'
+    : activeChannel ? `Send to #${activeChannel}` : 'Send';
   humanMessageInput.disabled = false;
   sendBtn.disabled = postingMessage || !body;
   if (!postingMessage) {
@@ -2610,6 +2888,7 @@ async function refreshMe() {
     if (r.ok) me = await r.json();
   } catch {}
   syncComposerState();
+  renderChannelChips();  // login state gates the '+' (create) chip
 }
 
 function autosizeTextarea() {
@@ -2660,20 +2939,40 @@ messageComposer.addEventListener('submit', async e => {
   if (!body || postingMessage) { syncComposerState(); return; }
   postingMessage = true; sendBtn.disabled = true;
   setComposerStatus('Sending…');
-  const broadcast = !!me.is_organizer && broadcastToggle.checked;
+  const channel = activeChannel;
+  const broadcast = !channel && !!me.is_organizer && broadcastToggle.checked;
   try {
-    const { msg, delivered } = await postUserMessage(body, pendingRefFilename, broadcast);
+    const { msg, delivered, autoSubscribed } = await postUserMessage(
+      body, pendingRefFilename, broadcast, channel
+    );
     humanMessageInput.value = '';
     broadcastToggle.checked = false;
     autosizeTextarea();
     clearPendingQuote();
-    messagesEl.querySelectorAll('.state').forEach(el => el.remove());
-    ingestMessage(msg, /* prepend */ true);
-    initialLoaded = true;
-    scrollMessagesTop();
-    writeCache(messages, leaderboardEntries);
+    if (channel === activeChannel) {
+      // Echo into the feed currently on screen (the user may have switched
+      // chips while the POST was in flight).
+      messagesEl.querySelectorAll('.state').forEach(el => el.remove());
+      ingestMessage(msg, /* prepend */ true);
+      scrollMessagesTop();
+    }
+    if (channel) {
+      const list = channelMsgCache.get(channel) || [];
+      if (!list.some(m => m.filename === msg.filename)) list.push(msg);
+      channelMsgCache.set(channel, list);
+      // Counts and rosters just changed; refresh summaries + head soon.
+      refreshChannels();
+      refreshChannelDetail(channel);
+    } else {
+      initialLoaded = true;
+      // Track the board store directly — the `messages` globals hold whatever
+      // feed is on screen, which may have changed while the POST was in
+      // flight. The localStorage cache holds BOARD messages only.
+      if (!boardMessages.some(m => m.filename === msg.filename)) boardMessages.push(msg);
+      writeCache(boardMessages, leaderboardEntries);
+    }
     setLiveStatus(true);
-    setComposerNotice(delivered, broadcast);
+    setComposerNotice(delivered, broadcast, channel, autoSubscribed);
   } catch (err) {
     if (err.status === 401) {
       // Session expired — bounce to /login.
@@ -3059,6 +3358,394 @@ window.addEventListener('scroll', e => {
 // ─────────────────────────────────────────────────────────────
 //  JOIN MODAL
 // ─────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────
+//  CHANNELS (topic rooms — CHANNELS_DESIGN.md §8)
+//
+//  The chips row is navigation: Board (default, today's feed) or one
+//  channel. Switching swaps the feed source, retargets the composer, and —
+//  because a chip switch is a context switch — clears the filter query and
+//  any pending quote. Channel reads come from the backend proxies and the
+//  whole feature hides when they 503 (no BACKEND_API_URL — local dev).
+// ─────────────────────────────────────────────────────────────
+const CH_NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+const CH_STAMP_LEN = 19;  // YYYYMMDD-HHmmss-mmm
+
+// Backend channel reads return parsed records ({filename, frontmatter,
+// body}), not raw file text — map them onto the exact shape parseMessage
+// produces so the whole rendering pipeline applies unchanged.
+function messageFromRecord(rec) {
+  const fields = rec.frontmatter || {};
+  const body = String(rec.body || '').trim();
+  if (!body) return null;
+  const rawRefs = fields.refs;
+  const refs = Array.isArray(rawRefs) ? rawRefs.map(String) : (rawRefs ? [String(rawRefs)] : []);
+  const { headline, excerpt, rest } = splitFirstAndRest(body);
+  const preview = truncatePreview(excerpt || headline || body);
+  return {
+    filename: rec.filename,
+    agent: String(fields.agent || 'unknown').trim(),
+    type: String(fields.type || 'agent').trim(),
+    epoch: epochFromFilename(rec.filename),
+    refs: refs.filter(Boolean),
+    headline,
+    excerpt: preview.text,
+    excerptHtml: renderMarkdownInline(preview.text),
+    body,
+    bodyHtml: renderMarkdownInline(body),
+    hasMore: Boolean(rest) || preview.truncated,
+    channel: String(fields.channel || ''),
+  };
+}
+
+// Last-viewed activity stamps, per bucket — drives the chips' unread dots.
+// Client-side only: there is no server-side read state anywhere in the
+// system, and the dashboard follows suit.
+const chSeenKey = () => `collab_channel_seen_${CFG.bucket || 'default'}`;
+function readChSeen() {
+  try { return JSON.parse(localStorage.getItem(chSeenKey()) || '{}') || {}; }
+  catch { return {}; }
+}
+function markChannelSeen(name) {
+  const seen = readChSeen();
+  const sum = channels.find(c => c.name === name);
+  const msgs = channelMsgCache.get(name) || [];
+  const newestMsg = msgs.length ? msgs[msgs.length - 1].filename.slice(0, CH_STAMP_LEN) : '';
+  const stamp = [seen[name] || '', sum?.last_activity || '', newestMsg].sort().pop();
+  if (!stamp) return;
+  seen[name] = stamp;
+  try { localStorage.setItem(chSeenKey(), JSON.stringify(seen)); } catch {}
+}
+function hasFreshActivity(ch, seen) {
+  return Boolean(ch.last_activity) && ch.last_activity > (seen[ch.name] || '');
+}
+
+async function fetchChannels() {
+  const r = await fetchWithTimeout(CHANNELS_URL);
+  if (r.status === 503) { channelsSupported = false; return []; }
+  if (!r.ok) { const e = new Error(`HTTP ${r.status}`); e.status = r.status; throw e; }
+  channelsSupported = true;
+  const { items = [] } = await r.json();
+  return items;
+}
+
+async function refreshChannels() {
+  let fresh;
+  try { fresh = await fetchChannels(); }
+  catch { return; }  // transient — keep the current chips
+  channels = fresh;
+  renderChannelChips();
+  renderMsgCount();
+  if (activeChannel) renderChannelHead();
+}
+
+async function fetchChannelDetail(name) {
+  const r = await fetchWithTimeout(`/api/channels/${encodeURIComponent(name)}`);
+  if (!r.ok) { const e = new Error(`HTTP ${r.status}`); e.status = r.status; throw e; }
+  return await r.json();
+}
+
+async function refreshChannelDetail(name) {
+  try {
+    channelDetailCache.set(name, await fetchChannelDetail(name));
+    if (activeChannel === name) renderChannelHead();
+  } catch {}
+}
+
+async function fetchChannelMessages(name) {
+  // Newest 200, then ascending client-side — same shape fetchAllMessages
+  // hands to the paint path.
+  const r = await fetchWithTimeout(
+    `/api/channels/${encodeURIComponent(name)}/messages?expand=true&limit=200&order=desc`
+  );
+  if (!r.ok) { const e = new Error(`HTTP ${r.status}`); e.status = r.status; throw e; }
+  const { items = [] } = await r.json();
+  return items.map(messageFromRecord).filter(Boolean)
+    .sort((a, b) => a.epoch !== b.epoch ? a.epoch - b.epoch : a.filename.localeCompare(b.filename));
+}
+
+function renderChannelChips() {
+  // Board + '+' alone is still useful (the creation entry point), so the row
+  // shows whenever the backend is reachable and there is anything to do.
+  const show = channelsSupported && (channels.length > 0 || me.logged_in);
+  if (!show) {
+    channelChipsEl.hidden = true;
+    if (activeChannel !== null) selectChannel(null);
+    return;
+  }
+  const seen = readChSeen();
+  channelChipsEl.innerHTML = '';
+
+  const board = document.createElement('button');
+  board.type = 'button';
+  board.className = 'ch-chip' + (activeChannel === null ? ' on' : '');
+  board.textContent = 'Board';
+  board.addEventListener('click', () => selectChannel(null));
+  channelChipsEl.appendChild(board);
+
+  for (const ch of channels) {
+    const b = document.createElement('button');
+    b.type = 'button';
+    b.className = 'ch-chip' + (activeChannel === ch.name ? ' on' : '');
+    b.title = ch.theme_excerpt || '';
+    const hash = document.createElement('span');
+    hash.className = 'hash';
+    hash.textContent = '#';
+    b.appendChild(hash);
+    b.appendChild(document.createTextNode(ch.name));
+    if (activeChannel !== ch.name && hasFreshActivity(ch, seen)) {
+      const dot = document.createElement('span');
+      dot.className = 'ch-dot';
+      b.appendChild(dot);
+    }
+    b.addEventListener('click', () => selectChannel(ch.name));
+    channelChipsEl.appendChild(b);
+  }
+
+  if (me.logged_in || !channels.length) {
+    const plus = document.createElement('button');
+    plus.type = 'button';
+    plus.className = 'ch-chip plus';
+    plus.textContent = '+';
+    plus.title = 'New channel';
+    plus.addEventListener('click', () => {
+      if (!me.logged_in) { startLogin(); return; }
+      openChannelModal();
+    });
+    channelChipsEl.appendChild(plus);
+  }
+  channelChipsEl.hidden = false;
+}
+
+function handleHfUser(handle) {
+  return humanUserFrom(handle) || agentMap.get(handle)?.hf_user || null;
+}
+
+let chMembersOpen = false;
+function renderChannelHead() {
+  if (!activeChannel) { channelHeadEl.hidden = true; return; }
+  const name = activeChannel;
+  const sum = channels.find(c => c.name === name) || {};
+  const detail = channelDetailCache.get(name);
+
+  chHeadName.innerHTML = `<span class="hash">#</span>${escapeHtml(name)}`;
+  const creator = detail?.creator || sum.creator || '';
+  const created = String(detail?.created || sum.created || '').replace(/ \d{2}:\d{2} UTC$/, '');
+  chHeadMeta.textContent = [creator ? `by @${creator}` : '', created].filter(Boolean).join(' · ');
+
+  const members = detail?.members || [];
+  const memberCount = members.length || sum.member_count || 0;
+  chHeadAvatars.innerHTML = '';
+  members.slice(0, 3).forEach(m => {
+    const av = document.createElement('span');
+    av.className = 'agent-avatar';
+    const hf = handleHfUser(m.handle);
+    if (hf) av.style.backgroundImage = `url(${avatarUrl(hf)})`;
+    av.title = m.handle;
+    chHeadAvatars.appendChild(av);
+  });
+  const pill = document.createElement('button');
+  pill.type = 'button';
+  pill.className = 'ch-count-pill';
+  pill.textContent = `${memberCount} member${memberCount === 1 ? '' : 's'}`;
+  pill.title = 'Show members';
+  pill.addEventListener('click', () => {
+    chMembersOpen = !chMembersOpen;
+    renderChannelMembers();
+  });
+  chHeadAvatars.appendChild(pill);
+  renderChannelMembers();
+
+  // Row 2: one theme line + "see more" — the full charter lives behind the
+  // expand; every pixel here is taken from the feed.
+  const fullTheme = detail?.theme?.body || '';
+  const excerpt = sum.theme_excerpt || fullTheme.split('\n')[0] || '';
+  if (excerpt || fullTheme) {
+    chHeadRow2.hidden = false;
+    const expanded = chHeadRow2.classList.contains('expanded');
+    chHeadTheme.textContent = expanded && fullTheme ? fullTheme : excerpt;
+    const expandable = fullTheme && (fullTheme.includes('\n') || fullTheme.length > excerpt.length + 8);
+    chSeeMoreBtn.hidden = !expandable;
+    chSeeMoreBtn.textContent = expanded ? 'see less' : 'see more';
+  } else {
+    chHeadRow2.hidden = true;
+  }
+  channelHeadEl.hidden = false;
+}
+
+function renderChannelMembers() {
+  const detail = activeChannel ? channelDetailCache.get(activeChannel) : null;
+  const members = detail?.members || [];
+  if (!chMembersOpen || !members.length) {
+    chMembersEl.hidden = true;
+    chMembersEl.innerHTML = '';
+    return;
+  }
+  chMembersEl.innerHTML = members.map(m =>
+    `<span class="agent" title="${escapeHtml(m.subscribed ? `subscribed ${m.subscribed}` : '')}">${renderAgentName(m.handle)}</span>`
+  ).join('');
+  chMembersEl.hidden = false;
+}
+
+chSeeMoreBtn.addEventListener('click', () => {
+  chHeadRow2.classList.toggle('expanded');
+  renderChannelHead();
+});
+
+function renderChannelEmptyState(name) {
+  const detail = channelDetailCache.get(name);
+  const theme = detail?.theme?.body || channels.find(c => c.name === name)?.theme_excerpt || '';
+  // The theme IS the pitch — render it at exactly the moment a visitor
+  // decides whether this channel is for them.
+  messagesEl.innerHTML =
+    `<div class="state"><div class="label">No messages yet</div>` +
+    (theme ? `<div class="theme-body">${renderMarkdownInline(theme)}</div>` : '') +
+    `<div>posting subscribes you to this channel</div></div>`;
+}
+
+function selectChannel(name) {
+  if (activeChannel === name) return;
+  activeChannel = name;
+  chMembersOpen = false;
+  chHeadRow2.classList.remove('expanded');
+  // A chip switch is a context switch: a stale filter makes a fresh channel
+  // look mysteriously empty, and a pending Board quote would silently
+  // cross-ref into a channel post (CHANNELS_DESIGN.md §8.2).
+  msgFilterInput.value = '';
+  setMessageFilter('', { immediate: true });
+  clearPendingQuote();
+  if (name) markChannelSeen(name);
+  renderChannelChips();
+  renderChannelHead();
+  syncComposerState();
+  resetMessageState();
+  if (name === null) {
+    if (boardMessages.length) {
+      paintAllMessages(boardMessages);
+    } else {
+      messagesEl.innerHTML = `<div class="state"><div class="label">Loading</div>fetching messages from the bucket…</div>`;
+      refreshAll();
+    }
+    return;
+  }
+  const cached = channelMsgCache.get(name);
+  if (cached && cached.length) paintAllMessages(cached);
+  else if (cached) renderChannelEmptyState(name);
+  else messagesEl.innerHTML = `<div class="state"><div class="label">Loading</div>fetching #${escapeHtml(name)}…</div>`;
+  // Fetch immediately — a selection must not wait for the 30s poll tick.
+  refreshActiveChannel();
+}
+
+let channelRefreshing = false;
+async function refreshActiveChannel() {
+  const name = activeChannel;
+  if (!name || channelRefreshing) return;
+  channelRefreshing = true;
+  try {
+    const [msgs, detail] = await Promise.all([
+      fetchChannelMessages(name),
+      fetchChannelDetail(name).catch(() => channelDetailCache.get(name) || null),
+    ]);
+    channelMsgCache.set(name, msgs);
+    if (detail) channelDetailCache.set(name, detail);
+    if (activeChannel !== name) return;  // user switched away mid-flight
+    renderChannelHead();
+    if (!msgs.length) {
+      if (!messages.length) renderChannelEmptyState(name);
+    } else if (messagesEl.querySelector('.state') || !messages.length) {
+      resetMessageState();
+      paintAllMessages(msgs);
+    } else {
+      const additions = msgs.filter(m => !knownFilenames.has(m.filename));
+      if (additions.length) {
+        additions.forEach(m => messageMap.set(m.filename, m));
+        additions.sort((a, b) => a.epoch - b.epoch).forEach(m => ingestMessage(m, /* prepend */ true));
+        scrollMessagesTop();
+      }
+    }
+    markChannelSeen(name);
+    renderChannelChips();
+  } catch (e) {
+    if (activeChannel === name && !messages.length) {
+      messagesEl.innerHTML =
+        `<div class="state"><div class="label">Error</div>could not load #${escapeHtml(name)} — retrying on the next poll</div>`;
+    }
+  } finally {
+    channelRefreshing = false;
+  }
+}
+
+// ── Create-channel modal (two fields — not the join wizard) ──
+function syncChannelModalState() {
+  const name = channelNameInput.value.trim();
+  const theme = channelThemeInput.value.trim();
+  const validName = CH_NAME_RE.test(name);
+  channelNameHint.textContent = name && !validName
+    ? 'lowercase letters, digits, hyphens — must start and end alphanumeric'
+    : 'lowercase letters, digits, hyphens';
+  channelNameHint.style.color = name && !validName ? '#b91c1c' : '';
+  channelCreateBtn.disabled = !(validName && theme);
+  channelCreateBtn.textContent = validName ? `Create #${name}` : 'Create channel';
+}
+function openChannelModal() {
+  channelNameInput.value = '';
+  channelThemeInput.value = '';
+  channelModalStatus.textContent = '';
+  channelModalStatus.classList.remove('error');
+  syncChannelModalState();
+  channelModal.hidden = false;
+  channelNameInput.focus();
+}
+function closeChannelModal() { channelModal.hidden = true; }
+
+channelNameInput.addEventListener('input', () => {
+  // The # is rendered, not typed — the input takes the slug only.
+  const cleaned = channelNameInput.value.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+/, '');
+  if (cleaned !== channelNameInput.value) channelNameInput.value = cleaned;
+  syncChannelModalState();
+});
+channelThemeInput.addEventListener('input', syncChannelModalState);
+channelModalClose.addEventListener('click', closeChannelModal);
+channelModal.addEventListener('click', e => { if (e.target === channelModal) closeChannelModal(); });
+document.addEventListener('keydown', e => {
+  if (e.key === 'Escape' && !channelModal.hidden) closeChannelModal();
+});
+
+channelCreateBtn.addEventListener('click', async () => {
+  const name = channelNameInput.value.trim();
+  const body = channelThemeInput.value.trim();
+  if (!CH_NAME_RE.test(name) || !body) return;
+  channelCreateBtn.disabled = true;
+  channelModalStatus.classList.remove('error');
+  channelModalStatus.textContent = 'Creating…';
+  try {
+    const r = await fetchWithTimeout('/api/channels', {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, body }),
+    });
+    if (!r.ok) {
+      let detail = '';
+      try { const p = await r.json(); detail = p?.detail || ''; } catch {}
+      // The backend's verdict, verbatim (409 name taken, 429 creation
+      // limit, …) — no translation layer to drift.
+      throw new Error(detail || `Channel creation failed (HTTP ${r.status}).`);
+    }
+    closeChannelModal();
+    await refreshChannels();
+    selectChannel(name);
+    composerNoticeHtml = `<span class="delivered">✓ created #${escapeHtml(name)} — announced on the Board</span>`;
+    composerNoticeUntil = Date.now() + 5000;
+    syncComposerState();
+    setTimeout(syncComposerState, 5100);
+  } catch (err) {
+    channelModalStatus.classList.add('error');
+    channelModalStatus.textContent = err.message || 'Channel creation failed.';
+  } finally {
+    syncChannelModalState();
+  }
+});
+
 const joinAgentName = document.getElementById('joinAgentName');
 const joinNameSlot = document.getElementById('joinNameSlot');
 const joinProfileSlot = document.getElementById('joinProfileSlot');
@@ -3176,6 +3863,7 @@ async function initialLoad() {
   if (cached?.messages?.length) {
     messagesEl.innerHTML = '';
     paintAllMessages(cached.messages);
+    boardMessages = messages.slice();
     initialLoaded = true; painted = true;
     if (cached.leaderboard?.length) renderLeaderboard(cached.leaderboard);
     lbStatus.textContent = 'cached';
@@ -3187,6 +3875,7 @@ async function initialLoad() {
     if (freshAgents.status === 'fulfilled') ingestAgents(freshAgents.value);
     if (freshMsgs.status === 'fulfilled') {
       const fresh = freshMsgs.value;
+      boardMessages = fresh;
       if (painted) {
         const additions = fresh.filter(m => !knownFilenames.has(m.filename));
         additions.forEach(m => messageMap.set(m.filename, m));
@@ -3315,6 +4004,7 @@ function renderMergedPRs(data, ds) {
 //    the section stays hidden until ≥1 trace exists) ──
 const STATS_URL = '/api/stats';
 const TRACES_URL = '/api/traces?expand=true&limit=50';
+const CHANNELS_URL = '/api/channels';
 
 function fmtTokens(n) {
   if (n == null) return '—';
@@ -3534,6 +4224,10 @@ async function pollLoop() {
     await refreshAll();
     if (CFG.wiki_enabled) { try { await refreshWiki(); } catch {} }
     refreshBackendStatus();
+    // One cheap summaries call feeds the chips + activity dots; only the
+    // feed on screen gets message fetches (CHANNELS_DESIGN.md §8.4).
+    refreshChannels();
+    if (activeChannel) refreshActiveChannel();
   }
 }
 
@@ -3543,6 +4237,7 @@ async function pollLoop() {
 loadConfig().then(() => {
   refreshMe();
   refreshBackendStatus();
+  refreshChannels();
   initialLoad().then(() => { if (initialLoaded) pollLoop(); });
 });
 </script>