> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useharmonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# The Pipeline

> Stage by stage: ingest, transcribe, understand, strategize, approve strategy, plan, draft, approve effects, publish, verify, learn.

Harmonia's pipeline is a linear stage machine. Each completed stage persists its payload and atomically records the next trigger in a Firestore outbox. Pub/Sub publication is claimed and finalized from that outbox; the durable tick recovers pending delivery after a crash.

```mermaid theme={"system"}
flowchart LR
    Q[queued] > I[ingest] > T[transcribe] > U[understand] > S[strategize] > SA[awaiting_strategy_approval] > P0[plan] > D[draft] > A[awaiting_approval]
    A -- approved --> P[publish] > V[verify] > L[learn] > C[complete]
    A -- rejected/skipped --> C2[complete]
```

## ingest

Resolves the video id, fetches official metadata (YouTube oEmbed; Data API adds duration when `YOUTUBE_API_KEY` is set), downloads bestaudio via yt-dlp, and — when the Data API is unavailable — measures the real duration locally with ffprobe so downstream stages never see a zero-length timeline.

## transcribe

Gemini 3.5 Flash returns `{language, segments:[{id,startSec,endSec,text}]}` from the audio inline payload.

## understand

Nimi receives the typed source package and returns `SourceAnalysis`. Deterministic validation checks
source identity, evidence bounds, provenance, confidence, and analysis-only authority before persisting
the complete object and canonical digest. Ryan receives that exact persisted analysis. See
[Nimi](/agents/nimi) for its method and [agent contracts](/reference/agent-contracts) for the handoff.

## strategize

Ryan turns the persisted analysis and bounded operator, performance, and eligible Memory Bank context
into one four-week `ContentStrategy` with grounded briefs. Application code validates its evidence
lineage and authority, then persists the proposal, version, and canonical digest. See
[Ryan](/agents/ryan) for the strategy method.

## awaiting\_strategy\_approval

An authenticated human decision must match the current strategy digest. One rejection with required
operator feedback permits strategy version 2; a second rejection terminates the job. Temi cannot run
for a missing, rejected, expired, or mismatched approval. Dashboard, chat, and allow-listed Telegram
decisions use the same tenant-scoped transaction.

## plan

Application code persists one immutable planning snapshot containing capabilities, commitments,
capacity, cadence policy, posting-window observations, assets, dependencies, and calendar projection.
Temi receives its exact ID and digest alongside the unchanged approved strategy and Nimi analysis.
After validating and persisting Temi's plan, deterministic code selects one eligible item for
production. Temi never mutates an external calendar. See [Temi](/agents/temi).

## draft

Noni receives only the selected editorial item, exact Ryan brief, and referenced Nimi evidence. Dara
reviews the exact draft against immutable input. Deterministic code permits at most one issue-bound
Noni revision, validates the complete trace, and prepares effect proposals from accepted content. See
[Noni](/agents/noni) and [Dara](/agents/dara); the full skills and tools inventory is
[here](/reference/agent-runtime-inventory).

Every action lands with `requiresApproval`, risk level, and its own idempotency key material.

## awaiting\_approval

Hard gate for X publishing and paid Veo/Lyria generation. Approvals arrive through the dashboard queue, chat ("approve job \<id>"), or a Telegram inline-button callback — all through the same decision engine, which records who approved what and when. Content-pack export, Gemini image generation, and local ffmpeg rendering are internal artifact actions with `approvalState: not_required`; they never inherit a fictional human decision and do not publish anything.

## publish

Executes policy-authorized actions in order, checking effect claims and receipts first for idempotency. Approval-required actions must carry the exact matching decision; internal artifact actions execute under their deterministic safe-action mandate:

| Action                        | Effect                                                          |
| ----------------------------- | --------------------------------------------------------------- |
| `publish_x_post`              | POST to X API v2 `/2/tweets`; receipt carries post id + URL     |
| `export_content_pack`         | Markdown bundle of moments, angles, drafts stored with a digest |
| `generate_image`              | Gemini image bytes into the asset store                         |
| `render_clip` / `render_reel` | Real ffmpeg cuts/captions/reframes into the asset store         |

Failures are classified: permanent errors stop the job visibly, transient errors nack for redelivery.

## verify

Independent re-fetch of every executed action: tweets re-read from X by id, pack digests compared against Firestore, asset digests re-checked from the store. Results are immutable verification records — the receipt says what we *did*, verification says what is *true*.

## learn

Measures published posts via public metrics, derives evidence-linked takeaways, and stores eligible facts for future Nimi analysis and Ryan strategy inputs.