Framework & Blueprint

	Framework	Blueprint
What it is	The structure	One unit, defined completely
Made of	Folders, templates, properties, vocabulary, roles	One markdown file: properties on top, a body below
Lives in	`.eidos/`, hidden at the root	A collection folder
Portable?	Yes: the piece one team hands to another	No: it is your product

The root

The root is the folder it all lives in. It can be named anything (Blueprints/ is the default) because it is found by the hidden .eidos/ inside it, never by its name. Several roots can live in one repository.

DirectoryBlueprints/ the root
- README.md a top-level doc: the front door
- Directory.eidos/ the framework
  - …
- Directoryassets/ type assets: images and documents the blueprints link to
  - …
- Directoryframes/ a collection: what the whole product is
  - architecture.md
- Directoryspecs/ a collection, grouped
  - Directoryplayback/ a declared group; one level, nothing deeper
    resume-playback.md one blueprint per file
- vision.md another top-level doc

Everything at the root is declared. A folder is .eidos/ or declared under folders with who owns it. owned_by: "@eidos/collections" is a collection (blueprints, optionally in groups), and it is the one kind the standard owns; owned_by: "@<tool>/<kind>" is a tool’s folder (the tool’s one identifier, then its own name for what the folder holds), and what it holds, how it is named, and what is checked inside are that tool’s to say; no owned_by is your own folder, described and left alone. A file is listed under top_level. Anything else is surfaced, and the owner declares it or moves it. Hidden entries like .git are exempt.

A folder is its owner’s. The standard’s rules on variants, grouping, templates, indexing, and naming reach @eidos/collections and no further. Nothing inside a folder it does not own is read. A check faults an owner that is malformed or an @eidos/ kind the standard does not name, and never a tool’s, known or not. A tool claims its folders in its own release; nobody invents an owner on its behalf.

The framework

.eidos/ is hidden the way .git and .obsidian/ are: present, out of the way, and sitting comfortably beside them in a vault.

Directory.eidos/
- Framework.yaml the framework document
- Directorytemplates/ one file per variant
  - spec.full.md
  - spec.micro.md
  - frame.architecture.md
- Directoryroles/ how an agent talks to each kind of person
  - developer.md one file per kind of person
- Directoryplugins/ a folder per tool
  - Directoryeidosmd/ the CLI’s own
    local.yaml local settings (gitignored)
    Directorylocal/ local files (gitignored)
    …
- me.md who is in the seat (local, gitignored)
- .gitignore ignores me.md, plugins//local.yaml, and plugins//local/

The top level of .eidos/ is the standard’s. A tool keeps what it needs under plugins/<name>/ and touches nothing else. Plugins →

`Framework.yaml`

One per root: the structure as data, with comments wherever you want them.

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: every file at the root, in the order they are read. A README, when the root has one, is listed like any other.
folders: every folder at the root, with owned_by when something owns it (quoted, since @ cannot start a plain YAML value). A collection also declares its variants (default: true on the one a new blueprint starts from; with none marked, it has none) and its grouping, where a group may name its own default with default_variant.
properties: the property contract, one block per owner: core (the standard’s), custom (yours), tools.<tool> (a tool’s). Properties →
vocabulary: the words the product is described in on purpose. Starts empty.
index: every collection’s blueprints, each with its id, title, summary, path, and group. Rebuilt wholesale by eidos index, which touches no other key. A blueprint without a summary is listed with none and flagged, never invented. The one derived view the standard defines; any other view is a tool’s.

Regions

A tool that keeps something inside a markdown file writes it in a region: a span between two HTML comments carrying the tool’s name, each alone on its line.

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

Inside is the tool’s, rewritten wholesale; outside is the person’s. The standard reads none of it, and a check faults only an opener with no closer. The browser shows a region as it is, labelled, rather than rendering it.

Why the split matters

The framework is the piece that travels. Your blueprints are your product and useless to anyone else. A framework is form with no content, and it is exactly what one team hands another so both write the same way. That is what a seed is: a framework with nothing in it. One framework, any number of roots.

It also sets the rule that surprises people most: the root owns its framework. A tool reads the framework from the root it is in, never from a copy of its own. There is no global config, and nothing has a hardcoded idea of what your collections are called.

In the CLI: eidos framework prints all of this, read from your own .eidos/.