eidosmd 0.1.0 → 0.2.0

package/standard/EIDOS.md

@@ -1,229 +1,182 @@
 # Eidos
 
-**Version:** 4.5.0
+**Version:** 5.0.0
 
-A markdown standard for defining the essence of a thing — a product, a body of work, anything you set out to make. One file is the complete source of truth for one unit of it, independent of time or status: as true of something planned as of something long finished.
+A system of organization for defining a product: an app, a book, a study, a workflow, anything work produces that has a shape. The structure is data, in a hidden folder, that a tool can check a root against; the product is written in markdown against that structure. One file is the complete source of truth for one unit of it, independent of time or status: as true of something planned as of something long finished.
 
-This file is the contract: the terms, the layout, and the rules. It names no collection, no shape, and no section — those belong to a framework, not to the standard. For worked frameworks see [`seeds/`](seeds). Doing the work takes a person, this contract, and the [skills](#for-an-agent).
+This file is the contract: the terms, the layout, and the rules. It names no collection, no template, and no section — those belong to a framework, not to the standard.
 
 ## Vocabulary
 
 Every term the standard uses, in the order they build on each other.
 
-| Term | What it is |
-| --- | --- |
-| **root** | The one folder Eidos lives in, holding the framework, the collections, and any top-level docs. Found by the hidden `_eidos/` inside it, never by its name. |
-| **framework** | The *structure* a root is written in — its collections, shapes, flavors, roles, naming convention, and Schema. Lives in the root's hidden `_eidos/`. Portable: the same framework governs any number of roots. |
-| **collection** | A top-level folder of repeated blueprints that share a body shape. A framework declares each one, and may group a collection's blueprints in one level of sub-folders. |
-| **blueprint** | One markdown file in a collection, defining one unit completely. Frontmatter (a contract) plus a body (a shape). |
-| **frame** | A blueprint describing the whole thing rather than one unit of it. Frames set what every other blueprint is judged against, and are revised whenever that judgment changes. Every framework declares a framing collection. |
-| **shape** | One body template: the sections a blueprint carries, in order, under set names, each with its guidance. Body only; frontmatter is generated. One file per shape, in `_eidos/shapes/`. |
-| **flavor** | A collection's shapes are variants of one family, and each variant is a flavor (`<kind>.<flavor>`). A collection declares one or more and marks one default — typically a light flavor a blueprint can grow out of, beside a fuller one. |
-| **property** | One frontmatter field: a name, a type, which collections it applies to, and a meaning. |
-| **Schema** | The framework's whole property contract: the core properties Eidos requires, plus whatever the framework adds. |
-| **top-level doc** | A one-of-a-kind document at the root — a Roadmap, a Vision, the generated canvas. Free-form: no shape, no flavors, no validation. |
-| **role** | A response contract for one kind of person, saying how an agent talks to them. |
-| **actor** | Who is in the seat right now: their role, plus a personal calibration. |
-| **seed** | A starting framework the standard ships. `install` copies one into a new root. |
-
-A blueprint captures **state and intent, not work**. A task describes work and dies when the work ships; a blueprint describes the thing and stays accurate across its whole life — drafted, built, deprecated.
+| Term              | What it is                                                                                                                                                                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **product**       | What you are defining: an app, a book, a study, a workflow, anything work produces that has a shape.                                                                                                                                                    |
+| **framework**     | How the files are organized: the collections, templates, variants, properties, vocabulary, and roles a product is written in. Lives in `.eidos/`, and the same framework can govern any number of products.                                             |
+| **root**          | The folder it all lives in: `.eidos/` and the files written with it. Found by the `.eidos/` inside it, never by its name.                                                                                                                               |
+| **collection**    | A top-level folder in the root holding files of one kind: specs, chapters, investigations. A framework declares each one, and may group its files in one level of sub-folders.                                                                          |
+| **blueprint**     | One markdown file in a collection, defining one thing completely: properties at the top, a body below.                                                                                                                                                  |
+| **unit**          | What one blueprint defines: one piece of the product, of the kind its collection holds: a spec, a chapter, an investigation. A collection's templates are named for its unit, in the singular.                                                          |
+| **template**      | The body a collection's blueprints follow: sections in order, under set names, each with a note on what goes there. Body only; frontmatter is illegal in a template. One file each, in `.eidos/templates/`.                                             |
+| **variant**       | A collection can have more than one template, and each is a variant (`<unit>.<variant>.md`). One is the default; a blueprint on another says so in its `variant` property.                                                                              |
+| **property**      | One field in a blueprint's frontmatter: a name, a type, which collections it applies to, and what it means. The framework's whole table of them, in `Framework.yaml`, is its Properties: the four Eidos requires, plus what the owner and any tool add. |
+| **vocabulary**    | The framework's table of words used on purpose: what each means, and what it is not.                                                                                                                                                                    |
+| **top-level doc** | A one-of-a-kind file at the root: a Vision, a map a tool generates. No template, no validation.                                                                                                                                                         |
+| **role**          | How an agent talks to one kind of person. `.eidos/me.md` says which role is in the seat.                                                                                                                                                                |
+| **plugin**        | A tool's own folder inside the framework, `.eidos/plugins/<name>/`, holding whatever that tool keeps there. The standard reads none of it.                                                                                                              |
+
+A blueprint captures a vision of the product as a source of truth. A task describes work and dies when the work ships; a blueprint describes the product and stays accurate across its whole life — drafted, built, deprecated.
 
 ## Layout
 
-The root is found by the hidden `_eidos/` inside it. It may be named anything; nothing points at it by path.
+The root is found by the hidden `.eidos/` inside it. It may be named anything; nothing points at it by path.
 
 ```txt
 Blueprints/              # the root — `Blueprints` is only the default name
   README.md              # the visible "start here"
-  _eidos/                # the framework (below)
-  <Framing>/             # the framing collection — declared first
-    index.md             #   generated leaf (a markdown framework; a YAML one keeps it inside the document)
-    <Frame>.md           #   one per kind of frame, flat
+  .eidos/                # the framework (below)
   <Collection>/          # a collection of blueprints; declare as many as the work needs
-    index.md             #   generated leaf, likewise
     <Group>/             #   one level of sub-folders, at most
       <Title>.md         #     one blueprint per file
-  roadmap.md             # a top-level doc — optional, yours
+  <Doc>.md               # a top-level doc — optional, yours
 ```
 
-Several roots in one repository nest as `Blueprints/<name>/…`, each with its own `_eidos/`.
+## The framework (`.eidos/`)
 
-## The framework (`_eidos/`)
-
-Hidden the way `.git` and `.obsidian` are: present, manageable, out of the way once set. The root is plausibly an Obsidian vault, and `_eidos/` sits beside `.obsidian/`.
+Hidden the way `.git` and `.obsidian` are: present, manageable, out of the way once set. Open the way `.obsidian/` is, too: the standard names its own entries, and a tool that keeps something in the framework gets a folder of its own under `plugins/`. A folder with no `.eidos/` is not a root.
 
 ```txt
-_eidos/
-  shapes/                  # one file per flavor
-    <kind>.<flavor-1>.md   #   a collection's default flavor
-    <kind>.<flavor-2>.md   #   a second flavor of the same kind
-    frame.<kind>.md        #   the framing collection's flavors, one per kind of frame
+.eidos/
+  templates/               # one file per variant
+    <unit>.<variant-1>.md   #   a collection's default variant
+    <unit>.<variant-2>.md   #   a second variant of the same unit
   roles/                   # response contracts, committed and team-tunable
-    framework-owner.md     #   the one every seed carries
+    framework-owner.md     #   the role that holds intent, scope, and decisions
     <role>.md              #   the rest are the framework's own
-  Framework.md             # the framework document, for people: version, naming, Top-Level, Collections, Schema
-                           #   (or Framework.yaml, the same as data with the index inside it, for scripts and agents)
-  me.md                    # the actor (personal, gitignored)
-  .gitignore               # ignores me.md — the one file here not committed
+  Framework.yaml           # the framework document: version, naming, top-level docs, collections, properties, vocabulary, and the index
+  plugins/                 # whatever tools keep in the framework, one folder each
+    <name>/                #   a tool's own; the standard reads none of it
+  me.md                    # who is in the seat (personal, gitignored)
+  .gitignore               # ignores me.md, and any personal file a plugin names
 ```
 
-The skills read the framework from the root they are working in, never from a copy of their own. A folder with no `_eidos/` is not a root.
-
-### `Framework.md`
-
-The framework document: the one file describing the structure rather than any single blueprint. It has two forms, the same fields in each, and a root keeps exactly one. This is the markdown form, for people: frontmatter for the facts tooling parses and a body indexing what it governs, readable in a vault and edited in place. The other is [`Framework.yaml`](#frameworkyaml), for scripts and agents.
-
-```markdown
----
-eidos_version: 4.5.0
-naming: kebab-case
----
-
-# Framework
-
-## Top-Level
-<!-- configure: top-level index (regenerated) -->
-- [README](../README.md) — the front door.
-
-## Collections
-
-### <Framing collection>
+### Plugins
 
-The framing docs — declared first.
+The top level of `.eidos/` is the standard's: the entries above, and whatever a later version adds. Everything else lives under `.eidos/plugins/`, one folder per tool, named for the tool: a CLI's cache, an editor extension's settings, a generator's templates, a script's state. What goes inside is the tool's own, and the standard neither reads nor validates it; a check never faults a folder there, a migration carries it across untouched, and a fresh root starts with none. A plugin folder is committed with the rest of the framework; a tool that keeps personal state names those files, and they go in `.eidos/.gitignore` beside `me.md`.
 
-- **Leaf:** [<Framing>/index.md](../<Framing>/index.md)
-- **Flavors:**
-  - [<kind>](shapes/frame.<kind>.md) — one flavor per kind of frame (mark one default).
-- **Canvas:** file
-
-### <Collection>
-
-One line on what this collection holds.
-
-- **Leaf:** [<Collection>/index.md](../<Collection>/index.md)
-- **Flavors:**
-  - [<flavor-1>](shapes/<kind>.<flavor-1>.md) — the fuller shape (default).
-  - [<flavor-2>](shapes/<kind>.<flavor-2>.md) — a lighter one to grow out of.
-- **Canvas:** card from `## <Section>`
-- **<Grouping>:**
-  - **<Group>** — one line on what falls under it.
-
-## Schema
-
-### Eidos Core
-<!-- the standard's block: id, title, summary, flavor, connects_to -->
-
-### Custom Properties
-| Name   | Type | Applies To   | Meaning                        |
-| ------ | ---- | ------------ | ------------------------------ |
-| <name> | Text | all          | Whatever this framework needs. |
-| <name> | Text | <Collection> | Scoped to one collection.      |
-```
-
-- **`eidos_version`** — the version this framework targets. `migrate` reads and bumps it.
-- **`naming`** — `kebab-case` (default), `TitleCase`, or `Title Case`. See [Naming](#naming).
-- **`## Top-Level`** — the top-level docs, `README` first. Framing docs are not here; they are a collection.
-- **`## Collections`** — one `###` each: its **Leaf**, its **Flavors** (default marked), its **Canvas**, and its grouping.
-- **`- **Canvas:**`** — how a canvas generator draws the collection: `file` (a full-file node, for prose read whole), `card` (a node embedding the blueprint), or `card from ## Section` (a node embedding that section). Absent means a plain card — a generator knows no collection by name and cannot guess which section is the summary.
-- **`## Schema`** — `### Eidos Core` (the standard's, rewritten by `migrate`) and `### Custom Properties` (the framework's).
+A tool touches only the folder it owns. The framework document, the templates, and the roles are the owner's, edited by hand or through a tool the owner runs; a plugin that needs the framework to know something declares it in its own folder, not in theirs.
 
 ### `Framework.yaml`
 
-The framework document may be data instead of markdown: `Framework.yaml` (or `.yml`) in place of `Framework.md`. It is the same framework, field for field, in the snake_case the frontmatter already uses, with comments wherever the owner wants them. Choose it when scripts and agents are the main readers: it parses without a markdown convention, and it carries the one thing the markdown form keeps elsewhere, the generated index, under `index` (see [Generated leaves](#generated-leaves)), so a YAML root is one document with everything in it. Choose markdown when people are: it renders in a vault and reads as prose. The markdown form's prose has no field to land in and stays behind when a root converts.
+The framework document: the one file describing the structure rather than any single blueprint, exactly one per root. It is data, `Framework.yaml` (or `.yml`), in snake_case, with comments wherever the owner wants them: the version and naming convention, the top-level docs, the collections, the Properties table, the Vocabulary, and the generated index, so a root is one document with everything in it. Scripts and agents parse it without a markdown convention, a person reads it the way they read any config file, and tools edit it in place.
 
 ```yaml
-eidos_version: 4.5.0
+eidos_version: 5.0.0
 naming: kebab-case            # absent = kebab-case
 top_level:                    # the top-level docs, README first
   - title: README
     path: ../README.md
     description: the front door.
-collections:                  # the first is the framing collection
-  - name: <Framing>
-    description: The framing docs.
-    canvas: file
-    flavors:
-      - name: <kind>
-        shape: shapes/frame.<kind>.md
-        description: one flavor per kind of frame
-        default: true
+collections:                  # one entry per collection
   - name: <Collection>
     description: One line on what this collection holds.
-    canvas: { mode: card, section: <Section> }
-    flavors:
-      - { name: <flavor-1>, shape: shapes/<kind>.<flavor-1>.md, description: the fuller shape, default: true }
-      - { name: <flavor-2>, shape: shapes/<kind>.<flavor-2>.md, description: a lighter one to grow out of }
+    variants:
+      - { name: <variant-1>, template: templates/<unit>.<variant-1>.md, description: the fuller template, default: true }
+      - { name: <variant-2>, template: templates/<unit>.<variant-2>.md, description: a lighter one to grow out of }
     grouping:
       label: <Grouping>
       property: <name>          # the custom property carrying the group, if one does
       groups:
         - { name: <Group>, description: one line on what falls under it }
-schema:
+properties:
   core: []                    # absent = the standard's core for this eidos_version
   custom:
     - { name: <name>, type: Text, applies_to: all, meaning: Whatever this framework needs. }
-    - { name: <name>, type: Text, applies_to: [<Collection>], meaning: Scoped to one collection. }
-index:                        # generated, regenerated wholesale by `index`; never hand-edited
+    - { name: <name>, type: Text, applies_to: [<Collection>], meaning: Scoped to one collection., <tool>: { <field>: <value> } }
+  tools:                      # one block per tool that declares properties of its own; absent = none
+    <tool>:
+      - { name: <name>, type: Text, applies_to: all, meaning: A property the tool keeps itself. }
+vocabulary:                   # the root's own terms; absent = none declared
+  - { term: <Term>, means: One line on what the word denotes here., not: ["<near-miss>, and why it is a different thing"] }
+  - { term: <Term>, means: A term its blueprint defines in full., not: [<near-miss>], see: ../<Collection>/<Group>/<Title>.md }
+index:                        # generated, regenerated wholesale; never hand-edited
   <Collection>:
     - { id: <id>, title: <Title>, summary: <the summary>, path: <Group>/<Title>.md, group: <Group> }
 ```
 
-- Every path is relative to `_eidos/`, as the markdown form's links are. An index entry's `path` is relative to its collection folder, as an `index.md` link is.
-- `canvas` is `file`, `card`, or `{ mode: card, section: <Section> }`. `default` marks a collection's default flavor; absent on all of them, the first is. `applies_to` is `all` or a list of collections. There is no **Leaf**: a structured root's index is inside the document.
-- A tool reads whichever document is present and treats the framework the same. Converting a markdown root means writing the same fields as data, removing `Framework.md` and each collection's `index.md`, and regenerating the index.
+- **`eidos_version`**: the version this framework targets. A migration reads and bumps it.
+- **`naming`**: `kebab-case` (default), `TitleCase`, or `Title Case`. See [Naming](#naming).
+- **`top_level`**: the top-level docs, `README` first, each a `title`, a `path`, and a `description`.
+- **`collections`**: one entry each: its `name`, its `description`, its `variants` (`default` marks the default; absent on all of them, the first is), and its `grouping` (a `label`, the custom `property` carrying the group if one does, and its `groups`).
+- **`properties`**: one block per owner. `core` is the standard's, rewritten by a migration (empty means the standard's core for this `eidos_version`); `custom` is the framework's, edited by the owner; `tools.<tool>` is one block per tool that declares properties of its own, that tool's and written by nobody else. `applies_to` is `all` or a list of collections. The four keys the standard names are the standard's; any other key on an entry is a tool's, named for the tool.
+- **`vocabulary`**: the root's own terms, one entry each: `term`, `means`, and `not` as a list, each item free to carry its clause, and `see` for the path to the blueprint that defines the term in full. Starts empty; absent means none declared.
+- **`index`**: every collection's blueprints, generated (see [The index](#the-index)). Rebuilt wholesale by whatever indexes the root, which rewrites this key and nothing else; never hand-edited.
+- Every path is relative to `.eidos/`; an index entry's `path` is relative to its collection folder.
 
-### Shapes and flavors
+### Templates and variants
 
-A shape is body-only: sections in their order, under set names, with their guidance. Every blueprint in a collection follows one of that collection's declared flavors, and a check validates against the flavor the blueprint names. Shape files are `<kind>.<flavor>.md`, lowercase and dotted. Top-level docs have no shape.
+A template is body-only: sections in their order, under set names, with their guidance, and nothing else. Frontmatter is illegal in a template: a blueprint's frontmatter is generated from the Properties table, never copied from a template, so a template that opens with a frontmatter block is faulted rather than read. What a template has to say about itself it says in its sections; how templates work is this standard's to say, not each template's to repeat. Every blueprint in a collection follows one of that collection's declared variants, and a check validates against the variant the blueprint names. A template file is named `<unit>.<variant>.md`, lowercase and dotted: the collection's unit, then the variant. Every variant a collection declares shares its unit, and a template file named any other way is faulted the way frontmatter in one is. Top-level docs have no template.
 
-The default flavor is what gets scaffolded; a blueprint on another records it in `flavor`. A blueprint on a lighter flavor is never faulted for the sections only a fuller one carries.
+The default variant is what gets scaffolded; a blueprint on another records it in `variant`. A blueprint on a lighter variant is never faulted for the sections only a fuller one carries.
 
-### Schema
+### Properties
 
-Each property is a row: **Name · Type · Applies To · Meaning**. A type comes from the set Obsidian uses — **Text, List, Number, Checkbox, Date, Date & time** — so frontmatter renders natively in a vault. Anything wanting more structure than one of those belongs in the body.
+Each property is an entry with four fields: `name`, `type`, `applies_to`, `meaning`. A type comes from the set Obsidian uses — **Text, List, Number, Checkbox, Date, Date & time** — so frontmatter renders natively in a vault. Anything wanting more structure than one of those belongs in the body.
 
 **Applies To** scopes a property to collections: `all`, or a list. Frontmatter is generated per blueprint from the properties that apply to its collection, so a scoped property never lands where it makes no sense.
 
+**Every property has an owner, and the owner is the block it sits in.** Eidos is the first tool: `properties.core` is its block, and a migration rewrites it. `properties.custom` is the framework owner's, and the owner edits it. A tool that needs properties of its own (the `eidos` CLI, an editor extension, a generator) declares them in a block of its own, `properties.tools.<tool>`, and that tool alone writes it: not the owner, not a migration, not another tool. A tool's properties are Properties properties like any other, generated into frontmatter where they apply, validated by a check, and bound by every rule here including the one against work-tracking; an unknown tool's block is never faulted. When a tool leaves, its block leaves with it, the values it held surfaced first the way any retired property's are.
+
+**A row may also carry a tool's fields.** The four the standard names come first and mean what they mean here. Past them, a tool that needs something per property it does *not* own (how an editor renders `status`, what a checker allows, an option list) adds its own under its own name: a key named for the tool on the property's entry. The standard reads its four and ignores the rest; a check never faults them, and an edit or a migration carries them across unchanged and never fills them in.
+
 **The core** — present on every blueprint, and the whole of what the standard requires:
 
-| Name | Type | Meaning |
-| --- | --- | --- |
-| `id` | Text | Stable, unique, kebab-case identity. Assigned once, never renamed. References point at it. |
-| `title` | Text | Human-readable name. Rename it freely; `id` is what holds still. |
-| `summary` | Text | One plain line: what this blueprint is. The source for the collection's [`index.md`](#generated-leaves) listing; absent, the index flags it. |
-| `flavor` | Text | Which flavor this blueprint follows. Absent = the collection's default. |
-| `connects_to` | List | Blueprints this one connects to on the canvas, each a link, drawn as a directed edge. |
+| Name      | Type | Meaning                                                                                                                          |
+| --------- | ---- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `id`      | Text | Stable, unique identity, in any form: a slug, a number, a GUID. Assigned once, never changed. References point at it.            |
+| `title`   | Text | Human-readable name. Rename it freely; `id` is what holds still.                                                                 |
+| `summary` | Text | One plain line: what this blueprint is. The source for the collection's [index](#the-index) listing; absent, the index flags it. |
+| `variant` | Text | Which variant this blueprint follows. Absent = the collection's default.                                                         |
+
+**Eidos defines no custom properties.** A lifecycle `status`, dates, a grouping, a dependency list, a relationship list — all are a framework's own choice, and how blueprints relate is better said in the body, as links in prose, than as a frontmatter field. Adding one means deciding all four of Name, Type, Applies To, and Meaning, then backfilling the blueprints it applies to.
+
+### Vocabulary
+
+The Properties table's sibling: where that table is the contract for properties, the Vocabulary is the contract for words. Each term is an entry: `term`, `means`, `not`, and `see` when a blueprint defines the concept in full. **term** is the word as prose uses it. **means** is one line. **not** is the near-misses, each with a clause on why it is a different thing, and it is where an entry earns its place: a term with nothing there is a dictionary entry, and a term that needs a body of its own is a blueprint, pointed at from its entry.
+
+Three layers of words meet in a root, and each is declared where it lives. The standard's terms are the table at the top of this file. A framework's structural names (its collections, variants, groups) are declared where the structure is. The root's own terms, the words the product itself is described in, are the framework's Vocabulary. **Eidos declares none of the last.** A Vocabulary starts empty and grows an entry when a word begins to carry a distinction worth keeping, each entry deciding all three of term, means, and not.
 
-**Eidos defines no custom properties.** A lifecycle `status`, dates, a grouping, a dependency list — all are a framework's own choice. Each [seed](seeds) makes its own set. Add one with `configure`, which presses for all four of Name, Type, Applies To, and Meaning, then backfills the blueprints it applies to.
+A declared term is the word (Rule 19). An agent authoring or checking a blueprint uses it, and where a near-miss appears says which term the Vocabulary would have, as a suggestion. This is distinct from what a role sets: a role is register, how deep an agent goes and what it surfaces for one kind of reader; the Vocabulary is meaning, what a word denotes for every reader.
 
-### Roles and the actor
+### Roles
 
 Not everyone who works on the same root plays the same part — one holds the intent, another builds or drafts from it, another reviews it, another answers for it. The agent responds to each differently, from two files:
 
-- **`_eidos/roles/<role>.md`** — one response contract per role: vocabulary and technical depth, what to surface versus fold away, and who holds which decisions. Which roles exist is the framework's call; each [seed](seeds) ships a set written against its own collections. Committed and team-tunable.
-- **`_eidos/me.md`** — personal and gitignored, one per person. Names the actor's role and calibrates it on three axes: **ownership**, **experience with the scope**, and **technical capacity**. Set it with `whoami`. Blank is fine.
+- **`.eidos/roles/<role>.md`** — one response contract per role: vocabulary and technical depth, what to surface versus fold away, and who holds which decisions. Which roles exist is the framework's call. Committed and team-tunable.
+- **`.eidos/me.md`** — personal and gitignored, one per person. Names your role and calibrates it on three axes: **ownership**, **experience with the scope**, and **technical capacity**. Blank is fine.
 
-One role is common to every seed: the **Framework Owner**, who holds the intent, the scope, and the decisions. The rest of the cast depends on the work.
+One role every framework has: the **Framework Owner**, who holds the intent, the scope, and the decisions. The rest of the cast depends on the work.
 
 ## Writing
 
 ### `README.md`
 
-A visible front door at the root: what the thing is, and pointers into it — the top-level docs, the collections and their indexes, and the framework document for the full index. Thin, orientation and links, edited in place.
+A visible front door at the root: what the product is, and pointers into it — the top-level docs, the collections, and the framework document for the full index. Thin, orientation and links, edited in place.
 
 ### Naming
 
 Everything a human reads in the tree — top-level docs, collection and sub-folders, blueprint files — follows the framework's `naming` convention.
 
-| Convention | A blueprint file | A grouping folder | For |
-| --- | --- | --- | --- |
-| **kebab-case** (default) | `blueprint-title-here.md` | `group-name/` | readable everywhere: no escaping, no `%20`, and the filename *is* the `id` |
-| **TitleCase** | `BlueprintTitleHere.md` | `GroupName/` | space-free, capitalized |
-| **Title Case** | `Blueprint Title Here.md` | `Group Name/` | a tree that reads like prose, at the cost of `%20` in every link |
+| Convention               | A blueprint file          | A grouping folder | For                                                              |
+| ------------------------ | ------------------------- | ----------------- | ---------------------------------------------------------------- |
+| **kebab-case** (default) | `blueprint-title-here.md` | `group-name/`     | readable everywhere: no escaping, no `%20`                       |
+| **TitleCase**            | `BlueprintTitleHere.md`   | `GroupName/`      | space-free, capitalized                                          |
+| **Title Case**           | `Blueprint Title Here.md` | `Group Name/`     | a tree that reads like prose, at the cost of `%20` in every link |
 
 An absent `naming` key means `kebab-case`.
 
-One convention governs the whole folder, and changing it later means renaming files, so it is settled at init. Whichever you pick: `_eidos/` is always lowercase; `README.md` keeps the name every tool already looks for; the `id` is always kebab-case; a grouping property's value matches its folder exactly; and fields meant for tools are not names in the tree.
+One convention governs the whole folder, and changing it later means renaming files, so it is settled at init. Whichever you pick: `.eidos/` is always lowercase; `README.md` keeps the name every tool already looks for; a grouping property's value matches its folder exactly; and fields meant for tools are not names in the tree.
 
 ### Linking
 
@@ -238,87 +191,75 @@ If a target has no blueprint yet, name it plainly rather than fabricating a link
 
 ### Blueprint bodies
 
-The body follows its flavor's shape. Keep the shape's order and names; leave a section out when it genuinely doesn't apply rather than leaving it empty. Within and beneath those sections, write it like a person would read it — sub-headings, tables, lists, small diagrams wherever they make the meaning clearer. Keep checkable statements short and observable, labeled the way the shape asks, with supporting detail pushed into a table or sub-section they point at.
+The body follows its variant's template. Keep the template's order and names; leave a section out when it genuinely doesn't apply rather than leaving it empty. Within and beneath those sections, write it like a person would read it — sub-headings, tables, lists, small diagrams wherever they make the meaning clearer. Keep checkable statements short and observable, labeled the way the template asks, with supporting detail pushed into a table or sub-section they point at.
 
-The sections themselves are documented in the shape file, not here.
+The sections themselves are documented in the template file, not here.
 
-### Frames and top-level docs
+### Top-level docs
 
-Both are loose prose: record what is true now, revise when it changes. They differ in one way. A **frame** is a blueprint — it follows a shape, carries the frontmatter contract, and is validated. A **top-level doc** is one-of-a-kind, filled in once and edited in place, so it needs no shared shape and gets none. A shape earns its keep by being stamped again; a document written once doesn't need a cookie-cutter.
+Loose prose: record what is true now, revise when it changes. A top-level doc is one-of-a-kind, filled in once and edited in place, so it needs no shared template and gets none: a template earns its keep by being stamped again, and a document written once doesn't need a cookie-cutter. That is the whole difference from a blueprint, which follows a template, carries the frontmatter contract, and is validated, even in a collection the framework keeps as loose prose.
 
-For a top-level doc you've already drafted, `format` organizes it into the house style without adding anything of its own.
+## The index
 
-## Generated leaves
+One derived view the standard defines, regenerated wholesale, annotating rather than gating, with nothing hand-written to preserve.
 
-Two derived views. Both are regenerated wholesale, annotate rather than gate, and have nothing hand-written to preserve.
+**The index.** Every collection's blueprints, listed in the framework document under `index`, one list per collection, so a human or agent can find a blueprint without scraping the tree. Each entry is the blueprint's `id`, `title`, `summary` (null when absent, never invented), `path` relative to the collection folder, and `group` when it has one; entries are grouped by sub-folder when the collection has them, flat when it doesn't, in file order. Rebuilt by `index`, which rewrites that key and nothing else in the document.
 
-**The index.** Each collection carries a generated `index.md` in its folder, listing its blueprints — grouped under their sub-folders when it has them, flat when it doesn't. Each line is the blueprint's `summary`, verbatim; a blueprint with none is flagged, never invented. Links are relative to the collection folder. Rebuilt by `index`.
-
-In a root whose framework document is YAML there are no `index.md` files: every collection's index lives inside the framework document under `index`, one list per collection, each entry the blueprint's `id`, `title`, `summary` (null when absent, never invented), `path` relative to the collection folder, and `group` when it has one, in the order the markdown index would list them. The same `index` rebuilds it wholesale, rewriting that key and nothing else in the document.
-
-```markdown
-# <Collection>
-
-<!-- index: <Collection> (regenerated) -->
-
-## <Group>
-- [<Title>](<Group>/<Title>.md) — the blueprint's one-line `summary`, verbatim.
-- [<Title>](<Group>/<Title>.md) — one bullet per blueprint, in file order.
-```
-
-**The canvas.** The spatial counterpart: an Obsidian `.canvas` map. Each collection draws the way it declares itself, is its own group, and nests a group per sub-folder; each blueprint's `connects_to` links become directed edges (with `depends_on` optionally overlaid in another color). The generated `.canvas` is itself a top-level doc — register it in `## Top-Level`. The standard ships no generator; the declarations are there for whichever tool draws one.
+**Any other view is a tool's.** A map, a graph, a report: a tool that draws one reads the index and the links in the bodies, keeps whatever it needs in its own Properties block or its `plugins/` folder, and writes its output as a top-level doc, registered under `top_level` like any other. The standard declares nothing for it.
 
 ## Rules
 
 The load-bearing conventions.
 
-1. **The frontmatter is the agreement; the body is guidance.** Properties are checked against the framework's Schema. Body sections are recommended structure, not requirements.
-2. **The root owns its framework.** Shapes and properties live in the root's `_eidos/`. A skill reads the framework from the root it is working in, not from a copy of its own.
-3. **Validation is framework-defined.** A check reads *that framework's* Schema and enforces it — the core properties plus the custom ones scoped to the blueprint's collection. The contract is the Schema, not a rule hardcoded in a tool.
+1. **The frontmatter is the agreement; the body is guidance.** Properties are checked against the framework's Properties table. Body sections are recommended structure, not requirements.
+2. **The root owns its framework.** Templates and properties live in the root's `.eidos/`. A tool reads the framework from the root it is working in, not from a copy of its own. Anything a tool keeps there lives under `.eidos/plugins/<name>/`, and a tool touches only the folder it owns.
+3. **Validation is framework-defined.** A check reads *that framework's* Properties table and enforces it — the core properties plus the custom ones scoped to the blueprint's collection. The contract is the Properties table, not a rule hardcoded in a tool.
 4. **Portability over prescription.** A missing core property is surfaced and added with a note on why; a missing section is noted and offered. Never refuse the file.
 5. **Write it like a human would read it.** The sections are a scaffold for a living blueprint, not a form to pour text into. If a blueprint reads like filled-in boilerplate, reshape it until it reads like someone wrote it.
 6. **Reference other blueprints with links, not bare names** — in prose and in properties alike. Each blueprint's `id` is still its permanent identity, sitting behind the link.
-7. **One shape family per collection, declared as flavors.** What flexes is *which* sections appear and *which* flavor a blueprint uses; never their order or names within a flavor. The shape is never forked per category.
-8. **Properties carry a type and a meaning.** Every property declares its name, its type, which collections it applies to, and what it means. Frontmatter is generated from the Schema, so a new blueprint is born conforming.
-9. **Soft labels are views, not structure.** A category label a framework adds drives views and filtering, never structure. An off-list value is valid. `flavor` carries the structural choice.
+7. **One template family per collection, declared as variants.** What flexes is *which* sections appear and *which* variant a blueprint uses; never their order or names within a variant. The template is never forked per category.
+8. **Properties carry a type, a meaning, and an owner.** Every property declares its name, its type, which collections it applies to, and what it means; the block it sits in says who owns it (Eidos, the framework, or a tool), and only the owner writes there. Frontmatter is generated from the Properties table, so a new blueprint is born conforming.
+9. **Soft labels are views, not structure.** A category label a framework adds drives views and filtering, never structure. An off-list value is valid. `variant` carries the structural choice.
 10. **A collection's grouping is the collection's own.** It may group its blueprints one level deep and may declare a property naming that grouping; the value then matches the folder, and an unknown value warns rather than blocks. The standard never names a grouping for it.
-11. **A shape names its own stable part.** Every shape has a part that holds still and a part that moves, and says which is which. If the stable part changes substantially, ask whether this is a different blueprint.
-12. **Non-goals carry the most weight.** Where a shape declares a section for what a blueprint deliberately will *not* do, that section is its strongest — it is where scope management actually happens. Still not a hard gate.
-13. **A shape documents its own conventions.** Section names, their order and meaning, and any labeling a shape asks for live in the shape file. This standard governs collections, shapes, flavors, and properties; it never governs a section.
-14. **No work-tracking fields.** No `sprint`, `estimate`, or `assignee` — the moment you add them, a blueprint becomes a task and rots. Bridge to a tracker with a link. The same holds in the body: a section describing how you mean to build a thing captures intent, never how far along it is.
-15. **The Eidos version is a framework fact.** It lives in the framework document, never as a per-blueprint property. Git holds the history; a framework that wants date properties declares them like any other.
+11. **A template names its own stable part.** Every template has a part that holds still and a part that moves, and says which is which. If the stable part changes substantially, ask whether this is a different blueprint.
+12. **Non-goals carry the most weight.** Where a template declares a section for what a blueprint deliberately will *not* do, that section is its strongest — it is where scope management actually happens. Still not a hard gate.
+13. **A template documents its own conventions.** Section names, their order and meaning, and any labeling a template asks for live in the template file. This standard governs collections, templates, variants, and properties; it never governs a section.
+14. **No work-tracking fields.** No `sprint`, `estimate`, or `assignee` — the moment you add them, a blueprint becomes a task and rots. Bridge to a tracker with a link. The same holds in the body: a section describing how you mean to build a product captures intent, never how far along it is.
+15. **The Eidos version is a framework fact.** The standard's version lives in the framework document as `eidos_version`, never as a per-blueprint property. Git holds the history, and a tool that snapshots the root keeps its record in its own `plugins/` folder; a framework that wants date properties declares them like any other.
 16. **Loose prose is revised in place.** A top-level doc, and any collection a framework marks as loose prose, records what is true now and is expected to change. That is revision, not work status.
 17. **The human authors; the agent facilitates.** Intent, scope, and decisions stay with the person. An agent formats, supplements, asks, and holds scope; it does not generate finished blueprints or set direction. A blueprint the owner did not think through is worse than none.
-18. **Read the actor before acting.** Read `_eidos/me.md` and the matching contract in `_eidos/roles/`, and respond as that role defines. The human-first principle holds for every role; only the mode changes. A blank or absent file defaults to full facilitation.
-19. **Every framework declares a framing collection.** Its name, its flavors, and how many it carries are the framework's own — a framework needs framing, not a particular set of frames. Required as a **declaration**: a framework that declares none is incomplete and a check says so. Never a gate: a declared frame left unwritten is a gap to surface, not a failure.
+18. **Read `me.md` before acting.** Read `.eidos/me.md` and the matching contract in `.eidos/roles/`, and respond as that role defines. The human-first principle holds for every role; only the mode changes. A blank or absent file defaults to full facilitation.
+19. **A declared term is the word.** Where the framework's Vocabulary declares a term, blueprints use it, and a near-miss it names is flagged with the declared term beside it, never refused and never swapped in silently. The standard declares no term of a framework's; a Vocabulary starts empty and grows a row at a time, each saying what the word means and what it is not.
 
 ## Versioning
 
 Semantic Versioning: major for breaking changes, minor for backward-compatible additions, patch for clarifications.
 
-This file holds the version of **the standard** — right now, **4.5.0** — and it moves only when the text of this file moves. A framework records the version it targets as `eidos_version` in its framework document; `migrate` reads and bumps it there. At tag time this file is copied as-is into `versions/` under its full semver name, so any two releases, even non-adjacent, can be diffed to migrate between them. Worked hops are in `versions/MIGRATIONS.md`. Tools may reject an unsupported version.
+This file holds the version of **the standard** — right now, **5.0.0** — and it moves only when the text of this file moves. A framework records the version it targets as `eidos_version` in its framework document; a migration reads and bumps it there. At tag time this file is copied as-is into `versions/` under its full semver name, so any two releases, even non-adjacent, can be diffed to migrate between them. Worked hops are in `versions/MIGRATIONS.md`. Tools may reject an unsupported version.
 
-**The plugin that ships this standard versions separately.** The skills and seeds change far more often than the standard does, so a release that fixes a skill bumps the plugin and leaves this file — and every framework's `eidos_version` — untouched. When you need to know what a framework conforms to, read this version; the plugin's is in `.claude-plugin/plugin.json`, and `CHANGELOG.md` records which standard each plugin release carried.
+**Tools that ship this standard version separately.** A CLI, a plugin, a starting framework: each changes far more often than the standard does, so a release of one leaves this file — and every framework's `eidos_version` — untouched. When you need to know what a framework conforms to, read this version; a tool names the standard it carries.
 
 ## For an agent
 
-_Operating detail. A human can stop above._
+*Operating detail. A human can stop above.*
+
+**If you have a shell, use the CLI.** Check for one first, every session: a host that has none today may have one after its next update. Run `eidos instructions` and follow it; it does the mechanical part deterministically and hands you only what you need. On a host with no shell, the Eidos skills stand in; each says when it applies.
 
-**Prefer the tooling.** The `eidos` command does the mechanical part: `init` scaffolds a root, `new` generates a conforming blueprint, `check` validates, `index` rebuilds the indexes, and `eidos instructions` prints the workflow. The skills carry the judgment: `eidos` authors and validates with the owner, `iterate` questions a rough idea into shape before any of that, `format` reshapes a draft already written, `install` scaffolds, `configure` adds a collection, flavor, or property and keeps the framework current, `index` rebuilds a collection's leaf, `whoami` sets the actor, `migrate` upgrades versions.
+**Find the framework in the root.** Locate the root by its `.eidos/` marker, not its name. Every operation reads that `.eidos/`. If a folder has none, offer to create a root. Check the framework's `eidos_version` against the standard you carry once per session: a gap is worth one line and an offer to migrate, never a block, and the framework in front of you is the operative contract either way. Never fall back to a hardcoded contract, and never assume a collection or section name — read what the framework declares. Leave `.eidos/plugins/` alone unless you are the tool that owns a folder in it; a folder you don't recognize there is not a problem to report.
 
-**Find the framework in the root.** Locate the root by its `_eidos/` marker, not its name. Every operation reads that `_eidos/`. If a folder has none, offer `install`. Check the framework's `eidos_version` against the standard you carry once per session: a gap is worth one line and an offer of `migrate`, never a block, and the framework in front of you is the operative contract either way. Never fall back to a hardcoded contract, and never assume a collection or section name — read what the framework declares.
+**Read `me.md` first.** Then the role file it names. Respond as that file defines the role — read it, don't infer from its filename. A framework defines its own cast.
 
-**Read the actor first.** `_eidos/me.md`, then the role file it names. Respond as that file defines the role — read it, don't infer from its filename. A framework defines its own cast.
+**Speak the root's terms.** The framework's Vocabulary says which word is the word and what it is not. Use the declared term in what you write; where the owner's draft or speech uses a near-miss, say which term the Vocabulary declares and ask, rather than substituting silently. A word the owner keeps using that no row declares is worth naming as a candidate; declaring it is the owner's call.
 
-**Navigate by the leaves.** `README.md` for orientation, the framework document (`_eidos/Framework.md` or `.yaml`) for the full index, each collection's `index.md` for its blueprints (or the document's `index`, in a YAML root). Read these instead of scraping the tree; regenerate them when stale.
+**Navigate by the index.** `README.md` for orientation, then `.eidos/Framework.yaml`: its `top_level` and `collections` for what the root holds, its `index` for every collection's blueprints. Read it instead of scraping the tree; regenerate the index when stale.
 
 **Authoring a blueprint:**
 
-1. From the framework document, take the Schema, the naming convention, and the target collection's flavors. Pick a flavor (the default unless the owner chooses another) and read its shape for the body. Name the file for its title in the convention; put a permanent kebab-case `id` inside.
+1. From the framework document, take the Properties table, the Vocabulary, the naming convention, and the target collection's variants. Pick a variant (the default unless the owner chooses another) and read its template for the body. Name the file for its title in the convention; put a permanent `id` inside, in whatever form the root uses.
 2. Generate frontmatter from the properties that apply to that collection. Fill values from what the owner tells you; leave a property blank rather than guessing it.
-3. Lead with the shape's opening sections and press hardest on its non-goals section. Read those names off the shape rather than assuming them, and follow whatever labeling it asks for. Omit a section that doesn't apply; keep the order and names of the ones that do.
+3. Lead with the template's opening sections and press hardest on its non-goals section. Read those names off the template rather than assuming them, and follow whatever labeling it asks for. Omit a section that doesn't apply; keep the order and names of the ones that do.
 4. Where the owner is vague, ask. Don't fill the gap with plausible prose.
 
-**Validating a blueprint:** check frontmatter against the framework's Schema (`id` kebab-case, dates as `YYYY-MM-DD`, custom properties scoped to the collection). Report missing body sections against *the blueprint's flavor shape*, flagging an absent non-goals section first, and note anything skipping the labeling that shape asks for. Confirm no work-tracking fields crept in. Surface, don't block — the output is a review a human acts on.
+**Validating a blueprint:** check frontmatter against the framework's Properties table, every block of it (`id` present and unique, dates as `YYYY-MM-DD`, custom and tool properties scoped to the collection). Report missing body sections against *the blueprint's variant template*, flagging an absent non-goals section first, and note anything skipping the labeling that template asks for. Note each near-miss the Vocabulary names, with the declared term beside it. Confirm no work-tracking fields crept in. Surface, don't block — the output is a review a human acts on.
 
 **Facilitate, don't author.** Format and structure what the owner gives you, supplement, ask, and press on scope. Never invent a blueprint's purpose, decide direction, or hand back a finished blueprint to rubber-stamp. When unsure, ask.

package/standard/seeds/README.md

@@ -1,6 +1,6 @@
 # Seeds
 
-The starting **frameworks** Eidos ships. A seed is a complete structure layer — collections, body shapes and their flavors, roles, and a property Schema — that [`install`](../skills/install) copies into a new root's `_eidos/`. Pick the one nearest what you're defining; reshape it from there with `configure`.
+The starting **frameworks** Eidos ships. A seed is a complete structure layer — collections, body templates and their variants, roles, a Properties table, and an empty Vocabulary and Versions — that `eidos init` copies into a new root's `.eidos/`. Pick the one nearest what you're defining; reshape it from there with the `eidos` CLI.
 
 | Seed | For | Collections |
 | --- | --- | --- |
@@ -8,18 +8,18 @@ The starting **frameworks** Eidos ships. A seed is a complete structure layer
 | [`book/`](book) | a book, long-form argument, or course | `Frames` (premise, reader, voice, market) · `Chapters` by part |
 | [`research/`](research) | a question, a study, or a programme of inquiry | `Frames` (question, prior work, method, ethics) · `Investigations` by strand |
 
-Every seed carries the same pieces, so the skills work identically across them:
+Every seed carries the same pieces, so the `eidos` CLI works identically across them:
 
 ```txt
 <seed>/
-  shapes/       # body shapes, one file per flavor (<kind>.<flavor>.md)
+  templates/       # body templates, one file per variant (<unit>.<variant>.md)
   roles/        # response contracts, one per role
-  Framework.md  # version, naming, Top-Level, Collections, and the property Schema
-  me.md         # blank actor frame (installs gitignored)
+  Framework.yaml # version, naming, top_level, collections, properties, vocabulary, and versions (and the index, once blueprints exist)
+  me.md         # blank me.md, who is in the seat (installs gitignored)
   .gitignore    # keeps me.md out of version control
   README.md     # the {{Product}} front-door template
 ```
 
 **Three seeds, one standard.** `software` is the default and the one the standard teaches from, but nothing in Eidos knows a collection by name: `book` calls its units `Chapters` and groups them by `part`, `research` calls them `Investigations` and groups them by `strand`, and both work the same way the software seed does. A seed is a starting point, not a cage — and it's the same kind of artifact you'd publish for someone else to start from.
 
-**None of these fit?** Start from the nearest and reshape it, or scaffold your own collections with `configure`.
+**None of these fit?** Start from the nearest and reshape it, or scaffold your own collections with the `eidos` CLI.