# LLMs e Agentes de Codigo

Projeto editorial, tecnico e comercial do livro **LLMs e Agentes de Codigo -- do zero ao fluxo profissional com inteligencia artificial**.

Subtitulo: **Como entender, usar e confiar em modelos de linguagem e agentes de codigo -- do primeiro prompt ao fluxo profissional**.

Autor: **Wallace Phillip Maclayne Alves Alencar**<br>
Marca autoral: **WPM · W. Phillip Maclayne**

## Visao Geral

Este repositorio preserva a historia de criacao, revisao, empacotamento e preparacao comercial do livro. Ele inclui o manuscrito em Markdown, documentacao editorial, inventarios, auditorias, HTMLs, CSSs, pagina de venda, materiais de apoio, fontes de pesquisa convertidas para Markdown e registros de preservacao.

O livro foi construido para leitores iniciantes e intermediarios que querem usar LLMs e agentes de codigo com metodo, seguranca e revisao humana. O tom editorial e pratico, didatico, conversacional e profissional, sem promessas exageradas e sem dependencia cega de ferramentas.

## Estado Atual do Projeto

- Fallback aprovado: `v1.1 profissional`.
- Variante visual aprovada: `v1.1 visual-light`.
- Candidata principal de publicacao: `v1.1 visual-light`, se a revisao humana final aprovar capa, miolo, legibilidade e experiencia de download.
- Material comercial separado: `release/LLMs-e-Agentes-de-Codigo-v1.1-marketing-visual.zip`.
- Pagina de venda estatica: `marketing/pagina-venda/`.
- Kit visual integrado: `assets-visuais/llms-agentes-codigo/`.
- Documentacao consolidada: `docs-completos/`.

## Onde Comecar

Para entender o projeto rapidamente, leia nesta ordem:

1. `docs-completos/INDEX.md`
2. `docs-completos/00-README-GERAL.md`
3. `docs-completos/20-RESUMO-EXECUTIVO.md`
4. `docs-completos/11-RELEASES-E-PACOTES.md`
5. `docs-completos/15-COMO-PUBLICAR.md`
6. `docs-completos/16-GUIA-PARA-GITHUB-E-DRIVE.md`
7. `docs-completos/24-CHECKLIST-FINAL-DE-PRESERVACAO.md`

## Estrutura do Repositorio

```text
.
├── AGENTS.md                 # Regras de trabalho para agentes neste projeto
├── DOCUMENTACAO-COMPLETA.md  # Documento consolidado anterior
├── README.md                 # Este guia
├── assets-visuais/           # Kit visual, tokens, guias e contexto visual
├── beta-readers/             # Materiais de leitura beta e feedback
├── biblioteca-prompts/       # Biblioteca de prompts do livro
├── checklists/               # Checklists praticos para o leitor
├── dist/                     # HTML/CSS versionados e PDFs locais nao versionados
├── docs-completos/           # Documentacao institucional atual
├── docs-projeto/             # Documentacao tecnica/editorial anterior
├── fontes/                   # Fontes Markdown reais usadas como base de pesquisa
├── manuscrito/               # Capitulos e manuscritos consolidados em Markdown
├── marketing/                # Pagina de venda e assets essenciais
├── planejamento/             # Arquitetura editorial, sumarios e planos
├── release/                  # Estruturas de release e materiais versionaveis
└── revisoes/                 # Auditorias, changelogs, relatorios e validacoes
```

## Conteudo Principal

### Manuscrito

A pasta `manuscrito/` contem os capitulos individuais, o glossario e versoes consolidadas do livro. O arquivo mais sensivel editorialmente e:

- `manuscrito/livro-v1.1-profissional.md`

Esse arquivo nao deve ser alterado sem pedido explicito quando a tarefa envolver uma nova versao editorial.

### Documentacao Completa

A pasta `docs-completos/` e a memoria institucional do projeto. Ela documenta:

- historico do projeto;
- arquitetura editorial;
- decisoes tecnicas;
- fluxo Markdown -> HTML -> PDF;
- releases e pacotes;
- identidade visual;
- pagina de venda;
- publicacao;
- preservacao;
- riscos e roadmap futuro.

### Revisoes

A pasta `revisoes/` concentra auditorias, changelogs, relatorios de QA e registros de correcao. Qualquer nova versao relevante deve gerar um novo relatorio nessa pasta, com veredito claro e severidade quando houver riscos.

### Marketing

A pasta `marketing/pagina-venda/` contem uma pagina estatica de venda. Ela deve ser tratada como material comercial separado do livro. Mudancas na pagina de venda nao devem modificar o manuscrito ou os artefatos finais do livro.

## Versoes Oficiais e Artefatos

As versoes aprovadas e candidatas sao:

- `v1.1 profissional`: fallback aprovado.
- `v1.1 visual-light`: variante visual aprovada e candidata principal de publicacao.
- `v1.0 final`: historico preservado.
- `v0.1 beta` e `v0.2 editorial`: historicos de evolucao.

Arquivos finais como PDFs, zips de release, backups e assets pesados devem ser preservados tambem fora do Git, preferencialmente no Google Drive, conforme `docs-completos/16-GUIA-PARA-GITHUB-E-DRIVE.md`.

## Arquivos Que Exigem Preservacao

Nao modifique, sobrescreva ou regenere sem autorizacao explicita e QA completo:

- `dist/LLMs-e-Agentes-de-Codigo-v1.1-profissional.pdf`
- `dist/LLMs-e-Agentes-de-Codigo-v1.1-profissional.html`
- `dist/book-style-profissional.css`
- `release/LLMs-e-Agentes-de-Codigo-v1.1-profissional.zip`
- `dist/LLMs-e-Agentes-de-Codigo-v1.1-visual-light.pdf`
- `dist/LLMs-e-Agentes-de-Codigo-v1.1-visual-light.html`
- `dist/book-style-visual-light.css`
- `release/LLMs-e-Agentes-de-Codigo-v1.1-visual-light.zip`
- `release/LLMs-e-Agentes-de-Codigo-v1.0-final.zip`
- `release/LLMs-e-Agentes-de-Codigo-v1.1-marketing-visual.zip`

## Politica GitHub e Drive

Este repositorio foi preparado para guardar o que e mais util em Git:

- documentacao;
- Markdown;
- HTML;
- CSS;
- pagina de venda;
- historico tecnico;
- relatorios;
- fontes textuais.

O Google Drive deve guardar:

- PDFs finais;
- zips de release;
- backups completos;
- assets visuais pesados;
- materiais comerciais congelados;
- copias finais para publicacao.

Essa divisao evita que o GitHub fique pesado demais e, ao mesmo tempo, mantem rastreabilidade editorial.

## Itens Locais Nao Versionados

Alguns arquivos permanecem locais por decisao de preservacao e peso, incluindo:

- PDFs em `dist/`;
- zips em `release/`;
- `kit-visual-llms-agentes-codigo.zip`;
- backups em `backup/`;
- assets brutos em `assets-visuais/llms-agentes-codigo/assets/`;
- amostras PNG em `revisoes/amostras-*`;
- assets pesados de marketing visual em `release/.../marketing-visual/assets/`.

Antes de publicar ou mover esses arquivos, valide se eles devem ir para GitHub, Drive ou ambos.

## Fluxo Seguro Para Nova Versao

Para qualquer nova versao editorial, visual ou comercial:

1. Ler `docs-completos/00-README-GERAL.md`.
2. Confirmar qual versao sera usada como base.
3. Registrar checksums dos artefatos criticos antes de editar.
4. Criar nova variante, sem sobrescrever releases aprovadas.
5. Fazer alteracoes somente nos novos arquivos.
6. Auditar PDF, HTML, sumario, capitulos, apendices, tabelas, boxes e rodapes.
7. Criar release separada.
8. Testar o zip com `unzip -t`.
9. Criar relatorio em `revisoes/`.
10. Confirmar que os artefatos preservados continuam intactos.

## Regras Editoriais

O conteudo deve manter:

- clareza;
- utilidade pratica;
- didatica;
- tom conversacional;
- responsabilidade tecnica;
- ausencia de hype;
- definicao de jargoes antes do uso;
- validacao, riscos e limites em temas tecnicos.

Quando alguma informacao depender de data, ferramenta, plano comercial, politica de privacidade, preco, limite ou versao, marque como `[VERIFICAR ATUALIZACAO]` ate haver verificacao em fonte oficial.

## Seguranca e Privacidade

Nao inclua:

- credenciais;
- tokens reais;
- chaves de API;
- dados pessoais sensiveis;
- documentos privados;
- automacoes ofensivas;
- informacoes comerciais nao autorizadas.

O livro contem exemplos didaticos sobre senhas, tokens e chaves. Esses exemplos devem permanecer claramente ficticios ou anonimizados.

## Comandos Uteis

Ver estado do Git:

```bash
git status --short --branch
```

Ver historico recente:

```bash
git log --oneline --decorate -5
```

Ver arquivos grandes locais:

```bash
find . -type f -size +50M -printf '%p %s bytes\n'
```

Testar um pacote zip:

```bash
unzip -t caminho/do/arquivo.zip
```

## Estado do Git

O historico inicial preserva:

- documentacao completa do projeto;
- manuscritos e fontes Markdown;
- pagina de venda;
- HTMLs e CSSs versionaveis;
- relatorios de revisao;
- correcao dos arquivos de `fontes/`, que foram transformados de symlinks absolutos em Markdown real dentro do repositorio.

## Licenca e Uso

Este projeto contem obra autoral, materiais editoriais, materiais comerciais e documentacao de producao. Antes de reutilizar, redistribuir ou publicar qualquer parte do conteudo, confirme a politica de licenciamento definida pelo autor.

## Regra de Ouro

Releases aprovadas sao evidencia historica. Nao altere uma versao aprovada para "melhorar" algo pequeno. Crie uma nova variante, audite, registre o motivo e preserve o fallback intacto.