@memoring/cli 0.12.1 → 0.15.0

package/dist/commands/stage.js

@@ -2,14 +2,27 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { apiFetch, ApiDedupedError, ApiError } from '../api.js';
 import { hasSession } from '../config.js';
+import { validateBatchReferences } from '../pdf/batchValidation.js';
+import { PdfDocumentCache } from '../pdf/documentCache.js';
 import { createDeck, listDecks, resolveDeck } from './deck.js';
+import { MATERIAL_REFERENCE_CONTRACT, toWireMaterialReference, validateMaterialReferences, } from './materialReferences.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".
-const LEGACY_TYPE_ALIASES = { NORMAL: 'NOTE' };
+const TYPES = ['NOTE', 'NORMAL', 'ONE_SHOT', 'QUESTION'];
+// Retrocompat: itens.json antigos com "type": "FLASHCARD" são normalizados para "NORMAL"
+// (rename da espécie V238 — o backend também aceita o token legado na entrada).
+const LEGACY_TYPE_ALIASES = { FLASHCARD: 'NORMAL' };
 const MAX_ITEMS = 50;
 const DEFAULT_SOURCE = 'Importação assistida (CLI)';
 const QUESTION_KINDS = ['MULTIPLA_ESCOLHA', 'CERTO_ERRADO'];
+/** MaterialReferenceInput e validação de referências vivem em materialReferences.ts
+ *  (fronteira única usada pelo stage e pelo `memoring reference`). */
+/**
+ * Slug minúsculo (letras, números, hífens, até 80 chars) que identifica o conceito
+ * do item. Segmentos alfanuméricos separados por hífen único — sem hífen no
+ * início/fim nem duplo, espelhando a validação do backend (`assignConceptKey`).
+ */
+const CONCEPT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CONCEPT_KEY_MAX = 80;
 const UNLIMITED = -1;
 /**
  * GET /notes/import/agent-guidance, fail-open como o fetchStoredCaps: sem sessão/rede
@@ -66,13 +79,13 @@ async function fetchStoredCaps() {
 /** Flags --max-<tipo>: no `stage create` limitam o lote; no `stage caps` gravam a preferência. */
 const MAX_FLAG_BY_TYPE = {
     NOTE: 'max-notes',
-    FLASHCARD: 'max-flashcards',
+    NORMAL: 'max-flashcards',
     ONE_SHOT: 'max-one-shots',
     QUESTION: 'max-questions',
 };
 const TYPE_LABEL = {
     NOTE: 'notas',
-    FLASHCARD: 'flashcards',
+    NORMAL: 'flashcards',
     ONE_SHOT: '1-shots',
     QUESTION: 'questões',
 };
@@ -92,7 +105,7 @@ function enforceTypeCaps(items, flags, stored) {
     const storedByType = stored
         ? {
             NOTE: stored.maxNotes,
-            FLASHCARD: stored.maxFlashcards,
+            NORMAL: stored.maxFlashcards,
             ONE_SHOT: stored.maxOneShots,
             QUESTION: stored.maxQuestions,
         }
@@ -139,29 +152,42 @@ const QUESTION_CONTRACT = {
 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 | QUESTION (obrigatório; NORMAL legado é aceito e mapeado para NOTE)',
+        type: 'NOTE | NORMAL | ONE_SHOT | QUESTION (obrigatório; FLASHCARD legado é aceito e mapeado para NORMAL)',
         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)',
-        back: 'string — resposta (obrigatório quando type=FLASHCARD|ONE_SHOT)',
+        front: 'string — pergunta (obrigatório quando type=NORMAL|ONE_SHOT)',
+        back: 'string — resposta (obrigatório quando type=NORMAL|ONE_SHOT)',
         subjectName: 'string? — matéria (ex.: "Direito Constitucional")',
         subtopicName: 'string? — subtópico',
         tags: 'string[]?',
+        conceptKey: `string? — conceito do item em slug minúsculo (letras/números/hífens, até ${CONCEPT_KEY_MAX} chars). Opcional por compatibilidade, mas FORTEMENTE RECOMENDADO em NORMAL/ONE_SHOT/QUESTION: cartões sobre o MESMO conceito compartilham a chave (ex.: "trib-art-4" num flashcard E numa questão do art. 4º do CTN — o whiteboard do app agrupa por conceito) e conceitos DIFERENTES usam chaves diferentes — nunca reuse a chave para outro conceito`,
         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 como PENDING — oculto no app até o 1º item aceite, que ativa o baralho e os ancestrais pendentes. 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}")`,
+        materialReferences: 'array? — referências ao material de origem (contrato em materialReferenceContract): vinculam o item à página do PDF no app — ao aceitar, o link abre o material NA PÁGINA e destaca o trecho exato (quote para PDF com texto, region para escaneado). Não confunda com source (texto livre) — use os dois juntos',
     },
     questionContract: QUESTION_CONTRACT,
+    materialReferenceContract: MATERIAL_REFERENCE_CONTRACT,
     example: [
         {
-            type: 'FLASHCARD',
+            type: 'NORMAL',
             title: 'CF/88 — objetivos fundamentais',
             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'],
+            conceptKey: 'const-cf88-art-3',
             source: 'Apostila constitucional.pdf',
+            materialReferences: [
+                {
+                    driveFileId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
+                    page: 35,
+                    excerpt: 'Objetivos fundamentais (art. 3º, CF/88).',
+                    quote: 'Art. 3º — Constituem objetivos fundamentais da República Federativa do Brasil construir uma sociedade livre, justa e solidária [...].',
+                    contextBefore: 'CAPÍTULO I — DOS PRINCÍPIOS FUNDAMENTAIS',
+                },
+            ],
         },
         {
             type: 'QUESTION',
@@ -169,6 +195,7 @@ const SCHEMA_JSON = {
             subjectName: 'Direito Tributário',
             deckName: 'Direito Tributário',
             tags: ['ctn', 'art-3'],
+            conceptKey: 'trib-ctn-art-3',
             source: 'aula-00.pdf',
             question: {
                 kind: 'CERTO_ERRADO',
@@ -177,15 +204,41 @@ const SCHEMA_JSON = {
                 commentHtml: 'É a definição do art. 3º do CTN (Lei 5.172/1966).',
             },
         },
+        {
+            type: 'NORMAL',
+            title: 'CTN art. 4º — territorialidade',
+            front: 'Qual a regra de incidência dos tributos quanto à aplicação da lei (art. 4º, caput, do CTN)?',
+            back: 'Regra geral: a lei que institui o tributo aplica-se a todos os fatos geradores ocorridos no território nacional.',
+            subjectName: 'Direito Tributário',
+            deckName: 'Direito Tributário',
+            tags: ['ctn', 'art-4'],
+            conceptKey: 'trib-art-4',
+            source: 'aula-00.pdf',
+        },
+        {
+            type: 'QUESTION',
+            title: 'CTN art. 4º — exceção à territorialidade',
+            subjectName: 'Direito Tributário',
+            deckName: 'Direito Tributário',
+            tags: ['ctn', 'art-4'],
+            conceptKey: 'trib-art-4',
+            source: 'aula-00.pdf',
+            question: {
+                kind: 'CERTO_ERRADO',
+                statementHtml: 'Nos termos do art. 4º do CTN, a lei tributária brasileira NUNCA se aplica a fatos geradores ocorridos no exterior, ainda que o fato tenha produzido efeitos no Brasil.',
+                correctAlternative: 2,
+                commentHtml: 'Parágrafo único do art. 4º: a lei brasileira pode reger fatos ocorridos no exterior quando a eles se refiram dispositivos expressos da Constituição.',
+            },
+        },
     ],
     typeCaps: 'preferência por usuário (`memoring stage caps`, vale para app e CLI) — limites são TETOS, nunca cotas: 50 é só o limite técnico por requisição, não a meta do lote; userCaps -1 = sem teto preferencial (não é incentivo a inflar), 0 = não gerar o tipo. Sem quantidade explícita no pedido, selecione só pontos realmente cobráveis, com cobertura seletiva e carga de revisão sustentável. 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 | QUESTION   (obrigatório; NORMAL legado é mapeado para NOTE)
+  type          NOTE | NORMAL | ONE_SHOT | QUESTION   (obrigatório; FLASHCARD legado é mapeado para NORMAL)
   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)
+  front, back   string — pergunta e resposta      (obrigatório quando type=NORMAL|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
@@ -199,7 +252,39 @@ const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/re
   subjectName?  string — matéria (ex.: "Direito Constitucional")
   subtopicName? string — subtópico
   tags?         string[]
+  conceptKey?   string — conceito do item em slug minúsculo (letras, números
+                e hífens, até 80 chars). Opcional por compatibilidade, mas
+                FORTEMENTE RECOMENDADO em NORMAL/ONE_SHOT/QUESTION: cartões
+                sobre o MESMO conceito compartilham a MESMA chave — ex.:
+                "trib-art-4" num flashcard E numa questão do art. 4º do CTN
+                (o whiteboard do app agrupa por conceito, não por cartão) —
+                e conceitos DIFERENTES usam chaves diferentes: nunca reuse
+                uma chave para outro conceito
   source?       string — origem do material (default: "${DEFAULT_SOURCE}")
+  materialReferences?  array — referências ao material de origem (opcional):
+      vinculam o item à página do PDF no app; ao aceitar, o link abre o material
+      NA PÁGINA e destaca o trecho exato. Não confunda com source (texto livre) —
+      use os dois juntos.
+    [ { driveFileId, page, excerpt?, quote?, contextBefore?, contextAfter?, region? } ]
+    driveFileId   string (obrigatório) — id do arquivo no Drive
+                  (\`memoring scratch list --json\`); trim, não vazio, <= 255
+    page          int >= 1 (obrigatório) — posição 1-based no documento
+                  (mesma numeração de \`scratch extract --pages\`); o POST
+                  converte para pageIndex 0-based — o campo page nunca vai no fio
+    excerpt?      string — dica CURTA do trecho que originou o item (trim,
+                  <= 500; vazio = omitido). É SÓ um rótulo humano: NÃO gera
+                  destaque no PDF
+    quote?        string — trecho LITERAL do material (trim, <= 1000; vazio =
+                  omitido). RECOMENDADO para PDF com texto: o app localiza e
+                  destaca esse trecho na página
+    contextBefore?/contextAfter?  string — texto colado antes/depois do quote no
+                  material (trim, <= 500 cada) — desempata ocorrências repetidas
+    region?       objeto { x, y, w, h } — região visual da página, normalizada
+                  0..1 com origem no topo-esquerdo (x,y) e tamanho (w,h); números
+                  FINITOS, w/h > 0, contida no quadrado 0..1 (x+w <= 1, y+h <= 1).
+                  Para PDF ESCANEADO/sem texto, use a região em vez de quote.
+                  PDF com texto → quote literal; escaneado → região; excerpt é
+                  só a dica curta — sozinho ele NÃO destaca nada
 
 Snapshot de QUESTION (questões manuais — sem identidade TEC):
   kind               MULTIPLA_ESCOLHA | CERTO_ERRADO   (obrigatório)
@@ -213,7 +298,7 @@ Snapshot de QUESTION (questões manuais — sem identidade TEC):
 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
 (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
+Dica: NORMAL 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;
@@ -268,43 +353,6 @@ async function resolveBatchDecks(items, flags) {
     }
     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) {
@@ -374,6 +422,10 @@ function validateQuestion(raw, where) {
         ...subjects,
     };
 }
+/**
+ * Validação das referências de material vive em materialReferences.ts
+ * (validateMaterialReferences — fronteira única com o `memoring reference`).
+ */
 function validateItems(raw) {
     const items = Array.isArray(raw) ? raw : raw?.items;
     if (!Array.isArray(items) || items.length === 0) {
@@ -400,7 +452,7 @@ function validateItems(raw) {
         if (it.type === 'NOTE' && (typeof it.content !== 'string' || it.content.trim() === '')) {
             fail(`${where} (${it.title}): type=NOTE exige content.`);
         }
-        if ((it.type === 'FLASHCARD' || it.type === 'ONE_SHOT') &&
+        if ((it.type === 'NORMAL' || it.type === 'ONE_SHOT') &&
             (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.`);
         }
@@ -410,16 +462,81 @@ function validateItems(raw) {
         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.`);
         }
-        return { ...it, source: typeof it.source === 'string' && it.source.trim() !== '' ? it.source : DEFAULT_SOURCE };
+        let conceptKey = null;
+        if (it.conceptKey !== undefined && it.conceptKey !== null) {
+            if (typeof it.conceptKey !== 'string') {
+                fail(`${where} (${it.title}): conceptKey deve ser uma string (slug minúsculo) ou null.`);
+            }
+            const key = it.conceptKey.trim();
+            if (key !== '') {
+                if (key.length > CONCEPT_KEY_MAX || !CONCEPT_KEY_PATTERN.test(key)) {
+                    fail(`${where} (${it.title}): conceptKey "${key}" inválido — use slug minúsculo com letras, ` +
+                        `números e hífens, até ${CONCEPT_KEY_MAX} chars (ex.: "trib-art-4"). Mesmo conceito, mesma chave; conceito diferente, chave diferente.`);
+                }
+                conceptKey = key;
+            }
+        }
+        const materialReferences = validateMaterialReferences(it.materialReferences, `${where} (${it.title})`);
+        const stageItem = {
+            ...it,
+            conceptKey,
+            source: typeof it.source === 'string' && it.source.trim() !== '' ? it.source : DEFAULT_SOURCE,
+        };
+        if (materialReferences) {
+            stageItem.materialReferences = materialReferences;
+        }
+        else {
+            delete stageItem.materialReferences;
+        }
+        return stageItem;
     });
 }
+/** Item no formato do POST /notes/review-inbox, com baralho e referências na mesma transação. */
+function toReviewInboxItem({ deckName, materialReferences, ...rest }, deckId) {
+    void deckName;
+    return {
+        ...rest,
+        deckId,
+        ...(materialReferences && materialReferences.length > 0
+            ? { materialReferences: materialReferences.map(toWireMaterialReference) }
+            : {}),
+    };
+}
 /**
  * Idempotência do lote: UUID derivado do conteúdo bruto. Re-rodar o mesmo arquivo
  * após uma falha ambígua (timeout pós-commit) reenvia o mesmo X-Client-Request-Id —
  * o servidor devolve o replay deduplicado em vez de duplicar os itens.
  */
-function batchRequestId(raw) {
-    const digest = createHash('sha256').update(raw).digest();
+function readGeneration(flags) {
+    const file = stringFlag(flags, 'generation-file');
+    if (!file) {
+        return null;
+    }
+    const raw = readFileSync(file, 'utf8');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        fail(`generation-file inválido: ${error.message}`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        fail('generation-file deve conter um objeto JSON com provider e requestedModel.');
+    }
+    const generation = value;
+    for (const field of ['provider', 'requestedModel']) {
+        if (typeof generation[field] !== 'string' || generation[field].trim() === '') {
+            fail(`generation-file: ${field} é obrigatório e não pode ser vazio.`);
+        }
+    }
+    return { value: generation, raw };
+}
+function batchRequestId(raw, generationRaw = '') {
+    const hash = createHash('sha256').update(raw);
+    if (generationRaw) {
+        hash.update('\0').update(generationRaw);
+    }
+    const digest = hash.digest();
     digest[6] = (digest[6] & 0x0f) | 0x80;
     digest[8] = (digest[8] & 0x3f) | 0x80;
     const hex = digest.subarray(0, 16).toString('hex');
@@ -437,6 +554,61 @@ const NO_SESSION_WARNING = 'SEM SESSÃO: userCaps, qualityRules e customInstruct
 export async function stageCommand(parsed) {
     const [sub] = parsed._;
     switch (sub) {
+        case 'validate': {
+            const file = stringFlag(parsed.flags, 'file');
+            const pdfMapFile = stringFlag(parsed.flags, 'pdf-map');
+            if (!file || file === '-' || !pdfMapFile) {
+                fail('informe --file lote.json e --pdf-map pdf-map.json (a validação não envia nada ao servidor).');
+            }
+            let items;
+            let pdfMap;
+            try {
+                items = validateItems(JSON.parse(readFileSync(file, 'utf8')));
+                const rawMap = JSON.parse(readFileSync(pdfMapFile, 'utf8'));
+                if (typeof rawMap !== 'object' || rawMap === null || Array.isArray(rawMap)) {
+                    throw new Error('esperado objeto driveFileId → caminho');
+                }
+                pdfMap = Object.fromEntries(Object.entries(rawMap).map(([key, value]) => {
+                    if (typeof value !== 'string' || value.trim() === '') {
+                        throw new Error(`caminho inválido para ${key}`);
+                    }
+                    return [key, value];
+                }));
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'CliError') {
+                    throw error;
+                }
+                fail(`não consegui ler o lote/pdf-map: ${error.message}`);
+            }
+            enforceDeck(items, parsed.flags);
+            enforceTypeCaps(items, parsed.flags, await fetchStoredCaps());
+            const cache = new PdfDocumentCache();
+            let result;
+            try {
+                result = await validateBatchReferences(items, pdfMap, cache);
+            }
+            finally {
+                await cache.close();
+            }
+            if (parsed.flags.json) {
+                printJson(result);
+            }
+            else {
+                for (const warning of result.warnings) {
+                    process.stdout.write(yellow(`aviso: ${warning}\n`));
+                }
+                for (const error of result.errors) {
+                    process.stdout.write(`erro: ${error}\n`);
+                }
+                process.stdout.write(`${result.valid ? green('Lote válido') : 'Lote inválido'} — ${result.stats.items} item(ns), ` +
+                    `${result.stats.references} referência(s), ${result.stats.validatedHighlights} destaque(s) conferido(s).\n`);
+            }
+            if (!result.valid) {
+                process.exitCode = 1;
+            }
+            return;
+        }
         case 'schema': {
             const authenticated = hasSession();
             const [caps, guidance] = await Promise.all([fetchStoredCaps(), fetchAgentGuidance()]);
@@ -547,45 +719,73 @@ export async function stageCommand(parsed) {
             if (batchDecks.createdNames.length > 0 && !parsed.flags.json) {
                 process.stdout.write(dim(`Baralho(s) criado(s) como PENDING (ocultos até o 1º aceite): ${batchDecks.createdNames.join(', ')}.\n`));
             }
+            const generation = readGeneration(parsed.flags);
             let created;
+            let importRunId = null;
+            let deduplicated = false;
             try {
                 const res = (await apiFetch('/notes/review-inbox', {
                     method: 'POST',
-                    // 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),
+                    body: {
+                        items: items.map((item, index) => toReviewInboxItem(item, batchDecks.deckIds[index] ?? null)),
+                        ...(generation ? { generation: generation.value } : {}),
+                    },
+                    requestId: batchRequestId(raw, generation?.raw),
                 }));
                 created = res.created;
+                importRunId = res.importRunId ?? null;
             }
             catch (e) {
                 if (e instanceof ApiDedupedError) {
-                    if (parsed.flags.json) {
-                        printJson({ created: [], ids: [], deduplicated: true });
+                    if (parsed.flags.replace) {
+                        const warning = '--replace removeu os itens antes do replay; os IDs anteriores não são mais válidos. Altere o lote e reenvie.';
+                        if (parsed.flags.json) {
+                            printJson({ created: [], ids: [], deduplicated: true, warning });
+                        }
+                        else {
+                            process.stdout.write(yellow(`Atenção: ${warning}\n`));
+                        }
                         return;
                     }
-                    process.stdout.write(green('Este lote já foi enviado antes — nada foi duplicado.\n'));
-                    if (parsed.flags.replace) {
-                        process.stdout.write(yellow('Atenção: --replace removeu os itens pendentes antes do envio — a caixa ficou vazia. Altere o lote e reenvie.\n'));
+                    if (!e.body) {
+                        if (parsed.flags.json) {
+                            printJson({ created: [], ids: [], deduplicated: true });
+                        }
+                        else {
+                            process.stdout.write(green('Este lote já foi enviado antes — nada foi duplicado.\n'));
+                        }
+                        return;
+                    }
+                    try {
+                        const replay = JSON.parse(e.body);
+                        if (!Array.isArray(replay.created)) {
+                            throw new Error('created ausente');
+                        }
+                        created = replay.created;
+                        importRunId = replay.importRunId ?? null;
+                        deduplicated = true;
+                    }
+                    catch {
+                        fail('o replay deduplicado não trouxe uma resposta JSON válida; nenhum ID foi presumido.');
                     }
-                    return;
                 }
-                if (e instanceof ApiError) {
+                else if (e instanceof ApiError) {
                     fail(`o servidor rejeitou o lote (${e.status}): ${e.body}`);
                 }
-                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`));
+                else {
+                    throw e;
+                }
             }
             if (parsed.flags.json) {
                 printJson({
                     created,
                     ids: created.map((note) => note.id),
+                    importRunId,
+                    ...(deduplicated ? { deduplicated: true } : {}),
                     decks: {
                         created: batchDecks.createdNames,
-                        assigned: created.length - deckFailures.length - batchDecks.deckIds.filter((id) => id === null).length,
-                        failed: deckFailures,
+                        assigned: created.length - batchDecks.deckIds.filter((id) => id === null).length,
+                        failed: [],
                     },
                 });
                 return;
@@ -597,14 +797,15 @@ export async function stageCommand(parsed) {
             return;
         }
         default:
-            process.stdout.write('Uso: memoring stage <schema|caps|create> [--file itens.json] [--replace] [--json]\n' +
+            process.stdout.write('Uso: memoring stage <schema|validate|caps|create> [--file itens.json] [--replace] [--json]\n' +
                 '  schema   imprime o contrato JSON dos itens (para humanos e agentes)\n' +
+                '  validate valida lote e referências sem enviar (--file + --pdf-map)\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' +
+                '           tipos: NOTE | NORMAL | ONE_SHOT | QUESTION\n' +
                 '           baralho OBRIGATÓRIO: deckName por item ou --deck "<nome|id>" no lote\n' +
                 '           (nomes inexistentes são criados como PENDING — ocultos no app até o\n' +
                 '           primeiro aceite; veja `memoring deck list`)\n' +

package/dist/config.js

@@ -6,6 +6,7 @@ const DEFAULTS = {
     realm: 'memoring',
     clientId: 'memoring-cli',
     apiBase: 'https://memoring.com.br/api',
+    webBase: 'https://memoring.com.br',
 };
 export function configDir() {
     if (process.env.MEMORING_CONFIG_HOME) {
@@ -35,6 +36,7 @@ export function loadConfig() {
         realm: process.env.MEMORING_KC_REALM ?? stored.realm ?? DEFAULTS.realm,
         clientId: process.env.MEMORING_KC_CLIENT ?? stored.clientId ?? DEFAULTS.clientId,
         apiBase: process.env.MEMORING_API_BASE ?? stored.apiBase ?? DEFAULTS.apiBase,
+        webBase: process.env.MEMORING_WEB_BASE ?? stored.webBase ?? DEFAULTS.webBase,
         accessToken: stored.accessToken,
         refreshToken: stored.refreshToken,
         accessTokenExpiresAt: stored.accessTokenExpiresAt,

package/dist/main.js

@@ -2,14 +2,18 @@
 import { ApiError } from './api.js';
 import { CliError, setColorEnabled, yellow } from './output.js';
 import { authCommand } from './commands/auth.js';
+import { batchCommand } from './commands/batch.js';
 import { deckCommand } from './commands/deck.js';
 import { inboxCommand } from './commands/inbox.js';
+import { referenceCommand } from './commands/materialReferences.js';
+import { planCommand } from './commands/plan.js';
+import { scratchCommand } from './commands/scratch.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.12.1';
+const VERSION = '0.15.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -19,19 +23,44 @@ Comandos:
   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 validate --file f       valida lote e referências localmente, sem enviar
+       --pdf-map map.json       mapa driveFileId → PDF local
   stage create [--file f]       envia itens (arquivo ou stdin) para a caixa de revisão
        [--replace]              esvazia a caixa antes de enviar
+       [--generation-file f]    proveniência provider/modelo do lote
   stage caps [--max-* N]        seus limites por tipo (valem pro app e pros agentes)
+  batch check|run|status|verify plan.json
+                                preflight, envio retomável e auditoria de atividades
   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>)
+  reference list <noteId>       referências de material de um card (fontes de estudo)
+  reference update <noteId> <refId> --file parcial.json
+                                corrige excerpt/quote/contextos/região de uma referência
+                                (merge: campo ausente mantém; null limpa; não troca
+                                nota, arquivo nem página)
+  scratch list [--all]          rascunhos do caderno no Google Drive (via proxy do
+                                backend — conecte o Drive pelo app; a CLI não faz OAuth)
+                                listados pelo CAMINHO da biblioteca (pasta/título)
+  scratch download <caminho|driveFileId>  baixa o .scratch.json + o PDF de fundo
+       [--out <dir>]            (se houver) — aceita o caminho do list ou o driveFileId
+       [--metadata-only]        só o JSON + metadados do PDF, sem baixar o binário
+  scratch extract <arquivo.pdf>   recorta páginas A-B num sub-PDF (pdf-lib)
+       [--pages A-B] [--all]    PDF > ~30 páginas sem --pages exige --all explícito
   deck list                     seus baralhos (id, nome, status, pai, a revisar, relevância, meta, recorde)
   deck create <nome>            cria um baralho (--parent <id|nome> p/ sub-baralho; --pending p/ importação)
   deck update <id|nome>         metadados do baralho (--relevance/--goal/--tone;
                                 --clear-* limpa um campo)
+  plan analyze <pdfs...>        analisa materiais; --web abre revisão sem criar plano
+  plan review <draftId>         lê/aguarda o rascunho (--wait) e exporta payload (--out f)
+  plan create --file f          cria o planejamento revisado; --draft uuid usa revisão web
+  plan current|next <planId>    Meta ativa / próxima Meta (--activities N no fluxo direto;
+                                --web revisa no app; --draft uuid conclui após REVIEWED)
+  plan start|complete|result    executa atividades e registra desempenho
+  plan exams list|create|delete gerencia provas; diagnostics e guia no subcomando plan
   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
@@ -43,7 +72,7 @@ Flags globais:
   --version     imprime a versão da CLI
   --help, -h    ajuda
 
-Ambiente (dev): MEMORING_API_BASE, MEMORING_KEYCLOAK_URL, MEMORING_KC_REALM, MEMORING_KC_CLIENT
+Ambiente (dev): MEMORING_API_BASE, MEMORING_WEB_BASE, MEMORING_KEYCLOAK_URL, MEMORING_KC_REALM, MEMORING_KC_CLIENT
 
 Atualização: a CLI verifica em background (1x/24h) se há versão nova e avisa no stderr.
 MEMORING_NO_UPDATE_CHECK=1 desativa a verificação.
@@ -91,12 +120,24 @@ async function main() {
         case 'stage':
             await stageCommand(sub);
             return;
+        case 'batch':
+            await batchCommand(sub);
+            return;
         case 'inbox':
             await inboxCommand(sub);
             return;
+        case 'reference':
+            await referenceCommand(sub);
+            return;
+        case 'scratch':
+            await scratchCommand(sub);
+            return;
         case 'deck':
             await deckCommand(sub);
             return;
+        case 'plan':
+            await planCommand(sub);
+            return;
         case 'update':
             await updateCommand(VERSION);
             return;