wiki-ingest-book

O que wiki-ingest-book faz?

Antes da primeira ingestão, leia docs/GOTCHAS.md no kit (pegadinhas operacionais, incluindo calibração de offset de página para livros).

Estende o padrão de ingestão do LLM-wiki para livros acadêmicos. Livros são pesados em contexto e não podem ser ingeridos de uma só vez, portanto esta skill usa uma abordagem em duas fases: primeiro uma visão geral do livro, depois capítulos sob demanda.

Papel e Limites

Faz: criar notas de livro, criar notas de capítulo, propagar descobertas para notas de conceito e método, atualizar o índice e o log.

NÃO faz: ler um livro inteiro em uma passada (risco de estouro de contexto), inventar metadados ou títulos de capítulos, ou duplicar o fluxo de trabalho de ingestão de artigos (capítulos seguem as mesmas regras de propagação de conceito que artigos).

Onde as coisas ficam

Os caminhos vêm de wiki.config.json (veja wiki-ingest). Livros e capítulos ficam em <wiki_root>/books/. Templates: templates/book.md e templates/chapter.md. A pasta que contém sua biblioteca de PDFs é pdf_library_dir no config.

Skills relacionadas

• wiki-ingest: compartilha as regras de decisão de status inicial e o field_titlecase_map usado para roteamento de índice.
• wiki-lint: execute após cada ingestão de capítulo. A verificação 8 (sincronia de chapters_ingested) e a verificação 9 (frontmatter book: do capítulo) capturam a maioria dos desvios comuns de ingestão de livro.

Contratos obrigatórios (devem valer após cada ingestão)

1. Cada nota de capítulo em books/{livro}_ChNN.md DEVE carregar book: "[[{nome_base_do_livro}]]" no frontmatter, e o alvo deve resolver para uma nota de livro existente. Verifique após escrever; se faltar, a verificação 9 do wiki-lint sinaliza.
2. Cada ingestão de capítulo DEVE anexar o número do capítulo à lista chapters_ingested: da nota do livro pai. Após anexar, liste {livro}_Ch*.md e confirme que os dois conjuntos coincidem; caso contrário, a verificação 8 do wiki-lint sinaliza o desvio.
3. Status inicial segue a tabela de status do wiki-ingest: stub para apenas definição, draft em andamento, e uma nota de capítulo atinge final com 2 ou mais descobertas com fonte (um capítulo é em si uma fonte). Notas de conceito e método derivadas seguem a regra de promoção estrita: final precisa de N obras-fonte distintas (min_distinct_sources_for_final, padrão 2), então um conceito construído apenas a partir deste livro permanece draft até que uma segunda fonte independente o corrobore.
4. Roteamento de índice usa field_titlecase_map para colocar novos conceitos e métodos sob a subseção de campo Title Case correta, nunca em um bloco datado de catch-all.

Preâmbulo (sempre, antes do Modo A ou Modo B)

1. Leia WIKI_SCHEMA.md.
2. Leia o template: Modo A usa templates/book.md; Modo B usa templates/chapter.md (e templates/book.md para referência).

Ferramentas: use as ferramentas de arquivo do host (Read/Write/Edit) para todas as escritas no vault.

---

Resolução de PDF local (preferido para texto completo)

Pasta padrão: pdf_library_dir no config (armazenamento de PDF do seu gerenciador de referências). Extrator: pdftotext (poppler) ou, para melhor fidelidade de tabelas, docling. Sempre execute pdftotext com -enc UTF-8.

Localize o PDF enumerando e grepando o autor, NÃO com uma ferramenta glob e NÃO com find -iname "*<autor>*"; ambos têm falsos negativos documentados para arquivos que existem em alguns sistemas de arquivos: find "<pdf_library_dir>" -iname "*.pdf" | grep -i <sobrenome_do_primeiro_autor>. Amplie a raiz para toda a biblioteca se a primeira passagem estiver vazia (livros também ficam em subpastas temáticas). Exatamente 1 correspondência: use-a. 0 ou mais de 1: pergunte ao usuário o caminho exato. Se isso também falhar: recorra ao texto completo do gerenciador de referências.

O algoritmo de resolução completo, a cascata de texto completo local-first e a tabela de decisão do MCP, detecção de PDF escaneado e o perigo de nome de arquivo não-ASCII estão em references/BOOK-INGEST-WORKFLOW.md (seções 1 e 1bis). Leia antes da primeira extração de um novo livro. O corpo abaixo mantém apenas os comandos usados para cada capítulo.

Comandos de extração

• Sumário / visão geral (Modo A): pdftotext -enc UTF-8 -f 1 -l 20 "<caminho>" - (primeiras 20 páginas, stdout).
• Intervalo de capítulo (Modo B): pdftotext -enc UTF-8 -f <pdf_inicio> -l <pdf_fim> "<caminho>" -. -f/-l usam números de página do PDF, não números de página do livro; converta a partir do sumário com o offset (próxima seção).
• Escrevendo o extrato em um arquivo que você lerá (Read): um trecho longo de capítulo pode ser mais fácil como arquivo do que como stdout. Escreva-o dentro do projeto (por exemplo _temp/{livro}_Ch{NN}.txt), não em um /tmp específico do sistema operacional que a ferramenta Read não pode abrir (Git Bash no Windows mapeia /tmp para algum lugar que ferramentas Windows não podem ver).

Calibração de offset de página (páginas do livro não são páginas do PDF)

O sumário de um livro lista números de página do livro; pdftotext -f/-l endereça páginas do PDF. Elas diferem por um offset (material de prefácio, pranchas) que cresce não linearmente ao longo do livro (figuras, tabelas, divisores de partes). Passar números do sumário diretamente para pdftotext extrai as páginas erradas, a perda de tempo mais comum na ingestão de capítulos. Calibre uma vez por livro, antes de extrair qualquer capítulo:

1. Escolha um capítulo com uma página inicial de livro conhecida. Estime pdf_inicio = pagina_do_livro + palpite_offset (material de prefácio geralmente tem 20 a 60 páginas).
2. Extraia apenas sua primeira página e confirme se o título do capítulo aparece. Ajuste em até 5 páginas até acertar.
3. Registre o offset calibrado na nota do livro (por exemplo > [!note] Offset do PDF: pg_livro + N = pg_pdf (zona: Parte X) perto do sumário) para que capítulos posteriores o reutilizem.
4. Recalibre por zona ou Parte em livros longos: um offset fixo único se desvia (por exemplo +36 no Cap 3 e +56 no Cap 21 em um livro didático). Para PDFs com camada de texto, dividir o texto em feeds de formulário fornece um mapa de página rápido com páginas iniciais exatas.

---

Modo A: Visão geral do livro

Gatilho: /wiki-ingest-book [título]

1. Resolva no gerenciador de referências: pesquise pelo título, depois busque metadados (título, autores, editores, ano, editora, ISBN, edição, DOI, citekey).
   • Ressalva de citekey com sufixo de ano (série de vários volumes ou Partes): um citekey do Better BibTeX como ...2019a / ...2019b NÃO mapeia de forma confiável para a Parte 1 versus Parte 2 de uma série do mesmo autor e mesmo ano (o sufixo é ordem de desambiguação, não significado). Sempre confirme o título real (e subtítulo ou "Parte N") a partir dos metadados antes de nomear a nota ou confiar em qual volume você tem.
2. Resolva o texto completo para o sumário (cascata; veja "Resolução de PDF local"):
   • Primário: pdftotext -enc UTF-8 -f 1 -l 20 "<caminho_local>" - (cerca de 3 a 8k tokens).
   • Fallback 1: texto completo do gerenciador de referências, apenas se o PDF local não estiver disponível E a saída tiver menos de 2.000 palavras.
   • Fallback 2: peça ao usuário para colar o sumário; marque como "Fonte: fornecida pelo usuário".
   • Fallback 3: conhecimento do modelo para livros didáticos bem conhecidos; marque cada item com [!note].
3. Determine o nome do arquivo: PrimeiroAutor_Ano_PalavraChave.md (sobrenome do primeiro autor, apenas ASCII; palavra-chave é 1 a 3 palavras sobre o tópico principal do livro). Se books/{nome_do_arquivo}.md existir, atualize in place.
4. Crie ou atualize a nota do livro em books/{nome_do_arquivo}.md a partir de templates/book.md. Defina last_verified para a data de hoje.
5. Preencha o sumário a partir do passo 2. Se incerto, marque capítulos com ? e anote a limitação.
6. Extraia de 3 a 5 temas de alto nível (apenas nível do livro, sem alegações específicas de capítulo). Propagação leve: atualize notas concepts/ apenas se o tema for central para uma linha de pesquisa E 2 ou mais artigos do wiki já o abordarem; caso contrário, apenas liste-o na nota do livro. Um tema que atinge uma nota segue a regra da tabela de evidências: passos 6b e 8b do Modo B.
7. Verificação de governança: aplique a correspondência de linha de pesquisa e o roteamento conceito-versus-método do passo 5 do wiki-ingest. No nível de visão geral, apenas anote quais capítulos provavelmente produzirão notas de método versus notas de conceito; a propagação completa ocorre no Modo B.
8. index.md: se o índice incorporar visualizações Bases, NÃO adicione uma entrada de livro; apenas aumente a contagem "## Quick Stats" "Livros (ingeridos)" quando esta ingestão completar uma nova ingestão de livro pai. No modo manual, adicione a entrada. Nunca toque em um índice legado congelado.
9. Anexe a log.md: ## [YYYY-MM-DD] ingest-book | {Título}: visão geral.
10. Relatório: caminho da nota do livro, temas identificados e quais capítulos estão disponíveis para ingestão profunda (/wiki-ingest-book [título] > Capítulo N).

---

Modo B: Ingestão de capítulo

Gatilho: /wiki-ingest-book [título] > Capítulo N (ou > Capítulo: [título do capítulo])

1. Leia a nota do livro existente em books/PrimeiroAutor_Ano_PalavraChave.md.

   • Se não existir: pare. Execute o Modo A primeiro, depois tente novamente.
   • Se o capítulo não estiver listado no sumário: anexe uma linha com status: pending, anote no relatório final, continue.
   • Se o capítulo já estiver marcado como ingested: confirme com o usuário antes de sobrescrever (padrão: atualizar in place, preservando [[wikilinks]] existentes).

2. Resolva o conteúdo do capítulo (cascata; veja "Resolução de PDF local"):

   • Pegue o intervalo de páginas do capítulo do sumário da nota do livro e converta páginas do livro em páginas do PDF com o offset registrado. Pergunte ao usuário apenas se os números de página do sumário forem desconhecidos.
   • Primário: pdftotext -enc UTF-8 -f <pdf_inicio> -l <pdf_fim> "<caminho_local>" - (um capítulo típico tem 1k a 8k tokens).
   • Fallback 1: se o capítulo for um item bookSection com entrada própria na biblioteca, use o texto completo desse item.
   • Fallback 2: texto completo do livro inteiro do gerenciador de referências, apenas se o PDF local não estiver disponível E o livro tiver menos de 5.000 palavras.
   • Fallback 3: peça ao usuário para colar o texto do capítulo.
   • Fallback 4: conhecimento do modelo, com [!warning] em cada alegação. Nunca atinge uma nota de conceito ou método e não recebe selo.

3. Nome do arquivo do capítulo: PrimeiroAutor_Ano_PalavraChave_ChNN.md (por exemplo Knuttgen_1987_Strength_Ch03.md).

4. Crie a nota do capítulo em books/{nome_do_arquivo_do_capitulo}.md a partir de templates/chapter.md. Defina last_verified para a data de hoje.

   • Contrato obrigatório: emita book: "[[{nome_base_do_livro_pai}]]" no frontmatter e verifique se resolve. Se não resolver, o pai não foi ingerido: execute o Modo A primeiro.
   • Status inicial: aplique a tabela de status do wiki-ingest. Um capítulo esqueleto com apenas a entrada do sumário preenchida é stub; um capítulo com pelo menos 2 descobertas com fonte é final.
   • Nível de evidência: evidence_level: textbook por padrão. Substitua para SR-MA ou SR apenas se o capítulo for, em si, uma revisão sistemática ou meta-análise independente. A qualidade da medição permanece inline nas descobertas, nunca no frontmatter.

5. Extraia de 3 a 8 conceitos e 1 a 4 métodos: mesmas regras de extração do wiki-ingest (veja references/BOOK-INGEST-WORKFLOW.md).

6. Verificação de governança: mesma correspondência de linha de pesquisa e roteamento conceito-versus-método do passo 5 do wiki-ingest. Decida explicitamente para este capítulo: notas de conceito (descobertas empíricas), notas de método (estruturas, protocolos) ou ambos. Conteúdo pedagógico geral tipicamente produz apenas notas de método; não force criação de conceito para conteúdo que pertence a methods/. 6b. Tabela de evidências e verificação, antes de qualquer propagação: aplique os passos 5b e 5c do wiki-ingest a este capítulo, com uma tabela auxiliar para o capítulo. Três adições para livros:

   • A coluna de página fornece tanto a página do PDF quanto a página impressa, e o título do capítulo é confirmado na página em que você aterrissa (um offset errado cita outro capítulo).
   • Um livro didático recebe leitura estrita: verifique cada mecanismo e marcador que a descoberta nomeia. A lista de causas ou critérios de um capítulo não é evidência para cada item, a menos que o item esteja na página.
   • Diga quem fala: uma alegação que o capítulo entrega a outro autor é escrita "X, conforme relatado por [[capítulo]]", e a opinião clínica de um capítulo não é escrita como resultado de ensaio. Apenas linhas que passam vão para os passos 7 e 8. Leia sinais da página renderizada.

7. Propague para notas de conceito, idêntico à ingestão de artigos: anexe a descoberta com um backlink [[nota_do_capitulo]] para a concepts/{Conceito}.md existente, ou crie uma nova a partir de templates/concept.md sob as mesmas regras de criação que wiki-ingest/references/CONCEPT-PROPAGATION.md.

8. Propague para notas de método se aplicável. 8b. Sele a nota do capítulo: aplique o passo 8b do wiki-ingest com o capítulo como obra (registre a verificação em source_verification: chave da biblioteca, ISBN, capítulo e páginas verificados, data).

9. Stubs de referência futura (automático): após o corpo do capítulo ser escrito, materialize quaisquer referências futuras para capítulos irmãos que ainda não existam:

   python skills/wiki-ingest-book/scripts/create_forward_ref_stubs.py \
     <wiki_root>/books/{livro}_Ch{NN}.md  <wiki_root>/books/{livro}.md   [--dry-run]
   

   O script varre o capítulo recém-ingerido em busca de links [[{livro}_ChNN]] (ciente de alias), lê a tabela ## Tabela de Conteúdo do hub do livro para recuperar título e páginas de cada capítulo faltante, deriva DOI e citekey do frontmatter do hub ({doi_base}_{N}, {citekey_base}_ch{N}), e escreve stubs UTF-8 com status: stub. Referências futuras sem uma linha no sumário são ignoradas e relatadas (ingestão manual necessária). As ações são registradas em _temp/wiki_ingest_book_stubs_created.md. A verificação 8 do wiki-lint honra status: stub, então esses stubs NÃO dessincronizam chapters_ingested, que permanece a lista canônica de capítulos realmente ingeridos.

   ⚠️ Nunca escreva um marcador de estado de ingestão na prosa de um capítulo. Sem *(pendente de ingestão)*, sem "ainda não ingerido" ao lado de um capítulo irmão, em ## Artigos Relacionados, em um marcador veja também, ou em qualquer outro lugar. O estado de ingestão é mutável e tem exatamente um lar: a linha ## Tabela de Conteúdo do hub do livro, que o passo 11 muda de pending para ingested. Um marcador copiado na prosa duplica um fato mutável em um lugar imutável: o irmão é ingerido, o sumário atualiza, e a prosa continua afirmando o oposto para sempre. Em uma auditoria, isso produziu 68 marcas obsoletas em 58 notas, cada dependência já ingerida. Nenhuma verificação de lint vê esta classe, porque cada arquivo permanece coerente consigo mesmo e a contradição existe apenas entre arquivos. Apenas link o irmão; se um trabalho estiver fora do wiki, nomeie-o em texto plano.

10. Relatório de conceitos ausentes (automático): após a escrita do capítulo, execute:

    python skills/wiki-ingest-book/scripts/report_missing_concepts.py \
      <wiki_root>/books/{livro}_Ch{NN}.md  <wiki_root>/concepts/  [--dry-run]
    

    O script varre a nota do capítulo em busca de [[Conceito]] links que não têm nota correspondente em concepts/. Ele agrupa por status (por exemplo, [!missing], [!todo], ou sem marcador), produz um relatório markdown em _temp/wiki_ingest_book_missing_concepts.md, e retorna um resumo que a resposta do agente deve incluir. Este relatório é apenas informativo: a skill não cria stubs de conceito automaticamente. Se o usuário solicitar a criação de um conjunto de stubs, use esta saída como entrada para uma execução de lote.

11. Atualize o sumário do hub do livro: localize a linha do capítulo na tabela ## Tabela de Conteúdo e mude seu status: para ingested. Se chapters_ingested: existir, anexe o número do capítulo; se não existir, crie-a como uma lista YAML de nível superior. Verificação de contrato: após a atualização, liste {livro}_Ch*.md e confirme a correspondência com a lista.

12. Anexe a log.md: ## [YYYY-MM-DD] ingest-book | {Título} > Capítulo {N}.

13. Relatório: caminho da nota do capítulo, número de descobertas com fonte, quaisquer notas de conceito/método criadas ou atualizadas, quaisquer capítulos irmãos stub criados, e quaisquer conceitos ausentes detectados.

---

Modo C (não implementado): Reingestão em lote

Atualmente não implementado. A trilha de pensamento para reingestão em lote deve ser desenvolvida como uma skill separada usando a interface /wiki-ingest -batch depois que o padrão de capítulo único estiver estável.

---

Referências externas

• wiki-ingest: skill pai compartilhando regras de propagação de conceito.
• wiki-lint: execute os checks 8 e 9 após cada ingestão de capítulo.
• references/BOOK-INGEST-WORKFLOW.md: algoritmo completo de resolução de PDF, tabela de decisão de cascata/MCP, detecção de PDF escaneado.
• references/CONCEPT-PROPAGATION.md: regras de criação de stubs de conceito.
• docs/GOTCHAS.md: pegadinhas operacionais específicas do kit (leia antes da primeira ingestão).