@memoring/cli 0.4.0 → 0.5.0

package/README.md

@@ -57,6 +57,7 @@ Os itens enviados nascem **PENDING_REVIEW** — nada entra nas suas listagens ne
 | `memoring stage` | schema (o contrato + seus limites por tipo) / 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 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 |
 
 ## Flags
@@ -92,11 +93,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`).
 - `source`: origem do material — default `"Importação assistida (CLI)"`.
-- Limites por tipo: `memoring stage caps` mostra/grava sua preferência (0 = não gerar o tipo) — o `stage schema` a expõe ao agente e o `create` a impõe; flags `--max-*` no `create` vencem por lote.
+- 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.
 
 ## Para agentes de IA
 
-Este pacote inclui uma skill em `skills/memoring-cli/SKILL.md` com o fluxo completo (auth → schema → gerar → stage → avisar o usuário). Aponte o agente para ela, ou simplesmente peça "use a cli do memoring" — os comandos são auto-descritivos (`--help` em todos).
+Este pacote inclui uma skill em `skills/memoring-cli/SKILL.md` com o fluxo completo (auth → schema → gerar → stage → avisar o usuário). O jeito mais fácil de um agente aprender a CLI de cabo a rabo é rodar **`memoring skill`** — o comando imprime o guia completo empacotado. Ou simplesmente peça "use a cli do memoring" — os comandos são auto-descritivos (`--help` em todos).
 
 ## Dev (backend local)
 

package/dist/commands/skill.js

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { fail } from './shared.js';
+/**
+ * `memoring skill` — imprime o SKILL.md empacotado no npm (guia completo da CLI para
+ * agentes de IA: fluxo, contrato, limites por tipo, armadilhas). É como um agente
+ * aprende a CLI de cabo a rabo sem precisar caçar o arquivo no node_modules.
+ */
+export function skillCommand() {
+    let content;
+    try {
+        content = readFileSync(new URL('../../skills/memoring-cli/SKILL.md', import.meta.url), 'utf8');
+    }
+    catch {
+        fail('não encontrei o SKILL.md empacotado — reinstale com `npm i -g @memoring/cli@latest`.');
+    }
+    process.stdout.write(content);
+    if (!content.endsWith('\n')) {
+        process.stdout.write('\n');
+    }
+}

package/dist/commands/stage.js

@@ -8,6 +8,28 @@ const TYPES = ['NOTE', 'FLASHCARD', 'ONE_SHOT'];
 const LEGACY_TYPE_ALIASES = { NORMAL: 'NOTE' };
 const MAX_ITEMS = 50;
 const DEFAULT_SOURCE = 'Importação assistida (CLI)';
+const UNLIMITED = -1;
+/** Rótulo de exibição de um teto: -1 → "à vontade". */
+function capLabel(max) {
+    return max === UNLIMITED ? 'à vontade' : `até ${max}`;
+}
+/**
+ * Teto vindo de flag ou preferência: inteiro -1..50, ou a palavra "livre" (= -1, à vontade).
+ * `null` quando a flag está ausente.
+ */
+function parseCapFlag(raw, flagName) {
+    if (raw === undefined) {
+        return null;
+    }
+    if (raw.trim().toLowerCase() === 'livre') {
+        return UNLIMITED;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < UNLIMITED || value > 50) {
+        fail(`--${flagName} inválido: use "livre" ou um inteiro entre -1 (à vontade) e 50 (veio ${JSON.stringify(raw)}).`);
+    }
+    return value;
+}
 /**
  * GET /notes/import/caps, fail-open: sem sessão ou sem rede devolve null (o schema
  * continua útil deslogado e o create só perde a validação extra). Só chama a API
@@ -44,23 +66,19 @@ const CAPS_FLAG_BY_FIELD = {
 };
 /**
  * Teto por tipo no lote (validação local): a flag --max-<tipo> vence; sem flag, vale a
- * preferência gravada do usuário (`memoring stage caps` / app). Tipo sem flag nem
- * preferência fica livre.
+ * preferência gravada do usuário (`memoring stage caps` / app). "livre"/-1 (à vontade)
+ * não limita; tipo sem flag nem preferência fica livre.
  */
 function enforceTypeCaps(items, flags, stored) {
     const storedByType = stored
         ? { NOTE: stored.maxNotes, FLASHCARD: stored.maxFlashcards, ONE_SHOT: stored.maxOneShots }
         : {};
     for (const [type, flag] of Object.entries(MAX_FLAG_BY_TYPE)) {
-        const raw = stringFlag(flags, flag);
+        const fromFlag = parseCapFlag(stringFlag(flags, flag), flag);
         let max;
         let source;
-        if (raw !== undefined) {
-            const parsed = Number(raw);
-            if (!Number.isInteger(parsed) || parsed < 0) {
-                fail(`--${flag} inválido: use um inteiro >= 0 (veio ${JSON.stringify(raw)}).`);
-            }
-            max = parsed;
+        if (fromFlag !== null) {
+            max = fromFlag;
             source = `--${flag}`;
         }
         else if (storedByType[type] !== undefined) {
@@ -70,9 +88,12 @@ function enforceTypeCaps(items, flags, stored) {
         else {
             continue;
         }
+        if (max === UNLIMITED) {
+            continue;
+        }
         const count = items.filter((item) => item.type === type).length;
         if (count > max) {
-            fail(`lote tem ${count} ${TYPE_LABEL[type]} e o limite é ${max} (${source}). Ajuste o lote ou o limite. ` +
+            fail(`lote tem ${count} ${TYPE_LABEL[type]} e o limite é ${max} (${source}). Ajuste o lote ou o limite ("livre" = à vontade). ` +
                 'Se um agente gerou este lote, peça a ele para respeitar os limites por tipo.');
         }
     }
@@ -101,7 +122,7 @@ const SCHEMA_JSON = {
             source: 'Apostila constitucional.pdf',
         },
     ],
-    typeCaps: 'preferência por usuário (`memoring stage caps`, vale para app e CLI) — o `stage schema` mostra os limites ao agente; flags do `stage create` (--max-notes N | --max-flashcards N | --max-one-shots N) 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, ou "livre") vencem a preferência por lote.',
 };
 const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/review-inbox):
 
@@ -118,7 +139,7 @@ Lote: 1 a ${MAX_ITEMS} itens, all-or-nothing — qualquer item inválido rejeita
 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.
 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.`;
+--max-notes N | --max-flashcards N | --max-one-shots N no create vencem por lote ("livre" = à vontade).`;
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -202,8 +223,8 @@ export async function stageCommand(parsed) {
                 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: ` +
-                        `até ${caps.maxNotes} nota(s), até ${caps.maxFlashcards} flashcard(s), até ${caps.maxOneShots} 1-shot(s).\n` +
-                        dim('(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)}.\n` +
+                        dim('("à vontade" = crie quantos o material justificar; altere com `memoring stage caps`; QUESTION não é estagiável pela CLI)\n'));
                 }
                 else {
                     process.stdout.write(dim('\n(limites por tipo indisponíveis — faça `memoring auth login` ou verifique a conexão)\n'));
@@ -216,14 +237,10 @@ export async function stageCommand(parsed) {
             const current = (await apiFetch('/notes/import/caps'));
             const updates = {};
             for (const [field, flag] of Object.entries(CAPS_FLAG_BY_FIELD)) {
-                const raw = stringFlag(parsed.flags, flag);
-                if (raw === undefined) {
+                const value = parseCapFlag(stringFlag(parsed.flags, flag), flag);
+                if (value === null) {
                     continue;
                 }
-                const value = Number(raw);
-                if (!Number.isInteger(value) || value < 0 || value > 50) {
-                    fail(`--${flag} inválido: use um inteiro entre 0 e 50 (veio ${JSON.stringify(raw)}).`);
-                }
                 updates[field] = value;
             }
             const hasUpdates = Object.keys(updates).length > 0;
@@ -236,10 +253,10 @@ export async function stageCommand(parsed) {
             }
             process.stdout.write((hasUpdates ? green('Limites gravados') : 'Limites por tipo') +
                 ' — valem para a importação do app e para os agentes via CLI:\n');
-            process.stdout.write(`  notas: até ${effective.maxNotes}   flashcards: até ${effective.maxFlashcards}   ` +
-                `1-shots: até ${effective.maxOneShots}   questões: até ${effective.maxQuestions}\n`);
+            process.stdout.write(`  notas: ${capLabel(effective.maxNotes)}   flashcards: ${capLabel(effective.maxFlashcards)}   ` +
+                `1-shots: ${capLabel(effective.maxOneShots)}   questões: ${capLabel(effective.maxQuestions)}\n`);
             if (!hasUpdates) {
-                process.stdout.write(dim('Altere com: memoring stage caps --max-flashcards 30 (0 = não gerar o tipo)\n'));
+                process.stdout.write(dim('Altere com: memoring stage caps --max-flashcards 30 (0 = não gerar o tipo; "livre" = à vontade)\n'));
             }
             return;
         }

package/dist/main.js

@@ -5,9 +5,10 @@ import { authCommand } from './commands/auth.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 { newerVersionAvailable, scheduleUpdateCheck } from './update.js';
-const VERSION = '0.4.0';
+const VERSION = '0.5.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -22,6 +23,7 @@ Comandos:
   inbox accept <id>|accept-all  aceita itens (entram nas listagens e na fila FSRS)
   inbox discard <id>            descarta um item pendente
   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
 
 Flags globais:
@@ -85,6 +87,9 @@ async function main() {
         case 'update':
             await updateCommand(VERSION);
             return;
+        case 'skill':
+            skillCommand();
+            return;
         case 'version':
             process.stdout.write(`memoring-cli ${VERSION}\n`);
             return;

package/package.json

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

@@ -3,38 +3,62 @@ name: memoring-cli
 description: Gere flashcards e notas a partir de materiais de estudo locais (PDFs, textos, anotações) e envie para a caixa de revisão do Memoring usando a CLI `memoring`. Use quando o usuário pedir para "usar a cli do memoring", criar flashcards/notas de uma pasta ou arquivo, ou enviar material de estudo para o Memoring.
 ---
 
-# Memoring CLI — geração de flashcards/notas por agente
+# Memoring CLI — guia completo para agentes
 
-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.
+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
 
 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).
 
-## Fluxo
+## Mapa dos comandos
 
-1. **Entenda o pedido** — qual pasta/arquivo/material virar flashcards/notas.
-2. **Leia o contrato**: `memoring stage schema --json`.
+| 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 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 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 skill` | imprime este guia |
+| `memoring update` | atualiza a CLI (decisão do usuário — nunca rode por conta própria) |
+
+Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-base`.
+
+## 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 e os limites**: `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, 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`.
+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`.
 
-## Regras do contrato (resumo — a fonte da verdade é `stage schema`)
+## 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`).
-- `title` sempre obrigatório; lote de 1 a 50 itens, all-or-nothing.
-- Se o usuário pedir limites por tipo (ex.: "no máximo 20 flashcards e 5 notas"), respeite-os ao gerar e valide com `--max-notes N --max-flashcards N --max-one-shots N` no `stage create` — o lote é rejeitado se exceder.
-- O `stage schema` mostra os **limites por tipo do usuário** (`userCaps` no JSON; texto no fim da saída em modo humano) — respeite-os ao gerar, mesmo sem pedido explícito no chat. Sem limites visíveis, o create ainda pode rejeitar pela preferência gravada: ajuste o lote e reenvie. Para MUDAR a preferência permanente, o usuário roda `memoring stage caps` — não rode por conta própria.
-- `ONE_SHOT` = pergunta de resposta única; prefira `FLASHCARD` para memorização.
+- `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.
 - 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)
+
+- 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.
+
+## 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.
+
 ## Armadilhas
 
 - **Nunca** use `--replace` sem o usuário pedir explicitamente — ele apaga 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.
-- Lotes grandes: divida em vários arquivos de até 50 itens e envie sequencialmente.
-- Flashcards bons são atômicos: uma ideia por cartão, pergunta direta, resposta completa mas curta.