Core concepts

Four objects, in a line. Understanding them explains most of the product.

Idea ──promote──► Draft ──schedule──► Slot ──tick──► published
                     │
                     └─ your click is the approval, unless it needs a review window (see below)

Idea

A one-line thing worth writing about. Ideas live in Planning, in the Library view.

Where they come from, as recorded on each idea:

Source	Meaning
commit	Mined from git history
vault	Mined from a notes folder
manual	You typed it
research	Generated from a saved post in Inspiration
import	Pushed through the API or MCP
backfill	Created by a historic backfill

Statuses:

Status	Meaning
new	In the inbox, not triaged
shortlisted	Kept for later
promoted	Turned into a draft
dismissed	Not doing it

An idea also carries a format (text, reel, carousel, video) and a pillar. A text idea can hold a longer story, the source material a version is written from, and a version per connected network: its own text for that network, never published on its own. See Planning.

Everything that pushes ideas from outside, the CLI and MCP, creates them at new. Nothing external can move one past that.

Draft (post)

The actual content. A draft has no platform: its real destination is the channels picked when it is scheduled. Drafts live in Planning, in the list and calendar views.

Status	Meaning
idea	Not yet promoted
draft	Being worked on. The only status you can edit freely from
awaiting_approval	AI-written, sitting in the review queue for a permitted human's first click
approved	Signed off. Now it can be scheduled
rejected	Killed. Recoverable back to draft

scheduled and published are not stored statuses: they are what the UI shows once a publication exists (a pending one reads "scheduled", a published one "published"), derived from the approval status plus the post's publications.

Format (the old "type"): text, reel, carousel, video. A format is a shape, never a network: a text post can go to LinkedIn, Threads or Bluesky, and a carousel to any carousel-capable channel.

Approval

A human always approves a post before it can be scheduled or published, but who that click is depends on who wrote the text and who is clicking:

• A permitted human clicking Schedule or Post now on their own account is the approval, in the same click, whoever wrote the text. There is no separate Approve step to find first.
• The review window (a draft sitting awaiting_approval, expiring if nobody approves it before its scheduled time) applies only to content a permitted human has not yet clicked on: AI-written drafts nobody has reviewed, and anything scheduled by someone without approval permission.

See Approve and schedule.

The one exception to all of this is Mark posted, which moves a draft to published because you posted it by hand somewhere. It records reality, it does not publish anything.

Schedule slot (publication)

A booking: this draft, on this account, at this time.

Status	Meaning
pending	Waiting for its time
publishing	In flight right now
published	Done
skipped	You cancelled it
failed	It went wrong
expired	Its time passed with nobody approving the post

One approved draft can have several slots, which is how cross-posting works: the same draft to Instagram and Bluesky at different times, with different captions.

How publishing actually runs

A scheduler ticks every minute and dispatches due, approved slots. Each publish is a background job with several attempts and increasing backoff.

Why a failed slot never double-posts

A slot moves to publishing before any network call, and the connector writes a journal entry immediately before the irreversible "go live" call.

So if a retry finds a slot where the commit was attempted, there was no clean failure, and no post id came back, it does not publish again. It fails the slot and asks you to verify manually. Posting twice is worse than posting late.

On failure, the draft stays scheduled rather than reverting, so you can inspect and retry.

Recovering a failed slot

In the Queue:

• Retry puts it back to pending. It does not re-run immediately, the next tick picks it up.
• Skip marks it skipped. One-way.
• Reschedule moves a pending slot to another time. It refuses a time already booked for the same account.

Brand and account

Brand is a workspace: its own identities, drafts, connections, queue, metrics, contacts. In the API and in code a brand is called a team.

Account is the billing container. One subscription, owning one or more brands. How many comes from the brands allowance on your plan.

There is no account switcher, only a brand switcher, because you only ever have one account.

Identity versus persona versus voice

Three different things feed the AI or the render.

Identity (formerly "content profile") is per brand, and there can be several. Name, handle, URL, accent colour, a logo and a photo. It styles a carousel's slides; it carries no voice.

Persona is one per brand, set on Settings → Brand. Your niche, your audience, what to avoid. It grounds everything.

Voice is one per brand, set on Settings → Voice. Non-negotiables, structure, a writing sample, per-network overrides, and your content pillars.

Rule of thumb: persona is who you are, voice is how you sound, identity is who a carousel's slides speak as.

Timezones

Two of them, deliberately.

Posting schedule timezone, set per brand in Settings, decides when your posts go out. This is the one you care about.

Deployment timezone is what the background jobs run in. It affects when metrics sync and when scans run, not when your content publishes.

What is automatic and what is not

Step	Who
Mining ideas from commits	Automatic, if you run the CLI
Generating ideas from research	You click a button
Writing a draft	AI, on your click
Approving	A permitted human's Schedule or Post now click, or an explicit Approve for content still in the review window
Scheduling	You. Always
Publishing at the slot	Automatic
Posting an outreach comment	You, by hand. Postlyra never posts these
Replying to a DM	You type it, you click send
An automation's DM reply	Automatic, sending text you wrote and activated
Syncing metrics	Automatic, nightly