@praeko/studio 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/). In the 0.x series a breaking change may ship in a minor version, always recorded here.
+
+## [0.2.0] - unreleased
+
+**Breaking: everything is English now.** The 0.1.0 surface was Portuguese; this is day 0 with almost no users, so the rename is done at once. No Portuguese alias is kept.
+
+- **Commands:** `novo→new`, `voz→voice` (`saldo→balance`, `vozes→voices`, `conta listar|adicionar→account list|add`, `config chave→config key`), `compilar→compile`, `corte→cut`, `prever→preview`, `capa→cover`, `folha→contact-sheet`, `checar→check`, `pacote→package`, `agendar→schedule`, `postar→post`, `fila→queue` (`list|run|cancel|install|remove`), `conta→account` (`connect|status`), `licencas→licenses`.
+- **Flags:** `--titulo→--title`, `--longo→--long`, `--qualidade→--quality` (`rascunho→draft`), `--voz→--voice`, `--alinhador→--aligner`, `--sem-failover→--no-failover`, `--de/--ate→--from/--to`, `--abertura→--hook`, `--motor→--engine`, `--escala→--scale`, `--quando→--when`, `--redes→--networks`, `--enviar→--send`, `--canais→--channels`, `--chave→--key`, `--aceitar→--accept`, `--sem-instalar→--no-install`, `--de-env→--from-env`, `--simular→--dry-run`, `--voz-id→--voice-id`.
+- **Project files:** `marca.json→brand.json`, `vozes.json→voices.json`, `episodios/→episodes/`, `episodio.yaml→episode.yaml`, `roteiro.txt→script.txt`, `palavras.json|ts→words.json|ts`, `voz.mp3→voice.mp3`, `publicacao.json→publication.json`, `textos.md→texts.md`, `agendamento.json→schedule.json`, and every YAML/JSON key (full table: `docs/studio-ingles.md` of the repository).
+- **Environment:** `PRAEKO_STUDIO_LANG→PRAEKO_LANG`, `PRAEKO_STUDIO_SEM_AVISO→PRAEKO_STUDIO_NO_NOTICE`, `PRAEKO_SEGREDOS→PRAEKO_SECRETS`, `PRAEKO_SEM_CHAVEIRO→PRAEKO_NO_KEYCHAIN`, `~/.config/praeko/segredos.json→secrets.json`.
+- **New:** `praeko studio migrate [--dry-run]` converts a 0.1.0 project in place (renames files and folders, rewrites keys, updates the TSX imports, `package.json` and the agent instruction blocks; backup in `.studio-backup/`, report at the end). It is the only code that still knows the Portuguese names.
+- **New:** `--lang pt` / `PRAEKO_LANG=pt` prints the common messages in Brazilian Portuguese; the default is English everywhere (help, errors, `doctor`, the agent skill, the project templates).
+- **New:** `--engine hyperframes` renders the video **and** the cover with HyperFrames; nothing from Remotion is used then.
+- The agent skill and the `AGENTS.md`/`CLAUDE.md`/`GEMINI.md` blocks are English by default (`--lang pt` available, using the new command names); block markers are `praeko-studio:start`/`end`.
+- All packages are TypeScript (strict); `@praeko/studio-core` and `@praeko/studio-kit` ship `.d.ts` files whose import specifiers resolve for consumers.
+- Library API renamed in `@praeko/studio-core` and `@praeko/studio-kit` (see their CHANGELOGs); the old names are gone.
+
+## [0.1.0] - 2026-11-07
+
+First published version. Praeko Studio was born inside a promotion project and was extracted for anyone to use with their own coding agent.
+
+- `praeko-studio` command (also through `praeko studio …`, by `@praeko/cli`): `init`, `new`, `voice`, `compile`, `cut`, `preview`, `render`, `cover`, `contact-sheet`, `check`, `package`, `schedule`, plus the new `doctor`, `licenses`, `skill install` and `docs` (named in Portuguese in that release).
+- `init` creates projects that depend on published packages by semver (`@praeko/studio-core`, `@praeko/studio-kit`); `--dev <studio>` keeps the local-path mode for contributors.
+- `skill install` writes the instructions for Claude Code, Codex, Gemini CLI, Cursor, opencode, Cline and Windsurf (pt-BR and en), with the two-step rule for publishing through MCP, the local file upload (`create_media_upload`) and the AI disclosure.
+- Voice: per-project and per-user voices file (no one's ids in the package); keys through an environment variable, the macOS keychain or a secrets file (600 permission); the Praeko key is the same as the `praeko` CLI's.
+- Default publishing through Praeko (`--via praeko`); the brand `links` became optional; the publication file gained the AI disclosure (checked by `check` and `package`; sent to YouTube as `containsSyntheticMedia` in direct publishing).
+- Remotion is **not MIT**: see `LICENSES.md` and `praeko studio licenses`.
+- Removed: the `bardo` alias, the old keychain service and `~/.config/bardo`. `queue install/remove` (launchd) only exists on macOS.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcone Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES.md

@@ -0,0 +1,36 @@
+# Praeko Studio licenses
+
+Verified on 2026-11-07. This file is not legal advice; each vendor's own text prevails.
+
+## Praeko Studio's code
+The packages `@praeko/studio`, `@praeko/studio-core` and `@praeko/studio-kit` are **MIT** (see `LICENSE`, Copyright (c) 2026 Marcone Santos), like `@praeko/sdk` and `@praeko/cli`. The sound effects (`pop`, `ding`, `thump`, `whoosh`) and the `avatar.png` of the project template were created for Studio (sounds synthesized by `scripts/generate-sfx.mjs`, with no third-party samples) and follow the same MIT license. The package ships no fonts, music, stock images or third-party art.
+
+## Notice you need to see (Remotion is NOT MIT)
+> **Remotion.** Remotion is *source-available*, not open source. It is **free** for individuals, non-profits, evaluation and companies with **up to 3 employees** (commercial use included). Companies with **4 or more people** need the **Company License** (remotion.pro/license). You install and run Remotion, so the license is **yours**, not Praeko's. Remotion also sells plans for those who **automate renders by program or agent** (Creators, Automators); their FAQ does not expressly say whether a local agent running `remotion render` counts: **ask Remotion** before using at scale. Praeko Studio does not copy or modify Remotion code: it uses it as a dependency (peer) that you install.
+
+This notice appears in the `README`, at install time (`praeko studio init`), in `praeko studio doctor` and in `praeko studio licenses` (`--accept` records that you read it in `~/.config/praeko/studio/licenses.json`).
+
+**Engines.** Remotion is the default engine for videos **and** covers. With `--engine hyperframes` (or `"engine": "hyperframes"` in `brand.json`) the video **and** the cover are rendered by HyperFrames and nothing from Remotion is used, so a project that only uses HyperFrames does not need a Remotion license. Scenes or covers written as TSX (`component:`) only exist in Remotion.
+
+**We do not promise "free forever":** Remotion's conditions may change (their own page warns that the license changes in Remotion 5.0). Review the license when you upgrade.
+
+## Third-party dependencies
+| Component | Where | License | Source |
+|---|---|---|---|
+| `remotion`, `@remotion/cli` (4.0.539) | installed in the user's **project** (peer of core/kit) | Remotion License (see above), not MIT | remotion.pro/license; github.com/remotion-dev/remotion (LICENSE.md) |
+| `react`, `react-dom` (19.2.3) | user's project (peer) | MIT | each package's package.json |
+| `@praeko/studio-core`, `-kit` | user's project | MIT | LICENSE |
+| `yaml` (2.9.1) | embedded in the `@praeko/studio` bundle | ISC | package.json |
+| `@elevenlabs/elevenlabs-js` (2.x) | dependency of `@praeko/studio` | MIT | package.json |
+| `hyperframes` (0.9.13, optional engine) | downloaded by `npx` the first time you use `--engine hyperframes` | Apache-2.0 | github.com/heygen-com/hyperframes |
+| `typescript`, `esbuild`, `@types/*` | development/build only | Apache-2.0 / MIT | package.json |
+| ffmpeg / ffprobe | you install | LGPL or GPL, depending on the build | ffmpeg.org/legal.html |
+| Chrome Headless Shell / Chromium | Remotion downloads it on the first render | Chromium/Google licenses | remotion.dev/docs/miscellaneous/chrome-headless-shell |
+
+## Services and models (you sign up)
+- **ElevenLabs**: its terms and your plan (voice cloning only with rights over the voice). The key is yours; Studio never prints it.
+- **Local VoiceStudio** (optional): the OmniVoice model is **CC-BY-NC (non-commercial use)**. It is not the default in any Studio configuration and **must not be used in monetized content**. Check the license of any local model you use.
+- **YouTube, Instagram, TikTok**: each network's terms and synthetic-content rules (see `praeko studio docs publish`).
+
+## Fonts and media
+No font is distributed. The project template uses system fonts (`Arial Black`, `Menlo`) that `doctor` checks; swap them in `brand.json` for open fonts (OFL) if you want the video to look the same on every system. Music, images and clips you add are your responsibility (rights and licenses).

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @praeko/studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Praeko Studio makes short (9:16) and long (16:9) videos from a script: voice, word-by-word captions, scenes, cover and publishing texts. You operate it with **your own coding agent** (Claude Code, Codex, Gemini CLI, Cursor, opencode…) on **your machine**: the agent writes the script and `episode.yaml`, runs the commands and, only after your yes, publishes through [Praeko](https://praeko.app/docs). Voice, render and agent are at your own cost; Studio calls no language model and none of your scripts leaves the machine until you publish.
+
+> **Licenses.** Praeko Studio's own code is MIT. **Remotion** (the default engine for videos and covers) is **not MIT**: free for individuals, non-profits and companies of up to 3 employees; companies with 4 or more people need the Company License ([remotion.pro/license](https://www.remotion.pro/license)). The license belongs to whoever installs and runs Remotion. HyperFrames (`--engine hyperframes`, which renders the video and the cover with nothing from Remotion) is Apache-2.0. Details: [LICENSES.md](./LICENSES.md) or `praeko studio licenses`.
+
+## Requirements
+Node 22 or newer, `ffmpeg` and `ffprobe` on the PATH, and a Chrome (Remotion downloads the Chrome Headless Shell on its own at the first render; it needs internet at that moment). macOS and Linux are supported; Windows is best effort and untested. `praeko studio doctor` checks everything.
+
+## Install
+```sh
+# npm
+npm install -g @praeko/studio
+# yarn
+yarn global add @praeko/studio
+# pnpm
+pnpm add -g @praeko/studio
+# bun
+bun add -g @praeko/studio
+# without installing
+npx @praeko/studio init my-channel
+```
+It also works as `praeko studio <command>` when `@praeko/cli` is installed (it hands over to Studio).
+
+## First video
+```sh
+praeko-studio init my-channel --name "My Channel" --agent claude   # project + instructions for your agent
+cd my-channel
+praeko-studio doctor
+praeko-studio new my-first --title "My first video"
+praeko-studio voice my-first --quality draft                       # estimated, silent voice: free, no network
+praeko-studio check my-first
+praeko-studio render my-first && praeko-studio contact-sheet my-first && praeko-studio cover my-first && praeko-studio package my-first
+```
+Open your agent in the project folder and ask for the video: the instructions (`CLAUDE.md`/`AGENTS.md`/`GEMINI.md`/`.cursor/rules`…) are already there (`praeko studio skill install --agent all` rewrites them). Docs of the installed version: `praeko studio docs`.
+
+## Publish
+`praeko studio schedule <slug> --via praeko --when "dd/mm hh:mm"` only simulates; `--send` really publishes. Through the Praeko MCP the upload of the local file uses `create_media_upload` and publishing is always in two steps (preview and confirmation code). Declare AI content in `publication.json` (`"ai": { "synthetic": true }`). See `praeko studio docs publish`.
+
+## Upgrading from 0.1.0
+0.2.0 is English only (commands, flags, files, keys). Convert an existing project once: `praeko studio migrate --dry-run`, then `praeko studio migrate` (backup in `.studio-backup/`, report at the end).
+
+## License
+MIT (the code of this package). See also [LICENSES.md](./LICENSES.md).