@gentbajko/slopify 2.5.0 → 3.0.1

package/dist/tutorials/Providers-and-Keys.md

@@ -0,0 +1,290 @@
+# Providers and Keys
+
+Slopify does no AI work itself: it calls providers you set up, on your own accounts. This page lists every provider, where to get each key, how to save and test it, how **Check all** checks everything at once, and how to add voices in **Settings → Voices**.
+
+**Where to find it:** Settings → Providers (keys, command-line tools and the system voice), Settings → Voices (voice IDs).
+
+## How providers are organised
+
+Settings → Providers shows three lists, one per kind of work. Each row says whether the provider is ready. Pick a row to open its setup beside the list: the steps, the key field or the command, and the actions.
+
+| List | What it makes | Providers |
+|---|---|---|
+| **Text** | Research, script, article, titles, descriptions, reviews | OpenRouter (API key), Claude Code CLI, Codex CLI, Gemini CLI (command line) |
+| **Speech** | Narration | ElevenLabs, OpenAI, Cartesia, Inworld, Google Gemini (API key), System voice (built in, no key) |
+| **Images** | Images, thumbnails, animated clips | fal.ai, Replicate, OpenAI, Google (API key), Codex CLI (command line) |
+
+Row states:
+
+| State | Meaning |
+|---|---|
+| **Key saved** | A key is stored for this provider. |
+| **No key** | No key yet; the provider is not selectable on Play. |
+| **Ready** | A command-line tool was found and is usable. |
+| **Needs attention** | The tool was found but something is wrong, for example Codex CLI is older than 0.149.1. |
+| **Not found** | The tool is not on this computer (or not at the saved path). For the System voice: no speech program was found. |
+
+Each row also says what kind it is: **Command line**, **Built in, no key** or **API key**.
+
+The command-line tools (Claude Code, Codex, Gemini) need no key: they use the sign-in you already have. They are covered on [AI CLIs](AI-CLIs).
+
+On a fresh install with no key saved, the page says **Paste a key to make its provider selectable on Play.** On the first launch Slopify also looks for the command-line tools. If it finds one it says so, names what it found and picks it on Play; choose **Got it** to hide that message. Narration needs no key either: without a voice key, the [System voice](#the-system-voice) reads it with your computer's own speech.
+
+## Where your keys are kept
+
+- A key is stored on this computer only and sent only to its own provider.
+- It is never put in a backup or an export. After you import a backup on another computer, enter your keys again.
+- A saved key is shown as a fixed row of dots, never any part of it.
+- Slopify reads the key when each call starts, so a key you change mid-run is used from the next call.
+- Readiness is checked again before each run.
+
+## Add a key
+
+1. Open **Settings → Providers**.
+2. Pick the provider in its list (for example **ElevenLabs** under **Speech**).
+3. Follow the numbered steps shown beside it. They link to the provider's sign-up page, the page that makes the key and, where there is one, its billing page. Once a key is saved, the steps fold under **Where to get a key**.
+4. Paste the key in **<Provider> API key**.
+5. Optional: choose **Test** to check the pasted key before you keep it. See [Test a key](#test-a-key).
+6. Choose **Save**. A tick shows beside Save for a moment.
+
+To replace a key, paste the new one and choose **Save**. To remove it, choose **Remove**, then **Remove key**. Projects that used that provider cannot retry until a key is saved again.
+
+The info button beside each provider's name says what it does and how it bills.
+
+## Test a key
+
+**Test** asks the provider whether a key works, with the cheapest harmless call it allows (such as listing its models). Nothing is generated or billed. The answer waits up to 15 seconds.
+
+- **Before saving:** with a key pasted in the field, Test checks that pasted key. It is sent only to its own provider, never stored and never logged. When it passes, the answer adds "It is not saved yet: choose Save to keep it."
+- **After saving:** with the field empty, Test checks the saved key.
+
+With neither, Test is greyed out: "Paste a key first."
+
+| Answer | What it means | What to do |
+|---|---|---|
+| Accepted | The key works. Except for OpenRouter, credit is only checked when Slopify first generates with it. | Nothing. |
+| Did not accept (HTTP 401) | Mistyped, revoked or for another account. | Make a new key, Save, Test. |
+| No credit (HTTP 402) | Key accepted, but the account has no credit or payment method. | Add credit on the provider's billing page. |
+| Refused (HTTP 403) | The key is restricted, or the account needs verifying or billing set up. | Check the permissions listed for that provider below. |
+| Too many requests (HTTP 429) | The key is usually valid. | Wait a minute and Test again. |
+| Problem on its side (HTTP 5xx) | The provider is having trouble. | Wait a few minutes and Test again. |
+| Did not answer / could not reach | No answer within 15 seconds, or no connection. | Check your internet, firewall or proxy. |
+| Unexpected answer | Anything else. | Check the key; if it keeps happening, use **Download diagnostics** in Settings and report it. |
+
+## Text providers
+
+### OpenRouter
+
+Writes the text with hundreds of models from many companies through one key. Charged per token from credit you buy on OpenRouter; prices follow the model catalogue (see [Models](Models)).
+
+1. Sign up at openrouter.ai/sign-up.
+2. Open **Credits** (openrouter.ai/settings/credits) and buy credit. Paid models are charged from it; a negative balance stops even free models.
+3. Open **Keys** (openrouter.ai/settings/keys), choose **Create API key**, and copy it.
+4. Paste it in Slopify, **Save**, then **Test**.
+
+Keys have no scopes. If you set a credit limit on the key, keep it above what a run costs. OpenRouter is the only provider whose Test also shows missing credit.
+
+### Claude Code CLI, Codex CLI, Gemini CLI
+
+No key. See [AI CLIs](AI-CLIs).
+
+## Speech providers
+
+### ElevenLabs
+
+Narrates with ElevenLabs voices, including voices you added to your ElevenLabs account. Billed in characters of narration from your ElevenLabs plan.
+
+1. Sign up at elevenlabs.io/app/sign-up.
+2. Open **Developers → API keys** (elevenlabs.io/app/developers/api-keys), choose **Create key**, and copy it.
+3. Paste it in Slopify, **Save**, then **Test**.
+
+A restricted key needs **Text to Speech** access and **Models** read access (models_read) for Test; Voices read helps when picking voices. Remove any credit quota or IP allowlist that would block this computer.
+
+### OpenAI (speech)
+
+Narrates with OpenAI's text-to-speech voices. Billed per character or per audio minute, depending on the model, from prepaid credit on your OpenAI platform account.
+
+1. Sign up or sign in at platform.openai.com/signup.
+2. Open **Billing** and buy prepaid credit. New accounts need at least $5 before any call works.
+3. Open **API keys** (platform.openai.com/api-keys), choose **Create new secret key**, and copy it. It is shown once.
+4. Paste it in Slopify, **Save**, then **Test**.
+
+A key with All permissions works. A restricted key needs **Models: Read** (for Test) and **Model capabilities: Request** (for speech and images).
+
+OpenAI appears twice in Settings, once under **Speech** and once under **Images**. Each has its own key field, so you can key one without the other. You can paste the same OpenAI key into both.
+
+### Cartesia
+
+Narrates with Cartesia voices, billed in characters from your Cartesia plan. The free plan needs no card, so it is an easy way to try narration.
+
+1. Sign up at play.cartesia.ai/sign-up.
+2. Open **API Keys** (play.cartesia.ai/keys), create a key, and copy it. It starts with `sk_car_`.
+3. Paste it in Slopify, **Save**, then **Test**.
+
+Keys have no scopes.
+
+### Inworld
+
+Narrates with Inworld voices, billed per character from your Inworld account.
+
+1. Sign up at platform.inworld.ai/signup.
+2. Open **API Keys** (platform.inworld.ai/api-keys) and choose **Generate new key**. It must be a Standard key; Realtime-only keys do not work.
+3. Copy the **Base64 credentials** value exactly as shown, without encoding it again.
+4. Paste it in Slopify, **Save**, then **Test**.
+
+On Play, choose the TTS-2 or TTS-2 Flash model and an Inworld voice (for example `Dennis`, or a voice from your workspace).
+
+How long text is handled:
+
+- Short text streams straight away.
+- With TTS-2, text over 4,000 characters goes as one async job of up to 100,000 characters. Inworld caps On-Demand accounts at 10,000. The audio is ready once the job finishes.
+- TTS-2 Flash sends parts of at most 4,000 characters. For long articles, pick paragraph chunking.
+- Pausing stops Slopify's own requests, but Inworld may still finish and bill a job it already accepted. Resuming starts a new request for any unfinished narration.
+
+Some features need Inworld: Narration Preparation and pronunciations need an Inworld TTS-2 model. See [Play-Narration](Play-Narration) and [Narration-Aliases-and-Glossary](Narration-Aliases-and-Glossary).
+
+### Google Gemini (speech)
+
+Narrates with Gemini's 30 prebuilt voices, billed per text and audio token on your Gemini API key. It uses the key saved for [Google images](#google): with one saved there, nothing is needed here. You can also save a key of its own under **Google Gemini** in the **Speech** list.
+
+Pick a Gemini voice in Settings → **Voices** (see [Add a voice](#add-a-voice)). With two speakers on Gemini voices (a podcast or interview, see [Multiple Voices](Multiple-Voices)), their consecutive turns go in one two-speaker request; a third voice starts a new request.
+
+### The system voice
+
+The **System voice** narrates with your computer's own speech program: free, no key, and no account. It sounds robotic, so it is best for trying Slopify out; add a keyed voice when you want a better one. A first 60-second short uses it when no voice key is saved (see [Your First Short](Your-First-Short)).
+
+Slopify looks for a speech program each time and uses the best one it finds:
+
+| System | Speech program |
+|---|---|
+| macOS | macOS voices (the built-in `say`) |
+| Windows | Windows voices (System.Speech, through PowerShell). Add voices in Windows Settings → Time & language → Speech. |
+| Linux | Piper, SVOX Pico, eSpeak NG or eSpeak, best first. Install one, for example `sudo apt install espeak-ng`, `sudo pacman -S espeak-ng` or `sudo dnf install espeak-ng`. Piper needs its voice models listed in `SLOPIFY_PIPER_VOICES`, and counts only when `piper --help` shows Piper's own options (the mouse settings app also called piper is left out). |
+| Docker | The image includes eSpeak NG. If it is missing, update the image. |
+
+Pick **System voice** in the **Speech** list to see what was found: "Found *engine*. Narration with it is free; a keyed voice (ElevenLabs, OpenAI) sounds better.", each program with its number of voices, and **Add a system voice**, which opens Settings → **Voices**. When nothing is found, it says what to install on your system. On Play it is offered as a TTS provider like the others, greyed out as **Speech Program Missing** when nothing is found.
+
+## Image providers
+
+### fal.ai
+
+Draws images and thumbnails with the models fal.ai hosts, charged per image from prepaid credit. fal.ai locks the account when the balance runs out, so a run stops at the images step until you add credit.
+
+1. Sign up at fal.ai/login.
+2. Open **Billing** (fal.ai/dashboard/billing) and buy credit.
+3. Open **Keys** (fal.ai/dashboard/keys), choose **Add key** with the **API** scope, and copy it.
+4. Paste it in Slopify, **Save**, then **Test**.
+
+The API scope is enough; Slopify does not need an ADMIN key.
+
+### Replicate
+
+Draws images and thumbnails with the models Replicate hosts, charged per image or per second of compute from credit bought up front.
+
+1. Sign in at replicate.com/signin.
+2. Open **Billing** (replicate.com/account/billing) and buy credit. Replicate needs credit before it runs paid models.
+3. Open **API tokens** (replicate.com/account/api-tokens), create a token, and copy it. It starts with `r8_`.
+4. Paste it in Slopify, **Save**, then **Test**.
+
+Tokens have no scopes.
+
+### OpenAI (images)
+
+Draws images and thumbnails with OpenAI's GPT Image models, charged per image from prepaid credit on your OpenAI platform account. Get the key as for [OpenAI speech](#openai-speech). GPT Image may also need **Verify Organization** under Settings → Organization → General on the OpenAI platform before it works.
+
+### Google
+
+Draws images and thumbnails with Google's Gemini image models, charged per image.
+
+1. Sign in to Google AI Studio (aistudio.google.com) with your Google account.
+2. Open **Projects** and choose **Set up billing** next to your project. Gemini image models are not on the free tier.
+3. Open **API keys** (aistudio.google.com/apikey), choose **Create API key**, and copy it.
+4. Paste it in Slopify, **Save**, then **Test**.
+
+Use a key made in AI Studio. An older Google Cloud key must be set to **Restrict to Gemini API only**, or Google rejects it.
+
+Google Gemini voices use this same key (see [Google Gemini (speech)](#google-gemini-speech)).
+
+### Codex CLI (images)
+
+Draws images with your ChatGPT sign-in instead of a key. See [AI CLIs](AI-CLIs#codex-images).
+
+## How many calls run at once
+
+| Provider | Calls at once |
+|---|---|
+| OpenRouter, ElevenLabs, OpenAI (speech and images), Cartesia, fal.ai, Replicate, Google | 3 |
+| Inworld | 5 |
+| Claude Code, Codex, Gemini (text) | 3 |
+| Codex CLI (images) | 4 |
+
+The keyed providers' numbers come from the model catalogue.
+
+## Check all providers
+
+**Check all** runs every check at once. Run it after changing a key, or when a run stops at a provider.
+
+1. Open **Settings → Providers**.
+2. Choose **Check all** at the top of the page (or press `Ctrl+K` and run **Check all providers**).
+3. Read the **Health check** section under the lists.
+
+For each provider it checks:
+
+- **Installed** and **Signed in** for a command-line tool. Gemini CLI's sign-in is read from its own files in `~/.gemini` (the sign-in method in `settings.json`, the Google sign-in in `oauth_creds.json`, or `GEMINI_API_KEY`), without starting it. When the files don't say, it tells you to run `gemini` once to confirm.
+- **Speech program found** for the System voice, with the program it speaks with.
+- **Key saved** and **Key valid** for a keyed provider, using the same call as **Test**. Nothing is generated or billed.
+- **Model reachable** for a keyed provider: Slopify asks the provider, with the saved key, about each model you chose (its model page, or the model list for OpenRouter and ElevenLabs), without generating anything. It reads, for example, "OpenRouter answered for … with this key." A provider with no such check says so.
+- **Chosen models**: that the models your templates, schedules, drafts and unfinished projects use are still offered. A retired one points you to **Switch** in Settings → Models (see [Models](Models#switch-away-from-a-retired-model)).
+
+Each provider's row has **Check again**, which checks that provider alone; its result replaces the row until the next **Check all**. It is the quick way to confirm a fix, such as signing a CLI in again.
+
+| Result | Meaning |
+|---|---|
+| **Ready** | Every check passed. |
+| **Check** | Something might stop a run, such as a rate limit or the provider being down during the check. |
+| **Needs fixing** | Something will stop a run. The line says how to fix it. |
+| **Not set up** | Neither set up nor used anywhere. These are listed together on one line. |
+
+The report stays while you move between Settings sections.
+
+## Add a voice
+
+Narration needs a voice ID from your speech provider. Slopify does not check the ID when you add it; a wrong ID fails when a run's narration uses it.
+
+1. Save a key for the speech provider in **Settings → Providers** (the Provider list only shows speech providers).
+2. Find the voice ID in the provider's voice library and copy it.
+3. Open **Settings → Voices**.
+4. Under **Add a voice**, fill in the fields and choose **Add voice**.
+
+| Field | What it does | Rules |
+|---|---|---|
+| **Voice name** | The name you pick the voice by on Play and in Edit project. Only you see it. | Required, up to 200 characters. Names can repeat. |
+| **Provider** | The text-to-speech service the ID belongs to. | Speech providers only. |
+| **Voice ID** | The provider's own ID for the voice. For Inworld, use an ID such as `Dennis`, or one from your workspace. For **System voice** it is a list of the voices found on this computer, grouped by speech program (**Pick a voice**); for **Google Gemini**, a list of Gemini's voices (**Pick a Gemini voice**). Picking one fills in the name too. | Required, up to 200 characters, unique per provider. |
+| **Languages** | The languages the voice speaks, as codes such as `es, de`. Play lists the voice only for projects in these languages. | 2 or 3 letter codes. Blank asks the provider when it can say; a voice with unknown languages shows as **Any (not known)** and is offered for every language. |
+
+## Manage your voices
+
+The **Voices** table lists **Name**, **Provider**, **Voice ID**, **Languages** and **Real person** for each voice.
+
+- **Edit** in the Languages cell changes the codes; choose **Save** or **Cancel**.
+- **Real person**: turn it on for a voice cloned from, or made to sound like, a real person. Prepare upload then answers Yes to YouTube's AI use question for videos it narrates. An AI voice that imitates no one stays off. Default: off. See [Publishing-to-YouTube](Publishing-to-YouTube).
+- **Remove**, then **Remove voice**, deletes it from the list. Projects that used the voice keep the audio they made with it.
+
+For projects with more than one narrator, see [Multiple-Voices](Multiple-Voices). For voices in other languages, see [Other-Languages](Other-Languages).
+
+## Tips
+
+- The cheapest way to start: sign in to a command-line tool for text and images, and use the System voice (free) or Cartesia's free plan for narration.
+- A Test that passes does not prove the account has credit (except on OpenRouter). The first real generation does.
+- If you share a machine, keep Slopify bound to `127.0.0.1`: anyone who reaches its port can use your keys.
+
+## Related pages
+
+- [AI CLIs](AI-CLIs)
+- [Models](Models)
+- [Costs and Run Cost](Costs-and-Run-Cost)
+- [Settings Reference](Settings-Reference)
+- [Play Narration](Play-Narration)
+- [Multiple Voices](Multiple-Voices)
+- [Troubleshooting](Troubleshooting)

package/dist/tutorials/Publishing-to-YouTube.md

@@ -0,0 +1,135 @@
+# Publishing to YouTube
+
+Slopify never uploads or publishes for you: there is no YouTube sign-in and no upload API. Instead, **Prepare upload** lists everything YouTube Studio asks for, in the order it asks, with a Copy button for each value, for the long video and for every short. You upload in Studio in your own browser and press Publish yourself. The optional [Studio-Extension](Studio-Extension) can fill Studio's upload dialog from the same list.
+
+**Where to find it:** a finished project → **Prepare upload** (the next action, and in the **YouTube** section), Home → **Ready to upload** → **Prepare upload**, or the Calendar's **Needs you** → **Prepare upload**. Settings → **YouTube Studio** holds the playlist, and each channel's **Brand** tab holds the links it uses.
+
+## Before your first upload
+
+1. Open **Settings → YouTube Studio** and type your **Playlist** name exactly as it is called in Studio (up to 150 characters), then press **Save**. It is the default for every channel; pick a channel in the list above the field to give that channel its own playlist. Leave it empty for no playlist.
+2. Open **Channels** → your channel → **Brand** and, under **Channel links**, add any links your descriptions use, such as `Patreon` or `Discord`. See [Channels](Channels#channel-links).
+3. In **Settings → Voices**, turn on **Real person** for any voice cloned from, or made to sound like, a real person.
+4. In **Library → Prompts**, turn on **Draws photorealistic pictures** for any Image prompt whose style looks like real photos or film.
+5. Turn on **YouTube description** on Play (Outputs row) for new videos, so they come with a description, chapters and tags.
+
+Steps 3 and 4 decide the AI use answer; see [AI use disclosure](#ai-use-disclosure).
+
+## Upload a video
+
+1. Open the finished project and press **Prepare upload**. The button is available once the video has been made.
+2. If the project has shorts, pick what to upload under **What to upload**: **Video**, **Short 1**, **Short 2** and so on. Each is uploaded to YouTube on its own, with its own title, description and tags.
+3. Open YouTube Studio in your browser and start an upload.
+4. Work down the list **In the order Studio asks**, using **Copy**, **Download** or **Open folder** on each row:
+
+| Step | What Prepare upload gives you |
+|---|---|
+| **Video file** | The file name, with **Download** and **Open folder** as small buttons. |
+| **Title** | The project's title (up to 100 characters), or the short's title. **Copy**. |
+| **Description** | The description with chapters and hashtags, links filled in. For a short: its description, the "Watch the full video:" line and its hashtags. **Copy**. |
+| **Thumbnail** | The thumbnail file, with **Open folder**. With three thumbnails: "The first under Thumbnail; all 3 in A/B Testing (beside the title)." Shorts have no thumbnail step, since Studio shows a frame of a short. |
+| **Playlist** | The project's channel's playlist from Settings → YouTube Studio (or the default one), or "None set". **Copy**. |
+| **Audience** | "No, it's not made for kids". |
+| **AI use (under Show more)** | **Yes** or **No**, with the reason. |
+| **Tags (under Show more)** | The tags, comma-separated. For a short, its hashtags without the `#`. **Copy**. |
+
+5. Tick the box beside each step as you go if you like. The ticks are only a note to yourself, remembered in this browser; they change nothing in the project.
+6. Check everything in Studio and publish there.
+7. Back in Slopify, press **Mark uploaded** (see [Mark a video uploaded](#mark-a-video-uploaded)).
+
+Below the list, the thumbnails are shown side by side as **A**, **B** and **C**, each with **Download**.
+
+With the extension installed and paired, press **Fill in YouTube Studio** instead of copying by hand. Each press queues the item under **Waiting for Studio**, so you can queue the video and its shorts and upload them one after another. While no extension is paired, Prepare upload shows how to install and pair it, with **Open YouTube Studio**. See [Studio-Extension](Studio-Extension). Prepare upload ends with "Slopify never publishes."
+
+## When something isn't ready
+
+If a part isn't made yet, Prepare upload says so at the top under "Some of it isn't made yet." and tells you what to do, for example:
+
+- The video isn't made yet: let the Video stage finish (or use Continue the run), then open Prepare upload again.
+- No YouTube description is written: turn on **YouTube description** in Edit project → **Prompts** to have one written with chapters and tags.
+- The thumbnail isn't made yet, or only 1 of 3 thumbnails is made: regenerate the missing ones in the project's Images section.
+- This project makes no thumbnail, so YouTube will pick a frame.
+- No playlist is set: set one in Settings → YouTube Studio.
+- A short isn't rendered yet.
+
+## AI use disclosure
+
+Studio asks every upload one question, behind **Show more**: whether AI was used in one of three ways. In YouTube's words:
+
+1. Makes a real person appear to say or do something they didn't say or do.
+2. Alters footage of a real event or place.
+3. Generates a realistic-looking scene that didn't actually occur.
+
+Selecting Yes adds YouTube's AI label to your video. YouTube does not ask for the label for clearly unrealistic content, minor edits such as colour or filters, or AI used for the script, title, thumbnail or captions.
+
+Slopify answers **Yes only when one of those three cases applies**, and **No** otherwise. An AI narrator and stylised AI pictures on their own are none of the three. Each case is something you mark, and every mark is off until you set it:
+
+| Case | What you mark | Where |
+|---|---|---|
+| 1. A voice that imitates a real person | **Real person** on a voice cloned from, or made to sound like, a real person. A video or short narrated by that voice (the narration voice or any speaker) gets Yes. | Settings → **Voices**, the Real person column |
+| 2. Real footage that is altered | In Prepare upload's AI use step, the switch **The uploaded clip is real footage (filmed, not made by AI)** (or "The N uploaded clips are…"). It appears when the project's images include uploaded video clips. With it on, the video gets Yes when the Look's **Atmosphere** overlay (embers, dust or fog) is laid over them. A colour grade, vignette or grain alone counts as a minor edit and stays No. | Prepare upload, per project |
+| 3. Photorealistic AI pictures | **Draws photorealistic pictures** on an Image prompt whose style looks like real photos or film. A video whose images are drawn from such a prompt, or a short whose **Image style** is one, gets Yes. The Built-in shorts style is not photorealistic. | Library → **Prompts**, in the Image prompt's editor (save the prompt first) |
+
+The AI use step shows the answer and why, naming the case in YouTube's words, for example that the narration uses a named voice marked in Settings → Voices as imitating a real person. When none applies, it says No and lists what was checked.
+
+Shorts are judged on their own: they show new pictures, never your uploaded clips, so case 2 never applies to a short.
+
+### Override per channel
+
+1. Open **Channels**, pick the channel and open its **Brand** tab.
+2. At the top, set **YouTube AI disclosure**:
+
+| Setting | Answer |
+|---|---|
+| **Automatic** (default) | The rule above. |
+| **Always Yes** | Yes for every video and short of this channel. |
+| **Always No** | No for every video and short of this channel. |
+
+It saves as you pick. A channel's Always Yes or Always No wins over every mark. The marks and the channel setting travel with a backup.
+
+## Chapters and the description
+
+The description in Prepare upload is the same one the project page shows: your edits kept, `{{Name}}` links filled in from the project's channel's links (its **Brand** tab) and the project's own **Previous video**. The **YouTube description (.txt)** and **YouTube tags (.txt)** downloads on the project page are this same text.
+
+Its chapters are fitted to YouTube's rules first (the first at 0:00, at least three, each at least 10 seconds). When anything was changed, the Description step says what, in a line starting "Chapters adjusted for YouTube:". To change the text itself, edit it on the project page; see [YouTube-Description](YouTube-Description).
+
+## Edit the description and tags before uploading
+
+Prepare upload shows what the project has; it has no editor of its own.
+
+1. Close Prepare upload.
+2. In the project's **YouTube** section, press **Edit** beside Summary, Chapters, Hashtags or Tags, change it and save.
+3. For a link, paste it under **Previous video for this project** and press **Save links**, or add it under **Channel links** on the channel's Brand tab.
+4. Open Prepare upload again; it shows your edits.
+
+A short's title, description and hashtags come from the shorts pick; to change which moments are used, see [Shorts](Shorts). Its full video line comes from **Full video link** in Edit project → **Shorts**.
+
+## Three thumbnails
+
+With **Thumbnails** set to 3 on Play or in Edit project → Images, Slopify draws the thumbnail prompt twice more with a different composition each time, for YouTube's A/B Testing (it replaced Test & compare). Prepare upload lists all three. In Studio, set the first under **Thumbnail**, then add all three with the **A/B Testing** button beside the title. Each extra thumbnail costs one image. See [Play-Outputs](Play-Outputs).
+
+## Mark a video uploaded
+
+Slopify does not check YouTube, so it can't know when you've published. After you upload:
+
+1. Press **Mark uploaded** on Home under **Ready to upload**, or in the Projects list.
+2. The video leaves the ready-to-upload lists and shows an **Uploaded** badge in Projects.
+3. Press **Undo** beside the badge to take the mark off.
+
+**Mark uploaded** is also a command in the command palette (`Ctrl+K`). Projects has a **Ready to upload** filter for finished videos you haven't marked yet.
+
+## Tips
+
+- Set the playlist once in Settings (per channel if your channels upload to different playlists); every upload pack names it.
+- Upload the long video first, then paste its link as the shorts' **Full video link** so each short's description points to it.
+- If the AI use answer surprises you, read its reason: it names the voice, footage or prompt that made it Yes.
+
+## Related pages
+
+- [Studio-Extension](Studio-Extension)
+- [YouTube-Description](YouTube-Description)
+- [Shorts](Shorts)
+- [Channels](Channels)
+- [Prompts](Prompts)
+- [Home-and-Projects](Home-and-Projects)
+- [Settings-Reference](Settings-Reference)
+- [Video-Editing](Video-Editing)

package/dist/tutorials/Recovery-and-Retries.md

@@ -0,0 +1,141 @@
+# Recovery and Retries
+
+Provider calls fail now and then: a rate limit, a timeout, a dropped connection, a refused prompt. Slopify retries what time can fix by itself, waits for used-up CLI plans instead of failing, and for everything else puts one button on the project page that fixes the cause or walks you through it. Work already made is never thrown away.
+
+**Where to find it:** a project → the next action panel in the right rail, and the failed step's own section.
+
+## What happens when a call fails
+
+Slopify handles a failed provider call in three tiers:
+
+| Tier | What happens | You see |
+| --- | --- | --- |
+| 1. Quick retries | The call is tried up to four times in about 40 seconds: the first try plus retries after 2, 8 and 30 seconds. A provider's own Retry-After (up to a minute) replaces the fixed wait. | Nothing; the step keeps running. |
+| 2. Waiting it out | If the quick retries run out on a failure time can fix, the step is not failed. It waits and runs again by itself, up to four more times, after about 2, 4, 8 and 16 minutes (about half an hour in all). Each wait is spread by a quarter either way, and is never shorter than the provider's Retry-After. | **Waiting to try again**: "Images will try again by itself at 14:05." No button; the run carries on when it does. |
+| 3. Failed | When the waits are used up, or the failure is one time cannot fix, the step fails and says why. | **Failed**, the error, and a fix-it or **Try ... again** button. |
+
+### What is waited out
+
+- Rate limits (HTTP 429 and each provider's own rate-limit errors).
+- Timeouts.
+- Dropped calls: a connection that never reached the provider or broke mid-answer, a provider server error (5xx), or a CLI the system killed mid-run.
+
+### What is never retried
+
+- A refusal by a content filter.
+- A key the provider rejected, or no key saved.
+- A request the provider does not support.
+- A lost CLI submission (Slopify cannot tell whether the CLI already did the work).
+
+These are the provider's final answer, and retrying would only spend your money again.
+
+A provider asking for a wait longer than an hour (a daily quota) is reported as a failure rather than waited out.
+
+### Time limits per call
+
+| Kind of call | Time limit per attempt |
+| --- | --- |
+| Text and narration | 120 seconds |
+| Image | 300 seconds |
+| Image animated into a clip | 900 seconds |
+
+A call that passes its limit is stopped (a streamed call when it sends nothing for that long), and the message says so, for example "The AI model did not answer within 120 seconds. It may be overloaded: wait a few minutes, then use Try again, or choose another model in the Providers section of Edit project."
+
+### Waits survive a restart
+
+The wait is saved in the database, so quitting or restarting Slopify keeps it: the step runs again when its time comes. While it waits the project reads as running. **Pause** holds it.
+
+## Waiting for CLI plan limits
+
+When Claude Code, Codex or Gemini says your plan allowance is used up, the call does not fail: it waits. Slopify stores the reset time for that CLI, and every call to it, from any project, waits until two minutes after the reset. Without a stated reset time it checks again every 30 minutes.
+
+The next action panel shows **Waiting for limits**, for example "Waiting for Codex limits (resets at 14:00)." with "Nothing to do: the run carries on by itself when they reset, and work that does not need Codex keeps going." There is nothing to press. A reset on another day shows the weekday (`Tue 14:00`); with no reset time, it says "(checking again at 14:30)"; with two plans, "Waiting for Codex and Claude limits".
+
+The same words appear everywhere the project shows up: on Home under Running now, on its row in Projects and on the Calendar, so you can tell a waiting run from a stuck one without opening it.
+
+- Other providers are not held up, and a waiting call holds no place in the provider queue.
+- The wait survives a restart: a stage that was waiting when Slopify stopped waits on the stored reset again at the next start.
+- A project paused or cancelled meanwhile is left alone.
+
+See [AI CLIs](AI-CLIs) and [Costs and Run Cost](Costs-and-Run-Cost) for the plan-limit share each run uses.
+
+## Fix-it buttons
+
+A failed step's fix becomes the project's next action, shown in the right rail and beside the step in its section. The mapping lives in one place in the code, so the page always offers the same fix for the same failure.
+
+| Failure | What the panel says | Button | What to do |
+| --- | --- | --- | --- |
+| A CLI is signed out or its sign-in expired | "Codex is signed out, so images stopped." | **Copy sign-in command**, then **Check again** | See [Sign a CLI in again](#sign-a-cli-in-again) below. |
+| A content filter refused an image or thumbnail prompt | "A content filter refused a prompt, so images stopped." | **Soften and retry** | See below. |
+| A content filter refused any other prompt | "A content filter refused a prompt, so the article stopped." | **Edit the prompt** | Opens Edit project so you can reword it, then try again. |
+| The model was retired | "The model for images is no longer offered." | **Switch model** | Opens Edit project; pick another model in **Providers**, save, and try again. |
+| A key was rejected, or none is saved | "The provider did not accept its key, so narration stopped." | **Open Settings → Providers → *provider*** | Paste a current key, save, then come back and try again. |
+| The disk is full | "The disk is full, so the video stopped." | **Free space** | Opens Settings → Backup & storage, which shows what uses the space and offers **Keep outputs only** per finished project. Then try again. |
+| Anything else | "Images stopped with an error." | **Try images again** | Trying again keeps everything already made. |
+
+**Error details** under the message shows the step's own words, for example which key or which model.
+
+The same fix-it buttons appear elsewhere too: Home's **Needs you** offers **Copy sign-in command** for a run stopped by a signed-out CLI, and a schedule whose topic generation failed, or a cast picture that failed, gets the same sign-in fix.
+
+### Sign a CLI in again
+
+1. Press **Copy sign-in command**. It copies `claude auth login` (Claude Code), `codex login` (Codex) or `gemini` (Gemini), and says so.
+2. Paste it in a terminal on the computer running Slopify and sign in.
+3. Press **Check again**. Slopify asks that CLI alone whether it is signed in now.
+   - Signed in: "Codex is signed in. Trying again." and the failed step runs again by itself.
+   - Still signed out: it says so and repeats the command; sign in, then press **Check again** once more.
+   - Can't tell (Gemini sometimes can't say): try the step again with **Try … again**.
+
+If the browser blocks the clipboard, type the command yourself; the notice names it.
+
+### Soften and retry
+
+For a refused image or thumbnail prompt, **Soften and retry** asks first ("Soften the refused prompt and try again?"). When you confirm:
+
+1. Your project's AI model rewrites each refused prompt without what a content filter could flag, keeping the scene and style.
+2. The new wording streams onto the step as it is written.
+3. The image is drawn from it and keeps it as its prompt.
+
+The AI call and the new image are charged like any other. Press **Keep the prompt** to back out and edit it yourself in **Edit project → Images**.
+
+## Try again
+
+**Try ... again** (for example **Try the article again**, **Try images again**) runs the failed step again. It does not ask first, because it destroys nothing: the pieces and outputs already made stay where they are and are reused.
+
+## Done with problems
+
+A failed step stops only the steps that need its output. The video never reads the thumbnail, so a failed thumbnail leaves the video rendering. When the run's main output was made (the video; the narration when there is no video; the article when there is neither) but another step failed, the project ends **Done with problems** instead of **Failed**. Each failed step shows its error and its fix.
+
+## After a crash or restart
+
+- A stage that was **running** when Slopify stopped is marked failed with the reason "interrupted". Nothing re-runs by itself: press **Try ... again**. If the project was paused at the time, the stage simply goes back to waiting.
+- A project that has unfinished work nothing will start on its own shows **Stopped** and **Continue the run**. Continuing makes only what is missing.
+- Steps waiting to retry, or waiting for CLI limits, carry on by themselves after the restart.
+- A queued batch project waits its turn as before.
+
+## Checkpoints and paused runs
+
+A checkpoint holds the run before a step so you can check what came before it. While held, the project shows **Waiting for you** and an **Approve ...** button; nothing after it runs until you approve. Checkpoints are stored with the project, so a restart does not lose them; when you save a new revision, a checkpoint whose reviewed inputs changed asks for your review again (the Checkpoints view says "Inputs changed. Review the current revision before approving."). See [Reviews and Checkpoints](Reviews-and-Checkpoints).
+
+A paused project keeps everything. **Continue the run** picks up where it stopped. See [Project Page](Project-Page#pause-continue-and-cancel-a-run).
+
+## Updating while work runs
+
+Pressing **Update** while a project is being made does not interrupt it. The update waits until no step is running, then installs by itself. Pressing it again drops the wait. See [Updating and Patch Notes](Updating-and-Patch-Notes).
+
+When an update or install cannot finish, Slopify puts the previous version back. The Docker launcher also keeps a recovery copy of your data in a Docker volume before it replaces the container, and names that volume if something goes wrong. See [Docker](Docker).
+
+## Tips
+
+- If a step keeps failing with the same error after **Try again**, open **Error details** and follow what it says. Most messages name the exact screen to fix it in.
+- Rate limits usually clear by themselves; you rarely need to do anything.
+- A kept output from an earlier revision is still in **History** if a remake goes wrong. See [Editing a Project](Editing-a-Project#history-and-saved-revisions).
+
+## Related pages
+
+- [Troubleshooting](Troubleshooting)
+- [Project Page](Project-Page)
+- [Editing a Project](Editing-a-Project)
+- [Providers and Keys](Providers-and-Keys)
+- [AI CLIs](AI-CLIs)
+- [Reviews and Checkpoints](Reviews-and-Checkpoints)