# Modelo de dados — documento-mapa 1

O JSON é a fonte de conteúdo das vistas e da versão textual. O template conserva a apresentação; o gerador valida referências e projeta o mesmo conteúdo em HTML e Markdown. Não mantenha uma verdade editada à mão no HTML gerado.

O exemplo `examples/agente-de-revisao.modelo.json` é o menor caso completo de duas vistas. `examples/conjunto-por-fila.modelo.json` acrescenta passagens entre agentes. Ambos são fictícios, sem integração real.

## Contrato dos objetos

Todos os campos da tabela são obrigatórios. IDs usam letras minúsculas, números e hífen, começando por letra; são únicos no documento inteiro.

| Objeto | Campos e sentido |
| --- | --- |
| Raiz | `schema_version: "1"`, `titulo`, `pergunta`, `publico`, `escopo`, `fora_do_escopo`, `versao`, `data` (AAAA-MM-DD), `condicao`, `conclusao`, `limites` (lista de textos), `fontes`, `nos`, `relacoes`, `vistas`, `percurso`. |
| Fonte | `id`, `titulo`, `localizador` (caminho, URL, seção ou descrição de insumo), `edicao`, `alcance`. Localizador é exibido como texto e não recebe consulta automática. |
| Nó | `id`, `nome`, `tipo`, `papel`, `detalhe`, `arquitetura`, `afirmacao`, `fontes` (IDs), `evidencia`. |
| Relação | `id`, `origem`, `destino`, `verbo`, `objeto`, `natureza`, `arquitetura`, `afirmacao`, `fontes`, `evidencia`, `meio`, `inicio`, `autoridade`, `registro`, `falha`, `confirmacao`. |
| Vista | `id`, `nome`, `pergunta`, `nota`, `posicoes` (mapa ID do nó → [x,y]), `grupos`, `arestas`. Padrão de 1100 × 640, nós 220 × 96; o perfil IPO permite geometria explícita. |
| Grupo da vista | `id`, `nome`, `nos` (IDs). O retângulo envolve os nós listados, calculado pelo gerador. Evite grupos sobrepostos; pertencimento não usa seta. |
| Aresta da vista | `relacao` (ID), `pontos` ([[x,y],…], mínimo 2), `rotulo` ([x,y]). A mesma relação pode ter traçado diferente em cada vista. |
| Percurso | `id`, `titulo`, `inicio`, `resultado`, `etapas`. |
| Etapa | `id`, `titulo`, `vista`, `relacao`, `entrada`, `transformacao`, `saida`, `excecao`. Cada relação escolhida deve aparecer naquela vista. |

`tipo` é texto curto, como agente, pessoa, orientação, conhecimento, documento, Skill, ferramenta, registro, entrega ou lacuna. Ícone não é exigido. A palavra precisa explicar o papel sem jargão.

`arquitetura`: atual, proposta, permanece, entra, sai ou muda. Diz a condição do objeto no desenho.

`afirmacao`: observado, documentado, declarado, inferido, proposto, decidido, não observado ou conflito. Diz a sustentação daquela afirmação. Observado pede evidência da observação; decidido pede autoridade e origem da decisão. O script verifica preenchimento, não julga a veracidade.

`natureza`: informacao, conhecimento, dependencia, controle ou retorno. Define o sentido da relação; proposta recebe tracejado por sua condição arquitetural ou afirmação. Proposta e tipo de relação são eixos diferentes.

## Julgamento antes de preencher

Orientação dá critérios; fonte do caso dá os fatos que esses critérios interpretam; Skill organiza transformação; ferramenta permite ler ou agir; Estado preserva a condição para retomar. A mesma peça pode reunir mais de uma função, desde que o texto as distinga. Não crie componente por arquivo apenas para completar uma lista.

Em `meio`, escreva como a relação ocorre. Em `inicio`, quem ou o que começa a operação. Em `autoridade`, que ordem cobre qual efeito. Em `registro`, onde o resultado persiste. Em `falha`, o que interrompe ou muda a passagem. Em `confirmacao`, qual evidência mostraria que ocorreu. Para relações de conhecimento, explique recuperação e aplicação; não invente um conector.

Relação de consulta aponta de quem consulta para a fonte; relação de fornecimento aponta da fonte para quem recebe. A direção precisa corresponder ao verbo. Registro em fila e leitura pelo destinatário são duas relações; chamada direta é uma terceira capacidade, que não se deduz das duas primeiras.

## Layout e leitura

Cada vista responde uma pergunta. Use de três a sete protagonistas e rótulos curtos junto às linhas; o detalhe completo permanece fora do SVG. Posicione o eixo principal da esquerda para a direita; reserve as faixas superior e inferior para contribuições e retornos. Não desenhe seta que atravessa um nó ou rótulo. O validador controla limites e referências; a inspeção visual confere cruzamentos e legibilidade.

O mesmo ID de agente em duas vistas permite destaque coordenado. Não duplique o nó para mudar seu nome em outra vista. Caso duas instâncias ou configurações sejam diferentes, use IDs distintos e explique a relação.

A seleção de uma etapa leva explicitamente à vista correspondente e destaca uma relação. Não é uma execução nem animação automática: cada etapa explica entrada, transformação, saída e exceção. Use etapas de retorno e recuperação quando mudarem o trabalho. Uma lacuna pode ficar apenas na lista textual com sua pergunta aberta; não lhe invente posição ou conexão.

## Futuro, evidência e neutralidade

Uma proposta declara pressupostos, alternativa relevante e o que poderia torná-la inadequada em `limites` ou nos detalhes. Não marque como atual tudo que aparece num arquivo de desenho. Conteúdo fornecido, conteúdo recebido pela IA, operação e resultado são níveis de prova distintos.

Em cenário fictício, identifique fonte de cenário e marque nós e relações como propostos. Essa fonte sustenta a coerência do exemplo, sem provar recurso da plataforma ou autorização do usuário. Exemplos distribuídos não carregam nomes, IDs de conta, demandas ou fontes privadas da autoria.

## Limite técnico desta edição

O contrato privilegia duas vistas pequenas e percurso. Não inclui execução, edição de sistema, chamada de outros projetos, importação de mídia, layout automático, comparação visual de alternativas ou verificação semântica por software. Para mais escala, separe vistas e conserve os IDs. A adaptação do modelo canônico de arquitetura é local ao produto; não muda o método institucional.



## Extensão IPO — candidata 0.2.0

Sem mudar os campos anteriores, o modelo pode acrescentar:

- Raiz `ipo`: `ciclo` (operacao ou construcao), `entradas`, `transformacoes`, `saidas` como listas de IDs. Os papéis são separados. Saída precisa de modelo de entrega.
- Raiz `rotas_entrega`: lista de `entrega`, `vista`, `relacoes`. Cada percurso é declarado e conferido na vista; não é uma busca de vizinhança que acende o sistema inteiro.
- Nó `icone`: ID do catálogo local ou símbolo `v-*`; `linha`: explicação operacional curta; `preparo`: disponivel, preparar ou opcional; `necessidade`: o que a pessoa precisa disponibilizar ou conferir; `canal` e `operacao`: veículo e capacidade necessária.
- Nó de saída `modelo_entrega`: `para_que`, `destinatario`, `formato`, `destino`, `aceitacao`, `template`. O exemplo fornece conteúdo adaptável, além do nome do arquivo.
- Vista `canvas`: [largura,altura]; `tamanhos`: ID → [largura,altura]; `rotulos`: [{x,y,texto}]. As dimensões e referências são conferidas; a inspeção visual continua necessária.

Preparo e sustentação são eixos distintos: 'disponível' exige evidência da instância; 'documentado' pode descrever algo ainda a preparar. O exemplo fictício usa apenas a preparar/proposto. Conector opcional não vira requisito quando a pessoa pode fornecer o mesmo conteúdo.

Selecionar uma saída ativa a vista declarada em sua rota e torna o mapa visível. Ao fechar o detalhe, o foco retorna ao controle correspondente nessa vista; isso mantém a referência utilizável quando a seleção começou numa representação que ficou oculta. A conferência de referências não julga se o autor incluiu uma relação sem pertinência: isso exige leitura semântica.