eidosmd 0.1.0

package/standard/EIDOS.md

@@ -0,0 +1,324 @@
+# Eidos
+
+**Version:** 4.5.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.
+
+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).
+
+## 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.
+
+## 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)
+  <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
+  <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
+```
+
+Several roots in one repository nest as `Blueprints/<name>/…`, each with its own `_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/`.
+
+```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
+  roles/                   # response contracts, committed and team-tunable
+    framework-owner.md     #   the one every seed carries
+    <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
+```
+
+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>
+
+The framing docs — declared first.
+
+- **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).
+
+### `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.
+
+```yaml
+eidos_version: 4.5.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
+  - 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 }
+    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:
+  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
+  <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.
+
+### Shapes and flavors
+
+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.
+
+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.
+
+### Schema
+
+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.
+
+**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.
+
+**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. |
+
+**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.
+
+### Roles and the actor
+
+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.
+
+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.
+
+## 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.
+
+### 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 |
+
+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.
+
+### 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.
+
+### 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 sections themselves are documented in the shape file, not here.
+
+### Frames and 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.
+
+For a top-level doc you've already drafted, `format` organizes it into the house style without adding anything of its own.
+
+## Generated leaves
+
+Two derived views. Both are regenerated wholesale, annotate rather than gate, and have nothing hand-written to preserve.
+
+**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.
+
+## 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.
+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.
+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.
+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.
+
+## 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.
+
+**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.
+
+## For an agent
+
+_Operating detail. A human can stop above._
+
+**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 `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 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.
+
+**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.
+
+**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.
+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.
+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.
+
+**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

@@ -0,0 +1,25 @@
+# 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`.
+
+| Seed | For | Collections |
+| --- | --- | --- |
+| [`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 skills work identically across them:
+
+```txt
+<seed>/
+  shapes/       # body shapes, one file per flavor (<kind>.<flavor>.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)
+  .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`.

package/standard/seeds/book/Framework.md

@@ -0,0 +1,87 @@
+---
+# The Eidos version this framework targets; migrate reads and bumps it.
+eidos_version: 4.5.0
+# How files, folders, and links are named: kebab-case | TitleCase | Title Case. Absent = kebab-case.
+naming: kebab-case
+---
+
+# Framework
+
+The framework's index and config, in one place: the version and naming convention above, and below the
+Top-Level documents, the Collections (with their flavors and grouping), and the property Schema. The
+visible `README.md` at the root is the friendly door to it; keep it current with the
+`configure` skill.
+
+## Top-Level
+
+<!-- configure: top-level index (regenerated) -->
+- [README](../README.md) — the root's front door: what this book is, and pointers in.
+<!-- One bullet per top-level document. README is the door and comes first; add your own below (an
+     Outline, a Synopsis, the generated Blueprint Map canvas), each a link and a one-line description.
+     The framing docs live in the Frames collection, not here. configure refreshes this list. -->
+
+## Collections
+
+A collection is a top-level folder of repeated blueprints that share a body shape. `Frames` holds the
+framing docs — the most primary thing the folder says about itself — and `Chapters` the book's
+units. Add more with `configure`. Each lists its flavors (the default marked), how it draws on
+the canvas, and its grouping, and points at its generated `index.md` leaf.
+
+### Frames
+
+The framing docs that set what every chapter is judged against — what the book argues, who it is for,
+how it sounds, and where it sits. This framework's framing collection; each frame follows the flavor
+of its kind, and one left unwritten is a gap to surface, not a failure.
+
+- **Leaf:** [Frames/index.md](../Frames/index.md)
+- **Flavors:**
+  - [premise](shapes/frame.premise.md) — what the book says, and why it has to exist (default).
+  - [reader](shapes/frame.reader.md) — who it is for, and what changes for them.
+  - [voice](shapes/frame.voice.md) — person, tense, register, and the rules the prose keeps.
+  - [market](shapes/frame.market.md) — shelf, comparables, and how it reaches readers.
+- **Canvas:** file
+
+### Chapters
+
+The book's units, one per chapter, grouped by part.
+
+- **Leaf:** [Chapters/index.md](../Chapters/index.md)
+- **Flavors:**
+  - [full](shapes/chapter.full.md) — the complete chapter shape (default).
+  - [sketch](shapes/chapter.sketch.md) — Intent, Open Questions, What Happens, Out of Scope; grow into full.
+- **Canvas:** card from `## Intent`
+- **Parts:** _(add one bullet per part — a name and a short description — as parts accrue)_
+
+## Schema
+
+The property contract — what a blueprint's frontmatter may carry, across every collection. Two parts: the
+**core** properties Eidos's own machinery uses, and the **custom** ones you (or the seed) add. Every
+custom property declares which collections it **applies to** — `all`, or a list — so a property never
+lands where it makes no sense (`part` is Chapters-only). A property's type comes from the Obsidian set
+(Text, List, Number, Checkbox, Date, Date & time), so frontmatter renders natively in an Obsidian
+vault. The `configure` skill edits this section.
+
+### Eidos Core
+
+_Present on every blueprint. Managed by the standard (Eidos 4.5.0); `migrate` rewrites this block on a version change — don't hand-edit it. (`flavor` absent = the collection's default; `connects_to` absent = no canvas edges; a missing `summary` is flagged by the index.)_
+
+| Name        | Type | Meaning                                                                                        |
+| ----------- | ---- | ---------------------------------------------------------------------------------------------- |
+| id          | Text | Stable, unique, kebab-case identity. Assigned once, never renamed. References point at it.      |
+| title       | Text | Human-readable name.                                                                           |
+| summary     | Text | One plain line — what this blueprint is, in a sentence, distilled from Intent. Source for the collection index.md listing; absent, the index flags it. |
+| flavor      | Text | Which body flavor this blueprint follows, from its collection's declared flavors. Absent = the collection's default flavor. |
+| connects_to | List | Blueprints this one connects to on the canvas, each a markdown link; drawn as a directed edge (this → target). The intentional map, distinct from depends_on. |
+
+### Custom Properties
+
+_Yours to shape with the `configure` skill. The seed ships a few useful defaults below — keep, scope, or drop any of them; Eidos doesn't depend on them. Absence where a property applies is a soft gap the validator notes, never refuses._
+
+| Name          | Type | Applies To | Meaning                                                                                    |
+| ------------- | ---- | ---------- | ------------------------------------------------------------------------------------------ |
+| status        | Text | all        | Lifecycle value: Draft / Outlined / Drafted / Revised / Final / Cut. An off-list value warns. |
+| date_created  | Date | all        | YYYY-MM-DD. The day the blueprint was first written. Set once.                                   |
+| date_modified | Date | all        | YYYY-MM-DD. The day the blueprint was last changed.                                              |
+| tags          | List | all        | Free tags.                                                                                  |
+| part          | Text | Chapters   | The grouping, matching the blueprint's sub-folder under its collection in the naming convention. An unknown value warns, never fails. |
+| depends_on    | List | Chapters   | Chapters a reader must have read first, each a markdown link. A reading dependency, not a canvas edge. |

package/standard/seeds/book/README.md

@@ -0,0 +1,22 @@
+# {{Product}}
+
+> **Start here.** This is the root for **{{Product}}** — the source of truth for what this
+> book is, chapter by chapter, true whether or not a word of it is drafted.
+
+{{One line: what the book says, and who it is for.}}
+
+## Where things are
+
+- **[Frames](Frames/index.md)** — what the book argues, who reads it, how it sounds, where it sits.
+- **[Chapters](Chapters/index.md)** — one file per chapter, grouped by part.
+
+The full index — every collection, its flavors, and the property Schema — is in
+[`_eidos/Framework.md`](_eidos/Framework.md).
+
+## How to use it
+
+A chapter here describes what the chapter **is**: why it exists, what happens in it, and what the
+reader leaves with. It is not a draft and not a task. Write the chapter's blueprint before the prose,
+and keep it true after — a chapter you cut stays here, marked `Cut`, so the reasoning survives.
+
+_A root. Its framework lives in [`_eidos/`](_eidos/); see [`_eidos/Framework.md`](_eidos/Framework.md) for the full index._

package/standard/seeds/book/_gitignore

@@ -0,0 +1,4 @@
+# Eidos: the per-actor file is personal and never shared.
+# Each person who works on this definition keeps their own me.md (here in _eidos/); the agent reads
+# it to know who they are. It is the one _eidos/ file that is not checked in.
+me.md

package/standard/seeds/book/me.md

@@ -0,0 +1,18 @@
+# Me
+
+Who is in the seat. This file is **personal and per-actor** — it is gitignored and never checked in, so
+each person who works on this folder keeps their own. The agent reads it before acting, to know who
+you are and how to help.
+
+Set who you are below — `install` asks, or just edit this file. Leaving it blank is fine: the agent
+defaults to full, framework-owner-style facilitation and offers to record who you are.
+
+## You are:
+
+<!-- Name your role and how you want to be helped. The base roles Eidos recognizes:
+     - Framework Owner — holds intent, scope, decisions; full authoring, press on scope.
+     - Developer — consumes specs to build; surface what's specced, clarify, flag gaps, help Testing/ACs.
+     - Stakeholder — reviews direction; explain, summarize, surface risk.
+     - Designer — shapes UX and audience; Audience, Behaviors, external interface.
+     - Project Manager — tracks scope and progress; in/out of scope, status, dependencies, effort.
+     Or write your own. -->

package/standard/seeds/book/roles/README.md

@@ -0,0 +1,12 @@
+# Roles
+
+Default **roles** for this framework — who is in the seat, and how the agent should respond to them. A role is a **response contract**: it sets the vocabulary, the level of technical depth, what to surface vs. fold away, and who holds which decisions. The agent reads it **before acting** (see the Eidos standard's `EIDOS.md`, "The actor").
+
+These are the book seed's baseline, browsable here and installed into a root's `_eidos/roles/` by `install` (committed, so a team can tune how a role is treated for their book). Each person who works on the folder picks one in their personal, gitignored `_eidos/me.md` and **calibrates** it — what they own on this folder, their experience with the scope, and their technical capacity — with the `whoami` skill. Role sets the baseline; calibration tunes it per person.
+
+- [Framework Owner](framework-owner.md) — holds intent, scope, and decisions.
+- [Editor](editor.md) — reads for structure and what the book promises.
+- [Collaborator](collaborator.md) — drafts alongside the owner.
+- [Reader](reader.md) — reacts to the book, doesn't build it.
+
+A role is a baseline, not a cage: an actor can write a custom role in their `me.md`, and a framework can add or reshape role files here. The human-first principle holds for every role — the human authors and decides; the role only changes _how_ the agent helps.

package/standard/seeds/book/roles/collaborator.md

@@ -0,0 +1,16 @@
+# Collaborator
+
+## Who they are
+
+Writes alongside the owner — a co-author, ghostwriter, or researcher. Reads a chapter to answer "what exactly am I drafting, and in whose voice?"
+
+## How to respond
+
+- **Vocabulary & depth:** full detail. The Voice frame's rules, the beats in order, the dependencies, and anything still undecided that would send a draft the wrong way.
+- **Decisions:** clarify and flag, don't decide. Argument, structure, and voice belong to the Framework Owner; surface the ambiguity rather than resolving it in the prose.
+- **Surface / hide:** surface What Happens, Voice, Dependencies, and Open Questions. Say plainly when a beat is underspecified.
+- **Focus:** what is promised versus what is vague; whether a chapter's beats can actually be drafted from what is written.
+
+## Calibration
+
+**Experience with the scope** sets how much of the Frames to restate before getting to the chapter.

package/standard/seeds/book/roles/editor.md

@@ -0,0 +1,16 @@
+# Editor
+
+## Who they are
+
+Reads for structure before prose. Wants to know what each chapter is for, whether the book delivers what the Premise promises, and where two chapters are doing the same work.
+
+## How to respond
+
+- **Vocabulary & depth:** craft terms are welcome — arc, pacing, throughline, register. Skip production mechanics unless asked.
+- **Decisions:** name the structural problem and the options; the cut, the merge, and the reorder belong to the Framework Owner.
+- **Surface / hide:** surface Intent, What the Reader Leaves With, Out of Scope, and Dependencies across chapters. Fold away drafting notes.
+- **Focus:** promises made in the Frames versus what the Chapters actually deliver; overlap between neighbors; a chapter whose Intent no longer matches its beats.
+
+## Calibration
+
+**Experience with the scope** sets how much of the book's argument to restate; **technical capacity** rarely matters here — talk craft, not tooling.

package/standard/seeds/book/roles/framework-owner.md

@@ -0,0 +1,16 @@
+# Framework Owner
+
+## Who they are
+
+Holds the **intent, scope, and decisions** — true ownership of whatever it defines, be it a product, a body of research, a methodology, or any other form of thought or effort. The person Eidos is built for — they think through what the thing is, and they own the calls. Everything else serves their clarity.
+
+## How to respond
+
+- **Vocabulary & depth:** lead with the terms of the thing itself and the decision at hand. But many Framework Owners are also technical — don't assume otherwise; follow their **technical capacity** calibration and go as deep as they want, rather than withholding mechanism by default.
+- **Decisions:** theirs. Bring choices and trade-offs for them to decide; never decide direction or resolve an Open Question on their behalf. Press hardest on **Out of Scope**.
+- **Surface / hide:** surface intent, scope, audience, criteria, and the consequences of a choice; fold mechanism into a link they can follow.
+- **Focus:** Intent, Out of Scope, the Premise and Reader frames, and whether each chapter still says what they mean.
+
+## Calibration
+
+Their **experience with the scope** and **technical capacity** adjust the dials above — a non-technical owner gets less jargon and more translation; a technical owner gets the mechanism without hand-holding; a deeply-experienced one gets less orientation. Determining direction is the constant; technical fluency is not assumed either way.

package/standard/seeds/book/roles/reader.md

@@ -0,0 +1,16 @@
+# Reader
+
+## Who they are
+
+A beta reader or early audience. Not a maker of the book — a test of it. Reads to react, not to fix.
+
+## How to respond
+
+- **Vocabulary & depth:** plain language. No craft jargon, no process, no drafting state. Talk about what the book says and does, never how it is being made.
+- **Decisions:** none are theirs. Ask what landed and what didn't; don't invite them to redesign the book.
+- **Surface / hide:** surface Intent and What the Reader Leaves With, in the book's own terms. Hide Open Questions, Decisions, Dependencies, and anything marked Cut.
+- **Focus:** whether the promise in the Frames is one they'd want, and whether a chapter delivered it.
+
+## Calibration
+
+**Technical capacity** is assumed low for the book's craft regardless of the reader's own field; **experience with the scope** sets how much of the premise to set up first.

package/standard/seeds/book/shapes/chapter.full.md

@@ -0,0 +1,45 @@
+<!--
+The Chapter shape — the body of a chapter, and the documentation of each section. A chapter's
+frontmatter is generated from the framework's Schema (in Framework.md), so it is not written here.
+Keep the sections that apply and delete the rest, but leave the order and headings as they are — a
+reader should know what to expect from any chapter in this folder. The italic prompts are
+guidance; delete them as you fill each section in.
+-->
+
+# {{title}}
+
+## Intent
+
+_Why this chapter exists — the work it does that no other chapter does. One or two paragraphs. This is the stable part: if Intent changes substantially, you probably have a different chapter, not an edit to this one._
+
+### Assumptions
+
+_What you're taking as given about the reader arriving here — what they already accept, what they've already read. Nested under Intent because they frame it. Surface them so a guess doesn't slip into What Happens as if it were settled._
+
+## Open Questions
+
+_Unresolved questions — what you don't yet know about this chapter and still need answered. Kept high, right after Intent, so uncertainty is seen rather than buried. When one is settled it graduates into an Assumption, a beat, or a Decision._
+
+## What Happens
+
+_The chapter's content as observable beats — the argument it makes or the events it covers, in order. Label each beat **B1:**, **B2:**, … (bold, unique within this chapter). Keep each beat short and checkable against a draft; push rich detail into a table or sub-section it points to. Evolves freely._
+
+- **B1:** <!-- the first thing this chapter does to the reader -->
+
+## What the Reader Leaves With
+
+_The checkable outcome — what a reader can do, believe, or feel at the end that they couldn't at the start. If it isn't listed here, this chapter doesn't promise it._
+
+## Out of Scope
+
+_Explicit non-goals — what this chapter deliberately does not cover, and which chapter covers it instead. The section the standard leans on hardest, because this is where a book's structure is actually held. A chapter without it tends to sprawl into its neighbors._
+
+## Dependencies
+
+_What a reader must have read, or you must have written, before this chapter works: earlier chapters, a Frame, an interview, a permission. The `depends_on` property at the top is the chapter-only subset of this, as links. Reference other chapters as markdown links — never bare names._
+
+## Notes & Decisions
+
+_Two things under one header. **Notes**: sources, quotes to chase, craft reminders specific to this chapter. **Decisions**: an append-only log, one line each, with an optional but recommended date._
+
+<!-- 2026-08-26: Moved the framing anecdote to Chapter 1, it was doing the same work twice. (Brenton) -->