@crievo/omni 0.0.0-stage → 0.1.1

package/studio/shared/types/api.ts

@@ -0,0 +1,1290 @@
+/* What the studio API returns (api/services/*.ts), shared by api/routes and web/. */
+
+import type { NavigateArgs } from "../omni-screens";
+
+/* voice-pause.json: voice swapped from the UI and being chosen; what comes after waits for "Seguir" */
+export type VoicePause = {
+  since: string;
+  lines: string[];
+  interrupted: string[];
+  claude_stopped: boolean;
+  removed?: string[];
+};
+
+export type StatusStage = {
+  id: string;
+  number: string;
+  name: string;
+  ok: boolean;
+  detail: string | null;
+  stale?: string[];
+  outdated?: boolean;
+  /* export: what changed after the export (captions, scenes, motion, voice) */
+  changed?: string[];
+  pause?: VoicePause | null;
+};
+
+export type PipelineStatus = {
+  video: string;
+  stages: StatusStage[];
+  next: { id: string; name: string } | null;
+  ready: boolean;
+  total_duration: number | null;
+  scenes: number;
+  lines: number;
+  warnings: string[];
+};
+
+/* reference swap requested from the UI (motion/reference-swap.json) */
+export type ReferenceSwap = {
+  from: string[];
+  to: string | null;
+  note: string | null;
+  requested_at: string;
+  applied: boolean;
+};
+
+/* approval of the motion script scenes (tools/approval.mjs, motion/approval.json)
+   and of the content script (script-approval.json, one item only: "script") */
+export type ApprovalItem = {
+  state: "pending" | "approved" | "change_requested";
+  comment: string;
+  at: string | null;
+  by: "user" | "auto" | "literal" | null;
+  edited?: boolean;
+};
+export type ApprovalRound = {
+  round: number;
+  opened_at: string;
+  deadline: string;
+  /* paused: the user is editing a change request; what is left is in remaining_ms */
+  mode: "auto" | "paused";
+  paused_at: string | null;
+  remaining_ms: number | null;
+  completed_at: string | null;
+  status: "pending" | "change_requested" | "approved";
+  pending_count: number;
+  change_requests: { id: string; comment: string }[];
+  auto_count: number;
+};
+export type ScenesApproval = ApprovalRound & { scenes: Record<string, ApprovalItem> };
+/* an edit made in the UI writes script.md and approves: `edited` on the item */
+export type ScriptApproval = ApprovalRound & { items: { script: ApprovalItem } };
+
+/* --- queue ----------------------------------------------------------------------- */
+export type TicketState = "waiting" | "running" | "ok" | "error" | "interrupted";
+
+export type Ticket = {
+  id: string;
+  tool: string;
+  video: string | null;
+  dir: string | null;
+  command: string;
+  pid: number;
+  origin: string;
+  session: string | null;
+  state: TicketState;
+  effective: TicketState;
+  arrived_at: string;
+  started_at: string | null;
+  ended_at: string | null;
+  exit_code: number | null;
+};
+
+export type Queue = { running: Ticket[]; waiting: Ticket[]; recent: Ticket[] };
+
+/* --- video summary / detail -------------------------------------------------------- */
+export type VideoFormat = { aspect: string; w: number; h: number; fps: number };
+
+export type FileEntry = { path: string; size: number; mtime: number };
+
+/* a content's Instagram carousel (api/services/carousel.ts, tools/carousel.mjs) */
+export type Deliverable = "video" | "carousel";
+export type CarouselStage = {
+  id: "script" | "composition" | "export" | "publish";
+  name: string;
+  ok: boolean;
+  missing: string | null;
+};
+export type CarouselPublication = {
+  caption?: string;
+  instagram?: {
+    id?: string;
+    url?: string | null;
+    published_at?: string;
+    slides?: number;
+    last_error?: { at: string; message: string };
+  };
+};
+export type CarouselSummary = {
+  title: string | null;
+  format: { ratio: string; w: number; h: number } | null;
+  slides: number;
+  stages: CarouselStage[];
+  warnings: string[];
+  next: string | null;
+  cover: FileEntry | null;
+  publication: CarouselPublication | null;
+  error?: string;
+};
+export type CarouselSlide = {
+  id: string;
+  role: "cover" | "content" | "payoff" | "cta" | null;
+  title: string | null;
+  text: string | null;
+  hero: string | null;
+  png: FileEntry | null;
+  warnings: string[];
+  generated_at: string | null;
+};
+export type CarouselDetail = CarouselSummary & {
+  goal: string | null;
+  caption: string;
+  origin: "script" | "video" | null;
+  references: string[];
+  slide_list: CarouselSlide[];
+  sheet: FileEntry | null;
+  export: { at: string; jpgs: FileEntry[] } | null;
+  texts: { script: string | null; composition: string | null };
+};
+
+/* the queue tasks of this video (server summary) */
+export type VideoTasks = { running: Ticket[]; waiting: (Ticket & { position: number })[] };
+
+export type VideoSummary = {
+  slug: string;
+  dir: string;
+  /* what the content delivers: video, carousel or both */
+  deliverables: Deliverable[];
+  /* false: "Sem narração e voz" (no spoken script, narration, voice or captions) */
+  narration: boolean;
+  carousel: CarouselSummary | null;
+  title: string;
+  format: VideoFormat | null;
+  status: PipelineStatus | null;
+  statusError: string | null;
+  scenes_approval: ScenesApproval | null;
+  script_approval: ScriptApproval | null;
+  reference_swap: ReferenceSwap | null;
+  tasks?: VideoTasks;
+  cover: FileEntry | null;
+  /* thumbnail/thumbnail.png, when one is selected (the publication cover) */
+  thumbnail: FileEntry | null;
+  created: number;
+  updated: number;
+  publication: Publication | null;
+  /* when it was archived; null = in the work list */
+  archived: string | null;
+};
+
+export type Clip = { from: number; to: number; offset?: number };
+export type Word = { w: string; s: number; e: number };
+
+export type Line = {
+  id: string;
+  text: string;
+  wav?: string;
+  dur?: number;
+  start?: number;
+  end?: number;
+  provider?: string;
+  provider_requested?: string;
+  /* the voice (profile) id that spoke the line */
+  voice_profile?: string;
+  /* the line has its own provider (chosen next to "Gerar outra fala"): the video's does not change it */
+  provider_pinned?: boolean;
+  instruct?: string | null;
+  clips?: Clip[];
+  words?: Word[];
+};
+
+/* one effect in scenes.json (tools/sound.mjs) */
+export type SoundCue =
+  | string
+  | {
+      name: string;
+      offset?: number;
+      db?: number;
+      anchor?: "peak" | "start";
+      trim?: [number, number | null];
+      fade?: [number, number];
+      dur?: number;
+      speed?: number;
+      pitch?: number;
+      duck?: number | false;
+    };
+
+export type Beat = {
+  element: string;
+  t?: number;
+  enters_with?: string;
+  sound?: SoundCue | SoundCue[];
+};
+
+export type Scene = {
+  id: string;
+  title?: string;
+  goal?: string;
+  visual?: string;
+  hero?: string;
+  min_duration?: number;
+  duration?: number;
+  start?: number;
+  html?: string;
+  mp4?: string;
+  transition?: "cut" | { continues?: string[]; sound?: SoundCue | SoundCue[] };
+  beats?: Beat[];
+  lines?: Line[];
+  lead_in?: number;
+  clips?: Clip[];
+  /* legacy */
+  video_offset?: number;
+};
+
+export type HistoryVersion = {
+  stage: string;
+  key: string | null;
+  at: string;
+  files: FileEntry[];
+  data: Record<string, any>;
+};
+
+/* scenes.json, whole */
+export type ScenesFile = {
+  title?: string;
+  format?: VideoFormat;
+  references?: string[];
+  scenes: Scene[];
+  total_duration?: number;
+  voice?: { provider?: string; voice_profile?: string };
+  captions?: Record<string, unknown>;
+  captions_in_motion?: boolean;
+  bed?: unknown;
+  cuts?: unknown;
+};
+
+export type ResolvedTiming = {
+  provisional: boolean;
+  total_duration: number;
+  scenes: {
+    id: string;
+    start: number;
+    duration: number;
+    beats: { element: string; t?: number; error?: string }[];
+    lines: { id: string; start: number; end: number }[];
+  }[];
+};
+
+export type ThumbnailRequest = {
+  random: { at: string } | null;
+  manual: { at: string; instruction: string } | null;
+  changes: Record<string, { at: string; instruction: string }>;
+};
+
+export type SoundPlan = {
+  items: {
+    id: string;
+    scene: string;
+    element: string;
+    name: string;
+    start: number;
+    peak: number;
+    gain_db: number;
+    duration?: number;
+    anchor?: "peak" | "start";
+  }[];
+  bed?: { name: string; start: number; duration: number; gain_db: number; duck_db: number } | null;
+  voice_lufs?: number;
+  warnings: string[];
+};
+
+/* --- sound timeline (GET /videos/:slug/sound, api/services/sound.ts getSoundData) ---------- */
+
+/* one layer of a place's sound, as the timeline edits it (SoundCue's object form) */
+export type SoundLayer = {
+  name: string;
+  anchor?: "peak" | "start";
+  offset?: number;
+  db?: number;
+  trim?: [number, number | null];
+  fade?: [number, number];
+  dur?: number;
+  speed?: number;
+  pitch?: number;
+  duck?: number | false;
+};
+/* a beat or a scene transition that can carry sounds; `instant` in voice time */
+export type SoundPlace = {
+  type: "beat" | "transition";
+  scene: string;
+  element: string;
+  instant: number | null;
+  error?: string | null;
+  sounds: SoundLayer[];
+};
+/* the video's background music (bed) */
+export type SoundBed = {
+  name: string;
+  db?: number;
+  from?: number;
+  to?: number;
+  trim?: [number, number | null];
+  fade?: [number, number];
+  loop?: boolean;
+  duck?: number | false;
+  /* 0.5–2: the music alone, faster or slower, its pitch kept (the export speed never touches it) */
+  speed?: number;
+} | null;
+/* an area cut (tools/cuts.mjs), in scenes.json time */
+export type SoundCut = { from: number; to: number };
+/* a sound of the kit or of the video's sfx/ */
+export type SoundEffectInfo = {
+  name: string;
+  origin: "kit" | "video";
+  role: string | null;
+  title: string;
+  music: boolean;
+  duration: number;
+  peak_s: number | null;
+  useful_end_s: number | null;
+  volume_lufs: number | null;
+};
+/* clips (tools/soundtrack.mjs): pieces of a scene's MP4 or of a line's WAV, `from`/`to` in the file and
+   `offset` how far the piece moves; `scene_clips` { <scene>: clips } and `line_clips` { <line>: clips } */
+/* `speed` (0.5–2, absent = 1): the piece plays faster and lasts (to − from) / speed (tools/soundtrack.mjs) */
+export type SoundClip = { from: number; to: number; offset: number; speed?: number };
+export type SoundCatalog = {
+  kit: SoundEffectInfo[];
+  video: SoundEffectInfo[];
+  roles: Record<string, { db: number; stretchable?: boolean }>;
+  level_db: number;
+  ducking: { db: number };
+  bed: { level_db: number; ducking_db: number; fade: [number, number] };
+};
+export type SoundData = {
+  total: number;
+  provisional: boolean;
+  format: { w: number; h: number; fps: number };
+  scenes: {
+    id: string;
+    title: string | null;
+    start: number;
+    duration: number;
+    clips: SoundClip[];
+    mp4: { path: string; mtime: number } | null;
+  }[];
+  lines: {
+    id: string;
+    scene: string;
+    start: number;
+    end: number;
+    dur: number;
+    clips: SoundClip[];
+    wav: string | null;
+    text: string;
+  }[];
+  places: SoundPlace[];
+  bed: SoundBed;
+  cuts: SoundCut[];
+  /* the export speed, 1 to 1.5: picture, voice and effects; never the bed */
+  speed: number;
+  catalog: SoundCatalog;
+  export: { path: string; mtime: number; cuts: SoundCut[]; scene_clips: Record<string, SoundClip[] | number> } | null;
+  /* the export at the chosen speed (export/<slug>-speed-<pct>.mp4), when there is one */
+  speed_export: { path: string; mtime: number; speed: number } | null;
+  export_outdated: boolean;
+  error?: string;
+};
+/* one effect of a draft's plan (POST /videos/:slug/sound/plan, tools/sound.mjs) */
+export type SoundPlanItem = {
+  id: string;
+  group: string;
+  type: "beat" | "transition";
+  layer: number;
+  scene: string;
+  element: string;
+  name: string;
+  url: string;
+  start: number;
+  duration: number;
+  peak: number;
+  beat: number;
+  anchor: string;
+  gain_db: number;
+  volume_lufs: number;
+  duck_db: number;
+  role: string | null;
+  origin: string;
+};
+export type SoundBedItem = {
+  name: string;
+  url: string;
+  start: number;
+  duration: number;
+  gain_db: number;
+  duck_db: number;
+};
+/* a draft's plan: the ready WAVs, the warnings, the voice level and the ducking spans */
+export type SoundDraftPlan = {
+  items: SoundPlanItem[];
+  bed: SoundBedItem | null;
+  warnings: string[];
+  voice: { lufs: number; measured: boolean };
+  ducking: { db: number; segments: [number, number][] };
+};
+/* the timeline's whole edit: what plan and save receive */
+export type SoundDraft = {
+  places: SoundPlace[];
+  bed: SoundBed;
+  cuts: SoundCut[];
+  speed: number;
+  scene_clips: Record<string, SoundClip[]>;
+  line_clips: Record<string, SoundClip[]>;
+};
+
+export type VideoDetail = VideoSummary & {
+  root: string;
+  history: HistoryVersion[];
+  runs: Ticket[];
+  scenes: ScenesFile | null;
+  resolved: ResolvedTiming | null;
+  resolvedError: string | null;
+  texts: { script: string | null; motion: string | null; brief: string | null; captions: string | null };
+  files: FileEntry[];
+  premiere: Record<string, any> | null;
+  assembly: Record<string, any> | null;
+  thumbnail: ThumbnailManifest | null;
+  thumbnailRequest: ThumbnailRequest | null;
+  sound: SoundPlan | null;
+  renders: Record<string, { start: number; duration: number; video_time: boolean } | null>;
+  carousel: CarouselDetail | null;
+};
+
+/* thumbnail/thumbnail.json (tools/thumbnail.mjs): the three random ones (v1–v3), the
+   user-instructed one (v4) and the one the user picked */
+export type ThumbnailManifest = {
+  format: { aspect: string; w: number; h: number };
+  generated_at: string;
+  versions: {
+    id: string;
+    name: string;
+    description: string | null;
+    html: string;
+    png: string;
+    generated_at?: string;
+    instruction?: string | null;
+    change?: { at: string; instruction: string };
+  }[];
+  selected: string | null;
+  selected_at?: string;
+};
+
+/* --- publication / schedule / accounts ----------------------------------------------- */
+/* publication.json (tools/publish.mjs): the text and the result per platform */
+export type PlatformPublication = {
+  id?: string;
+  url?: string | null;
+  studio?: string;
+  privacy?: string | null;
+  /* TikTok in draft mode: went to the app inbox */
+  draft?: boolean;
+  published_at?: string;
+  mp4?: string;
+  mp4_mtime?: number;
+  /* published by the scheduler: the time it was set for */
+  scheduled_for?: string;
+  /* the selected thumbnail used as cover (YouTube and Instagram) */
+  cover?: { version: string; applied: boolean; error?: string };
+  last_error?: { at: string; message: string };
+};
+/* `publish.mjs schedule`: the request kept for the day and time; leaves the file once published */
+export type ScheduledPost = {
+  when: string;
+  platforms: string[];
+  privacy: string;
+  tiktok_privacy: string;
+  republish?: boolean;
+  state: "scheduled" | "publishing" | "failed" | "missed";
+  attempts: number;
+  created_at?: string;
+  origin?: string;
+  started_at?: string;
+  pid?: number;
+  next_attempt?: string;
+  rescheduled_at?: string;
+  last_error?: { at: string; message: string };
+};
+export type LaunchdAgent = {
+  installed: boolean;
+  loaded: boolean;
+  node_ok: boolean;
+  log: string;
+  /* omnichat only: the cloud answers instead of the agent (omnichat.cloud.owns) */
+  cloud?: CloudHealth;
+};
+export type CloudHealth =
+  | {
+      owns: true;
+      ready: true;
+      active: boolean;
+      expires: string | null;
+      pause: { until: string; reason: string } | null;
+    }
+  | { owns: true; ready: false; reason: string };
+/* GET /api/publish/schedule: `publish.mjs scheduler --json` */
+export type Schedule = {
+  error?: string;
+  agent?: LaunchdAgent;
+  items?: (ScheduledPost & { slug: string; dir: string })[];
+};
+export type Publication = {
+  title?: string;
+  description?: string;
+  /* the same on Instagram and TikTok; caption_instagram is the old name */
+  caption?: string;
+  caption_instagram?: string;
+  tags?: string[];
+  text_generated?: { at: string; by: "claude" | "script" };
+  youtube?: PlatformPublication;
+  instagram?: PlatformPublication;
+  tiktok?: PlatformPublication;
+  schedule?: ScheduledPost;
+};
+/* GET /api/publish/accounts: `publish.mjs status --json` */
+/* the connected account: `account` is the text line; username (@), name and avatar go to the card */
+export type PlatformAccount = {
+  ready: boolean;
+  account?: string;
+  username?: string | null;
+  name?: string | null;
+  avatar?: string | null;
+  reason?: string;
+};
+export type PlatformAccounts = {
+  error?: string;
+  youtube?: PlatformAccount & { privacy?: string; audited?: boolean };
+  instagram?: PlatformAccount & { expires?: string | null };
+  tiktok?: PlatformAccount & { expires?: string | null; mode?: string; privacy?: string; audited?: boolean };
+  auto?: { approved: boolean; platforms: string[] };
+  scheduler?: LaunchdAgent;
+};
+
+/* --- omnichat on Instagram (tools/omnichat.mjs, api/services/omnichat.ts) ------------------ */
+/* <dir>/omnichat.json, key instagram: the rule. Born disabled */
+export type OmnichatRule = {
+  enabled: boolean;
+  keywords: string[];
+  /* any comment triggers */
+  any_comment: boolean;
+  link: string;
+  /* {username} and {link} are replaced; without {link}, it goes at the end */
+  dm: string;
+  /* one drawn per comment; empty = DM only; without the key, the config ones */
+  public_replies?: string[];
+  /* comment the account already answered by hand: skip, or send anyway (only if the
+     account's reply contains one of already_replied_if, when set) */
+  already_replied?: "skip" | "send";
+  already_replied_if?: string[];
+  /* generic requests ("quero", "me manda", "link"…, config omnichat.instagram.generic_phrases)
+     also trigger; mid-sentence, the agent reads the post context first. Without the key, true */
+  generic_phrases?: boolean;
+  /* what the DM delivers, in words, for Claude to read the context; empty, the caption and the link */
+  offer?: string;
+  /* the commented Reel link on the DM's first line (without {post} in the text): Instagram shows the
+     Reel card and the message reads as a reply to it. Without the key, false */
+  quote_post?: boolean;
+  /* the DM opens with a button and the link goes out when the person taps it (needs the webhook) */
+  button?: boolean;
+  /* the tap only delivers if the person follows the account (implies the button) */
+  require_follow?: boolean;
+  /* text above the button, the button, what goes to someone who taps without following and its button;
+     empty = the config's */
+  opening_dm?: string;
+  button_label?: string;
+  not_following_dm?: string;
+  retry_label?: string;
+  /* the link goes in a button that opens it ("Abrir link"), not in the DM's text */
+  link_button?: boolean;
+  link_label?: string;
+  /* false: whoever says they follow without following never gets "Receber sem seguir" (on without the key) */
+  follow_skip?: boolean;
+  skip_label?: string;
+  /* the DM of whoever got the link through that button; empty = the config's */
+  skip_dm?: string;
+  updated_at?: string;
+  enabled_at?: string;
+  disabled_at?: string;
+};
+export type OmnichatTotals = {
+  triggers: number;
+  dms: number;
+  public_replies: number;
+  queued: number;
+  uncertain?: number;
+  failures: number;
+  /* gated rules: opener sent, waiting for the tap or the follow / link delivered */
+  awaiting?: number;
+  delivered?: number;
+};
+export type OmnichatCommentState = "queued" | "retry" | "done" | "failed" | "skipped" | "uncertain";
+/* one comment of omnichat-record.json, as `log --json` returns it */
+export type OmnichatComment = {
+  id: string;
+  username: string | null;
+  text: string;
+  commented_at: string;
+  /* uncertain: generic request that Claude has not read in context yet */
+  state: OmnichatCommentState;
+  attempts?: number;
+  pauses?: number;
+  uncertain_count?: number;
+  error?: string;
+  reason?: string;
+  account_reply?: string | null;
+  context?: string | null;
+  manual?: boolean;
+  manual_at?: string;
+  dm?:
+    | { at: string; id: string | null; text?: string; error?: undefined }
+    | { error: string; failed_at: string; at?: undefined; text?: undefined };
+  /* rule with a button: where the person is after the opener */
+  gate?: {
+    state: "awaiting_tap" | "awaiting_follow" | "delivered";
+    via?: "button" | "quick_reply";
+    taps?: number;
+    last_tap_at?: string;
+    delivered_at?: string;
+    skipped_follow?: boolean;
+  };
+  /* manual: written in the UI and sent only as a comment, no DM (`send --public-only`) */
+  public_reply?:
+    | { at: string; id: string | null; text: string; manual?: boolean; error?: undefined }
+    | { error: string; failed_at: string; at?: undefined };
+};
+/* POST …/omnichat/comments: the Reel read now, and who did not get the DM */
+export type MissingDmItem = {
+  id: string;
+  username: string | null;
+  text: string;
+  commented_at: string;
+  /* what the agent already did with it; null: did not trigger, or not read yet */
+  state: OmnichatCommentState | null;
+  reason: string | null;
+  triggers: "yes" | "uncertain" | false;
+  account_reply: string | null;
+  /* Meta only accepts the DM up to 7 days after the comment */
+  within_deadline: boolean;
+};
+/* a reply nested in a comment: a person's, the account's own, or the account's loose "@person" comment */
+export type ThreadReply = {
+  id: string;
+  username: string | null;
+  text: string;
+  at: string;
+  own: boolean;
+  loose?: boolean;
+};
+/* a top-level comment of the post as a chat card, with what is nested in it */
+export type ThreadComment = ThreadReply & {
+  replies: ThreadReply[];
+  /* the DM that went; `exact` false: the rule's text as it reads today (older records did not keep it) */
+  dm: { at: string; text: string | null; exact: boolean; gate: string | null } | null;
+  state: OmnichatCommentState | null;
+  reason: string | null;
+  triggers: "yes" | "uncertain" | false;
+  within_deadline: boolean;
+};
+export type MissingDmList = {
+  checked_at: string;
+  read: number;
+  truncated: boolean;
+  without_dm: number;
+  items: MissingDmItem[];
+  /* every comment with its replies nested (the chat); `items` is the ones without the DM */
+  thread: ThreadComment[];
+};
+/* POST …/omnichat/comments/delete: one per comment */
+export type DeletedComment = { id: string; state: string; reason: string | null };
+/* POST …/omnichat/send: one per chosen comment */
+export type ManualSend = {
+  id: string;
+  username?: string | null;
+  state: string;
+  public_reply?: boolean;
+  reason: string | null;
+};
+export type OmnichatLog = {
+  totals: OmnichatTotals;
+  checked_at: string | null;
+  warning: string | null;
+  items: OmnichatComment[];
+};
+/* one item of the rule list (GET /api/omnichat) */
+export type OmnichatRuleSummary = {
+  /* a video's Reel, a content's carousel (videos/<slug>/carousel) or an outside post */
+  type: "video" | "post" | "carousel";
+  /* video slug (also the carousel's) or post code */
+  id: string;
+  dir: string;
+  enabled: boolean;
+  published: boolean;
+  post: string | null;
+  published_at: string | null;
+  /* null: any comment */
+  keywords: string[] | null;
+  updated_at: string | null;
+  totals: OmnichatTotals | null;
+  checked_at: string | null;
+  warning: string | null;
+  log_error: string | null;
+};
+/* GET /api/videos/<slug>/omnichat, /api/videos/<slug>/carousel/omnichat and /api/omnichat/posts/<code> */
+export type OmnichatRuleDetail = Omit<
+  OmnichatRuleSummary,
+  "enabled" | "keywords" | "updated_at" | "totals" | "checked_at" | "warning"
+> & {
+  rule: OmnichatRule | null;
+  /* what a new rule gets and how many go per pass (config omnichat.instagram) */
+  defaults: {
+    dm: string | null;
+    public_replies: string[] | null;
+    max_per_pass: number | null;
+    quote_post: boolean;
+    opening_dm: string | null;
+    button_label: string | null;
+    not_following_dm: string | null;
+    retry_label: string | null;
+    link_label: string | null;
+    skip_label: string | null;
+    skip_dm: string | null;
+  };
+  /* video: the first URL of the description, brief.md or source/request.md (social networks don't
+     count), which a new rule gets as link; `found_in` says where ("no brief.md") */
+  found_link: { link: string; found_in: string } | null;
+  /* video: with `enable` (omnichat.instagram.enable_on_publish), a rule not enabled yet turns on
+     when the Reel goes up; without a rule, `term` is what the narration asks ("comenta REA…") */
+  on_publish: { enable: boolean; term: string | null } | null;
+  log: OmnichatLog | null;
+};
+/* GET /api/omnichat: account and comments permission (cached 2 min), agent, pause and rules */
+export type OmnichatState = {
+  agent: LaunchdAgent | null;
+  pause: { until: string; reason: string; at: string } | null;
+  account:
+    | { ready: true; username: string; expires: string | null }
+    | { ready: false; reason: string; username?: undefined };
+  /* ready null: no recent post with a comment to check */
+  comments: { ready: boolean | null; reason?: string } | null;
+  checked_at: string;
+  rules?: OmnichatRuleSummary[];
+};
+
+/* --- sessions -------------------------------------------------------------------------- */
+export type TurnResult = {
+  duration_ms: number | null;
+  cost: number | null;
+  text: string;
+  error: boolean;
+  denied: string[];
+};
+
+export type SessionType = "video" | "reference" | "analysis" | "edit" | "omni";
+export type SessionState = "running" | "stopped" | "error" | "interrupted";
+
+export type Session = {
+  id: string;
+  /* "analysis": the Analytics page session (target "channel"), with the av-analysis skill */
+  type: SessionType;
+  target: string;
+  title: string;
+  created_at: string;
+  state: SessionState;
+  activity: number;
+  turns: number;
+  turn: {
+    n: number;
+    origin: string;
+    prompt: string;
+    started_at: string;
+    pid: number;
+    result: TurnResult | null;
+  } | null;
+  now: string | null;
+  total_cost: number;
+};
+/* server name for the same shape */
+export type SessionSummary = Session;
+
+/* --- references -------------------------------------------------------------------------- */
+export type Color = { hex: string; name: string };
+
+export type ReferenceSummary = {
+  name: string;
+  enabled: boolean;
+  title: string;
+  essence: string | null;
+  guide: string | null;
+  measurements: {
+    duration: number;
+    w: number;
+    h: number;
+    fps: number;
+    shots: number | null;
+    hold_pct: number | null;
+    strip: string | null;
+    step: number | null;
+    bpm: number | null;
+    source: string | null;
+  } | null;
+  palette: Color[];
+  cover: FileEntry | null;
+  frame: FileEntry | null;
+  video: FileEntry | null;
+  images: number;
+  videos: number;
+  updated: number;
+};
+
+export type ReferenceDetail = ReferenceSummary & {
+  dir: string;
+  files: FileEntry[];
+  texts: { path: string; type: string; text: string }[];
+  used_in: { slug: string; title: string }[];
+};
+
+/* --- services / usage -------------------------------------------------------------------- */
+export type VoiceProviderStatus = { id: string; name: string; default: boolean; ready: boolean; reason: string | null };
+
+export type Services = {
+  voicestudio: { ok: boolean; url: string; version: string | null; device: string | null };
+  voices: VoiceProviderStatus[];
+  premiere: { ok: boolean; started: boolean; age_ms: number | null };
+  /* pressure is shown to the user as is: "normal" | "atenção" | "crítica" */
+  memory: { swap_total_mb: number; swap_used_mb: number; free_pct: number; pressure: string; total_gb: number };
+  at: number;
+};
+
+/* voice usage (tools/usage.py summary --json) */
+export type UsageProviderRun = {
+  lines: number;
+  bytes: number;
+  chars: number;
+  audio_s: number;
+  lines_free?: number;
+  bytes_paid?: number;
+  estimated_usd?: number;
+  platform?: number;
+  estimated_credits?: number;
+};
+
+export type UsageRun = {
+  run: string;
+  at: string;
+  video: string | null;
+  providers: Record<string, UsageProviderRun>;
+  failures: { provider: string; line: string | null; reason: string | null }[];
+};
+
+export type UsageData = {
+  generated_at: string;
+  cycle: { start: string; end: string };
+  fish: {
+    name: string;
+    key: boolean;
+    voice_id: string | null;
+    model: string;
+    fallback_model: string | null;
+    balance: { credit: number | null; cumulative_top_up: number | null; at: string | null };
+    cycle: {
+      lines: number;
+      lines_free: number;
+      chars: number;
+      bytes: number;
+      bytes_paid: number;
+      estimated_usd: number;
+      platform: number | null;
+      platform_since: string | null;
+    };
+    price_usd_per_million_bytes: number;
+  };
+  cartesia: {
+    name: string;
+    key: boolean;
+    admin_key: boolean;
+    voice_id: string | null;
+    plan: string;
+    cycle_day: number;
+    quota: number;
+    used: number;
+    source: "platform" | "estimated";
+    read_at: string | null;
+    estimated: number;
+    remaining: number;
+    fraction: number;
+    cycle: { lines: number; chars: number };
+  };
+  voicestudio: { name: string; lines: number; audio_s: number };
+  by_video: {
+    video: string;
+    lines: number;
+    fish_usd: number;
+    cartesia_credits: number;
+    audio_s: number;
+    providers: string[];
+  }[];
+  runs: UsageRun[];
+  warnings: string[];
+  refresh: { live: boolean; errors: string[] };
+};
+
+export type Usage = UsageData | { error: string };
+
+/* --- settings ---------------------------------------------------------------------------- */
+export type KeyStatus = { name: string; masked: string | null; in_env: boolean };
+
+export type ModelChoice = { model: string; effort?: string };
+
+/* one voice: what it has on each provider and the try order (the first is preferred) */
+export type VoiceProfile = {
+  id: string;
+  name: string;
+  order: string[];
+  fish: string | null;
+  cartesia: string | null;
+  voicestudio: string | null;
+  elevenlabs: string | null;
+  avatar?: string | null;
+};
+
+export type Settings = {
+  voice: {
+    /* voice.order: the first is the default, the others are fallback */
+    order: string[];
+    /* voice profiles: the Fish and Cartesia voice_id under one name; default_profile is the id checked on a new video */
+    profiles: VoiceProfile[];
+    default_profile: string | null;
+    voicestudio: { profile: string | null };
+    fish: {
+      key: KeyStatus;
+      voice_id: string | null;
+      model: string;
+      fallback_model: string | null;
+      usd_per_million_bytes: number | null;
+    };
+    cartesia: {
+      key: KeyStatus;
+      admin_key: KeyStatus;
+      voice_id: string | null;
+      plan: string;
+      monthly_quota: number;
+      cycle_day: number;
+    };
+    elevenlabs: { key: KeyStatus; voice_id: string | null; model: string };
+  };
+  publish: {
+    auto: { approved: boolean; platforms: string[] };
+    text: { footer_youtube: string; footer_instagram: string; footer_tiktok: string; hashtags: string[] };
+    youtube: {
+      privacy: string;
+      audited: boolean;
+      category: string;
+      language: string;
+      made_for_kids: boolean;
+      synthetic_content: boolean;
+    };
+    instagram: { api_version: string; share_to_feed: boolean; cover_at_s: number | null };
+    tiktok: {
+      mode: "direct" | "draft";
+      privacy: string;
+      audited: boolean;
+      comments: boolean;
+      duet: boolean;
+      stitch: boolean;
+      ai_content: boolean;
+      cover_at_s: number | null;
+    };
+    schedule: { max_delay_h: number; attempts: number; interval_min: number };
+    keys: {
+      youtube_client_id: KeyStatus;
+      youtube_client_secret: KeyStatus;
+      youtube_connected: boolean;
+      instagram_connected: boolean;
+      tiktok_client_key: KeyStatus;
+      tiktok_client_secret: KeyStatus;
+      tiktok_connected: boolean;
+    };
+  };
+  models: {
+    orchestrator: ModelChoice | null;
+    reference: ModelChoice | null;
+    stages: (ModelChoice & {
+      stage: string;
+      in_skill: { model: string | null; effort: string | null; fork: boolean } | null;
+    })[];
+    options: { models: string[]; efforts: string[] };
+  };
+  /* omnichat.instagram: the rule turns on by itself when the Reel goes up; a new rule quotes the Reel in the DM */
+  omnichat: { enable_on_publish: boolean; quote_post: boolean };
+  agents: AgentsSettings;
+};
+
+/* the agent accounts (agents in the config; tools/lib/agents.mjs): N Claude dirs and N Codex homes,
+   in rotation order */
+export type AgentProvider = "claude" | "codex";
+export type AgentAccount = {
+  id: string;
+  provider: AgentProvider;
+  dir: string;
+  label: string;
+  enabled: boolean;
+  login: { email: string | null; detail: string | null } | null;
+  /* over its usage limit until then (ms) */
+  limited_until: number | null;
+  login_command: string;
+  logging_in: { state: "waiting" | "ok" | "error"; url: string | null; output: string; at: number } | null;
+};
+export type AgentsSettings = {
+  accounts: AgentAccount[];
+  next: string | null;
+  codex: {
+    model: string;
+    effort?: string;
+    sandbox: string;
+    bin: string;
+    installed: boolean;
+    options: { models: { id: string; label: string; efforts: string[] }[]; sandboxes: string[] };
+  };
+};
+
+/* --- getting started (/api/onboarding): the guide (docs/onboarding.md) in steps, each with the
+   tools/setup.mjs check -------------------------------------------------------------------- */
+export type OnboardingCheck = { id: string; title: string; state: "ok" | "missing" | "warning"; detail: string };
+export type OnboardingStep = {
+  id: string;
+  title: string;
+  markdown: string;
+  state: OnboardingCheck["state"] | null;
+  optional: boolean;
+  items: OnboardingCheck[];
+};
+export type Onboarding = { ready: boolean; checked: boolean; intro: string; steps: OnboardingStep[]; error?: string };
+
+/* --- analytics (tools/analysis.mjs context; metrics from tools/metrics.mjs) ----------------- */
+export type MetricsSnapshot = {
+  milestone?: string;
+  at: string;
+  age_h: number;
+  views: number | null;
+  reach: number | null;
+  likes: number | null;
+  comments: number | null;
+  saves: number | null;
+  shares: number | null;
+  interactions: number | null;
+  avg_watch_s: number | null;
+  watched_pct: number | null;
+  skip_3s_pct: number | null;
+  total_watch_h: number | null;
+};
+export type ComparableMetric =
+  | "views"
+  | "reach"
+  | "skip_3s_pct"
+  | "watched_pct"
+  | "avg_watch_s"
+  | "saves"
+  | "shares"
+  | "comments"
+  | "likes"
+  | "saves_per_k"
+  | "shares_per_k"
+  | "comments_per_k";
+export type Medians = { n: number } & Record<ComparableMetric, number | null>;
+export type MediansByMilestone = Record<"current" | "24h" | "72h", Medians>;
+export type ReelMetrics = {
+  slug: string;
+  title: string | null;
+  cover: FileEntry | null;
+  published_at: string;
+  url: string | null;
+  duration_s: number | null;
+  current: MetricsSnapshot | null;
+  snapshots: MetricsSnapshot[];
+  error: { at: string; message: string } | null;
+  removed: boolean;
+  pillar: string | null;
+  goal: string | null;
+  promise: string | null;
+  hook: { line: string | null; frame0: string | null; text: string | null; type: string | null } | null;
+  first_line: string | null;
+  analysis: { at: string } | null;
+  opening: boolean;
+  /* readings kept every 4 hours (the series comes only in the Reel detail) */
+  n_hourly: number;
+};
+export type AccountSnapshot = {
+  day: string;
+  at: string;
+  username: string;
+  followers: number | null;
+  following: number | null;
+  posts: number | null;
+  profile_visits_day: number | null;
+};
+export type Analytics =
+  | {
+      generated_at: string;
+      account: AccountSnapshot[];
+      medians: MediansByMilestone;
+      /* the hourly sum of the Reels (last 30 days) and the Reels published in that range */
+      progression: { t: number; views: number; comments: number; saves: number; followers: number | null }[];
+      publications: { t: number; slug: string; title: string | null }[];
+      /* the 3 s skip range before OmniVideo, if the playbook says so */
+      before: { skip_3s_pct: [number, number] } | null;
+      videos: ReelMetrics[];
+      agent: { installed: boolean; loaded: boolean; log: string };
+      last_analysis: { file: string; day: string; at: string; text: string | null } | null;
+      playbook: boolean;
+    }
+  | { error: string };
+export type ReelDetail =
+  | (ReelMetrics & { hourly: MetricsSnapshot[]; medians: MediansByMilestone; analysis_text: string | null })
+  | { error: string };
+
+/* --- the hosted studio's runner (GET /api/runner; the hub answers it in cloud/studio) -------------- */
+/* what kept the Mac out (cloud/studio/src/presence.mjs): its key refused (it pairs again by itself), the
+   protocol versions apart (`side` is the one to update), or disconnected by the user at /runner */
+export type RunnerProblem =
+  | { reason: "key"; at: string; host?: string }
+  | { reason: "protocol"; at: string; side: "mac" | "cloud"; host?: string }
+  | { reason: "revoked"; at: string; name?: string };
+
+/* --- the admin panel (GET /api/admin) ------------------------------------------------------------ */
+export type OmniAdminSettings = {
+  enabled: boolean;
+  engine: "grok" | "stream" | "chunks";
+  voice: string;
+  fish_model: string;
+  llm: string;
+};
+export type AdminInfo = {
+  /* this studio on the Mac is always admin; the hosted one, the emails in admin.emails */
+  admin: boolean;
+  email: string | null;
+  hosted: boolean;
+  omni: OmniAdminSettings | null;
+};
+
+/* --- Omni, the voice agent (GET /api/agent, POST /api/agent/session) --------------------------- */
+export type AgentGender = "female" | "male";
+export type AgentConfig = {
+  /* false: Omni is off (the widget hides) */
+  enabled: boolean;
+  /* the agent saved in console.x.ai (persona, greeting, keyterms, silence); null = the app's own */
+  xai_agent_id: string | null;
+  /* what Omni runs on, for every user (the admin panel, agent.engine) */
+  engine: "grok" | "stream" | "chunks";
+  gender: AgentGender;
+  /* Omni's face: the seed of its avatar */
+  avatar: string;
+  voices: Record<AgentGender, string>;
+  model: string;
+  language: string;
+  /* Grok asks "Ainda tá aí?" after nudge_s of silence; the page hangs up after hangup_s */
+  idle: { nudge_s: number; hangup_s: number };
+  /* a session can't start once today's spend reaches daily_usd; the page hangs up at max_session_min */
+  limits: {
+    /* Grok voice minutes per day; past it, Omni goes on in Claude mode */
+    daily_voice_min: number;
+    daily_usd: number;
+    max_session_min: number;
+    max_actions: number;
+    max_tool_calls: number;
+  };
+  /* waiting for the studio's work (wait_for_work): past this many minutes asleep, the call hangs up */
+  wait_max_min: number;
+};
+export type AgentStats = {
+  sessions: number;
+  minutes: number;
+  turns: number;
+  latency_p50_ms: number | null;
+  latency_p90_ms: number | null;
+  tool_calls: number;
+  tool_errors: number;
+  classify_cost_usd: number;
+  voice_cost_usd: number;
+  thumbs_up: number;
+  thumbs_down: number;
+  /* the same, per way of talking: Grok, or the cascade by streamed or whole-utterance STT */
+  by_mode: AgentModeStats[];
+};
+export type AgentModeStats = {
+  mode: "grok" | "stream" | "chunks";
+  sessions: number;
+  minutes: number;
+  turns: number;
+  latency_p50_ms: number | null;
+  latency_p90_ms: number | null;
+  cost_usd: number;
+  /* cost over the minutes the conversations lasted (null with no minutes yet) */
+  cost_per_min_usd: number | null;
+  thumbs_up: number;
+  thumbs_down: number;
+};
+/* voice_left_s <= 0: today's voice quota is used up and the widget is in Claude mode */
+export type AgentInfo = { config: AgentConfig; stats: AgentStats; error: string | null; voice_left_s: number };
+export type AgentSessionStart = {
+  ok: true;
+  id: string;
+  /* the xAI ephemeral token: only opens the WebSocket */
+  token: string;
+  expires_at: number;
+  url: string;
+  /* the session.update the browser sends right after connecting */
+  session: Record<string, unknown>;
+  /* the system message sent after it: the time and the studio's state */
+  context: string;
+  config: AgentConfig;
+  voice_remaining_s: number;
+};
+/* GET /api/agent/claude/:id: Omni's Claude mode, the turn's state and the answer once it ended */
+export type AgentClaudeReply = { state: string; text: string | null; now: string | null };
+/* an action staged by the agent, waiting for the screen's "Confirmar" */
+/* a card decided by voice (confirm_action, cancel_action): the page takes it away and opens `open` */
+export type AgentResolvedAction = {
+  id: string;
+  kind: string;
+  slug: string | null;
+  summary: string;
+  state: "confirmed" | "canceled" | "failed";
+  open: NavigateArgs | null;
+};
+
+export type AgentPendingAction = {
+  id: string;
+  session: string;
+  kind:
+    | "change"
+    | "create"
+    | "thumbnail"
+    | "publish"
+    | "schedule"
+    | "approval"
+    | "reference"
+    | "new_reference"
+    | "choose_thumbnail"
+    | "analysis"
+    | "omnichat"
+    | "omnichat_send";
+  slug: string | null;
+  title: string;
+  /* what will happen, in Portuguese */
+  summary: string;
+  created: string;
+  payload: Record<string, unknown>;
+  /* the cards this one replaced (a corrected request): the screen takes them away */
+  replaces?: string[];
+  /* the screen where its result shows: the page opens it with the card (shared/omni-actions) */
+  open?: NavigateArgs | null;
+};