@memoring/cli 0.12.0 → 0.13.0

package/README.md

@@ -87,15 +87,17 @@ Cada item do lote (1 a 50, all-or-nothing):
   "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",
+  "conceptKey": "const-cf88-art-3",
   "tags": ["cf88", "art-3"],
   "source": "Apostila constitucional.pdf"
 }
 ```
 
 - `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`).
+- `conceptKey`: conceito do item em slug minúsculo (letras, números e hífens, até 80 chars). Opcional por compatibilidade, mas **fortemente recomendado em FLASHCARD/ONE_SHOT/QUESTION** — cartões sobre o MESMO conceito compartilham a MESMA chave e conceitos DIFERENTES usam chaves diferentes (nunca reuse a chave). Ex.: um flashcard e uma questão sobre o art. 4º do CTN usam ambos `"trib-art-4"`. No app, o whiteboard do Rascunho agrupa por conceito: ângulos do mesmo conceito contam como uma frente só nas rodadas guiadas; sem chave, cada cartão é uma frente individual. No `inbox update <id>`, o `conceptKey` atual é preservado quando o campo não é informado.
 - `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.
+- Limites por tipo são **tetos, nunca cotas**: `memoring stage caps` mostra/grava sua preferência (`livre`/`-1` = sem teto preferencial — o padrão, não um incentivo a inflar o lote; `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. O 50 é apenas o limite técnico por requisição, não a meta: sem quantidade explícita, o agente deve selecionar apenas os pontos realmente cobráveis e manter uma carga de revisão sustentável.
 - 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/inbox.js

@@ -60,6 +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,
+        conceptKey: overrides.conceptKey ?? stringFlag(flags, 'concept') ?? current.conceptKey ?? null,
         deckId: deckId ?? overrides.deckId ?? current.deckId ?? null,
         question: overrides.question ?? current.question ?? null,
     };
@@ -166,7 +167,8 @@ export async function inboxCommand(parsed) {
                 '  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');
+                '               --tags a,b,c --source --concept trib-art-4 --type)\n' +
+                '               (--concept preserva/define o conceptKey; sem ele, o valor atual é mantido)\n');
             if (sub) {
                 process.exitCode = 1;
             }

package/dist/commands/stage.js

@@ -10,6 +10,13 @@ const LEGACY_TYPE_ALIASES = { NORMAL: 'NOTE' };
 const MAX_ITEMS = 50;
 const DEFAULT_SOURCE = 'Importação assistida (CLI)';
 const QUESTION_KINDS = ['MULTIPLA_ESCOLHA', 'CERTO_ERRADO'];
+/**
+ * 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
@@ -147,6 +154,7 @@ const SCHEMA_JSON = {
         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 FLASHCARD/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}")`,
@@ -161,6 +169,7 @@ const SCHEMA_JSON = {
             subjectName: 'Direito Constitucional',
             deckName: 'Direito Constitucional',
             tags: ['cf88', 'art-3'],
+            conceptKey: 'const-cf88-art-3',
             source: 'Apostila constitucional.pdf',
         },
         {
@@ -169,6 +178,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,8 +187,34 @@ const SCHEMA_JSON = {
                 commentHtml: 'É a definição do art. 3º do CTN (Lei 5.172/1966).',
             },
         },
+        {
+            type: 'FLASHCARD',
+            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) — 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.',
+    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):
 
@@ -199,6 +235,14 @@ 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 FLASHCARD/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}")
 
 Snapshot de QUESTION (questões manuais — sem identidade TEC):
@@ -294,6 +338,7 @@ async function assignDecks(items, created, deckIds) {
                     subtopicName: item.subtopicName ?? null,
                     tags: item.tags ?? [],
                     source: item.source ?? null,
+                    conceptKey: item.conceptKey ?? null,
                     deckId,
                     question: item.question ?? null,
                 },
@@ -410,7 +455,25 @@ 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;
+            }
+        }
+        return {
+            ...it,
+            conceptKey,
+            source: typeof it.source === 'string' && it.source.trim() !== '' ? it.source : DEFAULT_SOURCE,
+        };
     });
 }
 /**
@@ -466,7 +529,7 @@ export async function stageCommand(parsed) {
                     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)}, questões: ${capLabel(caps.maxQuestions)}.\n` +
-                        dim('("à vontade" = crie quantos o material justificar; altere com `memoring stage caps`)\n'));
+                        dim('("à vontade" = sem teto preferencial, não uma cota: selecione só o que for realmente cobrável; 50 é só o limite técnico por envio, nunca a meta. 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'));

package/dist/main.js

@@ -9,7 +9,7 @@ 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.0';
+const VERSION = '0.13.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]

package/package.json

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

@@ -27,7 +27,7 @@ O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring`
 | `memoring inbox list` | itens pendentes de revisão |
 | `memoring inbox accept <id>\|accept-all` | aceita itens (entram nas listagens e na fila FSRS) — **decisão do usuário: só rode se ELE pedir explicitamente** |
 | `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 inbox update <id> [--file parcial.json] [--title ...] [--front ...] [--back ...] [--tags a,b] [--concept trib-art-4] ...` | edita um item AINDA PENDENTE (merge com o estado atual — `conceptKey` é preservado se não for informado) |
 | `memoring skill` | imprime este guia |
 | `memoring update` | atualiza a CLI (decisão do usuário — nunca rode por conta própria) |
 
@@ -51,16 +51,19 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 - `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 como **PENDING** (oculto no app até o 1º item aceite). 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>" --pending` (o `stage create` só cria raiz pelo nome). O primeiro item aceito ativa o baralho e os ancestrais pendentes.
 - `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.
+- `conceptKey` = slug minúsculo (letras, números e hífens, até 80 chars) que identifica o CONCEITO do item. Opcional por compatibilidade, mas **fortemente recomendado em FLASHCARD/ONE_SHOT/QUESTION**. A regra é simples: cartões sobre o MESMO conceito compartilham a MESMA chave — ex.: um flashcard e uma questão sobre o art. 4º do CTN usam ambos `"trib-art-4"` — e conceitos DIFERENTES usam chaves diferentes, nunca reuse uma chave para outro conceito. No app, o whiteboard do Rascunho usa a chave para AGRUPAR por conceito: ângulos do mesmo conceito (flashcard, questão, 1-shot) contam como uma frente só nas rodadas guiadas — sem chave, cada cartão vira uma frente individual. Chaves curtas e estáveis, com contexto da matéria (ex.: `trib-ctn-art-3`, `const-cf88-art-3`), evitando chaves genéricas que fundam conceitos distintos.
 - 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.
 
-## Quantidades (limites por tipo)
+## Quantidades (limites são tetos, NUNCA cotas)
 
-- O default do usuário costuma ser **à vontade** (`userCaps` com `-1`): crie QUANTOS itens o material justificar — qualidade acima de quantidade, sem encher cota e sem repetir o mesmo fato em variações triviais.
-- Se `userCaps` trouxer tetos numéricos, distribua a geração para caber neles; `0` proíbe o tipo.
-- Se o usuário pedir quantidades no chat (ex.: "quero 30 flashcards e 5 notas"), o pedido vence o `userCaps`: gere e valide com `--max-flashcards 30 --max-notes 5` no `stage create`.
-- Lotes grandes: divida em vários arquivos de até 50 itens e envie sequencialmente.
+- **50 é apenas o limite técnico de itens por requisição, NÃO a meta do lote.** Nunca mire nesse número, não proponha faixas como “46–50” sem o usuário pedir e não acrescente itens para “fechar” um lote.
+- **Sem quantidade explícita no pedido, não estabeleça um alvo numérico antes de analisar o material.** A quantidade é consequência da seleção: inclua conceitos centrais, exceções e confusões realmente cobráveis, além das questões prontas. Não transforme cada parágrafo, detalhe secundário, exemplo ou sigla em cartão — a cobertura é SELETIVA, não exaustiva. Em dúvida, prefira menos itens.
+- **Considere a carga de revisão acumulada do usuário.** Milhares de páginas de estudo não podem virar dezenas de milhares de revisões mecânicas. Não use uma taxa de cartões por página (ex.: “50 a cada 10–15 páginas”): densidade e importância do assunto importam mais que o volume do PDF.
+- `userCaps` com `-1` significa apenas **sem teto preferencial**, não “cresça à vontade”. Tetos numéricos são limites máximos, nunca cotas a preencher; `0` proíbe o tipo.
+- Se o usuário pedir quantidades no chat (ex.: “quero 30 flashcards e 5 notas”), o pedido vence o `userCaps`: gere e valide com `--max-flashcards 30 --max-notes 5` no `stage create`.
+- Se a seleção de pontos realmente úteis ultrapassar 50 itens, divida em vários arquivos de até 50 e envie sequencialmente — nunca infle um lote para usar a capacidade disponível.
 
 ## Qualidade dos flashcards (o padrão que o app espera)