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](./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.