@memoring/cli 0.6.0 → 0.9.0

package/README.md

@@ -55,7 +55,8 @@ Os itens enviados nascem **PENDING_REVIEW** — nada entra nas suas listagens ne
 | --- | --- |
 | `memoring auth` | login / logout / status |
 | `memoring stage` | schema (o contrato + seus limites por tipo + as regras de qualidade e suas instruções custom — tudo que o agente deve seguir) / caps (mostra/grava os limites — valem para o app e para os agentes) / create (envia o lote, `--file` ou stdin, `--replace` esvazia a caixa antes; `--max-*` vence a preferência por lote) |
-| `memoring inbox` | list / accept `<id>` / accept-all / discard `<id>` |
+| `memoring inbox` | list / accept `<id>` / accept-all / discard `<id>` / discard-all / update `<id>` (edita item PENDENTE — merge do `--file` parcial e/ou flags `--title --front --back --tags a,b --deck nome ...`) |
+| `memoring deck` | list (seus baralhos) / create `<nome>` (idempotente; `--parent` p/ sub-baralho) |
 | `memoring update` | atualiza a CLI para a última versão (via npm) |
 | `memoring skill` | imprime o guia completo da CLI para agentes de IA (o SKILL.md empacotado) |
 | `memoring version` | versão da CLI |
@@ -91,9 +92,11 @@ Cada item do lote (1 a 50, all-or-nothing):
 }
 ```
 
-- `type`: `NOTE` (nota, exige `content` em markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`).
+- `type`: `NOTE` (nota, exige `content` em markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`), `QUESTION` (exige `question`: `kind` `MULTIPLA_ESCOLHA`/`CERTO_ERRADO`, `statementHtml`, `correctAlternative` 1-based — 1=Certo/2=Errado —, `alternatives` 2–5 só em múltipla escolha, `commentHtml`).
+- `deckName`: **obrigatório** (ou `--deck` no create) — cartão não fica sem baralho; o nome de um baralho existente (`memoring deck list`) é reutilizado, nome novo vira baralho criado no envio.
 - `source`: origem do material — default `"Importação assistida (CLI)"`.
 - Limites por tipo: `memoring stage caps` mostra/grava sua preferência (`livre`/`-1` = à vontade — o padrão; `0` = não gerar o tipo) — o `stage schema` a expõe ao agente (`userCaps`) e o `create` a impõe; flags `--max-*` no `create` vencem por lote.
+- Sem sessão, o `stage schema --json` sai com `authenticated: false`, `userCaps`/`qualityRules`/`customInstructions` nulos e um `warning` — agentes devem logar (`auth login`) e reler o schema ANTES de gerar.
 
 ## Para agentes de IA
 

package/dist/commands/deck.js

@@ -0,0 +1,99 @@
+import { apiFetch, ApiError } from '../api.js';
+import { fail, green, printJson, printTable, stringFlag } from './shared.js';
+export async function listDecks() {
+    return (await apiFetch('/notes/decks'));
+}
+/**
+ * Resolve uma referência de baralho ("123" por id ou nome exato, case-insensitive)
+ * contra a lista do usuário. Null quando não existe — quem chama decide se cria
+ * (stage create) ou falha (inbox update).
+ */
+export function resolveDeck(decks, ref) {
+    const asNumber = Number(ref);
+    if (Number.isInteger(asNumber) && asNumber > 0) {
+        return decks.find((d) => d.id === asNumber) ?? null;
+    }
+    const norm = ref.trim().toLowerCase();
+    return decks.find((d) => d.name.trim().toLowerCase() === norm) ?? null;
+}
+/** Cria o baralho (parentId null = baralho raiz/matéria). */
+export async function createDeck(name, parentId = null) {
+    try {
+        return (await apiFetch('/notes/decks', { method: 'POST', body: { name, parentId } }));
+    }
+    catch (e) {
+        if (e instanceof ApiError) {
+            fail(`o servidor rejeitou a criação do baralho "${name}" (${e.status}): ${e.body}`);
+        }
+        throw e;
+    }
+}
+export async function deckCommand(parsed) {
+    const [sub, ...rest] = parsed._;
+    switch (sub) {
+        case 'list': {
+            const decks = await listDecks();
+            if (parsed.flags.json) {
+                printJson(decks);
+                return;
+            }
+            if (decks.length === 0) {
+                process.stdout.write('Nenhum baralho — crie com `memoring deck create "<nome>"`.\n');
+                return;
+            }
+            const nameById = new Map(decks.map((d) => [d.id, d.name]));
+            printTable(decks.map((d) => ({
+                id: `#${d.id}`,
+                name: d.name,
+                parent: d.parentId !== null ? (nameById.get(d.parentId) ?? `#${d.parentId}`) : '—',
+                due: d.dueCount,
+            })), [
+                { key: 'id', label: 'ID' },
+                { key: 'name', label: 'NOME' },
+                { key: 'parent', label: 'BARALHO-PAI' },
+                { key: 'due', label: 'A REVISAR' },
+            ]);
+            process.stdout.write(`\n${decks.length} baralho(s).\n`);
+            return;
+        }
+        case 'create': {
+            const name = rest.join(' ').trim();
+            if (name === '') {
+                fail('informe o nome: memoring deck create "Direito Tributário" [--parent <id>].');
+            }
+            let parentId = null;
+            const parentRef = stringFlag(parsed.flags, 'parent');
+            if (parentRef !== undefined) {
+                const parent = resolveDeck(await listDecks(), parentRef);
+                if (!parent) {
+                    fail(`baralho-pai "${parentRef}" não encontrado — veja os ids/nomes com \`memoring deck list\`.`);
+                }
+                parentId = parent.id;
+            }
+            const existing = resolveDeck(await listDecks(), name);
+            if (existing) {
+                if (parsed.flags.json) {
+                    printJson({ deck: existing, alreadyExisted: true });
+                    return;
+                }
+                process.stdout.write(`Baralho "${existing.name}" já existe (#${existing.id}).\n`);
+                return;
+            }
+            const deck = await createDeck(name, parentId);
+            if (parsed.flags.json) {
+                printJson({ deck, alreadyExisted: false });
+                return;
+            }
+            process.stdout.write(green(`Baralho "${deck.name}" criado (#${deck.id}).\n`));
+            return;
+        }
+        default:
+            process.stdout.write('Uso: memoring deck <list|create> [nome] [--parent <id>] [--json]\n' +
+                '  list            lista seus baralhos (id, nome, pai, cartões a revisar)\n' +
+                '  create <nome>   cria um baralho (idempotente: nome existente só retorna o atual)\n' +
+                '                  --parent <id|nome> cria como sub-baralho\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}

package/dist/commands/inbox.js

@@ -1,8 +1,84 @@
+import { readFileSync } from 'node:fs';
 import { apiFetch, ApiError } from '../api.js';
-import { fail, green, printJson, printTable } from './shared.js';
+import { listDecks, resolveDeck } from './deck.js';
+import { fail, green, printJson, printTable, stringFlag } from './shared.js';
 async function listInbox() {
     return (await apiFetch('/notes/review-inbox'));
 }
+function parseId(idArg, sub) {
+    const id = Number(idArg);
+    if (!idArg || !Number.isInteger(id) || id <= 0) {
+        fail(`informe o id numérico do item: memoring inbox ${sub} <id> (veja os ids com \`memoring inbox list\`).`);
+    }
+    return id;
+}
+function parseTagsFlag(raw) {
+    return raw
+        .split(',')
+        .map((t) => t.trim())
+        .filter((t) => t !== '');
+}
+/**
+ * Edição de item PENDENTE (merge + PUT /api/notes/{id}): o PUT exige o objeto completo,
+ * então o estado atual vem do `inbox list` — que só retorna PENDING_REVIEW, o que já
+ * garante que o update não toca item aceito. Overrides vêm de --file (JSON parcial)
+ * e/ou flags; flags vencem o arquivo.
+ */
+async function updateInboxItem(parsed, id) {
+    const current = (await listInbox()).find((n) => n.id === id);
+    if (!current) {
+        fail(`item #${id} não está pendente de revisão — update só vale para PENDING_REVIEW (veja \`memoring inbox list\`).`);
+    }
+    let overrides = {};
+    const file = stringFlag(parsed.flags, 'file');
+    if (file) {
+        try {
+            overrides = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            fail(`JSON inválido em --file: ${e.message}`);
+        }
+    }
+    const flags = parsed.flags;
+    const tagsFlag = stringFlag(flags, 'tags');
+    const deckRef = stringFlag(flags, 'deck');
+    let deckId;
+    if (deckRef !== undefined) {
+        const deck = resolveDeck(await listDecks(), deckRef);
+        if (!deck) {
+            fail(`baralho "${deckRef}" não encontrado — veja \`memoring deck list\` ou crie com \`memoring deck create "${deckRef}"\` e tente de novo.`);
+        }
+        deckId = deck.id;
+    }
+    const merged = {
+        type: overrides.type ?? stringFlag(flags, 'type') ?? current.type,
+        title: overrides.title ?? stringFlag(flags, 'title') ?? current.title,
+        content: overrides.content ?? stringFlag(flags, 'content') ?? current.content ?? null,
+        front: overrides.front ?? stringFlag(flags, 'front') ?? current.front ?? null,
+        back: overrides.back ?? stringFlag(flags, 'back') ?? current.back ?? null,
+        subjectName: overrides.subjectName ?? stringFlag(flags, 'subject') ?? current.subjectName ?? null,
+        subtopicName: overrides.subtopicName ?? stringFlag(flags, 'subtopic') ?? current.subtopicName ?? null,
+        tags: overrides.tags ?? (tagsFlag !== undefined ? parseTagsFlag(tagsFlag) : current.tags ?? []),
+        source: overrides.source ?? stringFlag(flags, 'source') ?? current.source ?? null,
+        deckId: deckId ?? overrides.deckId ?? current.deckId ?? null,
+        question: overrides.question ?? current.question ?? null,
+    };
+    let updated;
+    try {
+        updated = (await apiFetch(`/notes/${id}`, { method: 'PUT', body: merged }));
+    }
+    catch (e) {
+        if (e instanceof ApiError) {
+            fail(`o servidor rejeitou a edição (${e.status}): ${e.body}`);
+        }
+        throw e;
+    }
+    if (parsed.flags.json) {
+        printJson(updated);
+        return;
+    }
+    process.stdout.write(green(`Item #${updated.id} [${updated.type}] "${updated.title}" atualizado — continua pendente de revisão.\n`));
+}
 export async function inboxCommand(parsed) {
     const [sub, idArg] = parsed._;
     switch (sub) {
@@ -26,10 +102,7 @@ export async function inboxCommand(parsed) {
         }
         case 'accept':
         case 'discard': {
-            const id = Number(idArg);
-            if (!idArg || !Number.isInteger(id) || id <= 0) {
-                fail(`informe o id numérico do item: memoring inbox ${sub} <id> (veja os ids com \`memoring inbox list\`).`);
-            }
+            const id = parseId(idArg, sub);
             try {
                 if (sub === 'accept') {
                     const note = (await apiFetch(`/notes/review-inbox/${id}/accept`, { method: 'POST' }));
@@ -68,12 +141,32 @@ export async function inboxCommand(parsed) {
             process.stdout.write(green(`${res.accepted} item(ns) aceito(s).\n`));
             return;
         }
+        case 'discard-all': {
+            const pending = await listInbox();
+            for (const note of pending) {
+                await apiFetch(`/notes/review-inbox/${note.id}`, { method: 'DELETE' });
+            }
+            if (parsed.flags.json) {
+                printJson({ discarded: pending.length });
+                return;
+            }
+            process.stdout.write(green(`${pending.length} item(ns) pendente(s) descartado(s).\n`));
+            return;
+        }
+        case 'update': {
+            await updateInboxItem(parsed, parseId(idArg, sub));
+            return;
+        }
         default:
-            process.stdout.write('Uso: memoring inbox <list|accept|accept-all|discard> [id] [--json]\n' +
-                '  list        lista os itens pendentes de revisão\n' +
-                '  accept <id> aceita um item (entra nas listagens e na fila FSRS)\n' +
-                '  accept-all  aceita todos os itens pendentes\n' +
-                '  discard <id> descarta um item pendente\n');
+            process.stdout.write('Uso: memoring inbox <list|accept|accept-all|discard|discard-all|update> [id] [--json]\n' +
+                '  list         lista os itens pendentes de revisão\n' +
+                '  accept <id>  aceita um item (entra nas listagens e na fila FSRS)\n' +
+                '  accept-all   aceita todos os itens pendentes\n' +
+                '  discard <id> descarta um item pendente\n' +
+                '  discard-all  descarta todos os itens pendentes\n' +
+                '  update <id>  edita um item PENDENTE (merge: --file parcial.json e/ou flags\n' +
+                '               --title --content --front --back --subject --subtopic\n' +
+                '               --tags a,b,c --source --type)\n');
             if (sub) {
                 process.exitCode = 1;
             }

package/dist/commands/stage.js

@@ -2,12 +2,14 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { apiFetch, ApiDedupedError, ApiError } from '../api.js';
 import { hasSession } from '../config.js';
+import { createDeck, listDecks, resolveDeck } from './deck.js';
 import { dim, fail, green, printJson, stringFlag, yellow } from './shared.js';
-const TYPES = ['NOTE', 'FLASHCARD', 'ONE_SHOT'];
+const TYPES = ['NOTE', 'FLASHCARD', 'ONE_SHOT', 'QUESTION'];
 // Retrocompat: itens.json antigos com "type": "NORMAL" são normalizados para "NOTE".
 const LEGACY_TYPE_ALIASES = { NORMAL: 'NOTE' };
 const MAX_ITEMS = 50;
 const DEFAULT_SOURCE = 'Importação assistida (CLI)';
+const QUESTION_KINDS = ['MULTIPLA_ESCOLHA', 'CERTO_ERRADO'];
 const UNLIMITED = -1;
 /**
  * GET /notes/import/agent-guidance, fail-open como o fetchStoredCaps: sem sessão/rede
@@ -66,11 +68,13 @@ const MAX_FLAG_BY_TYPE = {
     NOTE: 'max-notes',
     FLASHCARD: 'max-flashcards',
     ONE_SHOT: 'max-one-shots',
+    QUESTION: 'max-questions',
 };
 const TYPE_LABEL = {
     NOTE: 'notas',
     FLASHCARD: 'flashcards',
     ONE_SHOT: '1-shots',
+    QUESTION: 'questões',
 };
 /** Campo do ImportCaps ↔ flag (o `stage caps` também aceita --max-questions, usado pelo app). */
 const CAPS_FLAG_BY_FIELD = {
@@ -86,7 +90,12 @@ const CAPS_FLAG_BY_FIELD = {
  */
 function enforceTypeCaps(items, flags, stored) {
     const storedByType = stored
-        ? { NOTE: stored.maxNotes, FLASHCARD: stored.maxFlashcards, ONE_SHOT: stored.maxOneShots }
+        ? {
+            NOTE: stored.maxNotes,
+            FLASHCARD: stored.maxFlashcards,
+            ONE_SHOT: stored.maxOneShots,
+            QUESTION: stored.maxQuestions,
+        }
         : {};
     for (const [type, flag] of Object.entries(MAX_FLAG_BY_TYPE)) {
         const fromFlag = parseCapFlag(stringFlag(flags, flag), flag);
@@ -113,10 +122,24 @@ function enforceTypeCaps(items, flags, stored) {
         }
     }
 }
+/**
+ * Contrato do snapshot de questão estagiável pela CLI: apenas questões MANUAIS
+ * (sem identidade TEC — tecQuestionId e cia. nascem no servidor, nunca num payload
+ * de client). Espelha a validação de QuestionSnapshot.manual do backend.
+ */
+const QUESTION_CONTRACT = {
+    kind: 'MULTIPLA_ESCOLHA | CERTO_ERRADO (obrigatório)',
+    statementHtml: 'string — enunciado da questão (obrigatório; HTML leve)',
+    alternatives: 'string[] — 2 a 5 alternativas, não vazias (obrigatório em MULTIPLA_ESCOLHA; em CERTO_ERRADO não envie — o servidor usa o par fixo ["Certo", "Errado"])',
+    correctAlternative: 'int 1-based — gabarito (obrigatório; em CERTO_ERRADO: 1 = Certo, 2 = Errado)',
+    commentHtml: 'string? — explicação do gabarito (as regras de qualidade pedem sempre)',
+    subjectName: 'string? — matéria da questão (espelhe a do item; o snapshot guarda a dele)',
+    subtopicName: 'string? — subtópico da questão',
+};
 const SCHEMA_JSON = {
     description: 'Lote de 1..50 itens para POST /api/notes/review-inbox. All-or-nothing: qualquer item inválido rejeita o lote. Os itens nascem PENDING_REVIEW — o usuário aceita/edita/recusa em /cards/inbox.',
     item: {
-        type: 'NOTE | FLASHCARD | ONE_SHOT (obrigatório; NORMAL legado é aceito e mapeado para NOTE)',
+        type: 'NOTE | FLASHCARD | ONE_SHOT | QUESTION (obrigatório; NORMAL legado é aceito e mapeado para NOTE)',
         title: 'string (obrigatório)',
         content: 'string — corpo da nota em markdown (obrigatório quando type=NOTE)',
         front: 'string — pergunta (obrigatório quando type=FLASHCARD|ONE_SHOT)',
@@ -124,8 +147,11 @@ const SCHEMA_JSON = {
         subjectName: 'string? — matéria (ex.: "Direito Constitucional")',
         subtopicName: 'string? — subtópico',
         tags: 'string[]?',
+        deckName: 'string (OBRIGATÓRIO — cartão não fica sem baralho: consulte `memoring deck list`, reutilize um existente ou crie com `memoring deck create`; nome inexistente é criado no envio. A flag --deck do create vale como padrão do lote)',
+        question: 'objeto? — snapshot da questão (obrigatório quando type=QUESTION; contrato em questionContract)',
         source: `string? — origem do material (default: "${DEFAULT_SOURCE}")`,
     },
+    questionContract: QUESTION_CONTRACT,
     example: [
         {
             type: 'FLASHCARD',
@@ -133,28 +159,143 @@ const SCHEMA_JSON = {
             front: 'Quais são os quatro objetivos fundamentais da República (art. 3º da CF/88)?',
             back: 'I — construir uma sociedade livre, justa e solidária; II — garantir o desenvolvimento nacional; III — erradicar a pobreza e reduzir as desigualdades; IV — promover o bem de todos.',
             subjectName: 'Direito Constitucional',
+            deckName: 'Direito Constitucional',
             tags: ['cf88', 'art-3'],
             source: 'Apostila constitucional.pdf',
         },
+        {
+            type: 'QUESTION',
+            title: 'IBAMA 2025 — conceito de tributo',
+            subjectName: 'Direito Tributário',
+            deckName: 'Direito Tributário',
+            tags: ['ctn', 'art-3'],
+            source: 'aula-00.pdf',
+            question: {
+                kind: 'CERTO_ERRADO',
+                statementHtml: 'Considera-se tributo toda prestação pecuniária compulsória, instituída em lei, cobrada mediante atividade administrativa plenamente vinculada e que não constitua sanção por ato ilícito.',
+                correctAlternative: 1,
+                commentHtml: 'É a definição do art. 3º do CTN (Lei 5.172/1966).',
+            },
+        },
     ],
-    typeCaps: 'preferência por usuário (`memoring stage caps`, vale para app e CLI) — o `stage schema` mostra os limites ao agente (userCaps: -1 = à vontade, 0 = não gerar o tipo); flags do `stage create` (--max-notes N | --max-flashcards N | --max-one-shots N, ou "livre") vencem a preferência por lote.',
+    typeCaps: 'preferência por usuário (`memoring stage caps`, vale para app e CLI) — o `stage schema` mostra os limites ao agente (userCaps: -1 = à vontade, 0 = não gerar o tipo); flags do `stage create` (--max-notes N | --max-flashcards N | --max-one-shots N | --max-questions N, ou "livre") vencem a preferência por lote.',
 };
 const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/review-inbox):
 
-  type          NOTE | FLASHCARD | ONE_SHOT      (obrigatório; NORMAL legado é mapeado para NOTE)
+  type          NOTE | FLASHCARD | ONE_SHOT | QUESTION   (obrigatório; NORMAL legado é mapeado para NOTE)
   title         string                            (obrigatório)
   content       string — corpo da nota (markdown) (obrigatório quando type=NOTE)
   front, back   string — pergunta e resposta      (obrigatório quando type=FLASHCARD|ONE_SHOT)
+  question      objeto — snapshot da questão      (obrigatório quando type=QUESTION)
+  deckName      string — baralho de destino       (OBRIGATÓRIO — cartão não fica sem baralho:
+                                                   veja \`memoring deck list\`, reutilize ou crie
+                                                   com \`memoring deck create\`; --deck = padrão do lote)
   subjectName?  string — matéria (ex.: "Direito Constitucional")
   subtopicName? string — subtópico
   tags?         string[]
   source?       string — origem do material (default: "${DEFAULT_SOURCE}")
 
+Snapshot de QUESTION (questões manuais — sem identidade TEC):
+  kind               MULTIPLA_ESCOLHA | CERTO_ERRADO   (obrigatório)
+  statementHtml      string — enunciado (HTML leve)    (obrigatório)
+  alternatives       string[] — 2 a 5 alternativas     (obrigatório em MULTIPLA_ESCOLHA;
+                                                        em CERTO_ERRADO não envie — o par fixo é Certo/Errado)
+  correctAlternative int 1-based — gabarito            (obrigatório; CERTO_ERRADO: 1 = Certo, 2 = Errado)
+  commentHtml        string — explicação do gabarito   (recomendado)
+  subjectName/subtopicName  string? — matéria/subtópico DA QUESTÃO (o snapshot guarda os próprios)
+
 Lote: 1 a ${MAX_ITEMS} itens, all-or-nothing — qualquer item inválido rejeita o lote inteiro.
-Os itens nascem PENDING_REVIEW: o usuário aceita, edita ou recusa em /cards/inbox.
-Dica: FLASHCARD entra na fila de revisão espaçada (FSRS); ONE_SHOT é pergunta de resposta única.
+Os itens nascem PENDING_REVIEW: o usuário aceita, edita ou recusa em /cards/inbox
+(agentes podem editar pendentes com \`memoring inbox update <id>\`).
+Dica: FLASHCARD entra na fila de revisão espaçada (FSRS); ONE_SHOT é pergunta de resposta única
+(termo curto — ideal para princípios, leis, datas, prazos, siglas, termos em latim);
+QUESTION treina verificação objetiva (aproveite questões prontas do material).
 Limites por tipo: a preferência do usuário (abaixo, quando logado) vale por padrão;
---max-notes N | --max-flashcards N | --max-one-shots N no create vencem por lote ("livre" = à vontade).`;
+--max-notes N | --max-flashcards N | --max-one-shots N | --max-questions N no create vencem por lote ("livre" = à vontade).`;
+const NO_DECK_HINT = 'cartão não fica sem baralho: informe deckName no item ou --deck "<nome>" no lote. ' +
+    'Veja `memoring deck list` e reutilize um existente, ou crie com `memoring deck create "<nome>"`.';
+/** Exige baralho em TODO o lote: deckName no item ou a flag --deck como padrão. */
+function enforceDeck(items, flags) {
+    const batchDeck = stringFlag(flags, 'deck');
+    const index = items.findIndex((it) => !batchDeck && (typeof it.deckName !== 'string' || it.deckName.trim() === ''));
+    if (index >= 0) {
+        fail(`item #${index + 1} (${items[index].title}) está sem baralho — ${NO_DECK_HINT}`);
+    }
+}
+/**
+ * Resolve os baralhos do lote ANTES do POST: referências existentes são reutilizadas
+ * (id numérico ou nome exato case-insensitive) e nomes novos viram baralhos criados
+ * na hora — o agente nunca precisa sair do fluxo para criar estrutura.
+ */
+async function resolveBatchDecks(items, flags) {
+    const batchDeck = stringFlag(flags, 'deck')?.trim();
+    const refOf = (it) => typeof it.deckName === 'string' && it.deckName.trim() !== '' ? it.deckName.trim() : batchDeck;
+    const refs = new Set();
+    for (const it of items) {
+        const ref = refOf(it);
+        if (ref) {
+            refs.add(ref);
+        }
+    }
+    if (refs.size === 0) {
+        return { deckIds: items.map(() => null), createdNames: [] };
+    }
+    const decks = await listDecks();
+    const idByRef = new Map();
+    const createdNames = [];
+    for (const ref of refs) {
+        const existing = resolveDeck(decks, ref);
+        if (existing) {
+            idByRef.set(ref, existing.id);
+            continue;
+        }
+        if (Number.isInteger(Number(ref)) && Number(ref) > 0) {
+            fail(`baralho #${ref} não existe — ${NO_DECK_HINT}`);
+        }
+        const deck = await createDeck(ref);
+        decks.push(deck);
+        idByRef.set(ref, deck.id);
+        createdNames.push(ref);
+    }
+    return { deckIds: items.map((it) => idByRef.get(refOf(it) ?? '') ?? null), createdNames };
+}
+/**
+ * Atribui o baralho aos itens recém-estagiados (o POST da caixa de revisão não tem
+ * deckId — a atribuição é um PUT /notes/{id} por item, com o payload completo do
+ * item + deckId). Devolve os rótulos dos itens cuja atribuição falhou.
+ */
+async function assignDecks(items, created, deckIds) {
+    const failures = [];
+    for (let i = 0; i < created.length; i++) {
+        const deckId = deckIds[i];
+        if (deckId === null || deckId === undefined) {
+            continue;
+        }
+        const item = items[i];
+        try {
+            await apiFetch(`/notes/${created[i].id}`, {
+                method: 'PUT',
+                body: {
+                    type: item.type,
+                    title: item.title,
+                    content: item.content ?? null,
+                    front: item.front ?? null,
+                    back: item.back ?? null,
+                    subjectName: item.subjectName ?? null,
+                    subtopicName: item.subtopicName ?? null,
+                    tags: item.tags ?? [],
+                    source: item.source ?? null,
+                    deckId,
+                    question: item.question ?? null,
+                },
+            });
+        }
+        catch {
+            failures.push(`#${created[i].id} (${item.title})`);
+        }
+    }
+    return failures;
+}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -162,6 +303,68 @@ async function readStdin() {
     }
     return Buffer.concat(chunks).toString('utf8');
 }
+/**
+ * Valida o snapshot de questão manual espelhando QuestionSnapshot.manual do servidor:
+ * modalidade, enunciado, gabarito obrigatório apontando para alternativa existente e,
+ * em múltipla escolha, 2 a 5 alternativas não vazias. Certo/errado não leva
+ * alternatives — o servidor normaliza para o par fixo Certo/Errado.
+ */
+function validateQuestion(raw, where) {
+    if (typeof raw !== 'object' || raw === null) {
+        fail(`${where}: type=QUESTION exige o objeto "question" (veja o contrato em \`memoring stage schema\`).`);
+    }
+    const q = raw;
+    if ('tecQuestionId' in q || 'tecCadernoId' in q) {
+        fail(`${where}: a CLI só estagia questões manuais — não envie tecQuestionId/tecCadernoId (a identidade TEC nasce no servidor).`);
+    }
+    if (typeof q.kind !== 'string' || !QUESTION_KINDS.includes(q.kind)) {
+        fail(`${where}: question.kind deve ser ${QUESTION_KINDS.join(' | ')} (veio ${JSON.stringify(q.kind)}).`);
+    }
+    if (typeof q.statementHtml !== 'string' || q.statementHtml.trim() === '') {
+        fail(`${where}: question.statementHtml (enunciado) é obrigatório.`);
+    }
+    if (typeof q.correctAlternative !== 'number' || !Number.isInteger(q.correctAlternative)) {
+        fail(`${where}: question.correctAlternative (gabarito, int 1-based) é obrigatório.`);
+    }
+    const correct = q.correctAlternative;
+    const subjects = {
+        ...(typeof q.subjectName === 'string' ? { subjectName: q.subjectName } : {}),
+        ...(typeof q.subtopicName === 'string' ? { subtopicName: q.subtopicName } : {}),
+    };
+    if (q.kind === 'CERTO_ERRADO') {
+        if (correct < 1 || correct > 2) {
+            fail(`${where}: em CERTO_ERRADO o gabarito deve ser 1 (Certo) ou 2 (Errado) — veio ${correct}.`);
+        }
+        return {
+            kind: q.kind,
+            statementHtml: q.statementHtml,
+            correctAlternative: correct,
+            ...(typeof q.commentHtml === 'string' ? { commentHtml: q.commentHtml } : {}),
+            ...subjects,
+        };
+    }
+    if (!Array.isArray(q.alternatives) || q.alternatives.some((a) => typeof a !== 'string')) {
+        fail(`${where}: MULTIPLA_ESCOLHA exige question.alternatives como array de strings.`);
+    }
+    const alternatives = q.alternatives.map((a) => a.trim());
+    if (alternatives.length < 2 || alternatives.length > 5) {
+        fail(`${where}: MULTIPLA_ESCOLHA exige de 2 a 5 alternativas (vieram ${alternatives.length}).`);
+    }
+    if (alternatives.some((a) => a === '')) {
+        fail(`${where}: alternativas não podem ser vazias.`);
+    }
+    if (correct < 1 || correct > alternatives.length) {
+        fail(`${where}: gabarito ${correct} não aponta para alternativa existente (1..${alternatives.length}).`);
+    }
+    return {
+        kind: q.kind,
+        statementHtml: q.statementHtml,
+        alternatives,
+        correctAlternative: correct,
+        ...(typeof q.commentHtml === 'string' ? { commentHtml: q.commentHtml } : {}),
+        ...subjects,
+    };
+}
 function validateItems(raw) {
     const items = Array.isArray(raw) ? raw : raw?.items;
     if (!Array.isArray(items) || items.length === 0) {
@@ -192,6 +395,9 @@ function validateItems(raw) {
             (typeof it.front !== 'string' || it.front.trim() === '' || typeof it.back !== 'string' || it.back.trim() === '')) {
             fail(`${where} (${it.title}): type=${it.type} exige front e back.`);
         }
+        if (it.type === 'QUESTION') {
+            it.question = validateQuestion(it.question, `${where} (${it.title})`);
+        }
         if (it.tags !== undefined && (!Array.isArray(it.tags) || it.tags.some((t) => typeof t !== 'string'))) {
             fail(`${where} (${it.title}): tags deve ser um array de strings.`);
         }
@@ -217,32 +423,41 @@ async function emptyInbox() {
     }
     return pending.length;
 }
+const NO_SESSION_WARNING = 'SEM SESSÃO: userCaps, qualityRules e customInstructions ficam indisponíveis. ' +
+    'NÃO gere itens assim — rode `memoring auth login` (device flow, o usuário aprova no browser) e releia o schema antes de gerar.';
 export async function stageCommand(parsed) {
     const [sub] = parsed._;
     switch (sub) {
         case 'schema': {
+            const authenticated = hasSession();
             const [caps, guidance] = await Promise.all([fetchStoredCaps(), fetchAgentGuidance()]);
+            if (!authenticated) {
+                process.stderr.write(yellow(`aviso: ${NO_SESSION_WARNING}\n`));
+            }
             if (parsed.flags.json) {
                 printJson({
+                    authenticated,
                     ...SCHEMA_JSON,
-                    ...(caps
+                    userCaps: caps
                         ? {
-                            userCaps: {
-                                maxNotes: caps.maxNotes,
-                                maxFlashcards: caps.maxFlashcards,
-                                maxOneShots: caps.maxOneShots,
-                            },
+                            maxNotes: caps.maxNotes,
+                            maxFlashcards: caps.maxFlashcards,
+                            maxOneShots: caps.maxOneShots,
+                            maxQuestions: caps.maxQuestions,
                         }
-                        : {}),
-                    ...(guidance ?? {}),
+                        : null,
+                    qualityRules: guidance?.qualityRules ?? null,
+                    customInstructions: guidance?.customInstructions ?? null,
+                    ...(!authenticated ? { warning: NO_SESSION_WARNING } : {}),
                 });
             }
             else {
                 process.stdout.write(SCHEMA_TEXT + '\n');
                 if (caps) {
                     process.stdout.write(`\nLimites por tipo configurados por você — o agente DEVE respeitá-los ao gerar o lote: ` +
-                        `notas: ${capLabel(caps.maxNotes)}, flashcards: ${capLabel(caps.maxFlashcards)}, 1-shots: ${capLabel(caps.maxOneShots)}.\n` +
-                        dim('("à vontade" = crie quantos o material justificar; altere com `memoring stage caps`; QUESTION não é estagiável pela CLI)\n'));
+                        `notas: ${capLabel(caps.maxNotes)}, flashcards: ${capLabel(caps.maxFlashcards)}, ` +
+                        `1-shots: ${capLabel(caps.maxOneShots)}, questões: ${capLabel(caps.maxQuestions)}.\n` +
+                        dim('("à vontade" = crie quantos o material justificar; altere com `memoring stage caps`)\n'));
                 }
                 else {
                     process.stdout.write(dim('\n(limites por tipo indisponíveis — faça `memoring auth login` ou verifique a conexão)\n'));
@@ -257,6 +472,9 @@ export async function stageCommand(parsed) {
                             '\n');
                     }
                 }
+                else if (authenticated) {
+                    process.stdout.write(dim('\n(regras de qualidade indisponíveis — verifique a conexão e repita antes de gerar)\n'));
+                }
             }
             return;
         }
@@ -308,18 +526,24 @@ export async function stageCommand(parsed) {
                 fail(`JSON inválido: ${e.message}`);
             }
             const items = validateItems(parsedJson);
+            enforceDeck(items, parsed.flags);
             enforceTypeCaps(items, parsed.flags, await fetchStoredCaps());
+            const batchDecks = await resolveBatchDecks(items, parsed.flags);
             if (parsed.flags.replace) {
                 const removed = await emptyInbox();
                 if (!parsed.flags.json) {
                     process.stdout.write(dim(`${removed} item(ns) pendente(s) removido(s) da caixa de revisão.\n`));
                 }
             }
+            if (batchDecks.createdNames.length > 0 && !parsed.flags.json) {
+                process.stdout.write(dim(`Baralho(s) criado(s): ${batchDecks.createdNames.join(', ')}.\n`));
+            }
             let created;
             try {
                 const res = (await apiFetch('/notes/review-inbox', {
                     method: 'POST',
-                    body: { items },
+                    // deckName não faz parte do contrato do POST — o baralho é atribuído via PUT abaixo
+                    body: { items: items.map(({ deckName, ...rest }) => (void deckName, rest)) },
                     requestId: batchRequestId(raw),
                 }));
                 created = res.created;
@@ -327,7 +551,7 @@ export async function stageCommand(parsed) {
             catch (e) {
                 if (e instanceof ApiDedupedError) {
                     if (parsed.flags.json) {
-                        printJson({ created: [], deduplicated: true });
+                        printJson({ created: [], ids: [], deduplicated: true });
                         return;
                     }
                     process.stdout.write(green('Este lote já foi enviado antes — nada foi duplicado.\n'));
@@ -341,8 +565,20 @@ export async function stageCommand(parsed) {
                 }
                 throw e;
             }
+            const deckFailures = await assignDecks(items, created, batchDecks.deckIds);
+            if (deckFailures.length > 0) {
+                process.stderr.write(yellow(`aviso: ${deckFailures.length} item(ns) ficaram sem baralho por erro no PUT — corrija com \`memoring inbox update <id> --deck\`: ${deckFailures.join(', ')}\n`));
+            }
             if (parsed.flags.json) {
-                printJson({ created });
+                printJson({
+                    created,
+                    ids: created.map((note) => note.id),
+                    decks: {
+                        created: batchDecks.createdNames,
+                        assigned: created.length - deckFailures.length - batchDecks.deckIds.filter((id) => id === null).length,
+                        failed: deckFailures,
+                    },
+                });
                 return;
             }
             process.stdout.write(green(`OK — ${created.length} item(ns) aguardando revisão em /cards/inbox:\n`));
@@ -354,12 +590,16 @@ export async function stageCommand(parsed) {
         default:
             process.stdout.write('Uso: memoring stage <schema|caps|create> [--file itens.json] [--replace] [--json]\n' +
                 '  schema   imprime o contrato JSON dos itens (para humanos e agentes)\n' +
-                '           logado, inclui seus limites por tipo — o agente deve respeitá-los\n' +
+                '           logado, inclui seus limites por tipo e as regras de qualidade —\n' +
+                '           o agente deve ler o schema LOGADO, antes de gerar\n' +
                 '  caps     mostra/grava seus limites por tipo (--max-notes N | --max-flashcards N |\n' +
                 '           --max-one-shots N | --max-questions N; 0 = não gerar o tipo)\n' +
                 '  create   envia o lote para a caixa de revisão (arquivo ou stdin)\n' +
+                '           tipos: NOTE | FLASHCARD | ONE_SHOT | QUESTION\n' +
+                '           baralho OBRIGATÓRIO: deckName por item ou --deck "<nome|id>" no lote\n' +
+                '           (nomes inexistentes são criados; veja `memoring deck list`)\n' +
                 '           --replace esvazia a caixa antes de enviar\n' +
-                '           --max-notes N | --max-flashcards N | --max-one-shots N\n' +
+                '           --max-notes N | --max-flashcards N | --max-one-shots N | --max-questions N\n' +
                 '           vencem a preferência gravada por lote (validação local)\n');
             if (sub) {
                 process.exitCode = 1;

package/dist/main.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import { ApiError } from './api.js';
-import { setColorEnabled, yellow } from './output.js';
+import { CliError, setColorEnabled, yellow } from './output.js';
 import { authCommand } from './commands/auth.js';
+import { deckCommand } from './commands/deck.js';
 import { inboxCommand } from './commands/inbox.js';
 import { stageCommand } from './commands/stage.js';
 import { updateCommand } from './commands/update.js';
 import { skillCommand } from './commands/skill.js';
-import { fail, parseArgs as parse } from './commands/shared.js';
+import { parseArgs as parse } from './commands/shared.js';
 import { newerVersionAvailable, scheduleUpdateCheck } from './update.js';
-const VERSION = '0.6.0';
+const VERSION = '0.9.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -16,12 +17,19 @@ Uso: memoring <comando> [subcomando] [flags]
 Comandos:
   auth login|logout|status      autenticação (device flow — sem senha no terminal)
   stage schema                  contrato JSON dos itens da caixa de revisão
+                                (logado: inclui limites por tipo + regras de qualidade —
+                                agentes devem ler o schema LOGADO, antes de gerar)
   stage create [--file f]       envia itens (arquivo ou stdin) para a caixa de revisão
        [--replace]              esvazia a caixa antes de enviar
   stage caps [--max-* N]        seus limites por tipo (valem pro app e pros agentes)
   inbox list                    itens pendentes de revisão
   inbox accept <id>|accept-all  aceita itens (entram nas listagens e na fila FSRS)
   inbox discard <id>            descarta um item pendente
+  inbox discard-all             descarta todos os itens pendentes
+  inbox update <id>             edita um item pendente (--file parcial e/ou flags,
+                                inclui --deck <id|nome>)
+  deck list                     seus baralhos (id, nome, pai)
+  deck create <nome>            cria um baralho (--parent <id> p/ sub-baralho)
   update                        atualiza a CLI para a versão mais recente (via npm)
   skill                         guia completo da CLI para agentes de IA (imprime o SKILL.md)
   version                       versão da CLI
@@ -84,6 +92,9 @@ async function main() {
         case 'inbox':
             await inboxCommand(sub);
             return;
+        case 'deck':
+            await deckCommand(sub);
+            return;
         case 'update':
             await updateCommand(VERSION);
             return;
@@ -100,8 +111,16 @@ async function main() {
     }
 }
 main().catch((error) => {
+    if (error instanceof CliError) {
+        // mensagem já impressa pelo fail() — só converte em exit code, sem process.exit (ver CliError)
+        process.exitCode = 1;
+        return;
+    }
     if (error instanceof ApiError) {
-        fail(`falha na API (${error.status}): ${error.body}`);
+        process.stderr.write(`Erro: falha na API (${error.status}): ${error.body}\n`);
+        process.exitCode = 1;
+        return;
     }
-    fail(error instanceof Error ? error.message : String(error));
+    process.stderr.write(`Erro: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
 });

package/dist/output.js

@@ -25,7 +25,15 @@ export function printTable(rows, columns) {
         process.stdout.write(renderRow(columns.map((c) => String(row[c.key] ?? ''))) + '\n');
     }
 }
+/**
+ * Erro de uso/validação já reportado no stderr. O `main` o converte em exitCode 1
+ * SEM process.exit(): no Windows, sair via process.exit() com o timer do
+ * AbortSignal.timeout (apiFetch) ainda pendente derruba o processo com assert do
+ * libuv (exit 127 em vez de 1). A saída natural drena o loop e evita o crash.
+ */
+export class CliError extends Error {
+}
 export function fail(message) {
     process.stderr.write(red(`Erro: ${message}`) + '\n');
-    process.exit(1);
+    throw new CliError(message);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoring/cli",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "CLI do Memoring — envie flashcards/notas gerados por IA para a sua caixa de revisão, direto do terminal.",
   "repository": {
     "type": "git",

package/skills/memoring-cli/SKILL.md

@@ -7,22 +7,26 @@ description: Gere flashcards e notas a partir de materiais de estudo locais (PDF
 
 O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring` é a ponte entre você (o agente, que lê o material e gera o conteúdo) e a conta do usuário no app. Você NÃO chama a API HTTP diretamente — use sempre a CLI. Este guia está sempre disponível via `memoring skill`.
 
-## Pré-requisitos
+## Pré-requisitos (NESTA ORDEM — não pule)
 
 1. CLI instalada: `memoring version` deve responder. Se não, peça ao usuário: `npm install -g @memoring/cli`.
-2. Sessão ativa: `memoring auth status --json` → `authenticated: true`. Se não, peça ao usuário para rodar `memoring auth login` (device flow — ele aprova no browser; você não consegue fazer isso por ele).
+2. **Sessão ativa ANTES de qualquer geração**: `memoring auth status --json` → `authenticated: true`. Se não, peça ao usuário para rodar `memoring auth login` (device flow — ele aprova no browser; você não consegue fazer isso por ele) e ESPERE o login concluir.
+3. **NUNCA gere itens sem sessão.** Deslogado, o `stage schema` omite as regras de qualidade (`qualityRules`), os limites do usuário (`userCaps`) e as instruções custom (`customInstructions`) — o JSON traz `authenticated: false` + `warning`. Gerar sem essas regras produz lotes fora do padrão do app. Se o usuário insistir em gerar offline, avise que a qualidade ficará comprometida e que o lote precisará ser refeito.
 
 ## Mapa dos comandos
 
 | Comando | O que faz |
 | --- | --- |
 | `memoring auth login\|logout\|status` | sessão (device flow — sem senha no terminal) |
-| `memoring stage schema [--json]` | O CONTRATO dos itens + os limites por tipo do usuário — leia SEMPRE antes de gerar |
+| `memoring stage schema [--json]` | O CONTRATO dos itens + limites por tipo + regras de qualidade — leia SEMPRE, logado, antes de gerar |
 | `memoring stage caps [--max-* N\|livre]` | limites por tipo do usuário (preferência DELE — nunca escreva sem ele pedir) |
-| `memoring stage create --file f [--replace] [--max-* N]` | envia o lote (1 a 50 itens) para a caixa de revisão |
+| `memoring stage create --file f [--replace] [--max-* N] [--deck nome]` | envia o lote (1 a 50 itens) para a caixa de revisão — **baralho OBRIGATÓRIO** (deckName por item ou `--deck` no lote; nomes novos viram baralhos); `--json` devolve `created` + `ids` |
+| `memoring deck list` | seus baralhos (id, nome, pai) — consulte ANTES de gerar |
+| `memoring deck create <nome> [--parent id]` | cria baralho (idempotente) |
 | `memoring inbox list` | itens pendentes de revisão |
 | `memoring inbox accept <id>\|accept-all` | aceita itens (entram nas listagens e na fila FSRS) |
-| `memoring inbox discard <id>` | descarta um item pendente |
+| `memoring inbox discard <id>\|discard-all` | descarta item(ns) pendente(s) |
+| `memoring inbox update <id> [--file parcial.json] [--title ...] [--front ...] [--back ...] [--tags a,b] ...` | edita um item AINDA PENDENTE (merge com o estado atual) |
 | `memoring skill` | imprime este guia |
 | `memoring update` | atualiza a CLI (decisão do usuário — nunca rode por conta própria) |
 
@@ -31,16 +35,21 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 ## Fluxo padrão
 
 1. **Entenda o pedido** — qual pasta/arquivo/material vira flashcards/notas e se o usuário pediu quantidades.
-2. **Leia o contrato, os limites e as regras**: `memoring stage schema --json`. Além do contrato, a saída traz: `userCaps` — os limites por tipo DO USUÁRIO (`-1` = à vontade, `0` = não gerar o tipo, `N` = teto), respeite-os SEMPRE; `qualityRules` — as regras de qualidade INTEGRAIS (as mesmas que o app envia à LLM), aplique-as em TODOS os itens; `customInstructions` — instruções adicionais do usuário (quando não-nulas), também sempre aplicadas. Tudo isso vale mesmo sem pedido explícito no chat.
-3. **Leia os materiais** e gere os itens no contrato, num arquivo JSON (array ou `{ "items": [...] }`).
-4. **Envie**: `memoring stage create --file <arquivo> --json`. Se o lote for rejeitado por limite de tipo, ajuste o LOTE — não relaxe o limite do usuário.
-5. **Avise o usuário**: quantos itens foram para a caixa de revisão e onde aceitar — no app em `/cards/inbox` ou `memoring inbox list` / `memoring inbox accept-all`.
+2. **Confira a sessão**: `memoring auth status --json`. Sem `authenticated: true`, PARE e peça o login (ver Pré-requisitos).
+3. **Leia o contrato, os limites e as regras**: `memoring stage schema --json` (logado). Além do contrato, a saída traz: `userCaps` — os limites por tipo DO USUÁRIO (`-1` = à vontade, `0` = não gerar o tipo, `N` = teto), respeite-os SEMPRE; `qualityRules` — as regras de qualidade INTEGRAIS (as mesmas que o app envia à LLM), aplique-as em TODOS os itens; `customInstructions` — instruções adicionais do usuário (quando não-nulas), também sempre aplicadas. Tudo isso vale mesmo sem pedido explícito no chat.
+4. **Defina o baralho** — cartão NÃO fica sem baralho. Rode `memoring deck list`, escolha o baralho adequado ao material e reutilize o nome; se não existir, crie com `memoring deck create "<nome>"` (ou deixe o próprio `stage create` criar pelo nome). Todo item do lote deve levar `deckName` — ou use `--deck "<nome>"` no create como padrão do lote. Lote sem baralho é REJEITADO pela validação local.
+5. **Leia os materiais** e gere os itens no contrato, num arquivo JSON (array ou `{ "items": [...] }`).
+6. **Envie**: `memoring stage create --file <arquivo> --json`. Se o lote for rejeitado por limite de tipo, ajuste o LOTE — não relaxe o limite do usuário.
+7. **Guarde os `ids` retornados** pelo create: enquanto os itens estiverem PENDING_REVIEW você pode corrigi-los com `memoring inbox update <id>` — sem precisar descartar e reenviar.
+8. **Avise o usuário**: quantos itens foram para a caixa de revisão e onde aceitar — no app em `/cards/inbox` ou `memoring inbox list` / `memoring inbox accept-all`.
 
 ## O contrato (a fonte da verdade é `stage schema`)
 
-- `type`: `NOTE` (nota, exige `content` markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`).
+- `type`: `NOTE` (nota, exige `content` markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`) ou `QUESTION` (exige `question` — ver abaixo).
 - `title` sempre obrigatório; lote de 1 a 50 itens, all-or-nothing — qualquer item inválido rejeita o lote inteiro.
-- `ONE_SHOT` = pergunta de resposta única (uma palavra ou termo curto); prefira `FLASHCARD` para memorização.
+- `deckName` **OBRIGATÓRIO** (ou `--deck` no create como padrão do lote): cartão não fica sem baralho. Use o nome de um baralho de `memoring deck list`; nome inexistente é criado no envio.
+- `ONE_SHOT` = pergunta de resposta única (UMA palavra ou termo curto, texto puro). Ative o tipo sempre que o cobrável for recall de termo puro — nome de princípio/instituto, termo em latim, sigla, número de lei/artigo, data, prazo. Resposta cabe num termo → `ONE_SHOT`; exige frase ou explicação → `FLASHCARD`.
+- `QUESTION` = questão objetiva para verificação: `question.kind` (`MULTIPLA_ESCOLHA` | `CERTO_ERRADO`), `question.statementHtml` (enunciado), `question.correctAlternative` (gabarito, int 1-based; em CERTO_ERRADO, 1 = Certo, 2 = Errado), `question.alternatives` (2 a 5 textos — só em MULTIPLA_ESCOLHA), `question.commentHtml` (explicação do gabarito). **Se o material contiver questões prontas (provas, simulados, listas C/E), APROVEITE-AS como QUESTION** preservando enunciado e gabarito — não as achate em flashcards.
 - Preencha `source` com a origem real do material (nome do arquivo/pasta) — não use o default quando souber a origem.
 - `subjectName`/`subtopicName` quando o material tiver matéria/subtópico claros; `tags` curtas e em minúsculas.
 - NUNCA invente campos fora do contrato — o servidor rejeita o lote inteiro.
@@ -54,11 +63,12 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 
 ## Qualidade dos flashcards (o padrão que o app espera)
 
-Cartões atômicos: UMA ideia por cartão — se um conceito tem 3 partes cobráveis, crie 3 cartões, nunca um cartão com lista como resposta. A frente é uma pergunta direta que força LEMBRAR (não reconhecer). A resposta é auto-contida (faz sentido sem o material) e curta. Pares confundíveis (prazos, siglas, exceções) levam na frente o traço que os diferencia. Não invente conteúdo que não esteja no material.
+Cartões atômicos: UMA ideia por cartão — se um conceito tem 3 partes cobráveis, crie 3 cartões, nunca um cartão com lista como resposta. A frente é uma pergunta direta que força LEMBRAR (não reconhecer). A resposta é auto-contida (faz sentido sem o material) e curta. Pares confundíveis (prazos, siglas, exceções) levam na frente o traço que os diferencia. Não invente conteúdo que não esteja no material. Distribua os tipos: um bom lote usa NOTE, FLASHCARD, ONE_SHOT e QUESTION conforme o material pedir — não zere um tipo por timidez (termos, leis, datas e prazos cobráveis viram ONE_SHOT).
 
 ## Armadilhas
 
-- **Nunca** use `--replace` sem o usuário pedir explicitamente — ele apaga os itens pendentes existentes da caixa.
+- **Nunca** use `--replace` ou `inbox discard-all` sem o usuário pedir explicitamente — eles apagam os itens pendentes existentes da caixa.
 - Se aparecer um aviso de versão nova no stderr, ignore e siga o fluxo — **não** rode `memoring update` por conta própria; atualizar a CLI é decisão do usuário.
 - **Não** altere os limites do usuário (`stage caps`) por conta própria — é preferência dele, compartilhada com o app.
 - Se `stage create` falhar com erro de validação do servidor, corrija os itens indicados e reenvie — não relaxe o contrato.
+- Errou um item já enviado? Não reenvie o lote (duplicaria): use `memoring inbox update <id>` enquanto ele estiver PENDING_REVIEW.