mengyastore/.claude/skills/trellis-channel/references/forum.md

Forum Channels

Forum channels are durable, topic-style channels. They are created with --type forum at channel-creation time and are immutable after that. They are not normal chat streams: the default read path is forum summary -> one thread timeline -> current context.

Forum vs Regular Channel

A channel's type is set with --type on channel create and never changes:

• chat (default) — flat message timeline. channel messages always renders the event stream. Forum-only flags such as --thread and --action are rejected here.
• forum — thread-oriented. channel messages without filters renders a thread-board summary instead of raw events. The post, forum, thread, and thread rename subcommands only apply to forum channels.

Both types share the same scope model (--scope project is the default; --scope global puts the channel in the cross-project bucket).

Create A Forum Channel

trellis channel create design-feedback \
  --type forum \
  --scope global \
  --description "Cross-project design feedback board." \
  --context-raw "One thread per design topic; close when resolved." \
  --by main

Use --scope project for a board scoped to one repo, --scope global for a cross-project board.

Threads: Open, Comment, Status, Summary

Threads live inside a forum channel. Each thread is identified by a stable --thread <key> (lowercase kebab-case is conventional). The first action on a thread is opened; everything afterwards uses the same --thread key.

trellis channel post design-feedback opened \
  --scope global \
  --as main \
  --thread login-empty-state \
  --title "Empty state on the login screen" \
  --description "Track design feedback for the new login empty state." \
  --labels design,login \
  --context-raw "Spotted during the 0.4 release review." \
  --text-file /tmp/thread-open.md

trellis channel post design-feedback comment \
  --scope global \
  --as reviewer \
  --thread login-empty-state \
  --text-file /tmp/review.md

trellis channel post design-feedback status \
  --scope global \
  --as main \
  --thread login-empty-state \
  --status closed

trellis channel post design-feedback summary \
  --scope global \
  --as main \
  --thread login-empty-state \
  --summary "Adopted the option-B layout; ticket TRELLIS-123 owns the fix."

Key distinctions:

• --description is the durable thread description (the answer to "what is this thread about?"). It is set on opened and edited by re-running post with --description.
• --text / --stdin / --text-file is the event body — the comment or payload attached to this specific timeline entry.
• --labels and --assignees are CSV and replace the current value; they do not append.
• --summary is the rolling thread summary. Setting it on status closed is the standard way to mark a thread resolved with context.

--thread is required for every action except opened (where it is also required in practice — there is no anonymous thread).

Read A Forum

trellis channel messages design-feedback --scope global
trellis channel forum design-feedback --scope global --status open
trellis channel thread design-feedback login-empty-state --scope global
trellis channel messages design-feedback --scope global --raw --thread login-empty-state

If a peer says "I commented on the forum", run channel forum first to see which thread changed, then drill into that thread with channel thread <name> <thread>. Do not jump straight to ad-hoc events.jsonl parsing.

Context

Context entries are durable background that should always be in scope when reading a channel or a thread. They are not timeline events; they are projected separately and replayed for every reader.

Use the context subcommands. The legacy --linked-context-file / --linked-context-raw flags on create and post are deprecated aliases that fold into the canonical --context-file / --context-raw.

Add Context

# Channel-level context (whole forum)
trellis channel context add design-feedback \
  --scope global \
  --raw "Upstream feedback board; please link tasks before opening threads."

# Thread-level context (one thread)
trellis channel context add design-feedback \
  --scope global \
  --thread login-empty-state \
  --file "$PWD/.trellis/tasks/05-13-login-redesign/design.md"

• --thread <key> switches between channel-level and thread-level context.
• --file paths must be absolute; relative paths are rejected.
• --raw is plain text inline content.
• Both flags are repeatable; at least one is required for add / delete.
• --as <agent> records authorship; defaults to main.

List Context

trellis channel context list design-feedback --scope global
trellis channel context list design-feedback --scope global --thread login-empty-state --raw

--raw on list emits one JSON entry per line (useful for piping); without it you get a human-readable file <path> / raw <truncated text> listing. An empty store prints (no context).

Delete Context

trellis channel context delete design-feedback \
  --scope global \
  --thread login-empty-state \
  --raw "stale note"

You delete by value, not by id: pass the same --file or --raw value that was added. Repeat the flag to delete multiple entries in one call.

Reading Order

When reading a thread, work top-down:

1. Thread description (the durable "what is this about").
2. Context entries (channel-level + thread-level).
3. Timeline (opened, comment, status, summary).

If a context file is missing or unreadable, state that explicitly and continue with the remaining data — do not fabricate the content.

Title Projection

title projects a stable display title onto the channel without renaming the storage address. The channel name you pass to every command stays the same.

trellis channel title set design-feedback \
  --scope global \
  --title "Design feedback board"

trellis channel title clear design-feedback --scope global

• title set requires --title.
• --as <agent> records authorship; defaults to main.
• This is a presentation-layer change. Tooling and scripts keep using the original channel name.

Thread Rename

thread rename is the correction path when a thread was opened with the wrong key (typo, wrong slug convention, etc.). Threads do not support hard deletion — rename is the supported corrective action.

trellis channel thread rename design-feedback old-key new-key \
  --scope global \
  --as main

• --as <agent> is required.
• post <name> rename is rejected — you must use thread rename.

Deletion Discipline

Do not model single-comment deletion or hard thread deletion as normal workflow. Forum threads are append-only collaboration history. To correct state, use:

• post ... status to mark a thread closed / blocked / etc.
• post ... summary to record the resolution.
• post ... --labels to re-label (replaces the set).
• thread rename to correct a bad thread key.

Internal Changelog Pattern

A common use of a global forum channel is an internal release / runtime changelog. One thread per notable change keeps history searchable:

trellis channel create release-notes \
  --type forum \
  --scope global \
  --description "Internal release and runtime changelog." \
  --context-raw "One thread per notable change; close when shipped." \
  --by main

trellis channel post release-notes opened \
  --scope global \
  --as main \
  --thread release-2026-q1 \
  --title "Channel threads and forum UX in 0.6" \
  --description "Forum channel UX shipped in the 0.6 line." \
  --labels channel,release \
  --text-file /tmp/release-notes.md

Use stable, descriptive thread keys (e.g. release-2026-q1, runtime-event-schema-change) so later readers can find them by name.