eidosmd 0.2.0 → 0.3.0

package/standard/EIDOS.md

@@ -1,265 +1,207 @@
 # Eidos
 
-**Version:** 5.0.0
-
-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 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                                                                                                                                                                                                                                              |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **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.
+**Version:** 5.3.0
+
+Eidos is a way to define a product in markdown: an app, a book, a study, anything work produces that has a shape. The structure is data in a hidden folder that a tool can check against; the product is written in markdown against that structure. One file is the complete source of truth for one unit of the product, as true of something planned as of something long shipped.
+
+This file is the contract: the terms, the layout, and the rules. It names no collection, template, or section; those belong to a framework.
+
+## Terms
+
+| Term              | What it is                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| **product**       | What you are defining.                                                                                                         |
+| **framework**     | How the files are organized: folders, templates, properties, vocabulary, roles. Lives in `.eidos/`; one framework can govern many products. |
+| **root**          | The folder it all lives in. Found by the `.eidos/` inside it, never by its name.                                               |
+| **folder**        | A top-level folder in the root, declared with a type: `collection`, `assets`, or `other`.                                       |
+| **collection**    | A folder of blueprints of one kind: specs, chapters, investigations. Its sub-folders, if any, are its declared groups.          |
+| **blueprint**     | One markdown file in a collection, defining one unit of the product completely: properties on top, a body below.               |
+| **unit**          | What one blueprint defines: a spec, a chapter, an investigation. Templates are named for it, singular.                          |
+| **template**      | The body a collection's blueprints follow: sections in order, under set names. Body only. One file per variant in `.eidos/templates/`. |
+| **variant**       | One of a collection's templates (`<unit>.<variant>.md`). One is the default; a blueprint on another says so in `variant`.       |
+| **property**      | One frontmatter field: name, type, which collections it applies to, whether required, meaning, and options when closed. The whole table is the framework's Properties. |
+| **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, listed in the framework document. No template; the body is never validated.                  |
+| **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, `.eidos/plugins/<name>/`. The standard reads none of it.                                                   |
+| **region**        | A span in a markdown file that a tool owns, fenced by two HTML comments carrying its name. The standard reads none of it.        |
+
+A task describes work and dies when it ships. A blueprint describes the product and stays accurate for its whole life.
 
 ## Layout
 
-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)
-  <Collection>/          # a collection of blueprints; declare as many as the work needs
-    <Group>/             #   one level of sub-folders, at most
+Blueprints/              # the root; any name works, this is the default
+  .eidos/                # the framework
+    plugins/<name>/      #   a tool's own folder; local.yaml inside it is personal (gitignored)
+    roles/<role>.md      #   response contracts; framework-owner.md is always one
+    templates/           #   <unit>.<variant>.md, one per variant
+    .gitignore           #   ignores me.md and plugins/*/local.yaml
+    Framework.yaml       #   the framework document
+    me.md                #   who is in the seat (personal, gitignored)
+  <Assets>/              # type assets: files that are not markdown
+  <Collection>/          # type collection: blueprints
+    <Group>/             #   a declared group; nothing deeper
       <Title>.md         #     one blueprint per file
-  <Doc>.md               # a top-level doc — optional, yours
+  <Other>/               # type other: the owner's, described and left alone
+  <Doc>.md               # a top-level doc, listed under top_level
 ```
 
-## The framework (`.eidos/`)
+**Everything at the root is declared.** A folder is `.eidos/` or declared under `folders`; a file is listed under `top_level`. Anything else is surfaced, and the owner declares it or moves it. Hidden entries (`.git`, `.obsidian/`) are the host's and exempt.
 
-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.
+### Folders
 
-```txt
-.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 role that holds intent, scope, and decisions
-    <role>.md              #   the rest are the framework's own
-  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
-```
+| Type         | Holds                                              | The standard                                                                              |
+| ------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `collection` | blueprints, optionally in declared groups          | generates, validates, and indexes the markdown files; ignores any other file              |
+| `assets`     | files that are not markdown                        | reads nothing inside; the folder's name follows `naming`, the files keep their own       |
+| `other`      | whatever the description says                      | reads nothing inside; the folder is declared and otherwise left alone                     |
 
-### Plugins
+A collection is flat or grouped. Grouped, every sub-folder is a declared group, and a group holds blueprints and nothing deeper. A grouping property's value is the group's name; an unknown value warns.
 
-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`.
+### Plugins
 
-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.
+The top level of `.eidos/` is the standard's. A tool keeps what it needs in `.eidos/plugins/<name>/` and touches nothing else. The name is one identifier everywhere the tool appears (its folder, its Properties block, its regions): lowercase letters, digits, hyphens, unique in the root; `eidos` is reserved. A check never faults a plugin folder and a migration carries it across untouched. `local.yaml` inside it is one person's settings and is never committed.
 
 ### `Framework.yaml`
 
-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.
+One per root, `Framework.yaml` or `.yml`, snake_case, comments welcome. Every path is relative to `.eidos/`.
 
 ```yaml
-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:                  # one entry per collection
+eidos_version: 5.3.0
+naming: kebab-case            # kebab-case (default) | TitleCase | Title Case
+top_level:
+  - { title: <Title>, path: ../<Doc>.md, description: one line }
+folders:
   - name: <Collection>
-    description: One line on what this collection holds.
+    type: collection
+    description: one line
     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 }
+      - { name: <variant>, template: templates/<unit>.<variant>.md, description: one line, default: true }
     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 }
+        - { name: <Group>, description: one line }
+  - { name: <Assets>, type: assets, description: one line }
 properties:
-  core: []                    # absent = the standard's core for this eidos_version
+  core: []                    # the standard's; empty = the 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., <tool>: { <field>: <value> } }
-  tools:                      # one block per tool that declares properties of its own; absent = none
+    - { name: <name>, type: Text, applies_to: all, required: true, meaning: one line }
+    - { name: <name>, type: Text, applies_to: [<Collection>], options: [<Value>, <Value>], meaning: one line }
+  tools:
     <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
+      - { name: <name>, type: Text, applies_to: all, meaning: one line }
+vocabulary:
+  - { term: <Term>, means: one line, not: ["<near-miss>, and why"], see: ../<Collection>/<Title>.md }
+index:                        # generated; never hand-edited
   <Collection>:
-    - { id: <id>, title: <Title>, summary: <the summary>, path: <Group>/<Title>.md, group: <Group> }
+    - { id: <id>, title: <Title>, summary: <summary>, path: <Group>/<Title>.md, group: <Group> }
 ```
 
-- **`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.
-
-### Templates and variants
+- **`top_level`**: every file at the root, each a `title`, `path`, and `description`.
+- **`folders`**: every folder at the root, each a `name`, `type`, and `description`. A `collection` also carries `variants` (`default` marks one; absent, the first is) and `grouping`. An unknown type is a fault.
+- **`properties`**: one block per owner. `core` is the standard's, rewritten by a migration. `custom` is the owner's. `tools.<tool>` is that tool's alone. The six keys the standard names are the standard's; any other key on an entry is a tool's.
+- **`vocabulary`**: the root's own terms. Starts empty.
+- **`index`**: every collection's blueprints, rebuilt wholesale by whatever indexes the root, which touches no other key.
 
-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.
+### Templates
 
-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.
+A template is body only: sections in order, under set names, with guidance. Frontmatter in a template is a fault. The file is `<unit>.<variant>.md`, lowercase. A blueprint is validated against the variant it names; a lighter variant is never faulted for sections only a fuller one has.
 
 ### Properties
 
-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.
+Each entry: `name`, `type`, `applies_to`, `required`, `meaning`, and `options` when the value is one of a closed set.
 
-**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.
+- **type** is one of Text, List, Number, Checkbox, Date, Date & time.
+- **applies_to** is `all` or a list of collections.
+- **required** (absent = `false`): a required property is generated into every new blueprint and surfaced when missing. An optional one is written when it has a value; its absence is never a gap.
+- **options**: an ordered, non-empty list of allowed values, compared exactly. An off-list value is surfaced, never refused. An empty list is a fault. No default rides with it. `variant` and a grouping property take their sets from the structure and never carry `options`.
 
-**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 block a property sits in owns it, and only the owner writes there. The core:
 
-**The core** — present on every blueprint, and the whole of what the standard requires:
+| Name      | Type | Required | Meaning                                                                      |
+| --------- | ---- | -------- | ---------------------------------------------------------------------------- |
+| `id`      | Text | yes      | Stable, unique identity, in any form. Assigned once, never changed.          |
+| `title`   | Text | yes      | Human-readable name. Rename freely; `id` holds still.                        |
+| `summary` | Text | no       | One line: what this blueprint is. Feeds the index; absent, the index flags it. |
+| `variant` | Text | no       | Which variant this blueprint follows. Absent = the collection's default.     |
 
-| 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.
+Eidos defines no custom properties. Status, dates, grouping, dependencies: all the framework's choice.
 
 ### 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.
-
-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.
+Each entry: `term`, `means`, `not` (the near-misses and why each differs), and `see` when a blueprint defines it in full. Eidos declares none of a root's terms. Where a term is declared, blueprints use it; a near-miss is flagged with the term beside it, never swapped in silently.
 
 ### 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. 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 every framework has: the **Framework Owner**, who holds the intent, the scope, and the decisions. The rest of the cast depends on the work.
+`.eidos/roles/<role>.md` says how an agent responds to one kind of person: depth, what to surface, who decides. Every framework has a Framework Owner, who holds intent, scope, and decisions. `.eidos/me.md` names your role and calibrates it on ownership, experience with the scope, and technical capacity. Blank is fine.
 
 ## Writing
 
-### `README.md`
-
-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.
+Everything a human reads in the tree follows `naming`. Absent means `kebab-case`.
 
-| 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 |
+| Convention               | A blueprint file          | A group folder | Trade                                  |
+| ------------------------ | ------------------------- | -------------- | -------------------------------------- |
+| **kebab-case** (default) | `blueprint-title-here.md` | `group-name/`  | readable everywhere, no `%20`          |
+| **TitleCase**            | `BlueprintTitleHere.md`   | `GroupName/`   | space-free, capitalized                |
+| **Title Case**           | `Blueprint Title Here.md` | `Group Name/`  | reads like prose, `%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; a grouping property's value matches its folder exactly; and fields meant for tools are not names in the tree.
+Exceptions: `.eidos/` is lowercase, `README.md` keeps its name, a grouping value matches its folder exactly, and nothing inside an `assets` or `other` folder is held to the convention.
 
 ### Linking
 
-Point at another blueprint, doc, or section with a standard markdown link: the text is the human title, the path is the target's filename in the framework's convention (only a Title Case tree carries `%20`). Add a `#heading` anchor for a section. Properties that point outward hold links too, not bare ids — quote them in YAML, since a leading `[` starts a list:
-
-```yaml
-depends_on:
-  - "[Some Blueprint](../some-group/some-blueprint.md)"
-```
-
-If a target has no blueprint yet, name it plainly rather than fabricating a link.
+A standard markdown link, path relative to the file it sits in, text the human title, `#heading` for a section. Properties that point outward hold links too, quoted in YAML. Files that are not blueprints are linked or embedded the same way (`![Login flow](../assets/login-flow.png)`): no wikilinks, no absolute paths, no resolution by filename. A check verifies the path resolves. If a target has no blueprint yet, name it plainly.
 
-### Blueprint bodies
+### Bodies
 
-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.
+A blueprint's body follows its variant's template: keep the order and names, leave out a section that doesn't apply rather than leaving it empty, and write it like a person would read it. A top-level doc is loose prose, revised in place, with no template.
 
-The sections themselves are documented in the template file, not here.
+### Regions
 
-### Top-level docs
-
-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.
+A tool keeps what it needs inside a markdown file between `<!-- <tool>:<region> <args> -->` and `<!-- /<tool>:<region> -->`, each alone on its line. `<args>` is optional `key=value` pairs. Inside is the tool's, rewritten wholesale; outside is the person's. A region closes at the first matching closer (`-->` or `--!>`); a marker inside a fenced code block is text. An opener with no closer is faulted; a region for an unknown tool never is. Frontmatter holds no regions.
 
 ## The index
 
-One derived view the standard defines, regenerated wholesale, annotating rather than gating, with 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.
-
-**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.
+The one derived view the standard defines. Every collection's blueprints, under `index`: `id`, `title`, `summary` (null when absent, never invented), `path` relative to the collection, and `group`. Grouped by group when the collection has them, in file order. Any other view is a tool's, written as a top-level doc.
 
 ## Rules
 
-The load-bearing conventions.
-
-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 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 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 `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.
+1. **The frontmatter is the agreement; the body is guidance.** Properties are checked. Sections are recommended.
+2. **The root owns its framework.** A tool reads the framework from the root it is in, never from a copy of its own.
+3. **Validation is framework-defined.** A check enforces that framework's Properties table, nothing hardcoded.
+4. **Surface, never refuse.** A missing required property is added with a note; a missing section is offered. Never refuse the file.
+5. **Write it like a human would read it.** If it reads like filled-in boilerplate, reshape it.
+6. **Reference blueprints with links, not bare names,** in prose and properties alike. `id` sits behind the link.
+7. **One template family per collection, as variants.** What flexes is which sections appear; never their order or names.
+8. **Every property has a type, a meaning, and an owner.** Frontmatter is generated from the required ones, so a new blueprint is born conforming.
+9. **Soft labels are views, not structure.** A category property drives filtering, never structure. `variant` carries the structural choice.
+10. **A collection's grouping is its own.** Every sub-folder is a declared group; a group holds blueprints and nothing deeper.
+11. **A template names its own stable part.** If the stable part changes substantially, ask whether this is a different blueprint.
+12. **Non-goals carry the most weight.** Where a template has a section for what a blueprint will not do, that section is its strongest.
+13. **A template documents its own conventions.** The standard governs folders, templates, variants, and properties; never a section.
+14. **No work-tracking fields.** No sprint, estimate, or assignee; bridge to a tracker with a link. Intent, never progress.
+15. **The Eidos version is a framework fact,** in `eidos_version`, never on a blueprint.
+16. **Loose prose is revised in place.** That is revision, not work status.
+17. **The human authors; the agent facilitates.** Intent, scope, and decisions stay with the person.
+18. **Read `me.md` before acting,** then the role it names. Blank means full facilitation.
+19. **A declared term is the word.** A near-miss is flagged, never swapped silently.
+20. **A region is a tool's, by name.** Inside is the tool's; outside is the person's.
+21. **Everything at the root is declared.** Every folder has a type, every file an entry, and nothing is declared that isn't there.
 
 ## 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, **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.
-
-**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.
+Semantic Versioning. This file's version moves only when its text moves; a framework records the version it targets as `eidos_version`. Each release is frozen in `versions/` and the worked hops are in `versions/MIGRATIONS.md`. Tools ship their own version and may reject an unsupported standard.
 
 ## For an agent
 
-*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.
-
-**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.
-
-**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.
-
-**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 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 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 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 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.
+- **Use the CLI when you have a shell.** Run `eidos instructions`. Without one, the Eidos skills stand in.
+- **Find the root by `.eidos/`,** never by name. Read that framework; never assume a folder, section, or property name. Check `eidos_version` once per session; a gap is one line and an offer, never a block.
+- **Read `me.md` first,** then the role file. Speak the root's declared terms.
+- **Leave plugins and regions to their owners.** Carry them across as found; fault only an opener with no closer.
+- **Navigate by the framework document,** not the tree: `top_level`, `folders`, `index`. Check the root against it and surface what is missing on either side; never invent a description, never delete a file.
+- **Authoring:** take the Properties table, Vocabulary, naming, and the collection's variants; generate frontmatter from the required properties; follow the template's sections, pressing hardest on non-goals; where the owner is vague, ask.
+- **Validating:** frontmatter against every block of the Properties table; body against the blueprint's variant; links resolve; no work-tracking fields; near-misses flagged. Surface, don't block.
+- **Facilitate, don't author.** Never invent a blueprint's purpose or hand back a finished one to rubber-stamp.

package/standard/seeds/README.md

@@ -1,25 +1,21 @@
 # Seeds
 
-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.
+The starting frameworks Eidos ships. A seed is a complete `.eidos/` (templates, roles, `Framework.yaml`, `me.md`, `.gitignore`) plus a root `README.md`; `eidos init` installs the one you pick. Reshape it from there.
 
-| Seed | For | Collections |
+| Seed | For | Folders |
 | --- | --- | --- |
-| [`software/`](software) | a product, service, or system being built | `Frames` (architecture, audience, criteria, market) · `Specs` by domain |
-| [`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 `eidos` CLI works identically across them:
+| [`software/`](software) | a product, service, or system being built | `Frames` (architecture, audience, criteria, market) · `Specs` by domain · `assets` |
+| [`book/`](book) | a book, long-form argument, or course | `Frames` (premise, reader, voice, market) · `Chapters` by part · `assets` |
+| [`research/`](research) | a question, a study, or a programme of inquiry | `Frames` (question, prior work, method, ethics) · `Investigations` by strand · `assets` |
 
 ```txt
 <seed>/
-  templates/       # body templates, one file per variant (<unit>.<variant>.md)
-  roles/        # response contracts, one per role
-  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
+  roles/           # response contracts, one per role
+  templates/       # body templates, <unit>.<variant>.md
+  .gitignore       # keeps me.md and plugins/*/local.yaml out of version control
+  Framework.yaml   # the framework document
+  me.md            # blank; who is in the seat (personal)
+  README.md        # the {{Product}} front door, installed at the root
 ```
 
-**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 the `eidos` CLI.
+Nothing in Eidos knows a folder by name: `software` is the default, and the other two run the same machinery under different words. None fit? Start from the nearest and reshape it with the `eidos` CLI.