Framework e Blueprint

	Framework (a estrutura)	Blueprint (o plano)
O que é	A forma	Uma unidade, definida por completo
Feito de	Pastas, templates (modelos), propriedades, vocabulary (vocabulário), papéis	Um arquivo markdown: propriedades em cima, corpo embaixo
Vive em	`.eidos/`, escondido na raiz	Uma pasta de coleção
Portátil?	Sim: a peça que um time entrega a outro	Não: é o seu produto

A raiz

A raiz é a pasta em que tudo vive. Pode ter qualquer nome (Blueprints/ é o padrão) porque é encontrada pelo .eidos/ escondido dentro dela, nunca pelo nome. Várias raízes podem viver em um mesmo repositório.

DirectoryBlueprints/ a raiz
- README.md um documento de nível superior: a porta de entrada
- Directory.eidos/ o Framework
  - …
- Directoryassets/ pasta de assets: imagens e documentos que os Blueprints linkam
  - …
- Directoryframes/ uma coleção: o que é o produto inteiro
  - architecture.md
- Directoryspecs/ uma coleção, agrupada
  - Directoryplayback/ um grupo declarado; um nível, nada mais fundo
    resume-playback.md um Blueprint por arquivo
- vision.md outro documento de nível superior

Tudo na raiz é declarado. Uma pasta é .eidos/ ou é declarada sob folders com quem a possui. owned_by: "@eidos/collections" é uma coleção (Blueprints, opcionalmente em grupos), e é o único tipo que o padrão possui; owned_by: "@<tool>/<kind>" é a pasta de uma ferramenta (o identificador único da ferramenta, depois o nome próprio dela para o que a pasta contém), e o que ela contém, como é nomeada e o que é verificado dentro é essa ferramenta quem diz; sem owned_by é uma pasta sua, descrita e deixada em paz. Um arquivo é listado sob top_level. Qualquer outra coisa é trazida à tona, e o dono a declara ou a move. Entradas escondidas como .git são isentas.

Uma pasta é do seu dono. As regras do padrão sobre variants (variantes), agrupamento, templates, indexação e nomes alcançam @eidos/collections e nada além. Nada dentro de uma pasta que ele não possui é lido. Uma verificação aponta um dono malformado ou um tipo @eidos/ que o padrão não nomeia, e nunca o de uma ferramenta, conhecida ou não. Uma ferramenta reivindica as suas pastas na própria release; ninguém inventa um dono em nome dela.

O Framework

.eidos/ é escondido do jeito que .git e .obsidian/ são: presente, fora do caminho, e confortável ao lado deles em um vault.

Directory.eidos/
- Framework.yaml o documento do Framework
- Directorytemplates/ um arquivo por variant
  - spec.full.md
  - spec.micro.md
  - frame.architecture.md
- Directoryroles/ como um agente fala com cada tipo de pessoa
  - developer.md um arquivo por tipo de pessoa
- Directoryplugins/ uma pasta por ferramenta
  - Directoryeidosmd/ a própria da CLI
    local.yaml configurações locais (ignorado pelo git)
    Directorylocal/ arquivos locais (ignorado pelo git)
    …
- me.md quem está na cadeira (local, ignorado pelo git)
- .gitignore ignora me.md, plugins//local.yaml e plugins//local/

O nível superior de .eidos/ é do padrão. Uma ferramenta guarda o que precisa sob plugins/<name>/ e não toca em mais nada. Plugins →

`Framework.yaml`

Um por raiz: a estrutura como dados, com comentários onde você quiser.

eidos_version: 5.5.0
naming: kebab-case            # kebab-case | TitleCase | Title Case
top_level:                    # every file at the root
  - { title: README, path: ../README.md, description: the front door. }
folders:                      # every folder at the root, each with its owner
  - name: specs
    owned_by: "@eidos/collections"
    description: The product's units, one per blueprint, grouped by domain.
    variants:
      - { name: full, template: templates/spec.full.md, description: the complete spec, default: true }
      - { name: micro, template: templates/spec.micro.md, description: "Intent, Open Questions, ACs, Out of Scope" }
    grouping:
      label: Domains
      property: domain
      groups: []
  - { name: exports, owned_by: "@acme/exports", description: What the exporter writes; the exporter keeps it. }
  - { name: assets, description: Images and documents the blueprints link to. }
properties:
  core: []                    # the standard's four; rewritten by migrate
  custom:
    - { name: status, type: Text, applies_to: all, options: [Draft, Done], meaning: Lifecycle stage. }
    - { name: domain, type: Text, applies_to: [specs], required: true, meaning: The group. }
vocabulary: []                # the root's own terms
index: {}                     # generated by `eidos index`; never hand-edited

top_level: todo arquivo na raiz, na ordem em que são lidos. Um README, quando a raiz tem um, é listado como qualquer outro.
folders: toda pasta na raiz, com owned_by quando algo a possui (entre aspas, já que @ não pode começar um valor YAML sem aspas). Uma coleção também declara as suas variants (default: true na que um Blueprint novo usa; sem nenhuma marcada, não tem padrão) e o seu agrupamento, onde um grupo pode nomear a sua própria padrão com default_variant.
properties: o contrato de propriedades, um bloco por dono: core (as do padrão), custom (as suas), tools.<tool> (as de uma ferramenta). Propriedades →
vocabulary: as palavras com que o produto é descrito de propósito. Começa vazio.
index: os Blueprints de cada coleção, cada um com o seu id, title, summary, path e group. Reconstruído por inteiro pelo eidos index, que não toca em nenhuma outra chave. Um Blueprint sem summary é listado sem ele e sinalizado, nunca inventado. A única visão derivada que o padrão define; qualquer outra visão é de uma ferramenta.

Regiões

Uma ferramenta que guarda algo dentro de um arquivo markdown o escreve em uma região: um trecho entre dois comentários HTML que carregam o nome da ferramenta, cada um sozinho na sua linha.

<!-- eidosmd:backlinks -->
- [Session Management](../identity/session-management.md)
<!-- /eidosmd:backlinks -->

Dentro é da ferramenta, reescrito por inteiro; fora é da pessoa. O padrão não lê nada disso, e uma verificação aponta só uma abertura sem fechamento. O navegador mostra uma região como ela é, rotulada, em vez de renderizá-la.

Por que a separação importa

O Framework é a peça que viaja. Os seus Blueprints são o seu produto e inúteis para qualquer outra pessoa. Um Framework é forma sem conteúdo, e é exatamente o que um time entrega a outro para que os dois escrevam do mesmo jeito. É isso que uma semente é: um Framework sem nada dentro. Um Framework, qualquer número de raízes.

Ela também fixa a regra que mais surpreende: a raiz possui o seu Framework. Uma ferramenta lê o Framework da raiz em que está, nunca de uma cópia própria. Não há configuração global, e nada tem uma ideia fixa de como as suas coleções se chamam.

Na CLI: eidos framework imprime tudo isto, lido do seu próprio .eidos/.