@crievo/omni 0.0.0-stage → 0.1.1

package/reference/carousel-contract.md

@@ -0,0 +1,91 @@
+# The `carousel.json` contract
+
+One per piece of content, at `videos/<slug>/carousel/carousel.json`, next to
+`scenes.json` when the content is also a video. It is the only source of
+slide, text and order for the carousel. The `av-carousel` skill writes it;
+`tools/carousel.mjs` only reads it (what it writes goes to `build.json` and
+`export/export.json`).
+
+## Folder
+
+```
+carousel/
+  carousel.json        the source of truth (below)
+  script.md            strategy, covers, each slide's text, post caption
+  composition.md       reference, style and composition of each slide
+  src/_common.html     tokens, background and frame, pasted into every slide
+  src/<id>.html        the slide, from templates/slide.html
+  assets/              logo, screenshot… (come in as assets/<file>)
+  <id>.html            generated by the build: src + _common + the slide's variables
+  png/<id>.png         generated by the build
+  build.json           generated: hash of the final HTML and warnings of each slide
+  _sheet.png           generated: every slide in order, with id and title
+  _strip.png           generated with --strip: the slides joined, no gap
+  export/NN.jpg        generated by export, in carousel order (01.jpg…)
+  export/caption.txt   the post text
+  export/export.json   generated: what was exported, with each slide's hash
+  publication.json     the caption edited in the studio (`caption`) and the Instagram post
+                       (`instagram: { id, url, type, slides, published_at, export,
+                       previous?, last_error? }`), which publish.mjs carousel writes
+  omnichat.json        this post's omnichat rule (reference/omnichat.md)
+  omnichat-record.json what omnichat already did on this post (only omnichat.mjs writes)
+```
+
+What the content delivers lives outside, in `videos/<slug>/content.json`
+(`{ "deliverables": ["video", "carousel"] }`): the studio writes it on the
+request and on the "Fazer carrossel" (Make carousel) button. Without it, video
+applies, and carousel if the folder has one.
+
+## Root
+
+| field | owner | what it is |
+|---|---|---|
+| `slug` | `init` | the content folder's |
+| `title` | `init`, 1 | working title (the video's, if any) |
+| `format` | `init` | `{ ratio: "4:5" \| "1:1" \| "3:4", w, h }` (`carousel.formats` in the config) |
+| `origin` | `init` | `"script"` or `"video"` (born from the folder's video) |
+| `goal` | 1 · script | `saves`, `shares`, `followers` or `lead` |
+| `caption` | 1 · script | the post text, without the fixed hashtags |
+| `references` | 2 · composition (inherited from `scenes.json` with `--from-video`) | library folders the style came from |
+| `slides` | 1 · script | ordered list; the order is the swipe order |
+
+## Slide
+
+| field | owner | what it is |
+|---|---|---|
+| `id` | 1 | `s01`, `s02`… Reordering changes the list order, not the id |
+| `role` | 1 | `cover` (s01), `content`, `payoff`, `cta` (the last one) |
+| `title` | 1 | the title on screen |
+| `text` | 1 | the body on screen (may be missing on the cover and the CTA) |
+| `goal`, `visual`, `hero` | 1, 2 | what the slide communicates and shows; `hero` is the single highlighted element |
+
+The paths come from the id: `src/<id>.html`, `<id>.html`, `png/<id>.png`.
+
+## What the build injects
+
+Before each slide's `</head>`:
+
+```html
+<style id="omnivideo-slide">:root{ --slide-i:2; --slide-n:8; --slide-w:1080px; --slide-h:1350px; }</style>
+<script>window.OMNICAROUSEL = { slide, index, total, format, slides: [{ id, role }] }; window.OMNICARROSSEL = { … }</script>
+```
+
+`index` and `--slide-i` start at 0. `window.OMNICARROSSEL` is the same object
+with the PT keys (`indice`, `formato: { proporcao, w, h }`, `slides: [{ id,
+papel }]`), kept for slide code written before the English migration.
+`_common.html` goes in place of `<!-- omnivideo:common -->` (the old
+`<!-- omnivideo:comum -->` and `src/_comum.html` are still accepted), except
+its `<style>`s, which go up to the start of the `<head>`: they are the base,
+and the slide's `<style>` overrides. `data-free` (old: `data-livre`) exempts
+an element from the margin check.
+
+## Invalidation
+
+| changed | becomes invalid | who redoes it |
+|---|---|---|
+| `src/<id>.html` | the slide's PNG | `build --slide <id>` |
+| `_common.html`, the order, the number of slides or a slide's `role` | every PNG (the counter and `OMNICAROUSEL` change) | `build` |
+| any PNG | the export | `export` (`publish.mjs carousel` exports on its own if missing) |
+
+`carousel.mjs status` checks all of this through the hash of each slide's
+final HTML.

package/reference/cloud.md

@@ -0,0 +1,96 @@
+# The cloud
+
+What runs in the cloud. One Cloudflare Worker (`cloud/omnichat`) over Postgres (Neon, São Paulo),
+R2 and KV, with the same core as the CLI (`tools/lib`). No LLM and no render there: whatever needs Claude,
+ffmpeg or the files is done on the Mac, before (scheduling) or after (mirroring the results).
+
+| job | config flag | what the cloud does | what the Mac still does |
+|---|---|---|---|
+| omnichat | `cloud.omnichat` | Meta's webhook (comment → DM in seconds, button taps), a fallback pass every 30 min | the uncertain comments, by hand in the UI; mirrors the record for the studio |
+| metrics | `cloud.metrics` | reads every published Reel every hour (age milestones) | measures the MP4 duration; its agent pulls the records into `metrics.json` |
+| schedule | `cloud.schedule` | publishes at the time, one short step a minute | text, ffprobe, cover, omnichat plan and the upload when scheduling; its agent writes the outcome into `publication.json` |
+
+Why it is built this way (Workers, Neon, R2, the runner channel): `docs/adr/`; the product: `docs/prd.md`.
+Details: omnichat in `reference/omnichat.md` (In the cloud), the schedule in `reference/publish.md`
+(Schedule → In the cloud). The token of each platform lives sealed in the database (`TOKEN_KEY`); the CLI
+and the studio talk to the Worker with `OMNICHAT_CLOUD_SECRET` (the Worker's `SYNC_SECRET`).
+
+## The pieces
+
+- **Worker** `omnichat` at `https://omnichat.omnichat-worker.workers.dev` (`cloud/omnichat/wrangler.toml`):
+  crons every minute (schedule, gated by KV), every 30 min (omnichat), hourly at :05 (metrics) and
+  daily at 6:17 (token renewal). Deploy: `cd cloud/omnichat && npx wrangler deploy`.
+- **Postgres** Neon project `omnivideo` (`aws-sa-east-1`): `cloud/omnichat/schema.sql` (idempotent:
+  `psql "$(npx neonctl connection-string --project-id orange-cake-45887285)" -f schema.sql`).
+- **R2** `omnivideo-media`: the scheduled MP4s and covers, deleted when the job ends (and by a 7-day rule).
+- **KV** `omnivideo-kv`: `schedule:next`, so the minute cron only wakes the database when something is due.
+- **Worker** `omnivideo-studio` (`cloud/studio`, at `https://omni.crievo.com`): the hosted studio. It serves the
+  built web (`cd studio && bun run build`) and forwards `/api/*` and the file paths to the Mac through
+  the RunnerHub Durable Object, over the WebSocket the Mac opens (`bun studio.ts --runner`, or
+  `cloud.studio: true` with `cloud.studio_url`). Login with Google (Better Auth over Neon, only the
+  emails in `ALLOWED_EMAILS`); the Mac pairs with `node tools/runner.mjs login` and connects with its
+  key (`OMNIVIDEO_RUNNER_TOKEN`); `<studio>/runner` lists the Macs, with "Desconectar". While the studio
+  isn't connected, every request answers 503 and the page shows its own screen (`StudioOffline`: what happened, what to do on the Mac, a retry button, a check every 5 s). The hub remembers when the Mac was
+  last connected and what kept it out (`presence.mjs`: its key refused, the protocol versions apart, a
+  "Desconectar"), and that screen says the matching step (`web/lib/studio-offline.ts`). A refused key repairs
+  itself: the runner asks the cloud whether the key still holds and, if not, pairs again, opening the
+  approval page on the Mac (at most once an hour; never after a "Desconectar", which is the user's call).
+  `node tools/runner.mjs service install` keeps the studio on as a macOS service (starts at login, comes
+  back if it stops, log in `.runner/studio.log`; `service restart` after a `git pull`). Setup:
+  `node cloud/studio/setup-auth.mjs` (tables and secrets), then `npx wrangler deploy` in `cloud/studio`.
+  Every write that goes through to the Mac is logged (email, method, path, status; the last 2000, at
+  `<studio>/runner/audit`) and limited to 120 a minute per user (429 beyond it); a runner and a hub on
+  different protocol numbers refuse each other and say which side is old.
+  Protocol in `tools/lib/channel.mjs`, plan in `docs/specs/phase-1-split-api.md`.
+- **Each job has an off switch in the database** (`settings`: `active`, `metrics_active`,
+  `schedule_active`), set by `cloud push` from the config flag: the cloud never does a job while the Mac
+  still does it.
+
+## Turning a job over to the cloud
+
+1. `cloud.<job>: true` in `omnivideo.config.json`.
+2. The job's push: `omnichat.mjs cloud push --records --force`, `metrics.mjs cloud push`,
+   `publish.mjs cloud push`.
+3. Omnichat only: Meta's Callback URL to `<worker>/webhook`, then `omnichat.mjs agent uninstall`.
+
+Turning back: the flag to `false` and the push again (the cloud stops), and the local agent on.
+
+## Free plans and their limits
+
+- **Workers Free:** 10 ms of CPU and 50 subrequests per run. That is why a cloud pass sends at most 5 DMs
+  and the schedule goes one step a minute. Workers Paid ($5/month) lifts both if a post or an upload needs it.
+- **Neon Free:** 100 compute-hours a month; the database sleeps after 5 min without queries and wakes in
+  about a second. Nothing may query it every minute (the KV gate is for that).
+
+## To do
+
+### Alerts when something goes wrong
+
+Today an error in the cloud is only written down: `omnichat_log`, a comment's `failed` state, a schedule
+step's `last_error`, the account's `paused_until`. The studio shows the pause and whether the cloud
+answers, but nobody is told. Needed:
+
+- **What raises an alert:** a scheduled post that gave up on a platform (`failed`) or is still processing
+  past its time; the account paused by Meta (rate limit, block, token without permission); a token that
+  expired or was refused (Instagram, YouTube, TikTok), and one close to expiring (Instagram below 7 days,
+  TikTok's refresh token); the webhook answering errors (Meta retries, then drops the subscription); the
+  metrics failing for every Reel; the Worker throwing (Error 1102 for CPU, uncaught exceptions); the
+  database unreachable.
+- **Where it shows:** an `alerts` table in the cloud (kind, subject, message, first and last time, count,
+  resolved), deduplicated by kind and subject so a failure that repeats each minute is one alert; the
+  studio reads the open ones as a banner and a list; the CLI's `cloud status` lists them.
+- **How it reaches you with the studio closed:** a push the moment a critical one opens (a schedule that
+  failed, a paused account, a refused token) by email (Resend) or a Telegram bot, chosen in Settings; the
+  rest in a daily digest. Resolving: on its own when the condition clears (the post went up, the pause
+  ended), or by hand in the studio.
+- **The Worker's own health:** Cloudflare's Workers Logs or a tail into the alerts for 1102s and
+  exceptions, and a daily check that the crons ran (a `last_run` per cron in `settings`).
+
+### Next steps of the infrastructure
+
+- The monorepo of the plan (`apps/web`, `apps/cloud`, `apps/runner`, `packages/core`, `packages/contract`):
+  confirm before moving, since every path in the project changes.
+- Phase 1 (the studio's API split between the cloud and the runner, the studio web hosted, the
+  runner's outbound channel, Better Auth login): steps 1–3 live since 2026-10-17 (at first on
+  `omnivideo-studio.omnichat-worker.workers.dev`, now `https://omni.crievo.com`); the stream reconnecting checked in a browser the
+  same day. Spec: `docs/specs/phase-1-split-api.md`.