# Agenda - Hardware Specs Reorganization

## Problema

As specs de hardware hoje estão com cara de colcha de retalhos.

Há material útil, mas a organização mistura:

- capítulos extensos e narrativos;
- conteúdo normativo e conteúdo pedagógico;
- temas de VM, firmware, cartridge, assets e ABI no mesmo bloco de "hardware";
- granularidade desigual entre capítulos.

## Dor

- Fica difícil saber o que é norma e o que é explicação.
- A navegação está ruim para quem precisa alterar um domínio específico.
- Ownership documental por área não está claro.
- Revisões futuras tendem a acrescentar mais remendos em vez de consolidar o modelo.
- O risco de contradição entre spec, arquitetura e implementação cresce.

## Alvo da Discussao

Definir uma organização coerente para as specs do sistema, com separação clara entre:

- spec normativa;
- material conceitual/pedagógico;
- arquitetura de runtime;
- domínios de hardware/periféricos;
- firmware, cartridge e tooling-related specs.

## O Que Precisa Ser Definido

1. Taxonomia das specs.
   Quais grandes categorias devem existir:
   - machine/runtime
   - hardware/peripherals
   - firmware/system
   - cartridge/package
   - host ABI
   - assets/tooling

2. Critério de corte.
   O que pertence a "hardware" de fato e o que deve sair desse pacote.

3. Estrutura de navegação.
   Como organizar índice, capítulos, subpastas e documentos canônicos por domínio.

4. Nível de autoridade.
   Quais documentos são normativos e quais são apenas explicativos.

5. Estratégia de migração.
   Como reorganizar sem quebrar referências, sem perder contexto e sem reescrever tudo de uma vez.

## O Que Necessita Para Resolver

- inventário da estrutura atual;
- proposta de taxonomia e árvore de diretórios;
- mapeamento capítulo atual -> destino futuro;
- política para docs históricos ou híbridos;
- critério mínimo de consistência editorial para novos documentos.

## Fora de Escopo

- reescrever toda a spec de hardware imediatamente;
- normalizar cada frase ou estilo de escrita;
- atualizar todo conteúdo técnico de cada capítulo nesta mesma discussão.

## Critério de Saida Desta Agenda

Pode virar PR quando houver:

- taxonomia alvo aprovada;
- nova árvore de organização definida;
- mapa de migração dos capítulos atuais;
- decisão sobre normativo vs pedagógico;
- plano incremental de execução.