Arquitectura

Esta tradução pode estar atrás da página inglesa, que mudou depois de ser traduzida. Ler a página em inglês

Estrutura do projecto

Antes de leres: Clonar, compilar e testar — tens uma checkout que compila, e sabes que gates existem.

Esta página é o mapa do repositório: o que é cada ficheiro e directório de topo, quem o muda e quando, e que partes são geradas e nunca devem ser editadas à mão. Lê-a depois de Clonar, compilar e testar e antes de Arquitectura — a arquitectura explica porque o código está dividido dessa forma; esta página diz-te onde as coisas estão. Depois dela consegues colocar qualquer caminho do repositório, dizer quem o muda, e saber se o podes editar à mão ou se tens de o regenerar.

Um gate de CI mantém-na honesta: python3 scripts/dev_docs.py --check falha quando um caminho de topo acompanhado (ou um directório de segundo nível de crates/, bins/ ou docs/) falta nas tabelas abaixo, ou quando uma tabela nomeia um caminho que já não existe.

Ler o repositório em cinco minutos#

Começa na raiz e segue as dependências para dentro:

Cargo.toml — o workspace: todo crate membro, e toda versão de dependência (os membros só escrevem { workspace = true }).
bins/delonix-runtime-bin/src/main.rs — a CLI delonix. Cada grupo de comandos é um módulo debaixo de src/cmd/; segue o grupo que te interessa.
crates/<camada>/<crate>/src/lib.rs — o motor. O directório é a camada (foundation → contexts → adapters / providers → interfaces), e todo lib.rs abre com um comentário //! a dizer o que o crate faz. Os crates tem uma secção por crate.
docs/dev/ — este manual. docs/adr/ — as decisões por trás da estrutura.

O AGENTS.md é o diário de trabalho longo, em português, do projecto. É útil para descobrir onde procurar, mas partes dele estão desactualizadas; confirma no código o que ele diz.

Árvore anotada#

text

.
├── Cargo.toml, Cargo.lock        workspace members, shared dependency versions, lock file
├── rust-toolchain.toml           pinned Rust toolchain (clippy + rustfmt)
├── buf.yaml                      buf modules/lint for the node contract in proto/
├── deny.toml                     cargo-deny policy (advisories, licences, sources)
├── Makefile, Delonixfile         release binaries and the secondary CLI image
├── AGENTS.md                     project journal and agent rules (Portuguese)
├── ARCHITECTURE.md               C4 model of the engine (Portuguese)
├── README.rst, CONTRIBUTING.md   user entry point, contributor entry point
├── GOVERNANCE.md, MAINTAINERS.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE
├── .clinerules, .cursorrules     pointers to AGENTS.md for AI coding tools
├── .dockerignore, .gitignore, .git-blame-ignore-revs
├── .ai/                          skills for AI assistants (E2E quality)
├── .github/                      CI and release workflows, CODEOWNERS, issue/PR templates
├── crates/
│   ├── foundation/               pure shared types and rules (no mechanism)
│   ├── contexts/                 Compute, Stack, security decisions
│   ├── adapters/                 Linux, OCI, SDN, VM, volumes, state, scanner, telemetry
│   ├── providers/                remote systems behind ports (Proxmox VE, TrueNAS)
│   └── interfaces/               CRI, local management API, node API, MCP server
├── bins/
│   ├── delonix-runtime-bin/      the `delonix` CLI (+ templates, pt.po catalogue)
│   ├── delonix-mgmt-bin/         the `delonix-mgmt` binary
│   ├── delonix-node-api-bin/     the `delonix-node-api` binary
│   └── delonix-mcp-bin/          the `delonix-mcp` binary
├── proto/                        node contract delonix.node.v1 (draft, ADR-0040)
├── third_party/                  vendored googleapis protos (Apache-2.0)
├── tests/                        out-of-tree compatibility scripts (CRI, Docker API)
├── docs/
│   ├── adr/                      Architecture Decision Records
│   ├── api/                      OpenAPI — generated from proto/
│   ├── comandos/                 per-command user pages — generated by docs/gen.py
│   ├── dev/                      this handbook (English + translations)
│   ├── discovery/                dated investigations (historical)
│   ├── handbook/                 this handbook as HTML — generated
│   ├── releases/                 release notes, one per version (historical)
│   ├── roadmap/                  improvement-programme traceability matrix
│   ├── runtime/                  dated runtime discovery (historical)
│   └── schema/                   manifest JSON Schema — generated from code
├── scripts/                      CI gates, generators, E2E/chaos harnesses, installer
├── examples/                     manifests validated by CI
├── images/                       one folder per VM image: a `vm.yaml` recipe and a README
├── dist/                         systemd unit for delonix-cri
├── editors/                      VMfile syntax for Vim and VS Code
└── reports/                      dated audit reports (historical)

Ficheiros de topo#

Caminho	O que é	Quem o muda / quando	Ler mais
`Cargo.toml`	Raiz do workspace: a lista de membros, `[workspace.package]`, `[workspace.dependencies]` (todo caminho de crate e toda versão externa) e `[workspace.lints.clippy]`. A sua `version` é a tag publicada.	Quem acrescenta um crate ou dependência; a `version` muda só num commit de release (`scripts/version_gate.py`).	Convenções de código, Fluxo de contribuição
`Cargo.lock`	Grafo de dependências resolvido para o workspace inteiro; os builds usam `--locked`.	Actualizado pelo cargo quando as dependências mudam; faz commit dele com essa mudança.	Clonar, compilar e testar
`rust-toolchain.toml`	Fixa o canal de Rust com `rustfmt` e `clippy`, para o dev e a CI compilarem com o mesmo compilador.	Mantenedores, num commit dedicado.	Preparar o teu ambiente
`buf.yaml`	Configuração do `buf` v2: o módulo `proto/` (verificado) e o módulo vendorizado `third_party/googleapis` (não verificado), com as excepções de lint escritas.	Quem mudar as regras do contrato de nó.	`docs/adr/0040-engine-restructuring-layers-ports-node-contract.md`
`deny.toml`	Política do `cargo-deny`: avisos (cada um ignorado com uma razão), licenças, fontes. Corrido pelo job de CI `cargo-deny`.	Quem acrescentar uma dependência que o dispara — com justificação escrita.	Clonar, compilar e testar
`Makefile`	Alvos de conveniência: `binaries` (release do `delonix` + `delonix-cri`, o artefacto principal), `image`, `ghcr-push`, `bench`, `coverage`.	Mantenedores.	Clonar, compilar e testar
`Delonixfile`	Build multi-stage da imagem de container secundária da CLI (constrói `delonix` + `delonix-cri` a partir do código-fonte).	Mantenedores, quando o build da imagem muda.	Delonixfile e VMfile
`.dockerignore`	Mantém `target/`, `dist/` e `.git` fora do contexto de build do `Delonixfile`.	Raramente.	—
`.gitignore`	Ignora `target/`, `__pycache__/` e ficheiros locais de ferramentas de agente.	Raramente.	—
`.git-blame-ignore-revs`	Commits que o `git blame` deve saltar (a corrida de `rustfmt` em todo o workspace). Activa-se com `git config blame.ignoreRevsFile .git-blame-ignore-revs`.	Quem fizer um commit de reformatação em massa.	—
`AGENTS.md`	Diário do projecto e regras de agente, em português: a identidade e fronteira do motor (canónica), os gates, e um histórico longo por funcionalidade. Algumas secções estão desactualizadas.	Mantenedores e contribuidores que registam decisões e achados; conflitos resolvem-se mantendo os dois lados.	Começa aqui
`ARCHITECTURE.md`	Modelo C4 (contexto, containers, componentes) e desenho funcional do sistema, em português, renderizado no site do utilizador.	Escrito à mão, mantido em sincronia com o código em mudanças estruturais.	Arquitectura
`README.rst`	O ponto de entrada visível ao utilizador: o que é o Delonix, instalação, primeiros comandos.	Mudado com funcionalidades visíveis ao utilizador e releases.	Publicar a documentação
`CONTRIBUTING.md`	Porta de entrada curta do contribuidor que aponta para `docs/dev/`.	Mantenedores do manual.	Fluxo de contribuição
`GOVERNANCE.md`	Como as decisões são tomadas (modelo de um só mantenedor, ADRs para decisões estruturais).	Mantenedores.	`docs/adr/README.md`
`MAINTAINERS.md`	Quem mantém que área (um mantenedor hoje).	Mantenedores.	`GOVERNANCE.md`
`CODE_OF_CONDUCT.md`	Contributor Covenant.	Mantenedores.	—
`SECURITY.md`	Como relatar uma vulnerabilidade em privado (GitHub Private Vulnerability Reporting).	Mantenedores.	`docs/SECURITY-RELEASES.md`
`LICENSE`	Licença Apache-2.0 do projecto.	Nunca, na prática.	—
`.clinerules`	Ficheiro apontador para o assistente Cline: "as regras estão em `AGENTS.md`". A sua contagem de crates está desactualizada; o `AGENTS.md` e Os crates são autoritativos.	Raramente.	—
`.cursorrules`	O mesmo apontador, para o Cursor.	Raramente.	—

Código-fonte (crates/, bins/, proto/, tests/)#

A lista de crates, a camada de cada um e quem depende de quem são factos gerados em Arquitectura e Os crates; não são repetidos aqui.

Caminho	O que é	Quem o muda / quando	Ler mais
`crates/`	Todos os crates de biblioteca, um directório por camada (ADR-0040). O `scripts/arch_fitness.py` recusa um crate cujo directório não é a camada declarada na sua tabela `LAYERS`, e qualquer dependência contra a direcção permitida.	Toda funcionalidade do motor.	Arquitectura
`crates/foundation/`	Fundação pura: o modelo só-de-dados — erros, registos de dados simples (`Status`, os registos de firewall), o modelo de segredos, nomes gerados, as classes de código de saída e `DX_*` (`delonix-model`), e regras de rede sem dependências (`delonix-net-rules`). Só depende da fundação.	Mudanças que acrescentam um tipo partilhado ou uma regra pura.	Os crates
`crates/contexts/`	Contextos delimitados com os casos de uso: Compute, com os registos `Container` e `Vm` (`delonix-compute`), os próprios helpers do nó — registo de eventos, verificações de host e processo, despacho de servidor (`delonix-node`) —, Stack — Kinds, reconciliador, revisões (`delonix-stack`) — e as decisões de segurança do nó (`delonix-security-runtime`).	Funcionalidades que mudam o que o motor decide.	Os crates
`crates/adapters/`	Mecanismos neste nó: namespaces/cgroups de Linux (`delonix-linux`), imagens OCI (`delonix-oci`), rede e firewall (`delonix-sdn`), microVMs (`delonix-vm`), volumes (`delonix-volume`), estado persistido e o cofre de segredos (`delonix-state`), varredura de vulnerabilidades (`delonix-scanner`), logging/métricas/tracing (`delonix-telemetry`).	Funcionalidades que tocam no kernel, no disco ou numa ferramenta local.	Os crates, Introdução ao cloud native
`crates/providers/`	Sistemas remotos atrás de uma porta: um nó Proxmox VE como `VmBackend` (`delonix-proxmox`) e o provisionamento TrueNAS (`delonix-truenas`).	Mudanças a uma integração de provider; um provider novo entra aqui como implementação de uma porta.	`docs/adr/0008-proxmox-vm-backend.md`
`crates/interfaces/`	Servidores que expõem o motor: o CRI do Kubernetes (`delonix-cri`, que também produz o binário `delonix-cri`), a API de gestão local (`delonix-mgmt`), o servidor do contrato de nó (`delonix-node-api`) e o servidor MCP (`delonix-mcp`).	Mudanças a um desses protocolos.	Padrões cloud native
`bins/`	Crates de binário. Cada um compõe uma interface (imposto por `arch_fitness.py`).	Toda funcionalidade visível na CLI.	Arquitectura
`bins/delonix-runtime-bin/`	A CLI `delonix`: `src/main.rs`, um módulo por grupo de comandos em `src/cmd/`, o catálogo de mensagens em português `data/pt.po`, os templates do projecto `init` em `templates/`, `build.rs`, e `tests/architecture.rs`.	Toda funcionalidade com um comando, flag ou mensagem.	Convenções de código
`bins/delonix-mgmt-bin/`	O binário `delonix-mgmt`: um `main.rs` fino sobre o `delonix-mgmt`.	Raramente; a lógica vive no crate de interface.	Os crates
`bins/delonix-node-api-bin/`	O binário `delonix-node-api`: um `main.rs` fino sobre o `delonix-node-api` (o contrato de nó num socket unix, ADR-0040 P5).	Raramente; a lógica vive no crate de interface.	`docs/adr/0050-libvirt-linux-providers-capability-catalog.md`
`bins/delonix-mcp-bin/`	O binário `delonix-mcp`: um `main.rs` fino sobre o `delonix-mcp`.	Raramente; a lógica vive no crate de interface.	`docs/adr/0025-mcp-local-ai-control-surface.md`
`proto/`	O contrato de nó `delonix.node.v1` (`proto/delonix/node/v1/*.proto`), marcado como rascunho; fonte de verdade para o gRPC e HTTP/JSON e para o `docs/api/openapi.yaml`. Verificado por `scripts/contract_gate.py` (formato, lint, mudanças que quebram, mapeamentos HTTP, OpenAPI).	Mudanças ao contrato, revistas com cuidado — mudanças que quebram contra a última tag falham.	`proto/README.md`, ADR-0040
`tests/`	Verificações de compatibilidade fora da árvore cargo, não testes cargo: `tests/compat/cri-conformance.sh` (a suite `critest`) e `tests/compat/docker_api_smoke.py`. Os testes de integração cargo vivem no próprio `tests/` de cada crate.	Quem trabalha em compatibilidade com o CRI ou a API Docker.	`docs/cri-conformance.md`, Clonar, compilar e testar
`fuzz/`	Alvos `cargo-fuzz` sobre parsers escritos à mão alimentados com input não confiável (um `Dockerfile` de um repo clonado, uma string de referência de imagem). Tem o seu próprio `[workspace]`, para as flags de build do sanitizer nunca tocarem no principal; o job de CI `fuzz` corre cada alvo por 60s a cada push/PR.	Quem acrescentar um parser escrito à mão para input controlado externamente.	M04 de `docs/roadmap/13-improvements-traceability.md`

Documentação (docs/…)#

O docs/ é também a raiz do GitHub Pages. Os seus ficheiros de topo são uma mistura: as páginas HTML (index.html, cheatsheet.html, estrutura.html, …) e o .nojekyll são gerados pelo docs/gen.py; o próprio gen.py e Markdown como cli-stability.md, gitops.md, estrutura.md, guia-vm-lab.md são fontes escritas à mão que ele renderiza; o RELEASES.md é gerado por scripts/gen-releases.sh; e relatórios datados (AUDITORIA-E2E.md, RELATORIO-PRE-PRODUCAO.md, paridade-docker-podman.md, comparacao-medida.md, sovereignty-engine.md) registam o que foi medido numa determinada data.

Caminho	O que é	Quem o muda / quando	Ler mais
`docs/`	Raiz da documentação e site do utilizador (ver o parágrafo acima).	Mudanças visíveis ao utilizador regeneram o site com `python3 docs/gen.py`; a CI falha se o `docs/` em commit diferir do regenerado.	Publicar a documentação
`docs/adr/`	Architecture Decision Records, `NNNN-title.md`, com um índice em `docs/adr/README.md`. ADRs aceites nunca são reescritos — um ADR novo sucede-os.	Um contribuidor a propor uma decisão estrutural.	`docs/adr/README.md`, Fluxo de contribuição
`docs/api/`	`openapi.yaml`, gerado a partir de `proto/` pelo `protoc-gen-openapi`. Nunca o edites.	`python3 scripts/contract_gate.py --update` depois de uma mudança em `proto/`.	`proto/README.md`
`docs/comandos/`	Uma página HTML por grupo de comandos da CLI, gerada por `docs/gen.py` a partir do `--help` real do binário de release mais texto editorial no gerador.	Nunca à mão: edita `docs/gen.py`, reconstrói o binário, regenera.	Publicar a documentação
`docs/dev/`	Este manual do contribuidor: fonte Markdown em inglês, com traduções `pt-AO/` e `fr-FR/` que levam um hash `translated-from`. As regiões entre os marcadores `dev-docs:begin`/`dev-docs:end` são geradas por `scripts/dev_docs.py`; o resto é escrito à mão.	Mantenedores do manual; as regiões geradas acompanham o código e são actualizadas no momento da release.	Publicar a documentação
`docs/providers/`	`capability-matrix.md`, a matriz DECLARADA de capacidades dos providers (ADR-0050), gerada por `delonix provider matrix`; um teste no `delonix-runtime-bin` falha quando difere do output.	`delonix provider matrix > docs/providers/capability-matrix.md` depois de uma declaração mudar.	`docs/adr/0050-libvirt-linux-providers-capability-catalog.md`
`docs/discovery/`	Investigações e planos numerados e datados (inventários, spikes com os seus ficheiros de resultado crus). Registos históricos — não reescrever; escrever um novo.	Quem corre uma investigação antes de uma mudança estrutural.	`docs/adr/`
`docs/handbook/`	Este manual como um site (`en/`, `pt-AO/`, `fr-FR/`, `zh-CN/`, `index.html`), gerado por `scripts/dev_docs_site.py` a partir de `docs/dev/`. Nunca edites o HTML.	Regenerado com `python3 scripts/dev_docs_site.py` depois de uma mudança em `docs/dev/`, e no momento da release.	Publicar a documentação
`docs/proxmox/`	A matriz de cobertura da API do Proxmox VE (ADR-0049): `api-<ver>.routes.json`, o schema de uma release nomeada extraído do `apidoc.js` de um nó com a sua proveniência (data de obtenção, sha256), e `matrix-<ver>.md`, gerada a partir dele e das rotas que o crate do provider chama. Nunca editar a matriz.	`python3 scripts/proxmox_api_inventory.py docs/proxmox/api-9.2.2.routes.json --markdown > docs/proxmox/matrix-9.2.2.md` depois de uma rota ser acrescentada ao `delonix-proxmox`; o schema só quando uma release nova é medida.	`docs/adr/0049-proxmox-api-coverage-measured-matrix-not-a-cluster-proxy.md`
`docs/releases/`	Notas de release, um `v<versão>.md` por release. Um commit de release tem de acrescentar a sua própria (`version_gate.py`). Histórico — não reescrever notas passadas.	O commit de release.	Fluxo de contribuição
`docs/roadmap/`	Matriz de rastreabilidade de um programa de melhoria, onde toda célula cita uma medição ou diz "não medido".	Mantenedores, à medida que itens são medidos ou fechados.	—
`docs/runtime/`	Descoberta datada do runtime (estado actual, mapa de dependências de crates, alvo-vs-realidade). Histórico: os nomes de crate lá dentro são anteriores a renomeações posteriores.	Não actualizado; sucedido por Arquitectura e Os crates.	Arquitectura
`docs/schema/`	`v1/delonix.json`, o JSON Schema do manifesto, gerado a partir do código (ADR-0007).	`delonix manifest schema > docs/schema/v1/delonix.json` quando um tipo de manifesto muda.	`docs/adr/0007-generated-manifest-schema.md`

Ferramentas, CI e empacotamento (scripts/, .github/, dist/, editors/, examples/, reports/, third_party/, .ai/)#

Caminho	O que é	Quem o muda / quando	Ler mais
`scripts/`	Gates (`arch_fitness.py`, `lang_ratchet.py`, `contract_gate.py`, `version_gate.py`, `docs_cli_gate.py`, `cli-tree.sh`, `dev_docs.py`) com as suas linhas de base (`arch_baseline.json`, `lang_baseline.json`, `cli_baseline.tsv`), geradores (`dev_docs_site.py`, `gen-releases.sh`, `sbom.py`), arneses (`e2e.sh`, `chaos.sh`, `critest.sh`, `bench.sh`, `coverage.sh`), o instalador `install.sh`, builds de imagens de appliance em `appliances/`, e sondas de spike em `spikes/`.	Quem tiver uma mudança que mexa num ratchet (baixa a linha de base no mesmo commit); mantenedores para o resto.	Clonar, compilar e testar
`.github/`	`workflows/ci.yml` (todo gate no push e PR para `main`), `chaos.yml` (arnês de caos), `release.yml` (manual, `gh workflow run release.yml -f tag=vX.Y.Z`), `vm-image.yml` e `vm-appliances.yml` (publicação manual de imagens), mais `CODEOWNERS`, templates de issue e PR e um ficheiro apontador para o GitHub Copilot.	Mantenedores; um gate novo é acrescentado aqui e documentado no manual.	Clonar, compilar e testar, Publicar a documentação
`dist/`	`delonix-cri.service`, a unit systemd do servidor CRI (também embutida no binário).	Quem mudar como o `delonix-cri` corre sob o systemd.	Padrões cloud native
`editors/`	Realce de sintaxe do VMfile: `vim/` (ftdetect + syntax) e `vscode/` (configuração de língua + gramática TextMate).	Quem mudar a gramática do VMfile.	Delonixfile e VMfile
`examples/`	Manifestos de exemplo por Kind, um laboratório de rede multi-ficheiro (`lab-rede/`) e um pequeno projecto completo (`delonix-temp/`). O job `docs` da CI faz dry-run de todo `examples/*.yaml`, por isso um exemplo obsoleto ou partido faz o build falhar.	Toda funcionalidade que acrescenta ou muda um Kind.	Delonixfile e VMfile
`images/`	Uma pasta por imagem de VM: `ubuntu`, `debian`, `rocky`, `fedora` (receitas próprias que constroem offline) e oito appliances (`opnsense`, `proxmox`, `truenas`, `openstack`, `monitoring`, `carbonio`, `glpi`, `wazuh`) cujo `vm.yaml` nomeia um builder em `scripts/appliances/`. Cada uma tem um README; o `images/README.md` indexa-as e explica o `scripts/verify-images.sh`. Um teste unitário (`vmspec::every_shipped_recipe_is_valid_and_complete`) falha se uma receita deixar de ser lida ou apontar para um ficheiro ou builder em falta.	Quem acrescenta uma distro ou um appliance, ou muda o schema do `vm.yaml`.	Delonixfile e VMfile
`reports/`	Relatórios de auditoria datados: `code-quality/` e `production-readiness/<versão>/` (inventário, matriz de lacunas, backlog). Registos históricos de uma auditoria num commit — não reescrever; nada neles se torna implementado por estar listado.	Quem correr uma auditoria nova (ficheiros novos).	—
`third_party/`	Protos `googleapis` vendorizados (`google/api/annotations.proto`, `http.proto`) usados para o mapeamento HTTP do contrato de nó. Apache-2.0, cabeçalhos de licença mantidos; o commit de origem está registado no seu `README.md`. Nunca editado aqui.	Quem actualizar os protos vendorizados, os dois ficheiros de um mesmo commit upstream.	`third_party/googleapis/README.md`
`.ai/`	Skills neutras de ferramenta para assistentes de IA: `skills/delonix-runtime-e2e-quality/` (taxonomia de testes, contrato de provider, verificações de segurança, modelos de relatório).	Mantenedores.	—

Gerado vs escrito à mão#

Tudo abaixo é produzido por um comando. Edita a fonte, corre o gerador, faz commit dos dois — e espera que a CI falhe se editares a saída à mão.

Caminho	Ficheiro(s) gerado(s)	Comando gerador	Gate de CI que verifica
`docs/api/`	`openapi.yaml`	`python3 scripts/contract_gate.py --update`	job `contract gate` (`scripts/contract_gate.py`)
`docs/schema/`	`v1/delonix.json`	`delonix manifest schema > docs/schema/v1/delonix.json`	job `test`, teste `o_schema_publicado_esta_em_dia_com_o_codigo` em `bins/delonix-runtime-bin/src/cmd/schema.rs`
`docs/comandos/`	toda página	`python3 docs/gen.py` (precisa de `cargo build --release -p delonix-runtime-bin`)	job `generated docs and valid examples`, passo "O site publicado tem de ser o gerado" (`git diff` em `docs/`)
`docs/`	`*.html` de topo, `.nojekyll`	`python3 docs/gen.py`	o mesmo passo acima
`docs/`	`RELEASES.md`	`bash scripts/gen-releases.sh`	nenhum na CI: o `release.yml` regenera-o e faz commit dele depois de cada release
`docs/dev/`	só as regiões `dev-docs`	`python3 scripts/dev_docs.py`	job `arch fitness`, passo `python3 scripts/dev_docs.py --check`; também actualizado pelo `release.yml`
`docs/proxmox/`	`matrix-9.2.2.md`	`python3 scripts/proxmox_api_inventory.py docs/proxmox/api-9.2.2.routes.json --markdown > docs/proxmox/matrix-9.2.2.md`	job `script tests`, `scripts/test_proxmox_api_inventory.py` (`test_the_committed_matrix_is_up_to_date`)
`docs/handbook/`	toda página	`python3 scripts/dev_docs_site.py`	job `generated docs and valid examples`, `python3 scripts/dev_docs_site.py --check`; também actualizado pelo `release.yml`
`scripts/`	`cli_baseline.tsv`, `arch_baseline.json`, `lang_baseline.json`	`scripts/cli-tree.sh --update`, `arch_fitness.py --update`, `lang_ratchet.py --update`	jobs `cli surface` (`cli-tree.sh --gate`), `arch fitness`, `lang ratchet`
`Cargo.lock`	o ficheiro de lock	`cargo`	todo job cargo compila com `--locked`

Nada disto é feito commit: as man pages (delonix man --dir, verificadas com groff na CI) e o target/.

Onde vai um ficheiro novo?#

Um tipo ou regra que qualquer camada pode nomear, sem I/O → crates/foundation/. A matemática de rede pura vai para delonix-net-rules; os registos só-de-dados e os nomes vão para delonix-model.
Uma decisão ou caso de uso (o que correr, o que um Kind significa, um plano) → crates/contexts/.
Código que chama o kernel, o disco ou uma ferramenta local (ip, nft, qemu-img) → crates/adapters/, no crate que possui esse mecanismo.
Uma integração com um sistema remoto → uma implementação de porta nova em crates/providers/, nunca um if provider == … em código já existente.
Um servidor de protocolo novo → crates/interfaces/, composto por exactamente um binário em bins/.
Um comando ou flag da CLI → um módulo em bins/delonix-runtime-bin/src/cmd/, com a sua tradução em português em data/pt.po.
Um crate novo → o directório da sua camada e a tabela LAYERS em scripts/arch_fitness.py e [workspace.dependencies] no Cargo.toml, no mesmo commit.
Um manifesto de exemplo → examples/ (a CI faz dry-run dele). Uma decisão estrutural → docs/adr/. Documentação para contribuidores → docs/dev/.

As regras por trás desta lista, com exemplos, estão em Convenções de código — Estrutura: onde vai o código e Os crates.

Seguinte: Arquitectura — porque é que o código está dividido assim: as camadas, os processos em runtime, o grafo de crates e o estado em disco.

Editar esta páginadocs/dev/pt-AO/project-structure.md