Versioning

Two things version separately, both with Semantic Versioning. Conflating them is the most common source of confusion, so it’s worth being precise.

	The standard	The plugin
Lives in	EIDOS.md	.claude-plugin/plugin.json
A root records it as	eidos_version in _eidos/Framework.md	—
Moves when	the text of EIDOS.md moves	any release ships, including a skill fix
Seen by	migrate	/plugin install and update checks
Frozen copies	versions/	CHANGELOG.md

They started on the same number and have drifted, because the tooling changes far more often than the standard does.

Reading a release note

CHANGELOG.md records which standard each plugin release carried. A note that says Standard: unchanged means your roots need nothing — only the skills moved.

What the numbers mean for the standard

• Major — breaking changes.
• Minor — backward-compatible additions.
• Patch — clarifications.

At tag time, EIDOS.md is copied as-is into versions/ under its full semver name. That’s what makes the next section possible.

Migrations are non-sequential

This is the part that surprises people, and it’s a deliberate design choice.

migrate goes directly from any source version to any target by diffing the two frozen snapshots in versions/. v1.0.0 straight to v4.4.2 is one hop, not four. There is no chain of sequential upgrades to run in order, and no version you have to stop at on the way.

Worked hops are recorded in versions/MIGRATIONS.md.

Tools may reject an unsupported version.

What migration touches

migrate rewrites the ### Eidos Core block in your Framework.md and bumps eidos_version. That block is the standard’s, which is why hand-editing it is discouraged — your own properties live under ### Custom Properties and are never touched.

The current numbers

	Version
The standard	4.4.2
The plugin that ships it	4.5.2

The gap is the drift working as intended — the tooling has shipped releases the standard didn’t need.

4.4.1 → 4.4.2

A clarity pass over the vocabulary and the Rules. Set eidos_version: 4.4.2; nothing on disk has to move.

root is a declared term again. The one folder Eidos lives in — holding the framework, the collections, and any top-level docs — found by its _eidos/ and never by its name. 4.4.1 retired “definition” and left the concept unnamed, so the standard fell back on “an Eidos folder” in about a hundred places. The word was already doing the work; it’s now in the vocabulary.

shape and flavor stop defining each other. A shape is one body template, one file in _eidos/shapes/. A collection’s shapes are variants of one family, and each variant is a flavor. Neither concept moved — the table just stopped looping.

frame no longer reads as “expires”. It said “loose, point-in-time”, which sits badly beside a standard whose whole claim is that a blueprint is independent of time or status. A frame is what the whole thing is, taken whole rather than unit by unit, revised when that judgment changes. Nothing about how frames work has moved.

The Rules go 24 → 19, and renumber

Five restated a section above them and were dropped — not relaxed. If you cite Eidos rules by number anywhere, re-check them: that’s the one thing in this release that can go stale. What moved where →

The old rule on dates went with them. It mandated how date_created and date_modified behave, while the Schema section says Eidos defines no custom properties and that dates are a framework’s own choice. It keeps the half that binds — the Eidos version is a framework fact, in Framework.md — and leaves dates to whichever framework declares them. A framework already using those properties changes nothing; it now simply owns them outright.

The canvas is the Blueprint Map. It draws blueprints and their connects_to edges; the framework is the one thing it never draws. canvas writes blueprint-map.canvas from here on, and only when you don’t pass --out — so an existing framework-map.canvas keeps its name until you regenerate without one. If you do let it rename, update its bullet in ## Top-Level.

Per root

1. Set eidos_version: 4.4.2 in _eidos/Framework.md, and update the version note in its ## Schema block. That is the whole required migration.
2. Optionally regenerate the canvas to take the new name, and fix its ## Top-Level bullet if you do.
3. Optionally refresh the seed prose in _eidos/, which still says “Framework Map” where the standard now says “Blueprint Map”. Cosmetic — nothing reads those words.

Nothing else moves. No property, no body section, no filename, no collection.

4.4.0 → 4.4.1

A vocabulary release. Set eidos_version: 4.4.1; nothing on disk has to move. Three changes, all in the text of the standard:

item is now blueprint. The same thing it always was — one markdown file in a collection, defining one unit completely. No property, folder, or filename ever carried the word, so nothing an agent or a script reads changes.

definition is retired, with no replacement. It named the whole folder, but it collided with what a blueprint does — a blueprint defines a unit — and the everyday sense of the word is a dictionary entry rather than a folder tree. Eidos now turns on two words: framework and blueprint. Where the standard needs to name the folder, it says “an Eidos folder” or “the root”. (4.4.2 settled on root as a declared term — see above.)

The default root name is Blueprints/, plural, since it holds many. Only the default install offers; the root may still be named anything, and nothing points at it by path.

Per root

1. Set eidos_version: 4.4.1 in _eidos/Framework.md, and update the version note in its ## Schema block. That is the whole required migration.
2. Optionally refresh the seed prose in _eidos/. Framework.md’s intro lines, the shape files, and roles/*.md say “item” and “definition” where the standard now says “blueprint”. Purely cosmetic — nothing reads those words — so it’s worth doing only where nobody has edited the text since install wrote it.
3. Leave a hand-edited role or shape alone unless the owner asks. Their words are theirs.
4. Renaming the root is optional. An existing Blueprint/ works exactly as it did; rename it only if the owner wants the plural, and then it’s a plain folder rename with nothing pointing at it to fix.

Nothing else moves. No property, no body section, no filename, no collection.

4.3.2 → 4.4.0

The most recent move in the standard, and a good illustration of how small a change to it can be.

The hop before it. 4.4.0 changed one default. kebab-case is now what the standard recommends and what an absent naming key means; through 4.3.2 an absent key meant Title Case. A root that already carries the key is unaffected — the key is authoritative in both versions and only the fallback moved — so for almost everyone the whole migration is: bump eidos_version and stop.

For a root with no naming key, settle it rather than letting the default decide:

Read the convention off the files. The tree already answers the question. A collection folder or blueprint filename containing a space means Title Case; space-free and capitalized (WatchAVideo.md) means TitleCase; lowercase and hyphenated (watch-a-video.md) means kebab-case. Check a couple of collections rather than one file — and if they disagree, that’s a real inconsistency to surface, not something to average.

Confirm it with the owner, then write it into _eidos/Framework.md. State what the files say and what you’re about to record. Recording what the root already does is not a change to it.

Adopting kebab-case is a separate, deliberate pass

Never bundle it into the version bump. It renames every collection folder, sub-folder, and blueprint file, rewrites every link, and lowercases each grouping property’s value to match its folder (domain: Channels → domain: channels). Do it when the owner wants it, not because the default moved.

Two smaller notes in the same release:

• The canvas’s default filename follows the convention — blueprint-map.canvas under kebab-case, BlueprintMap.canvas under TitleCase, Blueprint Map.canvas under Title Case. The canvas skill only picks the name when you don’t pass --out, so an existing canvas keeps its name until you regenerate without one. If it does get renamed, update its bullet in ## Top-Level.
• README.md is now named as an exception beside _eidos/: it keeps the name every tool already looks for, whatever the convention. Nothing to change — this writes down what every folder was already doing.

Nothing else moves. No shape, no role, no property in the Schema, no body section.

Both example folders in examples/ were converted to kebab-case that release, if you want a worked diff to read.

Which version am I on?

Read eidos_version in your root’s _eidos/Framework.md. That’s the version your root conforms to — not whatever the plugin happens to be, and not what any per-blueprint property says, because there isn’t one.

Next

• Conventions
• Skills — migrate in context.