T-HUB/docs/user-guide.md

Tactical Media Broadcast Hub — User Guide

Post, schedule, monitor, and amplify across your social platforms from one dark, keyboard-friendly console. Admin setup help: admin-guide.md.

---

1. Getting started (onboarding)

The 3-step wizard (Onboarding screen):

1. Name your workspace — the tenant boundary for accounts, drafts, and the audit trail.
2. Invite your team — comma-separated emails; roles are assigned after they accept.
3. Connect your first accounts — pick platforms and Connect.

Only OAuth tokens (or bot tokens, for Telegram) are ever stored — the system never asks for or keeps platform passwords. Tokens live encrypted in the workspace vault; you can rotate or revoke them any time.

2. Streams — your monitoring console

The Streams screen is TweetDeck-style columns:

• Columns track a feed per platform (Home, Mentions, saved searches). (Configurable per-column subscriptions — accounts, lists, search terms — arrive with the archive/grabber update.)
• Cards show author, age, text, and engagement. Hover or navigate to a card and its amplify bar appears.
• Amplify buttons are honest: each platform's API is different, so each column shows only what that platform truly supports. Mastodon: Boost and Quote. Telegram: Forward. Some platforms show "no amplify — this platform's API exposes no reshare action". That's not a bug; it's us not pretending.

Keyboard first

Key	Action
j / ↓	next item
k / ↑	previous item
r	repost/boost the selected item
q	quote the selected item (opens composer popover with char limit)
Esc	close popover
⌘K / Ctrl+K	command palette — jump anywhere, quick actions

3. Compose — write once, adapt everywhere

• Rich editor with markdown shortcuts; per-platform character counters — add targets (Mastodon, Telegram, Facebook, Instagram) and the limit shown is the tightest one; each preview pane shows its own count and turns red when over.
• Visibility (public / followers / private), approval state (draft / submit for review / approved), and scheduling (date-time) per post.
• Right pane previews each target platform.

4. The approval flow

If your workspace uses approvals: write → Submit for review → an Approver gets it in Approvals → Grant (or reject with comments) → schedule or publish. Every step is permission-checked and lands in the audit trail. (Permissions are set by your workspace admin — see the roles table in the admin guide.)

5. Inbox — DMs and conversations

All direct-message conversations across connected accounts in one list (unread badges, assignees). Open a thread, reply inline. Note the honesty footer: messaging APIs allow replies within each platform's message window (e.g., 24h for Meta platforms); outside it, options narrow — we show you exactly what's possible rather than failing silently.

6. Channels — your connected accounts

Each account card shows: platform, handle, capability chips (what this connection can do), and health. A token expiring badge means reconnect soon. The "Connect" flow for new accounts is OAuth — you authenticate on the platform's own page; we only ever receive a token.

7. Team — members, roles, assets

• Members: change roles from the 10 seeded roles (Owner, Admin, Publisher, Editor, Approver, Analyst, Moderator, VideoPublisher, StreamOperator, BroadcastOperator). Removing a member takes effect immediately — their live sessions fail closed.
• Asset library: shared media grouped by collection (Brand, Launch, PR…). Items marked group-locked are scoped to a group; members outside it see the lock, not the file.

8. Audit trail — who did what

Every meaningful action (post published, role changed, connection added, credential rotated, approval granted…) is recorded in a tamper-evident hash chain. Filter by actor or action; click a row to open the diff viewer — what changed, field by field, with removed/added values. Secret values always show as [REDACTED]: keys and tokens are never written into the audit log, by construction. Export to CSV for compliance.

9. What's real vs. coming

Now (Level 1): monitoring streams, compose with previews, approvals, scheduling, publishing pipeline, encrypted credential vault, audit trail. (The screens currently run on representative sample data while the backend wiring lands.)

Coming:

• Archive & Grabber — your search subscriptions run server-side; every matching post is archived with media downloaded (encrypted, deduplicated) and searchable; videos included.
• Crosspost — one action moves content across platforms with your commentary (an Instagram image quoted into Mastodon, a Mastodon video into Facebook), flowing through approvals.
• Level 2 — video uploads, livestreams, the Virtual Channel / Auto Director master-control system, and the operator Control Room.

10. FAQ

Why can't I retweet on some columns? That platform's API doesn't expose resharing. We render only real capabilities.

Why did everyone get logged out after a role change? Security: authorization epochs bump and stale sessions fail closed. One re-login.

Where are my passwords? Nowhere. We store tokens only, envelope-encrypted. If you want to cut access, revoke the connection in-app or on the platform.

Who can see my stream keys / tokens? Nobody through the UI — not even workspace Owners; they're redacted from every screen, log, and audit entry by construction.