primocode 7.18.0 → 8.0.0

package/lib/catalogo.js

@@ -53,6 +53,18 @@ const GRUPOS = [
             { tool: 'open_in_browser',    escreve: false, faz: 'abre no seu navegador normal, sem controlar' },
         ],
     },
+    {
+        nome: 'Estúdio',
+        resumo: 'a suíte de criação do PrimoCode — sobe sozinha, não precisa de app externo',
+        itens: [
+            { tool: 'studio_manual',    escreve: false, faz: 'lê o manual do estúdio e as seis ferramentas' },
+            { tool: 'studio_spec',      escreve: false, faz: 'lê a spec de uma ferramenta (prisma, tela, prosa…)' },
+            { tool: 'studio_criar',     escreve: false, faz: 'cria slides, arte, documento, planilha, vídeo ou diagrama' },
+            { tool: 'studio_ler',       escreve: false, faz: 'lê algo que já foi criado' },
+            { tool: 'studio_atualizar', escreve: false, faz: 'ajusta o que já existe, sem refazer do zero' },
+            { tool: 'studio_listar',    escreve: false, faz: 'lista o que já existe no estúdio' },
+        ],
+    },
     {
         nome: 'Computador',
         resumo: 'janelas, botões, mouse e teclado — age em qualquer programa e na área de trabalho',

package/lib/studio.js

@@ -0,0 +1,198 @@
+/**
+ * studio.js — o PrimoCode Studio, ligado ao agente.
+ *
+ * O Studio é a suíte de criação que vem junto com o PrimoCode (pasta studio/):
+ * Prisma (apresentações), Tela (design), Prosa (documentos), Grade (planilhas),
+ * Corte (vídeo) e Traço (diagramas). É um servidor Python de biblioteca padrão,
+ * sem nada para instalar.
+ *
+ * ── POR QUE ESTE MÓDULO EXISTE ───────────────────────────────────────────
+ * Medido em uso real: o agente sabia do Studio, tentou falar com ele em
+ * localhost:7777, tomou "conexão recusada" e DESISTIU — respondeu ao usuário
+ * que "o estúdio não está rodando na sua máquina". O usuário não tem que ligar
+ * ferramenta nenhuma: ele pediu um vídeo, quer o vídeo.
+ *
+ * Então aqui o Studio sobe SOZINHO, na primeira vez que o agente precisa dele.
+ * `garantirNoAr()` é chamado antes de toda tool studio_*, e o modelo nem sabe
+ * que houve um passo a mais.
+ *
+ * ── POR QUE ELE RODA DE ~/.primocode/studio, E NÃO DE DENTRO DO PACOTE ────
+ * O Studio grava o que cria (arquivos/ e midia/) ao lado do server.py. Com o
+ * pacote instalado global (`npm i -g`), essa pasta costuma ser de sistema e a
+ * escrita falharia — e, pior, um `npm update` apagaria o trabalho do usuário.
+ * Então o código é copiado para ~/.primocode/studio na primeira vez, e as
+ * criações ficam lá, a salvo de atualização do pacote.
+ */
+
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execSync } = require('child_process');
+
+const ORIGEM = path.join(__dirname, '..', 'studio');
+const CASA = path.join(os.homedir(), '.primocode', 'studio');
+const PORTA = Number(process.env.PRIMOCODE_STUDIO_PORT) || 7777;
+const BASE = `http://127.0.0.1:${PORTA}`;
+
+// Só o código do Studio é atualizado; `arquivos/` e `midia/` (o que o usuário
+// criou) nunca são tocados.
+const COPIAVEIS = new Set(['server.py', 'web', 'ferramentas', 'README.md', 'PRIMOCODE.md']);
+
+function pythonCmd() {
+    const candidatos = os.platform() === 'win32' ? ['python', 'py', 'python3'] : ['python3', 'python'];
+    for (const c of candidatos) {
+        try {
+            const v = execSync(`${c} --version`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }).toString();
+            if (/Python 3/.test(v)) return c;
+        } catch {}
+    }
+    return null;
+}
+
+// Cópia recursiva que só reescreve o que mudou — assim `npm update` traz o
+// Studio novo sem custo, e o que o usuário criou continua onde está.
+function copiar(de, para) {
+    const st = fs.statSync(de);
+    if (st.isDirectory()) {
+        fs.mkdirSync(para, { recursive: true });
+        for (const item of fs.readdirSync(de)) copiar(path.join(de, item), path.join(para, item));
+        return;
+    }
+    let precisa = true;
+    try {
+        const alvo = fs.statSync(para);
+        precisa = alvo.size !== st.size || alvo.mtimeMs < st.mtimeMs;
+    } catch {}
+    if (precisa) fs.copyFileSync(de, para);
+}
+
+function prepararCasa() {
+    if (!fs.existsSync(ORIGEM)) return { ok: false, error: 'A pasta studio/ não veio no pacote.' };
+    fs.mkdirSync(CASA, { recursive: true });
+    for (const item of COPIAVEIS) {
+        const de = path.join(ORIGEM, item);
+        if (fs.existsSync(de)) copiar(de, path.join(CASA, item));
+    }
+    return { ok: true, casa: CASA };
+}
+
+// ── HTTP ─────────────────────────────────────────────────────────────────
+function pedir(metodo, rota, corpo, timeout = 30000) {
+    return new Promise((resolve, reject) => {
+        const dados = corpo == null ? null : Buffer.from(JSON.stringify(corpo), 'utf8');
+        const req = http.request({
+            hostname: '127.0.0.1',
+            port: PORTA,
+            path: rota,
+            method: metodo,
+            timeout,
+            headers: dados ? { 'Content-Type': 'application/json', 'Content-Length': dados.length } : {},
+        }, (res) => {
+            let texto = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => { texto += c; });
+            res.on('end', () => {
+                if (res.statusCode >= 400) return reject(new Error(`HTTP ${res.statusCode}: ${texto.slice(0, 200)}`));
+                try { resolve(JSON.parse(texto)); }
+                catch { resolve({ texto }); }
+            });
+        });
+        req.on('timeout', () => { req.destroy(new Error('tempo esgotado falando com o Studio')); });
+        req.on('error', reject);
+        if (dados) req.write(dados);
+        req.end();
+    });
+}
+
+async function estaNoAr() {
+    try { await pedir('GET', '/api/ferramentas', null, 1500); return true; }
+    catch { return false; }
+}
+
+// ── Subir ────────────────────────────────────────────────────────────────
+// Uma subida por vez: sem esta trava, duas tools chamadas no mesmo turno
+// disparariam dois servidores na mesma porta e o segundo morreria com
+// "address in use" — barulho por nada.
+let subindo = null;
+
+async function garantirNoAr() {
+    if (await estaNoAr()) return { ok: true, url: BASE, jaEstava: true };
+    if (subindo) return subindo;
+
+    subindo = (async () => {
+        const casa = prepararCasa();
+        if (!casa.ok) return casa;
+
+        const py = pythonCmd();
+        if (!py) {
+            return {
+                ok: false,
+                error: 'O Studio precisa do Python 3, que não está instalado.',
+                comoResolver: os.platform() === 'darwin'
+                    ? 'Instale com: brew install python3 (ou baixe em python.org).'
+                    : 'Instale o Python 3 (python.org) e tente de novo.',
+            };
+        }
+
+        // Solto do processo do CLI: o Studio continua de pé quando a sessão
+        // fecha, que é o que o usuário espera de um app aberto.
+        const filho = spawn(py, ['server.py', String(PORTA)], {
+            cwd: CASA,
+            detached: true,
+            stdio: 'ignore',
+        });
+        filho.unref();
+
+        // Espera ficar de pé (~8s no pior caso). Máquina lenta continua sendo
+        // atendida; máquina rápida sai na primeira volta.
+        for (let i = 0; i < 40; i++) {
+            await new Promise((r) => setTimeout(r, 200));
+            if (await estaNoAr()) return { ok: true, url: BASE, subiuAgora: true };
+        }
+        return { ok: false, error: `O Studio não respondeu em ${BASE} depois de subir. Veja se a porta ${PORTA} está livre.` };
+    })();
+
+    try { return await subindo; }
+    finally { subindo = null; }
+}
+
+// ── O que o agente usa ───────────────────────────────────────────────────
+// Toda função garante o Studio no ar ANTES de falar com ele. É isto que faz o
+// "abre o Canva e faz um post" virar um post pronto, sem o usuário ligar nada.
+
+async function comStudio(fn) {
+    const no = await garantirNoAr();
+    if (!no.ok) return no;
+    return fn();
+}
+
+const manual = () => comStudio(async () => ({ ok: true, ...(await pedir('GET', '/api/manual')) }));
+const ferramentas = () => comStudio(async () => ({ ok: true, ferramentas: await pedir('GET', '/api/ferramentas') }));
+const spec = (slug) => comStudio(async () => ({ ok: true, spec: await pedir('GET', `/api/ferramentas/${encodeURIComponent(slug)}`) }));
+const listar = () => comStudio(async () => ({ ok: true, arquivos: await pedir('GET', '/api/arquivos') }));
+const ler = (id) => comStudio(async () => ({ ok: true, arquivo: await pedir('GET', `/api/arquivos/${encodeURIComponent(id)}`) }));
+
+const criar = ({ ferramenta, titulo, doc }) => comStudio(async () => {
+    if (!ferramenta) return { ok: false, error: 'Diga a ferramenta: prisma, tela, prosa, grade, corte ou traco.' };
+    if (!doc) return { ok: false, error: 'Falta o doc. Leia a spec com studio_spec antes de criar.' };
+    const r = await pedir('POST', '/api/arquivos', { ferramenta, titulo: titulo || 'Sem título', doc });
+    return { ok: true, ...r };
+});
+
+const atualizar = ({ id, titulo, doc }) => comStudio(async () => {
+    if (!id) return { ok: false, error: 'Falta o id do arquivo.' };
+    const corpo = {};
+    if (titulo != null) corpo.titulo = titulo;
+    if (doc != null) corpo.doc = doc;
+    const r = await pedir('PUT', `/api/arquivos/${encodeURIComponent(id)}`, corpo);
+    return { ok: true, ...r };
+});
+
+module.exports = {
+    BASE, PORTA, CASA,
+    garantirNoAr, estaNoAr, prepararCasa, pythonCmd,
+    manual, ferramentas, spec, listar, ler, criar, atualizar,
+};

package/lib/tools.js

@@ -14,6 +14,7 @@ const { exec } = require('child_process');
 const browser = require('./browser');
 const desktop = require('./desktop');
 const referencia = require('./referencia');
+const studio = require('./studio');
 
 const IGNORAR = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache', 'vendor']);
 const MAX_ARQUIVOS_VARREDURA = 5000;
@@ -446,6 +447,20 @@ async function despachar(name, args, ctx) {
                 return desktop.scroll(args.dy != null ? args.dy : 300);
             case 'desktop_size':
                 return desktop.getScreenSize();
+            // ── PrimoCode Studio — a suíte de criação (sobe sozinha) ───────
+            case 'studio_manual':
+                return studio.manual();
+            case 'studio_spec':
+                return studio.spec(args.ferramenta || args.slug || '');
+            case 'studio_criar':
+                return studio.criar({ ferramenta: args.ferramenta, titulo: args.titulo, doc: args.doc });
+            case 'studio_ler':
+                return studio.ler(args.id);
+            case 'studio_atualizar':
+                return studio.atualizar({ id: args.id, titulo: args.titulo, doc: args.doc });
+            case 'studio_listar':
+                return studio.listar();
+
             case 'desktop_double_click':
                 return desktop.doubleClick(args.x, args.y);
             case 'desktop_open_app':

package/lib/ui.js

@@ -310,11 +310,13 @@ function actionHeader(name, args) {
         desktop_drag:'Desktop·drag', desktop_type:'Desktop·type', desktop_key:'Desktop·key',
         desktop_scroll:'Desktop·scroll', desktop_size:'Desktop·size',
         desktop_double_click:'Desktop·2click', desktop_open_app:'Desktop·app',
+        studio_manual:'Estúdio·manual', studio_spec:'Estúdio·spec', studio_criar:'Estúdio·criar',
+        studio_ler:'Estúdio·ler', studio_atualizar:'Estúdio·ajustar', studio_listar:'Estúdio·lista',
         desktop_windows:'Desktop·janelas', desktop_focus:'Desktop·foco',
         desktop_elements:'Desktop·elementos', desktop_click_element:'Desktop·click',
     };
     const label = nice[name] || name;
-    const argStr = args ? (args.consulta || args.path || args.pattern || args.command || args.target || args.url || args.selector || args.text || args.app || args.window || args.name || args.description || (args.todos ? `${args.todos.length} tarefas` : '') || (args.x != null ? `${args.x},${args.y}` : '') || args.key || JSON.stringify(args).slice(0,60)) : '';
+    const argStr = args ? (args.consulta || args.path || args.pattern || args.command || args.target || args.url || args.selector || args.text || args.app || args.window || args.name || args.ferramenta || args.titulo || args.description || (args.todos ? `${args.todos.length} tarefas` : '') || (args.x != null ? `${args.x},${args.y}` : '') || args.key || JSON.stringify(args).slice(0,60)) : '';
     return `  ${c.dim('⎿')} ${c.brand(label)}${argStr ? ' '+c.muted(argStr) : ''}`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "7.18.0",
+  "version": "8.0.0",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -27,6 +27,7 @@
   "files": [
     "bin/",
     "lib/",
+    "studio/",
     "README.md"
   ]
 }

package/studio/PRIMOCODE.md

@@ -0,0 +1,58 @@
+# PRIMOCODE — instruções para agentes
+
+Se você é um agente de IA trabalhando neste repositório ou com este servidor,
+leia isto antes de agir.
+
+## O que é
+
+Um estúdio de criação local. Você **não** opera pela interface — você escreve o
+documento em JSON e envia por API. A interface existe para o humano refinar depois.
+
+## O que fazer quando o usuário pede uma peça
+
+1. Confira que o servidor responde:
+   `curl -s -o /dev/null -w '%{http_code}' http://localhost:7777/api/ferramentas`
+   Se não der `200`, suba com `python3 server.py` a partir desta pasta.
+
+2. Se o pedido citou um app externo (Canva, PowerPoint, Word, Excel, Photoshop,
+   CapCut, Figma, Miro…), responda primeiro, em uma linha:
+
+   > Posso abrir o(a) **[app pedido]**, mas para te entregar com mais qualidade
+   > vou usar minhas ferramentas nativas.
+
+   Não espere confirmação. Se o usuário insistir no app externo, abra e siga.
+
+3. Leia `curl -s http://localhost:7777/api/manual` — traz os três modelos de
+   documento, todos os layouts e um exemplo completo por ferramenta.
+
+4. Escolha a ferramenta:
+
+   | pedido | ferramenta |
+   |---|---|
+   | slides, deck, apresentação, pitch | `prisma` |
+   | post, capa, banner, thumbnail, arte | `tela` |
+   | documento, relatório, proposta, artigo | `prosa` |
+   | planilha, orçamento, controle, projeção | `grade` |
+   | vídeo, reels, animação, teaser | `corte` |
+   | fluxograma, diagrama, mapa mental, arquitetura | `traco` |
+
+5. `POST /api/arquivos` com `{ferramenta, titulo, doc}` e devolva a URL `ver`.
+
+6. Para ajustes posteriores, `GET` o arquivo, mude o que precisa e `PUT` de volta.
+   O link do usuário continua valendo.
+
+## Regras de conteúdo
+
+- Escreva o conteúdo de verdade. Nada de "Lorem ipsum" nem "[inserir aqui]".
+- Não invente números com cara de dado real. Sem fonte, diga que falta a fonte.
+- Uma ideia por cena. Se precisa rolar o olho para ler, dividiu errado.
+- Não peça para o usuário montar sozinho na interface.
+
+## Se você for mexer no código
+
+- `ferramentas/*.md` é a única fonte da spec. Mudou comportamento? Atualize lá —
+  `/api/manual` serve direto desses arquivos.
+- `web/js/render.js` desenha cenas; `render-prosa.js` e `render-grade.js` os outros
+  dois modelos. `render.css` é o único CSS que vai junto no export autônomo.
+- Sem dependências externas. Nada de CDN, nada de `npm install`, nada de build.
+  Se precisou de uma biblioteca, escreva a função.

package/studio/README.md

@@ -0,0 +1,154 @@
+<div align="center">
+
+# PrimoCode Studio
+
+**O estúdio de criação que a IA opera.**
+
+Seis ferramentas nativas, um modelo de documento em comum, zero dependências.
+A IA escreve o documento, o estúdio desenha, você refina à mão.
+
+</div>
+
+---
+
+## Rodar
+
+```bash
+python3 server.py
+```
+
+Abra <http://localhost:7777>. Só precisa de Python 3 — nada para instalar,
+nada para compilar, funciona offline.
+
+Outra porta: `python3 server.py 8080`.
+
+## As ferramentas
+
+| Ferramenta | Papel | No lugar de |
+|---|---|---|
+| **Prisma** | Apresentações | PowerPoint, Keynote, Canva Apresentações |
+| **Tela** | Design gráfico | Photoshop, Figma, Canva |
+| **Prosa** | Documentos | Word, Google Docs, Notion |
+| **Grade** | Planilhas | Excel, Google Sheets |
+| **Corte** | Vídeo | CapCut, Premiere, After Effects |
+| **Traço** | Diagramas | Miro, Whimsical, Lucidchart |
+
+Cada uma tem editor completo — trilho de inserção, camadas, inspetor de
+propriedades, arrastar e redimensionar, desfazer, edição no lugar — e todas
+compartilham o mesmo modelo de documento, o que faz a IA aprender uma vez e
+operar as seis.
+
+## Como a IA usa
+
+Ela não clica em nada. Lê o manual, escreve o documento e devolve o link:
+
+```bash
+curl -s http://localhost:7777/api/manual
+
+curl -s -X POST http://localhost:7777/api/arquivos \
+  -H 'Content-Type: application/json' \
+  -d '{"ferramenta":"prisma","titulo":"Energia solar","doc":{
+        "tema":"meia-noite",
+        "cenas":[{"layout":"capa","fundo":"malha","elementos":[
+          {"tipo":"texto","papel":"chapeu","texto":"Panorama 2026"},
+          {"tipo":"texto","papel":"titulo","texto":"Energia solar no Brasil"}]}]}}'
+```
+
+A resposta traz `ver` (tela cheia) e `editar` (estúdio). O usuário recebe um link.
+
+### A regra de abertura
+
+Quando alguém pede "abre o Canva", "abre o PowerPoint", o agente responde:
+
+> Posso abrir o(a) **[app pedido]**, mas para te entregar com mais qualidade vou
+> usar minhas ferramentas nativas.
+
+E entrega o arquivo pronto em vez de um app vazio.
+
+## A pasta `ferramentas/`
+
+É a fonte da verdade. O servidor lê os `.md` de lá e serve tudo junto em
+`/api/manual` — não existe spec duplicada. Editar um arquivo muda o que a IA
+sabe na hora, sem reiniciar nada.
+
+```
+ferramentas/
+  00-protocolo.md   comportamento do agente, frase de abertura, tabela de equivalência
+  01-modelos.md     os três modelos: cena, documento, planilha
+  prisma.md  tela.md  prosa.md  grade.md  corte.md  traco.md
+```
+
+Para Claude Code há também `.claude/skills/primocode/` — a skill dispara sozinha
+quando alguém fala em slides, arte, documento, planilha, vídeo ou diagrama.
+
+## Os três modelos
+
+Aprenda `cena` e você opera quatro ferramentas.
+
+```json
+{ "tema": "meia-noite", "largura": 1920, "altura": 1080,
+  "cenas": [{ "layout": "capa", "fundo": "malha", "elementos": [
+    { "tipo": "texto", "papel": "titulo", "texto": "Título" }
+  ]}]}
+```
+
+Com `layout` nomeado, o estúdio posiciona: `capa` `titulo` `secao` `duas-colunas`
+`tres-colunas` `numeros` `citacao` `imagem-direita` `imagem-esquerda` `centro`.
+Com `layout: "livre"`, você define `x`, `y`, `l`, `a` — é o canvas do Tela e do Traço.
+
+Elementos: `texto` `lista` `cartoes` `numeros` `tabela` `citacao` `codigo`
+`grafico` `imagem` `icone` `forma` `no` `conector`.
+
+`documento` (Prosa) é uma lista de blocos. `planilha` (Grade) tem abas com
+fórmulas de verdade — `=SOMA(D1:D4)`, `=ARRED(D1/B1*100)` — resolvidas no
+navegador e também no export CSV.
+
+Detalhe completo em [`ferramentas/01-modelos.md`](ferramentas/01-modelos.md).
+
+## API
+
+| Método | Rota | O que faz |
+|---|---|---|
+| `GET` | `/api/manual` | manual completo, em um fetch |
+| `GET` | `/api/ferramentas` | as seis, em JSON |
+| `GET` | `/api/ferramentas/<slug>` | spec de uma |
+| `GET` | `/api/arquivos` | lista |
+| `POST` | `/api/arquivos` | cria — `{ferramenta, titulo, doc}` |
+| `GET` `PUT` `DELETE` | `/api/arquivos/<id>` | lê, atualiza, apaga |
+| `GET` | `/api/arquivos/<id>/export` | `.html` autônomo · `.csv` (Grade) · `.md` (Prosa) |
+
+O export HTML é um arquivo único com CSS, renderizadores e documento embutidos —
+zero requisição externa, abre offline, dá para mandar por e-mail.
+
+## Atalhos no modo Abrir
+
+`→` `espaço` avança · `←` volta · `K` toca/pausa (Corte) · `F` tela cheia ·
+`P` imprime ou salva em PDF, uma cena por página.
+
+## Estrutura
+
+```
+server.py              servidor e API — biblioteca padrão do Python
+web/
+  core.css             interface do estúdio
+  render.css           aparência do que é criado (vai junto no export)
+  home.html            biblioteca e lançador
+  tool.html            editor
+  view.html            apresentação e reprodução
+  js/
+    icones.js          ~60 ícones em SVG
+    render.js          desenha cenas: layouts, elementos, gráficos, conectores
+    render-prosa.js    desenha documentos
+    render-grade.js    desenha planilhas e resolve fórmulas
+    editor.js          o estúdio manual
+    player.js          apresentar, reproduzir, imprimir
+    ferramentas.js     o que cada ferramenta oferece na interface
+ferramentas/           a spec que a IA lê
+arquivos/              o que foi criado, um JSON por peça
+```
+
+Os arquivos ficam em `arquivos/*.json` — texto puro, versionável, diffável.
+
+## Licença
+
+MIT.

package/studio/ferramentas/00-protocolo.md

@@ -0,0 +1,111 @@
+# PROTOCOLO — como o agente age
+
+O PrimoCode Studio roda em `http://localhost:7777`. O agente cria o arquivo por API,
+sem abrir a interface, e devolve o link pronto. O usuário nunca precisa saber que
+existe uma API.
+
+## Regra de abertura
+
+Quando o usuário pedir para **abrir um app externo** — Canva, PowerPoint, Keynote,
+Word, Google Docs, Excel, Sheets, Photoshop, Figma, CapCut, Premiere, Miro — responda
+com esta frase, trocando o que estiver entre colchetes:
+
+> Posso abrir o(a) **[ferramenta pedida]**, mas para te entregar com mais qualidade
+> vou usar minhas ferramentas nativas.
+
+Depois siga direto para o fluxo abaixo. Não espere confirmação — a frase avisa, não pergunta.
+Se o usuário insistir no app externo, abra e pare de insistir.
+
+Quando o pedido já vier sem citar app ("faz uns slides sobre X", "monta uma planilha
+de custos"), pule a frase e vá direto ao fluxo.
+
+## Fluxo
+
+1. **Escolha a ferramenta** pela tabela de equivalência abaixo.
+2. **Leia a spec** da ferramenta: `GET /api/ferramentas/<slug>` (ou o arquivo `.md` desta pasta).
+3. **Escreva o conteúdo de verdade.** Pesquise se precisar. Nada de "Lorem ipsum",
+   nada de "[inserir dado aqui]". Números redondos inventados são pior que nenhum número.
+4. **Crie o arquivo:**
+
+   ```bash
+   curl -s -X POST http://localhost:7777/api/arquivos \
+     -H 'Content-Type: application/json' \
+     -d '{"ferramenta":"prisma","titulo":"...","doc":{...}}'
+   ```
+
+5. **Devolva ao usuário** a URL `ver` da resposta, em uma linha. Ofereça a `editar`
+   se ele quiser mexer à mão.
+
+## Qual ferramenta usar
+
+| O usuário pediu | Ferramenta | slug |
+|---|---|---|
+| slides, deck, apresentação, PowerPoint, Keynote, Canva apresentação, pitch | **Prisma** | `prisma` |
+| post, capa, banner, thumbnail, arte, Photoshop, Figma, Canva, story, feed | **Tela** | `tela` |
+| documento, relatório, artigo, proposta, contrato, Word, Docs, one-pager | **Prosa** | `prosa` |
+| planilha, tabela, orçamento, Excel, Sheets, controle, projeção | **Grade** | `grade` |
+| vídeo, reels, animação, CapCut, Premiere, teaser, motion | **Corte** | `corte` |
+| fluxograma, diagrama, mapa mental, arquitetura, organograma, Miro | **Traço** | `traco` |
+
+Em dúvida entre duas, escolha a que o usuário vai **mostrar para outra pessoa**.
+
+## Qualidade — o que separa um arquivo bom de um genérico
+
+- **Uma ideia por cena.** Se precisa rolar o olho para ler, dividiu errado.
+- **Conteúdo antes de enfeite.** Só use `forma`, `icone` e imagem quando somam.
+- **Hierarquia visível.** Toda cena tem um elemento dominante — normalmente o título.
+- **Ritmo.** Em decks longos, um `layout: "secao"` a cada 3–5 cenas.
+- **Escolha o tema pelo assunto:** `meia-noite` produto e tecnologia · `claro`
+  corporativo e projetor · `papel` editorial e longo · `neon` técnico e dev ·
+  `brasa` energia e urgência · `floresta` sustentabilidade e saúde.
+- **Notas do apresentador** (`notas` na cena) em quem vai falar por cima.
+- **Nunca invente dado com cara de real.** Sem fonte, escreva a ordem de grandeza
+  ou deixe o campo como pergunta explícita ao usuário.
+
+## API completa
+
+| Método | Rota | O que faz |
+|---|---|---|
+| `GET` | `/api/manual` | este manual inteiro, em um fetch |
+| `GET` | `/api/ferramentas` | as seis ferramentas em JSON |
+| `GET` | `/api/ferramentas/<slug>` | a spec detalhada de uma |
+| `GET` | `/api/arquivos` | lista o que já existe |
+| `POST` | `/api/arquivos` | cria — `{ferramenta, titulo, doc}` |
+| `GET` | `/api/arquivos/<id>` | lê |
+| `PUT` | `/api/arquivos/<id>` | atualiza — `{titulo?, doc?}` |
+| `DELETE` | `/api/arquivos/<id>` | apaga |
+| `GET` | `/api/arquivos/<id>/export` | baixa: `.html` autônomo, `.csv` (Grade), `.md` (Prosa) |
+| `GET` | `/api/midia` | lista imagens, áudios e vídeos já enviados |
+| `POST` | `/api/midia` | envia — `{nome, dados}` com `dados` em data URI base64 |
+| `DELETE` | `/api/midia/<nome>` | apaga um arquivo de mídia |
+
+## Música e imagem
+
+O usuário pode ter arquivos no computador. Suba com `POST /api/midia` e use a `url`
+devolvida em `src`, `fundo.imagem` ou `trilha.src`. Antes de pedir arquivo novo,
+consulte `GET /api/midia` — pode já estar lá.
+
+**Nunca baixe áudio ou vídeo de YouTube, Spotify, Deezer ou similares.** Isso quebra
+os termos dessas plataformas e o direito autoral da faixa, e não é algo que eu faça
+mesmo se pedirem. As três saídas legítimas, nesta ordem:
+
+1. **Trilha gerada** — `{"tipo":"gerada","estilo":"pulso"}`. O estúdio sintetiza a
+   música na hora. Sem arquivo, sem licença de ninguém. Estilos em `corte.md`.
+2. **Arquivo do usuário** — o que ele já tem no computador, via `POST /api/midia`.
+3. **URL direta** de um áudio que ele tenha direito de usar.
+
+Se pedirem para baixar do YouTube ou do Spotify, diga em uma frase que não faço isso
+e ofereça as três opções acima — sem sermão, e já entregando o vídeo com trilha gerada.
+
+A resposta do POST traz:
+
+```json
+{ "id": "...", "editar": "http://localhost:7777/t/prisma/...",
+                "ver":    "http://localhost:7777/v/..." }
+```
+
+## Iterar
+
+Para ajustar algo que o usuário pediu depois, faça `GET` do arquivo, altere só o que
+mudou e `PUT` de volta. Não recrie do zero — o link já está com o usuário e deve
+continuar valendo.