@crievo/omni 0.0.0-stage → 0.1.1

package/reference/studio.md

@@ -0,0 +1,666 @@
+# OmniVideo (studio)
+
+The OmniVideo screen follows a design system taken from the ElevenLabs app: light
+neutrals, Schibsted Grotesk for text and Geist Mono for numbers and code, from Google
+Fonts. Tokens in `studio/web/styles/tokens.css`; the rest in the partials that
+`studio/web/styles/index.css` imports, in cascade order. Details and where each rule
+lives: `studio/web/styles/design-system.md`.
+
+A local app that is the hub of this folder's pipeline. You can **start from
+it**: a new video and a new reference become a Claude session (`claude -p`,
+with the same skills as the chat), which the screen follows live and answers.
+It also covers what the chat does poorly: seeing several videos at once,
+reviewing media (players), coordinating the machine when videos run in
+parallel, and browsing the reference library.
+
+Each video's files remain the source of truth. The studio reads, watches and
+calls the tools in `tools/`; it has no database and never redoes any tool's
+work. Every tool works the same with the studio on or off, and the chat still
+counts: a video touched from the chat shows up the same way.
+
+## Start
+
+```bash
+cd <project folder>/studio && bun start                 # http://127.0.0.1:5432
+bun start --open                                        # and open it in the browser
+bun run dev                                             # with hot reload (for working on the studio)
+bun studio.ts --videos <dir>                            # also show the videos from another folder
+```
+
+`bun studio.ts --runner` (or `cloud.studio: true` in the config) also connects this server to the
+hosted studio (`cloud/studio`, `reference/cloud.md`): the same app answers the requests that come
+through the cloud, so the hosted screen is this one. It connects with the key that
+`node tools/runner.mjs login` writes into `.env`, and picks a new one up within 30 s. `bun run build` writes the web the cloud serves
+into `studio/dist/`.
+
+`bun start` installs the dependencies (react, react-dom, marked) if missing
+and starts the server. It listens only on `127.0.0.1:5432` (3900 and 3901
+belong to VoiceStudio). Bun 1.4, TypeScript, React; no build step: Bun
+bundles the web app at startup, and with `start` only at startup (changed the
+web app, restart). `bun run dev` turns on Bun's development server (`--dev`):
+a change in `web/` shows up in the browser right away (HMR, React and CSS
+without reloading), and `--watch` restarts the server when `studio.ts` or
+`server/` changes. Claude sessions and queue tools run in their own processes
+and survive the restart. `bun run types` checks the types.
+
+## How the screen works
+
+**Content, not just video.** Each folder in `videos/` is a piece of content that
+delivers a video, an Instagram carousel or both (`content.json`, written by the
+request). A new request picks it in the "O que criar" (What to create) cards;
+carousel only hides format and voice. The content page has one stepper per
+deliverable, with the Vídeo | Carrossel (Video | Carousel) switch on top when there
+are two; the stages of each pipeline are in `web/lib/stages.ts` (`PIPELINES`) and
+each one's result in `web/pages/VideoPage/components/StageResult.tsx` (the
+carousel's in `web/pages/VideoPage/components/Carousel*.tsx`). A new pipeline = a
+list in `PIPELINES`, its state in `getStageState` and one component per stage. The
+carousel: **Roteiro** (Script: the slides, `script.md` and the caption, with "Pedir
+alteração" (Request a change)), **Composição** (Composition: the slides in swipe
+order, each with the build warnings and "Pedir alteração", the sheet and
+`composition.md`) and **Publicar** (Publish: a one-slide-at-a-time viewer, the
+editable caption, the button that uploads to Instagram, the JPEGs and the post's
+omnichat). A video without a carousel gets "Fazer carrossel" (Make carousel) in the
+header. The data comes from `api/services/carousel.ts`, which imports the diagnosis from
+`tools/carousel.mjs`.
+
+**The banners on top** (`web/components/TopBanners.tsx`, fixed on every screen; their joint height is
+`--banner`): the studio not connected, in the hosted one (`RunnerBanner`), then **what broke** in red
+(`ErrorBanner`, the rules in `web/lib/alerts.ts`), then **what waits for a decision** (`HumanBanner`:
+script, scenes, voice being chosen). The red one lists a scheduled post that failed or missed its time, a
+platform whose last publish failed (video or carousel), a video whose status can't be read, a studio
+session that stopped with an error in the last 24 h, no agent account free (all at their limit, none
+switched on or none logged in; one at its limit is the rotation working), a connected platform that
+refuses its token or whose token expires within 7 days, and the omnichat paused by Meta or its cloud not
+answering. Each line links to where it is fixed and leaves on its own when the condition clears; × hides
+it in that browser until it fails again (the key names the occurrence). Settings, the platform accounts
+and the omnichat state have no SSE notice, so the banner asks for them again every 3 min.
+
+The video list has four tabs: **Em processamento** (In progress: pipeline
+incomplete), **Finalizados** (Finished: exported, not published),
+**Publicados** (Published: with a link on some platform, or scheduled; the
+scheduled ones on top, with each platform's icon) and **Arquivados**
+(Archived: the "Arquivar" (Archive) button at the end of the row;
+"Desarquivar" (Unarchive) puts the video back in the group it would be in).
+The classification is done by `web/lib/video-tabs.ts`.
+
+The **Publicar** (Publish) stage also has the **Thumbnail (opcional)**
+section, with four slots: "Gerar 3 aleatórias" (Generate 3 random) asks the
+video's Claude for three randomly drawn ideas (v1–v3), and the fourth slot has
+a box for your instruction (v4). The two requests are separate: redoing one
+does not erase the other. All of them come out in the video's style and
+aspect ratio, show up on screen by themselves, and each has "Usar este na
+publicação" (Use this one in the post) and "Baixar" (Download) below it. The
+selected one becomes `thumbnail/thumbnail.png` and is the post's cover: the
+publish form shows which one goes, and `publish.mjs` sends it to YouTube and
+Instagram at upload time (when scheduled, whichever is selected when the
+scheduler runs goes). TikTok gets a frame from the video. "Selecionada ·
+tirar" (Selected · remove) goes back to the video frame.
+
+Every finished version has **"Pedir alteração"** (Request a change): the user
+writes only what changes and Claude starts from that version's HTML, keeps
+everything else literally (spot changes, no redesign) and renders only that
+version. The previous HTML and PNG stay in `history/thumbnail/<vN>/`, the
+request in `thumbnail/request.json` (`changes`), and "Alterada: …"
+(Changed: …) appears under the version. Redoing the version from scratch
+(drawing another 3, redoing yours) clears that mark; changing the selected one
+removes the selection.
+
+The screen is organized by the pipeline stages. Each video has a **stepper**
+with the 11 stages of `status` (1, 2, P, 3…8), and each stage shows its
+current state:
+
+| state | when |
+|---|---|
+| feita (done) | `status` marks the stage |
+| rodando · 1min12s (running) | a tool of this stage holds the turn, for this video |
+| na fila · 2º (queued) | waiting for its turn (the position is in the whole machine's queue) |
+| esperando você (waiting for you) | an approval round (script or scenes) waiting for the user |
+| atenção (warning) | assembly outdated, or render with a changed start |
+| erro (error) | the last run of this stage failed and it is not done |
+| próxima (next) | the next stage in `status` |
+
+| page | what |
+|---|---|
+| `/videos` | all videos at once, each with its stepper; clicking a stage opens the video on it. Alongside, the Claude sessions, the machine queue and the services |
+| `/new` | new video: request, subject, format, duration, reference → folder, `source/request.md` and a Claude session |
+| `/videos/<slug>[/<stage>]` | the stepper, the video's **Claude session** (below), and for the chosen stage: on the left the **process** (state, the running run with its live log or the last one with its log, who does it, command, what it writes); on the right the **result**; and the **"Resultados anteriores"** (Previous results) button, which opens the drawer |
+| `/styles` | the reference library (cover, essence, measured summary, palette) and the request for a new one |
+| `/voice` | **"Perfil de voz"** (Voice profile) in the menu (icon: two randomly drawn avatars): the voice carousel (profiles, active, edit, clone), the same as Configurações → Voz (Settings → Voice), straight from the menu |
+| `/styles/<name>` | one reference: Claude session, palette, motion strip, videos, frames and sheets, guide and tokens in tabs, videos that use it |
+| `/queue` | who is running (with a live log), who is waiting, the latest ones with each one's log |
+| `/schedule[/week\|/day]` | the scheduled posts of every video (`schedule` in publication.json) by month, week and day, with each post's platforms and the selected cover. Only the day view shows the time, with the post at the exact time (posts at the same time share the width) and the now line; in the month view, hovering a day shows its videos with each one's time; in the week view, hovering a post shows its time. Clicking a post opens the video's Publicar stage; clicking a day (month) or the header (week) opens the day. **Dragging reschedules** (`POST /api/videos/<slug>/publish/schedule/reschedule`, `{ when }` → `publish.mjs schedule --reschedule`): in month and week, dropping on another day opens the time picker (starting at the post's current time); in the day view, the time is where the card lands, in 5 min steps, with a guide showing the time while dragging. A day or time already past does not accept the drop; a post being published does not drag |
+| `/` and `/analytics/<slug>` | **Dashboard**, the first menu item and the home page, following shadcn's dashboard-01 pattern. At the top, the collection state ("coleta de 4 em 4 h · última leitura há…"; clicking turns the agent on and off), "Coletar agora" (Collect now; GET-only on the API) and "Gerar análise" (Generate analysis). Four metric cards: followers (change since the previous snapshot), views in 7 days (sum of the Reels published in the week, against the previous one), 3 s skip rate and % watched (medians of the last 5, against the 5 before; the "before OmniVideo" figure comes from the playbook). Progression: the hour-by-hour sum of the Reels (`progression` from the context) as a wave line with area, of views, comments, saves or followers, over 24 h, 7 or 30 days, with a dot at each published Reel. Comparing the Reels (y bar with metric tabs and the median; the ones checked in the table are highlighted) and Highlights (best hook, most saves and most comments per thousand views). Tabs: Reels (the data table: sort by column, Columns to show and hide, filter by pillar and goal, search, selection with "Comparar" (Compare) side by side with the median and the best of each row, pagination from 20), Insights (the summary sentence of the latest `channel/analyses/<day>.md` and each insight in an accordion; the full analysis and the request with a focus also in accordions; the Claude session, type `analysis`, target `channel`), Plano (Plan) and Gancho × miolo (Hook × body). Explanations live in ⓘ or in the footer accordions. `/analytics/<slug>`: one Reel, with the "Dashboard / title" breadcrumb, "Analisar este Reel" (Analyze this Reel), four cards against the channel median (views, 3 s skip rate, % watched, saves per thousand), the hour-by-hour wave line (`instagram.hourly`, 24 h and 72 h marked) and the tabs Diagnóstico (Diagnosis: the `analysis.md`, sections in accordions), Abertura (Opening: the sheet of the first 3 seconds and the script's hook), Marcos (Milestones) and Roteiro (Script); the other metrics in an accordion |
+
+Without a stage in the URL, the page opens on what matters now: what is
+running, what is waiting for you, what failed, what is queued, the next one; a
+finished video opens on the export.
+
+The result of each stage:
+
+| stage | result |
+|---|---|
+| 1 script | `script.md` and `brief.md` |
+| 2 motion script | table of the scenes (title, hero, goal) and `motion.md` |
+| 3 composition | still and sheet of each scene with the minimum duration, the transition, the beats and how many sounds; the cut sheets, the overall ones |
+| 4 narration | the lines of each scene and each beat's `enters_with` |
+| 5 voice | each line with a player, duration and words per second |
+| 5 timing | the video's timeline (scenes, lines and beats at the computed times) and the table |
+| 6 render | each scene's MP4 and the **sound timeline** (editor below) |
+| 7 captions | **position on screen** (editor below), and the captions from `captions.srt` |
+| 8 export | the MP4 from `assemble.mjs`, what went in (scenes, lines, effects, captions, loudness) and the check sheet |
+
+**Caption position** (stage 7): a preview of `templates/captions.html` (the
+same HTML that `assemble.mjs` renders) over the scene's real frame, with the
+safe area marked. You pick the scope (all, the scene of the selected caption,
+only that caption), the platform's safe area and the style (only in all), the
+anchor in the 3×3 grid and X/Y (slider, number, ±10, dragging the caption in
+the preview). In All, also the safe area **Margens** (Margins: top, bottom,
+left, right, in % of the frame; changing the platform resets the adjustment).
+A caption may sit outside the safe area: the preview shows the warning with
+the side and the px, and does not block. Inherited values appear faded. Below
+the position, **Cor, contorno e sombra** (Color, outline and shadow: text,
+pill background and opacity, outline, shadow with color, opacity, blur and
+X/Y), in the same chosen scope (all, scene or only that caption); each field
+has ↺ to go back to the level above or the style default. **"Gravar
+posição"** (Save position) writes `captions` in `scenes.json`; it applies at
+the next assembly. Rules in `reference/captions.md`.
+
+**Sound timeline** (stage 6, full screen, without the result header): on the
+left, the preview filling the space, with the controls in a floating pill in
+the bottom corner (play, start, voice volume from 0 to 100% only for listening
+here (the export keeps the voice at its own level; the effects' ducking stays
+the same, so you hear the effects as they sit under the voice), time, zoom, ?
+with the voice level and the tips), and the timeline below, with Renderizar
+(Render) and the save state; both stay fixed, fitting the window. On the
+right, the only column that scrolls: Resultados anteriores, the plan's
+warnings, the chosen effect's panel (the column scrolls back to the top when
+choosing), the **sound library** in 3-column cards (the ones captured for the
+video and the kit by role, with search and ▶ to hear the file) and, after it,
+the scene renders in 2 columns. The timeline has a ruler, scenes, lines (with
+the ducking segments shaded), a diamond per beat (▲ at scene changes), the
+effects in lanes colored by kit role, and the bed. Clicking an empty diamond
+puts a sound on the beat (▲: on the scene change); dragging an effect changes
+its `offset`, and with **Shift** duplicates it (the original stays; the copy,
+with the same settings, goes to the beat nearest to where it was dropped);
+**Ctrl or Cmd + click** selects several, which drag together and, with Shift,
+duplicate together (each copy with the same duration and the same spacing, and
+the copies stay selected); **Delete** or Backspace removes whatever is
+selected (one, several or the bed). A library sound goes in by dragging it to
+the timeline, or with one click on it and another on the timeline (Esc
+cancels): on a diamond it becomes a layer of that beat, on an effect it
+replaces that effect's sound, on the bed row it becomes the bed (music only
+goes there), and on empty space it goes to the nearest beat, with the
+`offset` that puts the peak where it was dropped. The chosen effect's panel
+has the sound (the kit by role and what was captured for the video), anchor,
+`offset`, volume, the **trim** on the file's waveform (drag the edges),
+fades, stretch (`dur`) or speed, pitch, ducking, layers (+ layer) and remove.
+The bed has sound, volume, from/to, fades, loop and ducking. Every adjustment
+is planned by `tools/sound.mjs` itself in a draft (`.sound-draft/<slug>/`,
+outside the video folder, so it doesn't trigger the watcher), and the screen
+plays the finished WAVs with the voice in Web Audio, with the muted export on
+top just for the picture: what you hear is what `assemble.mjs` mixes. Change
+something while playing and it restarts from the same point; Space plays and
+pauses. **Saving is automatic**: 5 s after the last edit, the draft goes to
+`scenes.json` (`sound` on the beats, `transition.sound` and `bed`), and
+leaving the screen before that saves on the way out. Saving does not render:
+**Renderizar** (runs `assemble.mjs` through the queue) lights up when there is
+a saved edit the export doesn't have yet (`scenes.json` newer than the
+export MP4).
+
+A stage's **previous results** drawer has the versions the tools kept (see
+below), each with the queue run that produced it and its log, to play, view
+and **compare side by side with the current one**; and every run of the stage
+for this video, with its log.
+
+Stage and next come from `omnivideo.py status --json`; each beat's time from
+`tools/timing.mjs` (`beatTime`), the same one the build uses. Everything
+updates by itself: the server watches the video folders and `.queue/` and
+notifies the screen over SSE.
+
+## Previous versions (`history/`)
+
+The tools overwrite their result on every run. So the drawer has something to
+show, before overwriting they copy the version that was there, with the
+file's original time, into the video:
+
+```
+videos/<slug>/history/<stage>/[<key>/]<stamp>/
+```
+
+| stage | who keeps it | what | key |
+|---|---|---|---|
+| `composition` | `build-motion.mjs --stills/--sheets/--transitions` | the scene's still and sheet; the cut's sheet | `c01`, `transition-c01-c02` |
+| `voice` | `omnivideo.py voice` | the WAV and `voice/<line>.json` (the text it said) | `c01f1` |
+| `render` | `build-motion.mjs --render` | the scene's MP4 and `render.json` | `c01` |
+| `sound` | `sound.mjs` (and `assemble.mjs`) | `plan.json` and `preview.wav` | — |
+| `captions` | `omnivideo.py captions` | `captions.srt` | — |
+| `assembly` | `assemble.mjs` (and `premiere.mjs assemble`, if used) | the MP4, the sheet and `assembly.json` (or `premiere.json`) | — |
+| `check` | `premiere.mjs check` (optional) | the frames | — |
+
+- **Only what changed is kept.** If the new result comes out equal to the
+  previous one (deterministic render of a scene that didn't change, `sound`
+  with no change), the copy is discarded.
+- **The last 5 are kept** for each result (`history.versions` in the config).
+- **The version leads to the run by time.** The stamp is the time the
+  original result was written, which falls inside the run that produced it;
+  the screen finds that run in the queue. Composition doesn't go through the
+  queue, so its versions have no run.
+- **Loose exports:** the stage 8 drawer also lists the other MP4s in
+  `export/` (an old Premiere export, for example).
+- The helper is `tools/history.mjs` (`keepPrevious`) and its Python twin
+  `tools/history.py` (`keep_previous`). `history/` is outside git.
+- Since this version, `voice` writes `voice/<line>.json` next to each WAV
+  (text, instruction, hash, duration), like the MP4's `render.json`: that is
+  what lets a line's previous version show what it said.
+
+Services, without touching anything:
+
+| service | how it is seen |
+|---|---|
+| VoiceStudio | `GET /health` |
+| Premiere | the heartbeat the MCP Bridge panel writes to `<premiere.temp_dir>/bridge-heartbeat.json` every ~1 s. Up to 2.5 s the bridge is connected (the same limit as the MCP server); up to 15 s, slow bridge (the panel lags with Premiere busy); beyond that, bridge down |
+| memory | `sysctl vm.swapusage kern.memorystatus_level kern.memorystatus_vm_pressure_level`; swap ≥ 90 % turns red: the voice starts blowing past the 305 s |
+
+The studio does **not** call `premiere.mjs status`: `verify_premiere_connection`
+opens Premiere if it is closed and sends a script to the bridge, which runs
+one at a time, in the middle of an assembly.
+
+## Machine queue
+
+One heavy task at a time on the machine, whether it comes from the chat, the
+terminal or the studio:
+
+| tool | goes through the queue | stays out |
+|---|---|---|
+| `omnivideo.py` | `voice` (only if there is a line to generate), `captions` | `status`, `timing` |
+| `build-motion.mjs` | with `--render` | stills, sheets and transitions |
+| `sound.mjs` | `sound.mjs videos/<slug>` | `capture`, `download`, `effects`; the `prepareSound` inside `assemble` is already in its turn |
+| `assemble.mjs` | assembling and exporting, and `--sheet` (tool `assembly`) | — |
+| `premiere.mjs` (optional) | `assemble`, `check`, `export` | `status`, `call` |
+
+`check` goes in because the Premiere bridge runs one script at a time and
+`export` locks Premiere: a `check` in the middle of an export would get no
+answer. For the same reason, `premiere.mjs status` with `assemble`, `check`
+or `export` running answers "Premiere ocupado" (Premiere busy) right away
+(exit 0), without talking to the bridge, and `call` refuses (exit 1) until the
+task ends.
+
+Whatever can be checked without the machine is checked **before** waiting for
+the turn: `voice` with no new line, `captions` without audio or without
+timing, `--render` with provisional timing, `assemble` with a missing MP4 or
+captions, `check` or `export` without `premiere.json`. The error comes out
+right away; a chat doesn't wait half an hour in the queue to find out a file
+was missing.
+
+### How it works
+
+The mechanism is always the same, with the studio on or not: **the file lock
+is the queue, and the studio only shows it.** So nothing changes when the
+studio crashes, restarts or starts in the middle of a task.
+
+1. The tool writes a ticket, `.queue/<id>.json`: tool, video, command, pid,
+   origin (`chat`, `terminal`, `studio`), arrival.
+2. It waits to be the oldest live ticket waiting and then takes the `flock`
+   on `.queue/machine.lock`. The kernel releases the flock when the process
+   dies, even with `kill -9`: there is no forgotten lock.
+3. On its turn, the tool's output goes to the terminal as always **and** to
+   `.queue/<id>.log`, which the screen shows live.
+4. On exit, the ticket becomes `ok`, `error` (with the exit code) or
+   `interrupted`.
+
+A `waiting` or `running` ticket of a dead process, or without a heartbeat for
+more than 15 s (a live ticket renews its mtime every 2 s; that is what catches
+a reused pid), counts as interrupted and gets out of the way. The last 100
+finished tickets are kept, with their logs.
+
+The protocol lives in `tools/job_queue.py` (`with turn("voice", dir):`). The
+Node tools use `tools/job-queue.mjs` (`await turn("render", dir)`), which
+runs `job_queue.py` as a guardian: a Python process that waits for the turn,
+holds the flock while the Node process lives and releases it when the stdin
+pipe closes.
+
+Details:
+
+- **Without contention, nothing changes in the output.** The waiting notice
+  only appears when there is a wait.
+- **Whoever waits re-reads `scenes.json` on its turn.** The wait can be long
+  and the chat may have changed the video meanwhile.
+- **A child inside its parent's turn doesn't wait.** The task holding the turn
+  passes `OMNIVIDEO_TURN` to its children; a child asking for the turn inside
+  it goes straight through (avoids the deadlock of a heavy tool calling
+  another).
+- **`OMNIVIDEO_QUEUE=0` turns the queue off.** Emergencies only: without it,
+  two heavy tasks fight over the machine again.
+
+### In the terminal
+
+```bash
+PY=.venv/bin/python
+$PY tools/job_queue.py            # who runs, who waits, the latest ones
+$PY tools/job_queue.py --json     # the same as data
+```
+
+Whoever waits sees on stderr (the message text is PT):
+
+```
+fila: esperando a vez de voz · rodando voz · 2026-10-12-x (chat 04e33526, pid 86225) há 2min13s; 1 na frente
+fila: vez de voz depois de 2min30s de espera
+```
+
+## The chat and the queue
+
+- **A heavy tool may wait for its turn.** With another video running, a
+  `voice` or a `--render` can sit for minutes before starting. Run heavy tools
+  in the background (`run_in_background`) and wait for the completion
+  notification, instead of a command with a timeout: the Bash timeout kills
+  the tool mid-wait, and it loses its place in the queue.
+- **Before concluding it is stuck,** look at `$PY tools/job_queue.py`: if it is
+  `waiting`, it is in the queue; if it is `running`, the log is in
+  `.queue/<id>.log`.
+- **Don't kill another video's task** to jump ahead. It belongs to another
+  session.
+
+## Scene approval in the studio
+
+After the motion script, `av-motion` opens an approval round
+(`tools/approval.mjs open`) and the session sits in `approval.mjs wait`. In
+stage 2 of the video page, each scene shows title, hero, goal and visual,
+with **"Aprovar"** (Approve) and **"Pedir alteração"** (Request a change; the
+comment is required: it is what Claude will adjust), and **"Aprovar todas"**
+(Approve all) at the bottom.
+
+- **Notice.** On any studio page, a new round plays a short sound (Web Audio,
+  synthesized; the browser only plays it after some click on the page) and the
+  tab title gets `● Aprovar cenas 9:41 · …` with the countdown. A round that
+  was already waiting when the page opened only shows in the title.
+- **Automatic approval.** With nobody touching it, the pending scenes approve
+  themselves at the deadline (`motion.approval.auto_approve_min`, 10 min) and
+  the session moves on to the composition. Whoever reads first after the deadline
+  applies it: `wait`, the studio or `status`.
+- **Editing pauses the countdown.** Clicking Pedir alteração (or typing in the
+  comment) calls `scenes/pause`: what remains goes to `remaining_ms` and the
+  title shows `⏸ 7:32`, stopped. Sending or cancelling the last open change
+  calls `scenes/resume`, and the countdown picks up where it stopped
+  (`deadline = now + remaining_ms`). A screen that didn't pause (another tab,
+  reloaded page) shows **"Retomar contagem"** (Resume countdown). Approving a
+  scene pauses nothing.
+- **Who waits.** The session stays in `wait` during the pause. Only if the
+  pause runs past the whole deadline (abandoned edit) does it exit with 4 and
+  the session stops. Then the studio handles the rest: a per-video alarm
+  applies the deadline when the countdown resumes and expires, and resumes the
+  stopped session (only for a round finished less than 1 h ago, so as not to
+  wake an old session).
+- **End of the round.** With all decided, a session still in `wait` moves on
+  by itself; one that stopped is resumed by the studio (also when the decision
+  finishes while the turn is closing). With changes, `av-motion` adjusts only
+  those scenes and opens another round, with a new deadline; approved scenes
+  stay approved.
+
+`motion.approval.enabled: false` in the config turns it off: the round is born
+approved. The file, `motion/approval.json`, is described in the header of
+`tools/approval.mjs`; in the chat, the user answers and Claude runs
+`approval.mjs decide`.
+
+## Swapping the reference mid-video
+
+In stage 2 (or by clicking "Estilo visual: …" at the top of the video), **"Trocar
+estilo visual"** (Swap visual style) opens the same picker as the new video, with
+the current one marked, and an optional comment. The request goes to the
+video's session (resumes the stopped one or opens one), which follows the
+`omnivideo` skill, the "visual style" row: new style in `motion.md`,
+scenes reopened only if the visual changed, and then the composition (base and
+scenes), render and export.
+
+The state changes right away, without waiting for Claude: the studio writes
+the request to `motion/reference-swap.json`. Stage 2 shows **refazendo**
+(redoing) until `motion.md` is rewritten with the new reference. Script,
+lines and voice stay. The screen says what will be redone depending on where
+the video is. With the session running, the request is refused: wait for the
+turn or stop the session.
+
+## Claude sessions
+
+A request made on the screen becomes a `claude -p` session at the omnivideo
+root, with the project's skills and CLAUDE.md. Each turn runs until Claude
+stops (at an abandoned approval, at a blocker, at delivery); the next reply resumes
+**the same session** (`--resume`), with everything it already knows.
+
+| starts | prompt | goes until |
+|---|---|---|
+| New video (`/new`) | `/omnivideo` + the folder already created + `source/request.md` | delivery (it waits at the approvals, which resume it) |
+| Continue with Claude (video without a session) | `/omnivideo` resuming from where `status` says | the next stop |
+| New reference | skill `av-reference`: measure, Tipo, curves, GUIDE.md, proof in code compared with the piece | guide written and proof |
+| Ask Claude (reference) | the request, with the reference folder | what was asked |
+| Reply | the text, in the same session | the next stop |
+
+**Scenes decided in the studio resume the session** that stopped at scene
+approval (section Scene approval in the studio).
+
+**One running session per video or reference.** Replying mid-turn is refused;
+the **"Parar"** (Stop) button ends the whole process group (claude and the
+tools it opened). Whatever was already written stays; "continuar" (continue)
+resumes.
+
+**Where it lives.** `.sessions/<id>/session.json` (type, target, turns with
+prompt and pid) and `turn-<n>.jsonl` (each turn's stream-json output). The
+state comes from there: a turn with a `result` finished (stopped or error),
+without `result` and with a live pid it is running, without both it was
+interrupted. claude runs in its own process group and writes straight to the
+file: the studio can go down and come up mid-turn. To open it in the
+terminal: `claude --resume <id>`.
+
+**Permissions.** With no terminal, nobody approves anything: whatever asks for
+approval is denied immediately (`--permission-prompts none`). `auto` mode
+denies almost everything in that situation; that's why it is `acceptEdits`
+plus a list in `studio.claude.allow` (config), with `{python}` replaced by
+VoiceStudio's Python. A Bash rule doesn't match a shell variable, so the
+session gets a system prompt asking for the full Python path, one command per
+call and heavy tools in the foreground (the Bash timeout goes up to
+`studio.claude.bash_timeout_ms`). Whatever is denied shows on screen in red;
+add the rule to the config and reply asking it to try again.
+
+| `studio.claude` | |
+|---|---|
+| `bin` | the executable (`claude`) |
+| account | not a field here: `agents.accounts` (below) |
+| the model | the session's model and effort come from `models.orchestrator` (video) and `models.reference` in the config, re-read every turn (`--model`, `--effort`). The stages run in a fork with the model from `models.stages`, written into the skills by `tools/models.mjs apply` |
+| `permission_mode` | `auto` (the classifier approves the common and denies the risky; re-read every turn). `acceptEdits` goes back to depending only on the allowlist |
+| `budget_usd` | ceiling per turn (`--max-budget-usd`), `null` for no ceiling |
+| `bash_timeout_ms` | the limit of one command: 2 h, for long voice and render runs |
+| `allow` | allowed tools and Bash rules |
+
+### Agent accounts
+
+`agents` in the config, the logic in `tools/lib/agents.mjs` (shared with `publish.mjs text` and the
+omnichat classifier), the screen in Configurações → Agente de IA → Contas de agente.
+
+| `agents` | |
+|---|---|
+| `accounts` | `[{ id, provider: "claude" \| "codex", dir, label?, enabled? }]`, in rotation order. `dir` is the account's `CLAUDE_CONFIG_DIR` or `CODEX_HOME`, each with its own login (`claude auth login` / `codex login` with the variable set; the screen's "Entrar" runs it). Empty: `~/.claude-personal`. `~/.claude` is refused in code |
+| `codex.model`, `codex.effort` | the model of every Codex session (`-m`, `model_reasoning_effort`); the options come from the account's `models_cache.json` |
+| `codex.sandbox` | `auto` (default): workspace-write with network and the library writable, `approval_policy=on-request` with Codex's `auto_review` reviewer, so what must leave the sandbox (Chrome in the renders) asks and is decided like Claude's auto mode. `full`: no sandbox |
+| `codex.bin` | the CLI; default `codex` on the PATH or the one the ChatGPT app ships |
+
+- **Rotation:** a new session goes to the next ready account (on, logged in, not over its limit);
+  `.accounts/state.json` keeps the cursor and the limits. A session stays on its account while it
+  is free.
+- **Limit:** a turn that ends on the account's limit (Claude: the 429 with the rejected
+  `rate_limit_event` and its `resetsAt`; Codex: `turn.failed` with the usage-limit message) sets the
+  account aside until the reset (1 h when unknown) and starts a `failover` turn on the next one, at
+  most once per account. Claude to Claude copies the transcript (`<dir>/projects/<cwd>/<id>.jsonl`
+  and its subagents) and resumes the same conversation; to or from Codex the turn opens a new
+  conversation whose prompt carries the first request, the last turns and the instruction to check
+  the files before acting (`handoff` in the turn). With no account free, the turn stays on the
+  limit message and "Liberar" on the screen puts an account back by hand.
+- **Codex turns:** `codex exec --json` (then `exec resume <thread>`), the thread id read from the
+  turn's first event, `CLAUDE.md` as the project doc (`project_doc_fallback_filenames`), the
+  studio's context plus the Codex notes as `developer_instructions`, and the skills through
+  `.agents/skills`. It reports tokens, not dollars.
+
+## References
+
+The library (`references.dir` in the config) is each video's design system:
+the motion script picks a reference and takes from it the palette,
+typography, curves and rhythm of every scene. On the screen, each reference
+shows what exists in its folder: guide (`GUIDE.md` or the first `.md`),
+`measurements.json` (summary, palette by area, motion strip), tokens
+(`*tokens*.json`, where the palette comes from when there are no
+measurements), videos, `frames/` and `sheets/`. **"Novo estilo visual"** (New
+visual style) asks for a link and/or photos (nothing else: the name comes from
+the link or the photos) and opens a session that measures and writes the guide. Each reference's toggle adds or removes a
+`.disabled` in the folder: disabled, it is faded and listed separately,
+disappears from the new video picker, and `reference.mjs list` only mentions
+it at the end, as "não use" (don't use). Deleting moves the folder to the
+Trash.
+
+## Settings
+
+`/settings`, by category. **Voz** (Voice): just the voice carousel (profiles
+in `voice.profiles`), in the ElevenLabs style: the voice in the center becomes
+the **active** one (`voice.default_profile`, the one preselected for a new
+video) or opens for **editing**; the last item adds a voice. Adding or editing
+opens a drawer: the voice's name and its **providers** (Fish Audio, Cartesia,
+VoiceStudio). Each provider is where you enter what it needs: API key (in
+`.env`, masked), Fish's model and fallback, Voice ID (or the VoiceStudio
+profile, by name) and, on a new voice, recording or uploading audio to clone.
+With more than one provider on the voice, the list order is the priority of
+use (the profile's `order`): the 1st is used and the following ones are
+fallbacks. API key and model apply to every voice of the provider and save
+right away; Voice ID and order save on "Gravar voz" (Save voice). The avatar
+is a liquid orb whose colors come from the voice's id; every avatar on the page is drawn by
+`web/lib/orb.ts` (one shared WebGL context, the same shader as the video scenes'
+`VoiceAvatar` component) and reacts to the voice while it plays. **Agente de IA:** the agent accounts (Claude
+and Codex, in rotation order, each with its login, its limit and "Entrar"), Codex's model and
+sandbox, and the Claude models per stage. The keys go
+to `.env` and come back to the screen only masked; the rest goes to
+`omnivideo.config.json`. The Uso (Usage) screen only shows what is chosen.
+
+## API
+
+Everything on `127.0.0.1:5432`. A request with another `Host` is refused (DNS
+rebinding); POST requires `content-type: application/json` and, if `Origin`
+comes, that it be the studio's own.
+
+| route | what |
+|---|---|
+| `GET /api/videos` | a summary per video: `status` (the JSON from `status --json`), the scenes' `approval` (with the expired deadline already applied), cover |
+| `POST /api/videos` | `{ request, deliverables?, subject?, format?, duration?, reference? }` → folder, `content.json`, `source/request.md` and session; returns `slug` and `session`. `deliverables`: `["video"]` (default), `["carousel"]` or both |
+| `POST /api/videos/<slug>/carousel/create` | `{ note? }` → puts the carousel in the deliverables and asks the content's session (from the folder's video, if any) |
+| `POST /api/videos/<slug>/carousel/adjust` | `{ slide?, request, stage }` → a change asked of the session (`av-carousel … ajustar:`) |
+| `POST /api/videos/<slug>/carousel/caption` | `{ caption }` → `carousel/publication.json` |
+| `POST /api/videos/<slug>/carousel/publish` | `{ caption?, republish? }` → `publish.mjs carousel --confirm` (minutes) |
+| `POST /api/videos/<slug>/reference` | `{ reference, note? }` → a request to the video's session to swap the style reference (`""` = Claude picks another); refuses a video without a motion script and the same reference without a note |
+| `POST /api/videos/<slug>/claude` | `{ message }` → resumes the video's latest session, or opens one |
+| `GET /api/sessions` | the sessions, most recent first: state, current turn, what Claude is doing now, final answer, denied permissions, cost |
+| `GET /api/sessions/<id>` | the session with all its turns |
+| `GET /api/sessions/<id>/log` | SSE: the session's readable transcript (`log`) and `end` when the turn stops |
+| `POST /api/sessions/<id>/reply` | `{ message }` → new turn in the same session |
+| `POST /api/sessions/<id>/stop` | ends the running turn |
+| `GET /api/references` · `/api/references/<name>` | the library; one reference with texts, media and where it is used |
+| `POST /api/references` | `{ name, source, note? }` → session that measures and writes the guide |
+| `POST /api/references/<name>/claude` | `{ message }` → a request about a reference |
+| `POST /api/references/<name>/enable` | `{ enabled }` → removes or adds the `.disabled` |
+| `POST /api/references/<name>/delete` | moves the reference folder to the Trash |
+| `GET /ref/<name>/<path>` | a file of a reference (image, video, text) |
+| `GET /api/videos/<slug>` | everything about the video: `scenes.json`, resolved times, texts (scripts and `captions.srt`), media files with mtime, `history` (the kept versions), `runs` (every queue run of this video), `premiere.json`, `sound/plan.json` |
+| `POST /api/videos/<slug>/scenes/decide` | `{ scene, decision: "approve" \| "change", comment? }` → `motion/approval.json`; change requires a comment. A finished round resumes the video's stopped session |
+| `POST /api/videos/<slug>/scenes/approve-all` | the round's pending scenes become approved |
+| `POST /api/videos/<slug>/scenes/pause` | the user opened a change: `mode: "paused"`, what remains goes to `remaining_ms` |
+| `POST /api/videos/<slug>/scenes/resume` | the change was sent or cancelled: the countdown picks up where it stopped |
+| `POST /api/videos/<slug>/voice/regenerate` | `{ line }` → `omnivideo.py voice --regenerate <line>`: another reading of the same text, through the queue, **of that line only** (even with the video's provider changed, the others are not redone); answers right away (only an error from before the queue comes back) |
+| `POST /api/videos/<slug>/voice/generate` | `{}` → `omnivideo.py voice` with no arguments: generates the lines that are missing, changed text or were requested from another provider. It is the “Gerar as N falas com <voz>” (Generate the N lines with <voice>) button of the Voz stage picker, which only appears when the chosen provider differs from that of some already generated line |
+| `POST /api/videos/<slug>/voice/use` | `{ line, version }` → `omnivideo.py voice --use <line> <version>`: the reading kept in `history/voice/<line>/<version>/` becomes current again and the current one goes to the history; refuses a version of another text and while the video's voice is running |
+| `POST /api/videos/<slug>/line/text` | `{ line, text }` → the line's `text` in `scenes.json`; a line with voice gets the new reading right away (`voice --regenerate`). A text that removes the word an `enters_with` points at is not saved: it becomes a request to the video's session (`chatWith`), which saves the line, changes the beat with it and generates the voice |
+| `POST /api/videos/<slug>/publish/text` | `{ redo }` → `publish.mjs text`: title, description, post caption and tags from the script (Claude writes them; without it, they come from the script). Without `redo`, only what is empty. The Publicar stage calls it by itself when the video has no text yet |
+| `POST /api/videos/<slug>/publish` | `{ title, description, caption, privacy, tiktok_privacy, youtube, instagram, tiktok, republish }` → text in `publication.json` and `publish.mjs --confirm` (waits for the upload; one per video) |
+| `POST /api/videos/<slug>/archive` | `{ archive }` (default `true`) → writes or deletes `archived.json` (`{ at }`) in the video folder. Archiving takes it off the work list, deleting nothing; refuses a video with a scheduled post or a task running/queued. Only the screen reads the file: no pipeline stage does |
+| `POST /api/videos/<slug>/thumbnail` | `{ mode: "random" }` or `{ mode: "manual", instruction }` → writes the request to `thumbnail/request.json` (`random` or `manual`) and asks the video's Claude for the three random ones (v1–v3) or the manual version (v4) (skill `av-thumbnail`). `{ mode: "change", version, instruction }` changes an already created version (keeps the previous HTML and PNG in `history/` and asks Claude only for the change, preserving the rest). Refuses while the video's session is running. Generates nothing by itself: only with this request |
+| `POST /api/videos/<slug>/thumbnail/choose` | `{ version: "v1"\|"v2"\|"v3"\|"v4"\|"none" }` → `thumbnail.mjs choose`: the version becomes `thumbnail/thumbnail.png`, the cover that `publish.mjs` sends; `none` removes the selection |
+| `GET /api/publish/accounts` | `publish.mjs status --json`, cached for 5 min (`?refresh` asks again) |
+| `GET /api/queue` | `{ running, waiting, recent }` |
+| `GET /api/queue/<id>/log` | SSE: the log so far and what arrives (`log`), and `end` when the task finishes |
+| `GET /api/services` | VoiceStudio, Premiere, memory |
+| `GET /api/videos/<slug>/captions` | captions with id and scene, resolved position, the format's safe areas, anchors and styles |
+| `GET /api/videos/<slug>/captions/page` | the video's `captions.html` (`?preview=1` marks the safe area and accepts `postMessage({ position, t })`) |
+| `GET /api/videos/<slug>/captions/frame?t=` | JPEG of the motion at second `t` of the video, from the scene's MP4 |
+| `POST /api/videos/<slug>/captions/position` | `{ scope: "video" \| "scene" \| "caption", target?, value }` → `captions` in `scenes.json`; `value: null` removes a scene's or caption's adjustment |
+| `GET /api/videos/<slug>/sound` | sound timeline: total, scenes, lines (video time), sound places (each beat with its instant and each scene change, with the sounds), the bed, the catalog (kit by role and the video's `sfx/`, measured) and the export's base MP4 |
+| `POST /api/videos/<slug>/sound/plan` | `{ places, bed }` (draft) → the `sound.mjs` plan with the URL of each finished WAV under `/sound-draft/<slug>/…`; nothing is written to the video |
+| `POST /api/videos/<slug>/sound` | `{ places, bed }` → `sound` on the beats, `transition.sound` and `bed` in `scenes.json` (validated; defaults are dropped) |
+| `POST /api/videos/<slug>/sound/reassemble` | runs `assemble.mjs` (waits for its turn in the queue) |
+| `GET /kit/<name>` | MP3 from the global kit (`kit/sfx/`), for the waveform |
+| `GET /api/usage` | `tools/usage.py summary --json`: Fish balance, Cartesia quota, usage per video and latest generations (only reads the local log) |
+| `POST /api/usage/refresh` | the same with `--live`: asks the platforms now and writes the reading to `.usage/` |
+| `GET /api/analytics` | `tools/analysis.mjs context` (account, medians at the current reading and at the 24 h and 72 h milestones, also per thousand views, the channel's hour-by-hour `progression` and the `publications` in it, the playbook's `before` range, each Reel with metrics, strategy and hook, the agent) plus the text of the latest channel analysis |
+| `GET /api/analytics/reels/<slug>` | one Reel from the context, with the `hourly` series from metrics.json, the medians and its `analysis.md` |
+| `POST /api/analytics/collect` | `metrics.mjs collect --force`: redoes the current reading of all of them (GET-only on the API) |
+| `POST /api/analytics/agent` | `{ enable }` → installs or uninstalls the metrics agent (launchd, every 4 hours) |
+| `POST /api/analytics/analyze` | `{ slug?, focus? }` → the `av-analysis` skill in the analysis session (resumes the stopped one, or opens one) |
+| `POST /api/analytics/claude` | `{ message }` → replies to the analysis session (or opens one with the question) |
+| `GET /api/settings` | what the Settings screen edits; keys only masked, and the accounts of each Claude folder |
+| `POST /api/settings/key` | `{ name, value }` → `FISH_API_KEY`, `CARTESIA_API_KEY` or `CARTESIA_ADMIN_API_KEY` in `.env` (`""` removes) |
+| `POST /api/settings/default-voice` | `{ provider }` → `fish`, `cartesia` or `voicestudio` moves to the front of `voice.order`; the others stay as fallbacks in the order they were |
+| `POST /api/settings/voice-profile` | `{ id?, name, order?, fish?, cartesia?, voicestudio? }` → creates (without `id`) or edits an item of `voice.profiles`; at least one provider (Fish: 32 hex; Cartesia: UUID; VoiceStudio: profile name); `order` is the priority among them; the first voice created becomes the active one |
+| `POST /api/settings/voice-profile/default` | `{ id }` → `voice.default_profile` (the active voice) |
+| `POST /api/settings/voice-profile/remove` | `{ id }` → removes the profile from `voice.profiles` (if it was the default, the first remaining one takes over) |
+| `POST /api/settings/voice-id` | `{ provider, voice_id }` → `voice.<provider>.voice_id` (Fish: 32 hex; Cartesia: UUID) |
+| `POST /api/settings/fish-model` | `{ model, fallback }` → `voice.fish.model` and `voice.fish.fallback_model` (`s2.1-pro-free` or `s2.1-pro`; `fallback: null` turns it off) |
+| `POST /api/settings/fish-price` | `{ value }` → `usage.fish.usd_per_million_bytes` |
+| `POST /api/settings/models` | `{ orchestrator?, reference?, stages?: { <skill>: { model, effort? } } }` → `models` in the config and `tools/models.mjs apply` on the skills |
+| `POST /api/settings/claude` | `{ config_dir }` → `studio.claude.config_dir` (`null` = `~/.claude`) |
+| `GET /api/events` | SSE: `queue`, `services` and `sessions` with the data, `video` with the slug that changed, `reference` with the name |
+| `GET /media/<slug>/<path>` | a video file, with Range (206) for the players; only media and text, never outside the video folder |
+
+## Files
+
+```
+studio/studio.ts          entry: args, HTML routes, Bun.serve; the rest goes to the API
+studio/api/app.ts         the Hono app: local-only guard, every router, errors (AppType)
+studio/api/routes/        one thin router per domain: validate (zod) → service → respond
+studio/api/services/      videos (status, times, media, history), queue (reading
+                          and log), services,
+                          approval (motion script scenes), events,
+                          sessions (claude -p, state, transcript), create (video,
+                          reference, chat, verdict), references, usage,
+                          analytics (metrics, collect, agent, Claude analysis),
+                          sound (sound timeline: data, draft, save), carousel…
+studio/api/test/          bun test: guard, validation, routes on a fixture root
+                          (OMNIVIDEO_ROOT points the services at another root)
+studio/shared/            zod schemas (shared/schemas) and response types
+                          (shared/types), used by the API and the web
+studio/web/               React (TanStack Router + Query, typed hono/client in lib/api.ts):
+                          pages/VideosPage (overview),
+                          NewVideoPage, VideoPage (stepper, process, result,
+                          StageDrawer, SoundTimeline, one component per stage),
+                          components/SessionPanel (session and reply), ReferencesPage,
+                          components/StageStepper, lib/stages.ts (what each stage is),
+                          QueuePage, SettingsPage (UsageCategory), AnalyticsPage,
+                          components/ui/chart.tsx (shadcn charts on Recharts, no Tailwind),
+                          components/ApprovalNotice (sound and title)
+.sound-draft/             WAVs of the sound timeline draft (generated)
+tools/approval.mjs        scene approval: open, wait, decide, deadline
+.sessions/                one folder per Claude session (outside git)
+.usage/events.jsonl       usage log of the paid voices (outside git)
+tools/usage.py            usage logging and reading (Fish, Cartesia)
+tools/metrics.mjs         Reel metrics; tools/analysis.mjs gathers what the Analytics screen shows
+tools/job_queue.py        the queue protocol (and the guardian of the Node tools)
+tools/job-queue.mjs       the turn for the Node tools
+tools/history.mjs, .py    previous versions of the results
+.queue/                   tickets, logs and the lock (outside git)
+videos/<slug>/history/    previous versions of each video (outside git)
+```
+
+## For later (the architecture already allows it)
+
+- **Studio MCP for the chat**, with a tool that waits for the approval made
+  on the screen: it means watching `script-approval.json` and
+  `motion/approval.json`, which are already where the decisions land.
+- **Actions from the screen** (regenerate a line, fix pronunciation,
+  re-render a scene, assemble, export): the studio calls the tool with
+  `OMNIVIDEO_ORIGIN=studio`, and it joins the queue by itself, like any other.
+- **Timeline** with waveform and beats: `/api/videos/<slug>` already returns
+  the resolved times and the WAVs.
+- **Attaching a file to the request** (PDF, style video) straight into
+  `source/`: today it comes in by path, and the POST only accepts JSON.
+- **Granting permission from the screen**: the denied notice would get a
+  button that writes the rule to `studio.claude.allow`.