Versionamento

Duas coisas são versionadas separadamente, ambas com versionamento semântico. Confundi-las é a fonte de confusão mais comum, então vale ser preciso.

	O padrão	O plugin
Vive em	EIDOS.md	.claude-plugin/plugin.json
Uma raiz o registra como	eidos_version no _eidos/Framework.md	—
Se move quando	o texto do EIDOS.md se move	sai qualquer versão, incluindo uma correção em uma skill
Visto por	migrate	/plugin install e as verificações de atualização
Cópias congeladas	versions/	CHANGELOG.md

Eles começaram no mesmo número e se separaram, porque o tooling muda muito mais often do que o padrão.

Lendo uma nota de versão

O CHANGELOG.md registra qual padrão cada versão do plugin carregava. Uma nota que diz Standard: unchanged significa que as suas raízes não precisam de nada: só as skills se moveram.

O que os números significam para o padrão

• Maior: mudanças que quebram.
• Menor: acréscimos retrocompatíveis.
• Correção: esclarecimentos.

Na hora da tag, o EIDOS.md é copiado tal e qual para versions/ com o nome semver completo dele. É isso que torna a próxima seção possível.

As migrações não são sequenciais

Esta é a parte que surpreende as pessoas, e é uma escolha de design deliberada.

O migrate vai direto de qualquer versão de origem para qualquer destino, comparando os dois instantâneos congelados em versions/. Da v1.0.0 direto para a v4.4.2 é um salto, não quatro. Não há uma cadeia de atualizações sequenciais a executar em ordem, nem nenhuma versão em que você precise parar no caminho.

Os saltos desenvolvidos estão registrados em versions/MIGRATIONS.md.

As ferramentas podem recusar uma versão não suportada.

O que a migração toca

O migrate reescreve o bloco ### Eidos Core do seu Framework.md e sobe o eidos_version. Aquele bloco é do padrão, que é a razão de editá-lo à mão ser desaconselhado: as suas próprias propriedades vivem sob ### Custom Properties e nunca são tocadas.

Os números atuais

	Versão
O padrão	4.4.2
O plugin que o distribui	4.5.2

A diferença é a separação funcionando como pretendido: o tooling lançou versões de que o padrão não precisava.

4.4.1 → 4.4.2

Uma passada de clareza sobre o vocabulário e as regras. Defina eidos_version: 4.4.2; nada em disco precisa se mover.

root volta a ser um termo declarado. A única pasta em que o Eidos vive (contendo o Framework, as coleções e quaisquer documentos de nível superior), encontrada pelo _eidos/ dela e nunca pelo nome. A 4.4.1 aposentou “definição” e deixou o conceito sem nome, então o padrão recorria a “uma pasta Eidos” em cerca de uma centena de lugares. A palavra já fazia o trabalho; agora ela está no vocabulário.

shape e flavor param de definir um ao outro. Um shape é um modelo de corpo, um arquivo em _eidos/shapes/. Os shapes de uma coleção são variantes de uma mesma família, e cada variante é um flavor. Nenhum dos dois conceitos se moveu: a tabela apenas parou de dar voltas.

frame já não se lê como “expira”. Ele dizia “solto, de um dado momento”, o que ficava mal ao lado de um padrão cuja afirmação inteira é que um Blueprint é independente do tempo e do estado. Um frame é o que a coisa inteira é, tomada por inteiro em vez de unidade a unidade, revisada quando esse julgamento muda. Nada sobre como os frames funcionam se moveu.

As regras vão de 24 para 19, e são renumeradas

Cinco reformulavam uma seção acima delas e foram removidas, não afrouxadas. Se você cita regras do Eidos por número em algum lugar, confira de novo: essa é a única coisa desta versão que pode ficar desatualizada. O que foi para onde →

A velha regra sobre datas foi junto. Ela determinava como date_created e date_modified se comportam, enquanto a seção de Schema diz que o Eidos não define nenhuma propriedade personalizada e que datas são escolha de um Framework. Ela mantém a metade que obriga (a versão do Eidos é um fato do Framework, no Framework.md) e deixa as datas para o Framework que as declarar. Um Framework que já usa essas propriedades não muda nada; agora ele simplesmente é dono delas por completo.

O canvas é o mapa de Blueprints. Ele desenha Blueprints e as arestas connects_to deles; o Framework é a única coisa que ele nunca desenha. O canvas escreve blueprint-map.canvas daqui em diante, e só quando você não passa --out, então um framework-map.canvas existente mantém o nome dele até você regenerar sem um. Se você deixar que ele seja renomeado, atualize o item dele em ## Top-Level.

Por raiz

1. Defina eidos_version: 4.4.2 no _eidos/Framework.md, e atualize a nota de versão no bloco ## Schema dele. Essa é toda a migração obrigatória.
2. Opcionalmente regenere o canvas para que ele assuma o nome novo, e conserte o item dele em ## Top-Level se fizer isso.
3. Opcionalmente atualize a prosa da semente em _eidos/, que ainda diz “Framework Map” onde o padrão agora diz “Blueprint Map”. Cosmético: nada lê essas palavras.

Nada mais se move. Nenhuma propriedade, nenhuma seção de corpo, nenhum nome de arquivo, nenhuma coleção.

4.4.0 → 4.4.1

Uma versão de vocabulário. Defina eidos_version: 4.4.1; nada em disco precisa se mover. Três mudanças, todas no texto do padrão:

item agora é blueprint. A mesma coisa que sempre foi: um arquivo markdown dentro de uma coleção, definindo uma unidade por completo. Nenhuma propriedade, pasta ou nome de arquivo jamais carregou a palavra, então nada do que um agente ou um script lê muda.

definition é aposentado, sem substituto. Ele nomeava a pasta inteira, mas colidia com o que um Blueprint faz (um Blueprint define uma unidade) e o sentido cotidiano da palavra é um verbete de dicionário, não uma árvore de pastas. O Eidos agora gira sobre duas palavras: Framework e Blueprint. Onde o padrão precisa nomear a pasta, ele diz “uma pasta Eidos” ou “a raiz”. (A 4.4.2 se decidiu por root como termo declarado; veja acima.)

O nome de raiz padrão é Blueprints/, no plural, já que ela guarda muitos. Apenas o padrão que o install oferece; a raiz ainda pode ter qualquer nome, e nada aponta para ela por caminho.

Por raiz

1. Defina eidos_version: 4.4.1 no _eidos/Framework.md, e atualize a nota de versão no bloco ## Schema dele. Essa é toda a migração obrigatória.
2. Opcionalmente atualize a prosa da semente em _eidos/. As linhas de introdução do Framework.md, os arquivos de shape e roles/*.md dizem “item” e “definition” onde o padrão agora diz “blueprint”. Puramente cosmético (nada lê essas palavras), então só vale a pena onde ninguém tiver editado o texto desde que o install o escreveu.
3. Deixe em paz um papel ou shape editado à mão a menos que o dono peça. As palavras dele são dele.
4. Renomear a raiz é opcional. Um Blueprint/ existente funciona exatamente como funcionava; renomeie-o só se o dono quiser o plural, e então é uma simples renomeação de pasta sem nada apontando para ela para consertar.

Nada mais se move. Nenhuma propriedade, nenhuma seção de corpo, nenhum nome de arquivo, nenhuma coleção.

4.3.2 → 4.4.0

O movimento mais recente no padrão, e uma boa ilustração de quão pequena uma mudança nele pode ser.

O salto anterior a esse. A 4.4.0 mudou um padrão. kebab-case é agora o que o padrão recomenda e o que uma chave naming ausente significa; até a 4.3.2 uma chave ausente significava Title Case. Uma raiz que já carrega a chave não é afetada (a chave manda nas duas versões e só o valor de reserva se moveu), então para quase todo mundo a migração inteira é: suba o eidos_version e pare.

Para uma raiz sem chave naming, resolva isso em vez de deixar o padrão decidir:

Leia a convenção nos arquivos. A árvore já responde à pergunta. Uma pasta de coleção ou nome de arquivo de Blueprint contendo um espaço significa Title Case; sem espaços e com maiúsculas (WatchAVideo.md) significa TitleCase; minúsculo e com hifens (watch-a-video.md) significa kebab-case. Confira algumas coleções em vez de um arquivo, e se elas discordarem, isso é uma inconsistência real a trazer à tona, não algo a tirar a média.

Confirme com o dono, e então escreva no _eidos/Framework.md. Declare o que os arquivos dizem e o que você está prestes a registrar. Registrar o que a raiz já faz não é uma mudança nela.

Adotar kebab-case é uma passada separada e deliberada

Nunca a junte com a subida de versão. Ela renomeia cada pasta de coleção, subpasta e arquivo de Blueprint, reescreve cada link, e passa para minúsculas o valor de cada propriedade de agrupamento para coincidir com a pasta dela (domain: Channels → domain: channels). Faça isso quando o dono quiser, não porque o padrão se moveu.

Duas notas menores na mesma versão:

• O nome de arquivo padrão do canvas segue a convenção: blueprint-map.canvas em kebab-case, BlueprintMap.canvas em TitleCase, Blueprint Map.canvas em Title Case. A skill canvas só escolhe o nome quando você não passa --out, então um canvas existente mantém o nome dele até você regenerar sem um. Se ele acabar renomeado, atualize o item dele em ## Top-Level.
• README.md agora é nomeado como exceção ao lado de _eidos/: ele mantém o nome que toda ferramenta já procura, seja qual for a convenção. Nada a mudar: isto põe por escrito o que toda pasta já fazia.

Nada mais se move. Nenhum shape, nenhum papel, nenhuma propriedade no Schema, nenhuma seção de corpo.

As duas pastas de exemplo em examples/ foram convertidas para kebab-case naquela versão, caso você queira ler um diff desenvolvido.

Em qual versão eu estou?

Leia o eidos_version no _eidos/Framework.md da sua raiz. Essa é a versão à qual a sua raiz se conforma, não a que o plugin por acaso tem, e não o que qualquer propriedade por Blueprint diga, porque não existe uma.

A seguir

• Convenções
• Skills: o migrate em contexto.