@memoring/cli 0.8.0 → 0.10.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>` / discard-all / update `<id>` (edita item PENDENTE — merge do `--file` parcial e/ou flags `--title --front --back --tags a,b ...`) |
+| `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 |
@@ -92,6 +93,7 @@ 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`), `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.

package/dist/commands/deck.js

@@ -0,0 +1,281 @@
+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;
+    }
+}
+const COVER_TONES = ['gray', 'orange', 'green', 'blue', 'purple'];
+const GOAL_MAX_LENGTH = 160;
+const GOAL_DISPLAY_MAX = 30;
+/** "4,5" (vírgula decimal pt-BR) ou "—" quando sem relevância. */
+function formatRelevance(relevance) {
+    return relevance === null ? '—' : relevance.toFixed(1).replace('.', ',');
+}
+/** Countdown da data-alvo em dias: futuro "42d", atrasado "-3d" (base UTC, sem fuso). */
+function goalCountdown(goalDate) {
+    if (!goalDate) {
+        return null;
+    }
+    const target = Date.parse(`${goalDate}T00:00:00Z`);
+    if (Number.isNaN(target)) {
+        return null;
+    }
+    const now = new Date();
+    const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    return `${Math.round((target - today) / 86_400_000)}d`;
+}
+/** META da listagem/update: goal + countdown da data-alvo, célula de ~30 chars. */
+function formatGoal(deck) {
+    const suffix = (() => {
+        const countdown = goalCountdown(deck.goalDate);
+        return countdown === null ? '' : ` (${countdown})`;
+    })();
+    const budget = GOAL_DISPLAY_MAX - suffix.length;
+    let goal = (deck.goal ?? '').trim();
+    if (goal.length > budget) {
+        goal = `${goal.slice(0, Math.max(1, budget - 1)).trimEnd()}…`;
+    }
+    const label = `${goal}${suffix}`.trim();
+    return label === '' ? '—' : label;
+}
+/** 45s | 12min | 1h05 — segundos inteiros; médias chegam já arredondadas. */
+function formatRunSeconds(seconds) {
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes}min`;
+    }
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}`;
+}
+/**
+ * Recorde exibido: para o pai é a MÉDIA ARITMÉTICA dos filhos com recorde (o
+ * fastestRunSeconds do DeckView é só do próprio baralho — quem tem a árvore
+ * toda calcula a média); sem filho com recorde, cai no próprio do baralho.
+ */
+function recordOf(deck, childrenByParent) {
+    const records = (childrenByParent.get(deck.id) ?? [])
+        .map((child) => child.fastestRunSeconds)
+        .filter((seconds) => seconds !== null);
+    if (records.length > 0) {
+        return Math.round(records.reduce((sum, seconds) => sum + seconds, 0) / records.length);
+    }
+    return deck.fastestRunSeconds;
+}
+function parseRelevanceFlag(raw) {
+    const normalized = raw.replace(',', '.');
+    if (!/^\d+(\.\d)?$/.test(normalized)) {
+        fail(`--relevance inválido: use 0 a 5 com no máximo 1 casa decimal (ex.: 4 ou 4,5 — veio ${JSON.stringify(raw)}).`);
+    }
+    const value = Number(normalized);
+    if (value > 5) {
+        fail(`--relevance deve estar entre 0 e 5 (veio ${raw}).`);
+    }
+    return value;
+}
+function parseGoalFlag(raw) {
+    const goal = raw.trim();
+    if (goal === '') {
+        fail('--goal vazio — para limpar a meta use --clear-goal.');
+    }
+    if (goal.length > GOAL_MAX_LENGTH) {
+        fail(`--goal excede ${GOAL_MAX_LENGTH} caracteres (veio ${goal.length}).`);
+    }
+    return goal;
+}
+function parseGoalDateFlag(raw) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        fail(`--goal-date inválido: use o formato AAAA-MM-DD (veio ${JSON.stringify(raw)}).`);
+    }
+    const time = Date.parse(`${raw}T00:00:00Z`);
+    if (Number.isNaN(time) || new Date(time).toISOString().slice(0, 10) !== raw) {
+        fail(`--goal-date inválido: ${raw} não é uma data real.`);
+    }
+    return raw;
+}
+function parseToneFlag(raw) {
+    const tone = raw.trim().toLowerCase();
+    if (!COVER_TONES.includes(tone)) {
+        fail(`--tone inválido: use ${COVER_TONES.join(' | ')} (veio ${JSON.stringify(raw)}).`);
+    }
+    return tone;
+}
+const METADATA_SPECS = [
+    { valueFlag: 'relevance', clearFlag: 'clear-relevance', field: 'relevance', parse: parseRelevanceFlag },
+    { valueFlag: 'goal', clearFlag: 'clear-goal', field: 'goal', parse: parseGoalFlag },
+    { valueFlag: 'goal-date', clearFlag: 'clear-goal-date', field: 'goalDate', parse: parseGoalDateFlag },
+    { valueFlag: 'tone', clearFlag: 'clear-tone', field: 'coverTone', parse: parseToneFlag },
+];
+/**
+ * Monta o body do PUT /metadata com SÓ os campos informados: flag de valor
+ * envia o valor validado, --clear-* envia null explícito (limpa), os dois
+ * juntos é erro. Ausente dos dois = campo intacto (o PUT não toca).
+ */
+function metadataBody(flags) {
+    const body = {};
+    for (const spec of METADATA_SPECS) {
+        const raw = stringFlag(flags, spec.valueFlag);
+        const clear = flags[spec.clearFlag] === true;
+        if (raw !== undefined && clear) {
+            fail(`--${spec.valueFlag} e --${spec.clearFlag} não podem ir juntos — use um ou outro.`);
+        }
+        if (raw !== undefined) {
+            body[spec.field] = spec.parse(raw);
+        }
+        else if (clear) {
+            body[spec.field] = null;
+        }
+    }
+    if (Object.keys(body).length === 0) {
+        fail('nada a atualizar — informe ao menos um campo: --relevance, --goal, --goal-date, --tone ou um --clear-*.');
+    }
+    return body;
+}
+function printDeckSummary(deck) {
+    process.stdout.write(green(`Baralho "${deck.name}" (#${deck.id}) atualizado.\n`));
+    process.stdout.write(`  relevância:  ${formatRelevance(deck.relevance)}\n`);
+    process.stdout.write(`  meta:        ${formatGoal(deck)}\n`);
+    process.stdout.write(`  tom de capa: ${deck.coverTone ?? '—'}\n`);
+}
+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]));
+            const childrenByParent = new Map();
+            for (const d of decks) {
+                if (d.parentId !== null) {
+                    const siblings = childrenByParent.get(d.parentId) ?? [];
+                    siblings.push(d);
+                    childrenByParent.set(d.parentId, siblings);
+                }
+            }
+            printTable(decks.map((d) => ({
+                id: `#${d.id}`,
+                name: d.name,
+                parent: d.parentId !== null ? (nameById.get(d.parentId) ?? `#${d.parentId}`) : '—',
+                due: d.dueCount,
+                relevance: formatRelevance(d.relevance),
+                goal: formatGoal(d),
+                record: (() => {
+                    const record = recordOf(d, childrenByParent);
+                    return record === null ? '—' : formatRunSeconds(record);
+                })(),
+            })), [
+                { key: 'id', label: 'ID' },
+                { key: 'name', label: 'NOME' },
+                { key: 'parent', label: 'BARALHO-PAI' },
+                { key: 'due', label: 'A REVISAR' },
+                { key: 'relevance', label: 'RELEVÂNCIA' },
+                { key: 'goal', label: 'META' },
+                { key: 'record', label: 'RECORDE' },
+            ]);
+            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;
+        }
+        case 'update': {
+            const ref = rest.join(' ').trim();
+            if (ref === '') {
+                fail('informe o baralho: memoring deck update <id|nome> [--relevance 0-5] [--goal "txt"] ...');
+            }
+            const deck = resolveDeck(await listDecks(), ref);
+            if (!deck) {
+                fail(`baralho "${ref}" não encontrado — veja os ids/nomes com \`memoring deck list\`.`);
+            }
+            const body = metadataBody(parsed.flags);
+            let updated;
+            try {
+                updated = (await apiFetch(`/notes/decks/${deck.id}/metadata`, { method: 'PUT', body }));
+            }
+            catch (e) {
+                if (e instanceof ApiError) {
+                    fail(`o servidor rejeitou a atualização do baralho "${deck.name}" (#${deck.id}) (${e.status}): ${e.body}`);
+                }
+                throw e;
+            }
+            if (parsed.flags.json) {
+                printJson(updated);
+                return;
+            }
+            printDeckSummary(updated);
+            return;
+        }
+        default:
+            process.stdout.write('Uso: memoring deck <list|create|update> [id|nome] [flags]\n' +
+                '  list             lista seus baralhos (id, nome, pai, a revisar, relevância, meta, recorde)\n' +
+                '  create <nome>    cria um baralho (idempotente: nome existente só retorna o atual)\n' +
+                '                   --parent <id|nome> cria como sub-baralho\n' +
+                '  update <id|nome> define metadados do baralho\n' +
+                '                   --relevance 0-5 (1 casa) | --goal "txt" (<=160) | --goal-date AAAA-MM-DD\n' +
+                '                   --tone gray|orange|green|blue|purple | --clear-relevance --clear-goal\n' +
+                '                   --clear-goal-date --clear-tone (limpa o campo) | --json\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}

package/dist/commands/inbox.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { apiFetch, ApiError } from '../api.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'));
@@ -40,6 +41,15 @@ async function updateInboxItem(parsed, id) {
     }
     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,
@@ -50,7 +60,7 @@ async function updateInboxItem(parsed, id) {
         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: overrides.deckId ?? current.deckId ?? null,
+        deckId: deckId ?? overrides.deckId ?? current.deckId ?? null,
         question: overrides.question ?? current.question ?? null,
     };
     let updated;

package/dist/commands/stage.js

@@ -2,6 +2,7 @@ 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', 'QUESTION'];
 // Retrocompat: itens.json antigos com "type": "NORMAL" são normalizados para "NOTE".
@@ -146,6 +147,7 @@ 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}")`,
     },
@@ -157,6 +159,7 @@ 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',
         },
@@ -164,6 +167,7 @@ const SCHEMA_JSON = {
             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: {
@@ -183,6 +187,13 @@ const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/re
   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.
+                                                   Espelhe a hierarquia do material: matéria = baralho
+                                                   raiz; tema da aula/capítulo = sub-baralho criado
+                                                   ANTES com \`deck create "<tema>" --parent "<matéria>"\`
+                                                   — o create-por-nome só cria baralho raiz)
   subjectName?  string — matéria (ex.: "Direito Constitucional")
   subtopicName? string — subtópico
   tags?         string[]
@@ -205,6 +216,90 @@ Dica: FLASHCARD entra na fila de revisão espaçada (FSRS); ONE_SHOT é pergunta
 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 | --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) {
@@ -435,18 +530,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;
@@ -468,8 +569,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, ids: created.map((note) => note.id) });
+                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`));
@@ -487,6 +600,8 @@ export async function stageCommand(parsed) {
                 '           --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 | --max-questions N\n' +
                 '           vencem a preferência gravada por lote (validação local)\n');

package/dist/main.js

@@ -2,13 +2,14 @@
 import { ApiError } from './api.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 { parseArgs as parse } from './commands/shared.js';
 import { newerVersionAvailable, scheduleUpdateCheck } from './update.js';
-const VERSION = '0.8.0';
+const VERSION = '0.10.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -25,7 +26,12 @@ Comandos:
   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)
+  inbox update <id>             edita um item pendente (--file parcial e/ou flags,
+                                inclui --deck <id|nome>)
+  deck list                     seus baralhos (id, nome, pai, a revisar, relevância, meta, recorde)
+  deck create <nome>            cria um baralho (--parent <id|nome> p/ sub-baralho)
+  deck update <id|nome>         metadados do baralho (--relevance/--goal/--goal-date/--tone;
+                                --clear-* limpa um campo)
   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
@@ -88,6 +94,9 @@ async function main() {
         case 'inbox':
             await inboxCommand(sub);
             return;
+        case 'deck':
+            await deckCommand(sub);
+            return;
         case 'update':
             await updateCommand(VERSION);
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoring/cli",
-  "version": "0.8.0",
+  "version": "0.10.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

@@ -20,7 +20,10 @@ O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring`
 | `memoring auth login\|logout\|status` | sessão (device flow — sem senha no terminal) |
 | `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; `--json` devolve `created` + `ids` |
+| `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, a revisar, relevância, meta, recorde) — consulte ANTES de gerar |
+| `memoring deck create <nome> [--parent id]` | cria baralho (idempotente) |
+| `memoring deck update <id\|nome> [--relevance <0-5>] [--goal "<txt>"] [--goal-date AAAA-MM-DD] [--tone <gray\|orange\|green\|blue\|purple>] [--clear-*]` | define metadados do baralho (relevância, meta, data-alvo, tom de capa; `--clear-*` limpa o campo) |
 | `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>\|discard-all` | descarta item(ns) pendente(s) |
@@ -35,15 +38,17 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 1. **Entenda o pedido** — qual pasta/arquivo/material vira flashcards/notas e se o usuário pediu quantidades.
 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. **Leia os materiais** e gere os itens no contrato, num arquivo JSON (array ou `{ "items": [...] }`).
-5. **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.
-6. **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.
-7. **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`.
+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). **Espelhe a hierarquia do material:** a matéria vira baralho raiz; o tema da aula/capítulo vira sub-baralho criado ANTES com `memoring deck create "<tema>" --parent "<matéria>"` — o create-por-nome do `stage create` só cria baralho raiz. 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`) 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.
+- `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. Espelhe a hierarquia do material: matéria = baralho raiz; tema da aula/capítulo = sub-baralho criado ANTES com `deck create "<tema>" --parent "<matéria>"` (o `stage create` só cria raiz pelo nome).
 - `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.