@memoring/cli 0.13.0 → 0.15.0

package/dist/pdf/documentCache.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { pdfTextItemViewportBox } from './quoteLocate.js';
+export class PdfDocumentCache {
+    documents = new Map();
+    pages = new Map();
+    async pageCount(filePath) {
+        return (await this.load(filePath)).doc.numPages;
+    }
+    async pageItems(filePath, pageNumber) {
+        const key = `${resolve(filePath)}:${pageNumber}`;
+        let pending = this.pages.get(key);
+        if (!pending) {
+            pending = this.readPage(filePath, pageNumber);
+            this.pages.set(key, pending);
+        }
+        return pending;
+    }
+    async close() {
+        const loaded = await Promise.allSettled([...this.documents.values()]);
+        for (const result of loaded) {
+            if (result.status === 'fulfilled') {
+                await result.value.doc.destroy();
+            }
+        }
+    }
+    load(filePath) {
+        const key = resolve(filePath);
+        let pending = this.documents.get(key);
+        if (!pending) {
+            pending = this.loadDocument(key);
+            this.documents.set(key, pending);
+        }
+        return pending;
+    }
+    async loadDocument(filePath) {
+        const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+        const require = createRequire(import.meta.url);
+        const packageDir = dirname(require.resolve('pdfjs-dist/package.json'));
+        const loadingTask = pdfjs.getDocument({
+            data: new Uint8Array(readFileSync(filePath)),
+            standardFontDataUrl: `${packageDir}/standard_fonts/`,
+            cMapUrl: `${packageDir}/cmaps/`,
+            cMapPacked: true,
+        });
+        return { doc: await loadingTask.promise, pdfjs };
+    }
+    async readPage(filePath, pageNumber) {
+        const { doc, pdfjs } = await this.load(filePath);
+        const page = await doc.getPage(pageNumber);
+        const viewport = page.getViewport({ scale: 1 });
+        const content = await page.getTextContent();
+        const items = [];
+        for (const raw of content.items) {
+            if (!('str' in raw) || typeof raw.str !== 'string' || raw.str.length === 0)
+                continue;
+            if (!Array.isArray(raw.transform) || raw.transform.length !== 6)
+                continue;
+            const tx = pdfjs.Util.transform(viewport.transform, raw.transform);
+            items.push({
+                str: raw.str,
+                ...pdfTextItemViewportBox(tx, Number(raw.width ?? 0), Number(raw.height ?? 0)),
+            });
+        }
+        return items;
+    }
+}

package/dist/pdf/quoteLocate.js

@@ -0,0 +1,181 @@
+export function normalizeSearchText(value) {
+    return value
+        .toLocaleLowerCase('pt-BR')
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '');
+}
+export function pdfTextItemViewportBox(tx, itemWidth, itemHeight) {
+    const em = Math.hypot(tx[2] ?? 0, tx[3] ?? 0);
+    const w = Math.max(0, itemWidth);
+    const h = itemHeight > 0 ? itemHeight : em;
+    return { x: tx[4] ?? 0, y: (tx[5] ?? 0) - h * 0.8, w, h };
+}
+const NO_ITEM = -1;
+const SAME_LINE_TOL_PTS = 2;
+function collapseSpaces(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function itemCenterY(item) {
+    return item.y + item.h / 2;
+}
+function sameLine(a, b) {
+    return Math.abs(itemCenterY(a) - itemCenterY(b)) <= SAME_LINE_TOL_PTS;
+}
+export function normalizePageItems(items) {
+    let norm = '';
+    const map = [];
+    const starts = [];
+    const lens = [];
+    let lastWasSpace = true;
+    for (let i = 0; i < items.length; i += 1) {
+        const normalized = normalizeSearchText(items[i].str);
+        starts.push(norm.length);
+        let emitted = 0;
+        for (const ch of normalized) {
+            if (/\s/.test(ch)) {
+                if (!lastWasSpace && norm.length > 0) {
+                    norm += ' ';
+                    map.push(i);
+                    emitted += 1;
+                }
+                lastWasSpace = true;
+                continue;
+            }
+            norm += ch;
+            map.push(i);
+            emitted += 1;
+            lastWasSpace = false;
+        }
+        lens.push(emitted);
+        const next = items[i + 1];
+        if (next && !lastWasSpace && !/\s$/.test(normalizeSearchText(items[i].str)) && !sameLine(items[i], next)) {
+            norm += ' ';
+            map.push(NO_ITEM);
+            lastWasSpace = true;
+        }
+    }
+    return { norm, map, starts, lens };
+}
+function matchesBefore(norm, matchStart, context) {
+    if (context.length === 0)
+        return false;
+    if (matchStart >= context.length && norm.slice(matchStart - context.length, matchStart) === context) {
+        return true;
+    }
+    return (matchStart >= context.length + 1 &&
+        norm[matchStart - 1] === ' ' &&
+        norm.slice(matchStart - 1 - context.length, matchStart - 1) === context);
+}
+function matchesAfter(norm, matchEnd, context) {
+    if (context.length === 0)
+        return false;
+    if (norm.slice(matchEnd, matchEnd + context.length) === context)
+        return true;
+    return (norm[matchEnd] === ' ' &&
+        norm.slice(matchEnd + 1, matchEnd + 1 + context.length) === context);
+}
+function findOccurrences(haystack, needle) {
+    const out = [];
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at < 0)
+            return out;
+        out.push(at);
+        from = at + 1;
+    }
+}
+function rectsForRange(items, page, start, end) {
+    const rects = [];
+    let i = start;
+    while (i < end) {
+        const itemIndex = page.map[i];
+        if (itemIndex === NO_ITEM) {
+            i += 1;
+            continue;
+        }
+        let j = i;
+        while (j < end && page.map[j] === itemIndex)
+            j += 1;
+        const len = Math.max(1, page.lens[itemIndex]);
+        const fracStart = Math.min(1, Math.max(0, (i - page.starts[itemIndex]) / len));
+        const fracEnd = Math.min(1, Math.max(fracStart, (j - page.starts[itemIndex]) / len));
+        const item = items[itemIndex];
+        const w = (fracEnd - fracStart) * item.w;
+        if (w > 0.01 && item.h > 0) {
+            rects.push({ x: item.x + fracStart * item.w, y: item.y, w, h: item.h });
+        }
+        i = j;
+    }
+    return rects;
+}
+export function mergeRectsByLine(rects) {
+    const sorted = [...rects].sort((a, b) => a.y - b.y || a.x - b.x);
+    const lines = [];
+    for (const rect of sorted) {
+        const line = lines.find((candidate) => Math.abs(candidate[0].y - rect.y) <= SAME_LINE_TOL_PTS);
+        if (line)
+            line.push(rect);
+        else
+            lines.push([rect]);
+    }
+    const out = [];
+    for (const line of lines) {
+        line.sort((a, b) => a.x - b.x);
+        let current = null;
+        for (const rect of line) {
+            if (!current) {
+                current = { ...rect };
+                continue;
+            }
+            const gap = rect.x - (current.x + current.w);
+            if (gap <= 1) {
+                const right = Math.max(current.x + current.w, rect.x + rect.w);
+                current.w = right - current.x;
+                current.h = Math.max(current.h, rect.h);
+            }
+            else {
+                out.push(current);
+                current = { ...rect };
+            }
+        }
+        if (current)
+            out.push(current);
+    }
+    return out;
+}
+export function locateQuoteInPageItems(items, query) {
+    const quote = collapseSpaces(normalizeSearchText(query.quote));
+    if (quote.length === 0 || items.length === 0)
+        return null;
+    const contextBefore = collapseSpaces(normalizeSearchText(query.contextBefore ?? ''));
+    const contextAfter = collapseSpaces(normalizeSearchText(query.contextAfter ?? ''));
+    const page = normalizePageItems(items);
+    const occurrences = findOccurrences(page.norm, quote);
+    if (occurrences.length === 0)
+        return null;
+    let chosen;
+    if (occurrences.length === 1) {
+        chosen = occurrences[0];
+    }
+    else {
+        let bestScore = -1;
+        let best = [];
+        for (const at of occurrences) {
+            const score = (matchesBefore(page.norm, at, contextBefore) ? 1 : 0) +
+                (matchesAfter(page.norm, at + quote.length, contextAfter) ? 1 : 0);
+            if (score > bestScore) {
+                bestScore = score;
+                best = [at];
+            }
+            else if (score === bestScore) {
+                best.push(at);
+            }
+        }
+        if (bestScore <= 0 || best.length !== 1)
+            return null;
+        chosen = best[0];
+    }
+    const rects = mergeRectsByLine(rectsForRange(items, page, chosen, chosen + quote.length));
+    return rects.length > 0 ? rects : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoring/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "CLI do Memoring — envie flashcards/notas gerados por IA para a sua caixa de revisão, direto do terminal.",
   "repository": {
     "type": "git",
@@ -22,11 +22,17 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "start": "node dist/main.js",
+    "test": "vitest run",
     "prepack": "npm run build"
   },
+  "dependencies": {
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^5.7.284"
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "typescript": "^5.8.0"
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.4"
   },
   "license": "UNLICENSED"
 }

package/skills/memoring-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Gere flashcards e notas a partir de materiais locais, envie para revisão e opere planejamentos de estudo no Memoring usando a CLI `memoring`. Use quando o usuário pedir para "usar a cli do memoring", criar flashcards/notas, analisar PDFs para planejar estudos, gerar Metas, registrar atividades/resultados, diagnósticos ou provas.
 ---
 
 # Memoring CLI — guia completo para agentes
@@ -20,14 +20,24 @@ 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] [--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 stage validate --file f --pdf-map map.json` | valida estrutura, páginas e quotes no PDF local, sem qualquer POST; usa o mesmo localizador do destaque do app |
+| `memoring stage create --file f [--replace] [--max-* N] [--deck nome] [--generation-file f]` | envia o lote (1 a 50) num único POST transacional, com baralho/referências; `--json` devolve `created` + `ids` + `importRunId`; generation-file registra provider/modelo sem inferi-los |
+| `memoring batch check\|run\|status\|verify plan.json [--resume]` | preflight, envio retomável e auditoria por ID de várias atividades; nunca aceita itens |
 | `memoring deck list` | seus baralhos (id, nome, status, pai, a revisar, relevância, meta, recorde) — consulte ANTES de gerar |
 | `memoring deck create <nome> [--parent id] [--pending]` | cria baralho (idempotente); `--pending` deixa oculto até o primeiro item aceite |
 | `memoring deck update <id\|nome> [--relevance <0-5>] [--goal "<txt>"] [--tone <gray\|orange\|green\|blue\|purple>] [--clear-*]` | define metadados do baralho (relevância, meta, tom de capa; `--clear-*` limpa o campo) |
+| `memoring plan schema\|analyze\|review\|create\|list\|show` | contrato e ciclo de criação: PDFs → proposta → revisão no JSON ou web (`analyze --web`) → plano; `review --wait` lê o handoff e `create --draft` exige REVIEWED |
+| `memoring plan current\|next\|start\|complete\|postpone\|dismiss\|cancel\|result\|tec-result` | executa Metas/atividades; `next` direto exige `--activities N`; `next --web`/`--draft` faz handoff web; resultados manuais ou cache-only do TEC; `cancel` é redução definitiva de escopo (nunca recompõe o tipo) |
+| `memoring plan performance\|error-patterns\|comparison\|journey\|coordinates\|exams` | diagnósticos, guia e provas (`exams list/create/delete`) |
 | `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] [--concept trib-art-4] ...` | edita um item AINDA PENDENTE (merge com o estado atual — `conceptKey` é preservado se não for informado) |
+| `memoring reference list <noteId> [--json]` | referências de material de um card (fontes de estudo) — página exibida 1-based, com o tipo de destaque (quote ou região) |
+| `memoring reference update <noteId> <referenceId> --file parcial.json [--json]` | corrige `excerpt`/`quote`/`contextBefore`/`contextAfter`/`region` de uma referência (merge: campo ausente mantém o atual, `null`/string vazia limpa; `region` valida `x,y,w,h` em 0..1, `w/h` > 0; não altera nota, arquivo nem página) |
+| `memoring scratch list [--all]` | rascunhos do caderno no Google Drive (via proxy do backend — default só cadernos FREE_NOTEBOOK; `--all` inclui CARD_SCRATCH), listados pelo **CAMINHO da biblioteca** (pasta/título — cada documento é pasta-folha; cards vivem em `Rascunhos de cards/<noteId\|título>`); `--json` inclui o `path` de cada um |
+| `memoring scratch download <caminho\|driveFileId> [--out <dir>] [--metadata-only]` | baixa o `.scratch.json` + PDF, ou só metadados com `--metadata-only`; aceita caminho completo ou driveFileId, nunca escolhe em ambiguidade |
+| `memoring scratch extract <arquivo.pdf> [--pages A-B] [--all] [--out <alvo>]` | recorta a faixa num sub-PDF (pdf-lib); `--text` extrai o TEXTO da faixa com pdfjs-dist (stdout, `--- Página N ---` por página; `--out` grava em arquivo); > ~30 páginas sem `--pages` exige `--all` explícito |
 | `memoring skill` | imprime este guia |
 | `memoring update` | atualiza a CLI (decisão do usuário — nunca rode por conta própria) |
 
@@ -41,18 +51,58 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 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 e a estrutura for destinada à importação, crie com `memoring deck create "<nome>" --pending` (ou deixe o próprio `stage create` criar pelo nome — nesse caso o baralho também nasce **PENDING**). **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>" --pending` — o create-por-nome do `stage create` só cria baralho raiz. Use `--pending` na estrutura criada para importação: baralhos PENDING ficam ocultos no app (árvore, filtros, fila, estatísticas) até o **primeiro item aceite** — o aceite ativa o baralho E os ancestrais pendentes de uma vez; descartar não ativa. 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.
+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. Errou o quote/contexto/região de uma referência? `memoring reference list <noteId>` + `memoring reference update <noteId> <referenceId> --file parcial.json` corrigem os metadados sem tocar no item.
 8. **Avise o usuário e PARE**: informe quantos itens foram para a caixa de revisão, os `ids` e onde ele revisa — no app em `/cards/inbox` (ou `memoring inbox list` para ver o estado). O fluxo termina AQUI: aceitar (`memoring inbox accept <id>` / `memoring inbox accept-all`) é decisão do usuário e só acontece quando ELE pedir explicitamente — aponte o caminho, não execute.
 
+## Planejamento de estudos (`memoring plan`)
+
+Use este fluxo quando o pedido for organizar PDFs num plano, gerar uma Meta ou acompanhar atividades. A análise por IA acontece **somente no backend**: a CLI envia os PDFs, aguarda o job e adapta a resposta num rascunho editável. Não tente reproduzir essa análise com uma LLM local nem chame a API diretamente.
+
+1. Confirme `memoring auth status --json` e leia `memoring plan schema --json`. O schema contém o contrato do plano e da prova, as três maturidades e os motivos de erro.
+2. **Ofereça a revisão web como opção recomendada**, deixando também o fluxo de JSON no terminal. Na web, o usuário revisa numa interface amigável e o agente continua sendo o único que cria plano/Meta. Os PDFs aceitos são 1 a 10 arquivos de até 50 MB cada, com basenames únicos mesmo entre pastas; upload e polling da análise têm timeouts separados de 10 minutos (`MEMORING_MULTIPART_TIMEOUT_MS` configura o upload, em ms).
+3. Para a **revisão web**, rode `memoring plan analyze <pdfs...> --web --json`. Isso cria apenas um rascunho `PLAN` e abre `/planning/new?draft=<uuid>` (`--no-open` suprime a abertura; `MEMORING_WEB_BASE` muda a origem, default `https://memoring.com.br`). Leia a resposta estruturada `{draft, reviewUrl, nextCommand}`: guarde `draft.id`, mostre `reviewUrl` ao usuário e aguarde ele concluir a revisão. `memoring plan review <uuid> --wait --json` consulta até `draft.status === "REVIEWED"` (timeout default 10 minutos; `--timeout <segundos>` ajusta). Sem `--wait`, `review <uuid> --json` apenas consulta; `draft` é alias de `review`. Para salvar somente o payload já revisado, acrescente `--out proposta-revisada.json`; `--out` recusa `OPEN`. Timeout não apaga rascunho — consulte novamente ou informe o usuário, sem criar.
+4. Crie somente dentro do pedido do usuário e **somente após REVIEWED**: `memoring plan create --draft <uuid> --json`. A CLI valida tipo/status/payload, envia a criação e apaga o rascunho apenas depois do sucesso. Nunca tente criar a partir de `OPEN`, nunca trate o clique web como criação e não repita o POST cegamente após erro de rede. Guarde `plan.id`; consulte com `plan list` e `plan show <planId>`.
+5. Se o usuário preferir o **fluxo antigo**, rode `memoring plan analyze <pdfs...> --out proposta.json` e revise nome, objetivo, `weeklyMinutes`, disciplinas/assuntos, páginas, `deckId`/`tecNotebookId` e, obrigatoriamente, `maturity` por disciplina. O rascunho usa `BEGINNER` como default conservador, não diagnóstico; também são aceitos `INTERMEDIATE`/`ADVANCED` e rótulos PT-BR. Preserve índices 0-based de `materialIndex`/`prerequisiteTopicIndex`. Depois rode `memoring plan create --file proposta.json --json`. Sem `--web`, `analyze --json` continua imprimindo apenas o rascunho e permite `> proposta.json`.
+6. Para abrir um ciclo no fluxo direto, `memoring plan next <planId> --activities N --json`. **Nesse fluxo `--activities` continua obrigatório (1..200)** e vira `activityTarget`; não omita nem presuma um alvo se o usuário não o informou. Para escolha web, ofereça `memoring plan next <planId> --web --json`: nasce só um handoff `GOAL` com `payload: {}` e URL `/planning/<planId>?goalDraft=<uuid>`. Aguarde `plan review <uuid> --wait --json` chegar a REVIEWED e rode `memoring plan next <planId> --draft <uuid> --json`; a CLI confere plano, tipo, status e `activityTarget` antes de criar, apagando o rascunho só após sucesso. `current <planId>` lê a Meta ativa e seus IDs de atividade.
+7. Execute com `start|complete|postpone|dismiss|cancel <activityId>` (`cancel` = cancelar definitivamente: encerra a atividade na Meta e o tipo não volta nas próximas — só use quando o usuário pedir redução de escopo). Resultado manual: `result <activityId> --total N --correct N [--seconds N] [--errors FORGETTING:2,INATTENTION:1]`; total/correct são obrigatórios, correct ≤ total e a soma classificada ≤ total-correct. Ao regravar sem `--seconds`/`--errors`, a CLI omite esses campos e preserva os valores atuais; no contrato do backend, `errors` omitido preserva a classificação e `errors: []` limpa. Motivos: `UNKNOWN`, `FORGETTING`, `CONCEPTUAL_CONFUSION`, `INATTENTION`, `INTERPRETATION`, `TIME_SHORTAGE`, com aliases PT-BR. `tec-result <activityId>` apenas importa o resultado já disponível no caderno TEC (addon necessário) — não faz sync nem login.
+8. Acompanhe com `performance|error-patterns|comparison|journey <planId>` e `coordinates`. Provas: `plan exams list`, `plan exams create --file prova.json` (contrato no schema) e `plan exams delete <examId>` só quando o usuário pedir a exclusão. Create de prova também aceita `--name --date YYYY-MM-DD --total --correct [--plan-id N] [--subjects '<array JSON>']`.
+
+Todos os comandos aceitam `--json`, sem texto humano no stdout. Leia os campos estruturados em vez de parsear texto: handoffs web usam `{draft, reviewUrl, nextCommand}`; `review` devolve o rascunho completo com `status` e `payload`; o `analyze` sem web e os recibos de delete são exceções de formato já descritas. As operações usam somente endpoints autenticados e user-scoped; tokens nunca entram nas URLs de revisão.
+
+## Vários lotes e proveniência
+
+- Antes de enviar referências, rode `stage validate --file lote.json --pdf-map map.json`: ele usa o mesmo localizador do app e rejeita quotes inexistentes/ambíguos, sem escrever nada.
+- Para várias atividades, use `batch check` antes e `batch run --resume` depois. O manifesto tem `version`, `pdfMap` e `activities` com `id`, `batchFile`, `deckName`, `expectedReferences` e `generationFile` opcional. O batch exige baralho existente e único; crie a hierarquia antes com `deck create`.
+- O state fica em `<plan>.state.json`. O resume usa IDs do state; se ele for perdido após um POST, o replay recupera a resposta original. O dedupe dura 7 dias — não trate reenvio antigo como idempotente.
+- `generationFile` registra provider/modelo solicitado e resolvido, versões e métricas. Só preencha o que a chamada à LLM realmente informou; nunca presuma o modelo a partir do agente. O aceite continua sendo decisão do usuário.
+- O piloto `scripts/notes/gemini-pdf-to-batch.mjs` apenas gera JSON e o valida localmente. Depois siga `batch check`/`run`; ele não cria nem aceita itens.
+
+## Rascunhos do Drive → flashcards (`memoring scratch`)
+
+Quando o usuário pedir flashcards/notas de um **rascunho do caderno manuscrito** (que vive no Google Drive do app), use o pacote `scratch` — a CLI lista e baixa via proxy do backend. A CLI **não inicia o OAuth do Google**: se o Drive não estiver conectado, o comando falha com 409 e você deve orientar o usuário a conectar pelo app (Caderno → vincular Drive).
+
+1. **`memoring scratch list`** — encontre o rascunho pelo **caminho** da biblioteca (ex.: `Direito Administrativo/Aula 02`); use o caminho (ou o `driveFileId`) no download. Default lista só cadernos; `--all` inclui rascunhos de card.
+2. **`memoring scratch download "<caminho>" [--out <dir>]`** — aceita o caminho completo mostrado no list (acentos, maiúsculas e espaços livres — `"direito administrativo/ AULA 02"` funciona) ou o `driveFileId`. Baixa o `.scratch.json` e, se o rascunho tem PDF de fundo, o PDF junto (nome legível do arquivo; asset `<hash>.pdf` como fallback). A saída diz quantas páginas o PDF tem (≈ **2.700 tokens/página densa**) e, acima de ~30 páginas, já sugere o recorte. Caminho não encontrado ou ambíguo → o erro lista os candidatos: refine o caminho ou use o `driveFileId` — nunca chute.
+3. **Interprete a faixa pedida em linguagem natural** — "páginas 20 a 35", "só o capítulo 2", "da metade em diante". O recorte é OBRIGATÓRIO quando o material é grosso: **acima de ~60 páginas, NUNCA gere do PDF inteiro**. Quando a faixa for vaga ("o capítulo 2"), estime as páginas (índice/sumário do material) e **peça confirmação do usuário antes de gerar**.
+4. **`memoring scratch extract <pdf> --pages A-B`** — gera o sub-PDF `<nome>-pA-B.pdf` com a estimativa de tokens da faixa. O comando **força a decisão**: PDF com mais de ~30 páginas sem `--pages` só sai com `--all` explícito — um erro aí NÃO é falha, é a trava de contexto funcionando; recorte e siga. **PDF digitalizado em texto?** Acrescente `--text`: o comando extrai o texto puro da faixa (páginas separadas por `--- Página N ---`) no stdout — muito mais barato que "ler" o PDF. PDF 100% escaneado (só imagem) sai vazio no `--text`: nesse caso gere do sub-PDF recortado.
+5. **Gere os cartões APENAS do recorte** — leia o PDF recortado (não o original), aplique o `stage schema` logado (limites, regras de qualidade, instruções custom) e a taxonomia: `NORMAL` (flashcard frente/verso), `ONE_SHOT` (resposta de um termo — leis, datas, prazos, siglas), `QUESTION` (questões prontas do material — aproveite-as), `NOTE` (síntese em markdown). `conceptKey` no slug do conceito para o whiteboard agrupar.
+   **Vincule cada item à página do material:** inclua `materialReferences: [{ "driveFileId": "<id do `scratch list --json`>", "page": <página visível 1-based>, "quote": "<trecho LITERAL do material>", "excerpt": "<dica curta>" }]` — `page` é a posição 1-based no documento (a mesma numeração do `--pages` do recorte, não um índice 0-based). Ao aceitar o item, o link abre o PDF **na página** e destaca o quote; para PDF escaneado/sem texto use `"region": { "x", "y", "w", "h" }` (0..1) em vez de quote; `source` continua sendo o texto livre da origem.
+6. **`memoring stage create --file itens.json`** e reporte: o que foi estagiado, quantos itens, os `ids` e que o usuário revisa em `/cards/inbox` — o aceite continua sendo decisão DELE.
+
 ## 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).
+- `type`: `NOTE` (nota, exige `content` markdown), `NORMAL` (flashcard frente/verso) ou `ONE_SHOT` (exigem `front` + `back`) ou `QUESTION` (exige `question` — ver abaixo). `FLASHCARD` legado é aceito e mapeado para `NORMAL` no backend.
 - `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 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`.
+- `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 → `NORMAL`.
 - `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.
+- `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 NORMAL/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.
+- `materialReferences` (opcional): referências ao material de origem que vinculam o item à **página do PDF** e destacam o trecho exato usado no card — ao aceitar, o link do item abre o material **na página** com o destaque. Cada entrada é `{ "driveFileId", "page", "excerpt?", "quote?", "contextBefore?", "contextAfter?", "region?" }`: `driveFileId` vem do `memoring scratch list --json` (id do arquivo no Drive), `page` é a posição **1-based** no documento (a CLI converte para 0-based no envio; a validação local rejeita page < 1 ou não inteira antes de qualquer POST). A regra do destaque:
+  - **PDF com texto → `quote` literal** (até 1000 chars): é o que o app localiza e destaca. `contextBefore`/`contextAfter` (até 500 cada) desempatam ocorrências repetidas.
+  - **PDF escaneado/sem texto → `region`** (`{ x, y, w, h }` normalizada 0..1, origem topo-esquerdo; números finitos, `w/h` > 0, `x+w <= 1`, `y+h <= 1`): selecione a região do recorte em vez de quote.
+  - **`excerpt` é só uma dica curta** (até 500) — sozinho NÃO gera destaque.
+  Referência já criada com quote/contextos errados? Não reenvie o lote: `memoring reference update <noteId> <referenceId> --file parcial.json` faz merge (campo ausente mantém; `region: null` limpa). Não substitui `source` (texto livre) — use os dois juntos.
 - `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.
 
@@ -67,7 +117,7 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 
 ## Qualidade dos flashcards (o padrão que o app espera)
 
-Cartões atômicos: UMA ideia por cartão — se um conceito tem 3 partes cobráveis, crie 3 cartões, nunca um cartão com lista como resposta. A frente é uma pergunta direta que força LEMBRAR (não reconhecer). A resposta é auto-contida (faz sentido sem o material) e curta. Pares confundíveis (prazos, siglas, exceções) levam na frente o traço que os diferencia. Não invente conteúdo que não esteja no material. Distribua os tipos: um bom lote usa NOTE, FLASHCARD, ONE_SHOT e QUESTION conforme o material pedir — não zere um tipo por timidez (termos, leis, datas e prazos cobráveis viram ONE_SHOT).
+Cartões atômicos: UMA ideia por cartão — se um conceito tem 3 partes cobráveis, crie 3 cartões, nunca um cartão com lista como resposta. A frente é uma pergunta direta que força LEMBRAR (não reconhecer). A resposta é auto-contida (faz sentido sem o material) e curta. Pares confundíveis (prazos, siglas, exceções) levam na frente o traço que os diferencia. Não invente conteúdo que não esteja no material. Distribua os tipos: um bom lote usa NOTE, NORMAL, ONE_SHOT e QUESTION conforme o material pedir — não zere um tipo por timidez (termos, leis, datas e prazos cobráveis viram ONE_SHOT).
 
 ## Armadilhas