eidosmd 0.1.0 → 0.2.0

package/dist/src/program.js

@@ -1,11 +1,13 @@
 // The eidos command line, assembled: every command, its options, and its help.
 // `cli.ts` is the executable entry; this module is what tests build.
+import path from 'node:path';
 import { Command } from 'commander';
 import { loadRoot } from './context.js';
 import { runAgents } from './commands/agents.js';
 import { DEFAULT_PORT, runBrowser } from './commands/browser.js';
+import { runCanvasList, runCanvasNew, runCanvasSchema, runCanvasShow } from './commands/canvas.js';
+import { runMigrate } from './commands/migrate.js';
 import { runCheck } from './commands/check.js';
-import { runConvert } from './commands/convert.js';
 import { runFramework } from './commands/framework.js';
 import { runIndex } from './commands/index.js';
 import { runInit } from './commands/init.js';
@@ -13,7 +15,9 @@ import { runInstructions, runStandard } from './commands/instructions.js';
 import { runList } from './commands/list.js';
 import { runNew } from './commands/new.js';
 import { runSeeds } from './commands/seeds.js';
+import { offerGit, runSetup } from './commands/setup.js';
 import { runShow } from './commands/show.js';
+import { runVersionList, runVersionRecord } from './commands/version.js';
 import { runRoles, runWhoami } from './commands/whoami.js';
 import { CliError, EXIT_USAGE, printError, today } from './output.js';
 import { packageVersion, standardVersion } from './paths.js';
@@ -42,7 +46,7 @@ export function buildProgram() {
         .name('eidos')
         .description(`Eidos: one markdown file is the complete source of truth for one unit of a thing.\nScaffold, validate, and index a root of blueprints; hand an agent the workflow with \`eidos instructions\`.`)
         .version(`eidosmd ${packageVersion()} (standard ${standardVersion()})`, '-v, --version', 'print the CLI version and the standard it carries')
-        .option('--root <path>', 'the root to work in (default: found from the working directory by its _eidos/ marker)')
+        .option('--root <path>', 'the root to work in (default: found from the working directory by its .eidos/ marker)')
         .enablePositionalOptions()
         .showHelpAfterError('(run with --help for usage)')
         .addHelpText('after', `
@@ -52,11 +56,12 @@ Start with \`eidos instructions\` for the workflow, or \`eidos seeds\` and \`eid
     program
         .command('init')
         .argument('[root]', 'the root folder to create', 'Blueprints')
-        .description('create a root from a bundled seed: its framework as _eidos/Framework.yaml, a folder per collection, a blank blueprint per framing flavor')
+        .description('create a root from a bundled seed: its framework as .eidos/Framework.yaml, a folder per collection, a blank blueprint per framing variant (the framing docs are recommended; --no-framing leaves them out)')
         .option('--seed <name>', 'the seed to install (see `eidos seeds`)', 'software')
         .option('--naming <convention>', 'kebab-case | TitleCase | "Title Case"; governs every human-facing name, settled once', 'kebab-case')
         .option('--group <name>', 'a starting group under the grouped collection (repeatable)', collect, [])
         .option('--product <name>', "fills the README's {{Product}} placeholder")
+        .option('--no-framing', 'leave out the seed\'s framing collection (the docs about the whole product, recommended for every product)')
         .option('--date <YYYY-MM-DD>', 'the date written into the scaffolded frames', today())
         .option('--dry-run', 'print every write and touch nothing', false)
         .option('--json', 'machine-readable result', false)
@@ -68,47 +73,40 @@ Examples:
   eidos init Blueprints --seed software --group Identity --group Billing --product "Care Connect"
   eidos init docs/product --seed research --naming TitleCase --dry-run
 
-Writes Framework.yaml, the form the CLI works in. A root that keeps Framework.md (the form for people) is converted with \`eidos convert\`.`)
-        .action((root, options) => {
+Writes the seed's Framework.yaml into the root with its guidance as comments, the naming, the starting groups, and the collection names set in it.`)
+        .action(async (root, options) => {
         run(() => runInit(root, options));
+        // In a terminal, the one setting worth asking for right away; the rest is `eidos setup`.
+        if (process.exitCode === 0 && !options.json && !options.dryRun)
+            await offerGit(path.resolve(root ?? 'Blueprints'));
     });
     program
         .command('seeds')
-        .description('list the bundled seeds: each one a complete starting framework, with its collections and flavors')
+        .description('list the bundled seeds: each one a complete starting framework, with its collections and variants')
         .option('--json', 'machine-readable result', false)
         .action((options) => {
         run(() => runSeeds(options));
     });
     withRoot(program.command('framework'))
-        .description("show the root's framework: version, naming, top-level docs, collections (flavors, canvas, groups), and the property Schema")
+        .description("show the root's framework: version, naming, top-level docs, collections (variants, groups), the Properties table, and the Vocabulary")
         .option('--json', 'the framework as JSON: the document form plus root, file, and format', false)
-        .option('--as <format>', 'print the framework as the yaml document a scriptable root keeps in _eidos/')
+        .option('--as <format>', 'print the framework as the yaml document, normalized, with this CLI\'s guidance as comments')
         .addHelpText('after', `
-Read this before assuming any collection, flavor, section, or property name; the framework declares its own.
-The document is _eidos/Framework.md (for people) or Framework.yaml (for scripts and agents): the same fields in each.
+Read this before assuming any collection, variant, section, or property name; the framework declares its own.
+The document is .eidos/Framework.yaml. A root still on the 4.x Framework.md is moved by \`eidos migrate\` first.
 
-Output (--json): { root, file, format, eidos_version, naming, top_level[], collections[{ name, description, canvas, flavors[{ name, shape, description, default }], grouping{ label, property, groups[] } }], schema{ core[], custom[{ name, type, applies_to, meaning }] } }
-
-This is the one command that also reads a Framework.md root, so a root can be inspected before \`eidos convert\` moves it.`)
-        .action((options) => {
-        run(() => runFramework(loadRoot(globals(options), process.cwd(), { allowMarkdown: true }), options));
-    });
-    withRoot(program.command('convert'))
-        .description('move a markdown root to Framework.yaml, the form the CLI works in: the same framework with the index inside it; Framework.md and each index.md removed')
-        .option('--dry-run', 'print the writes and touch nothing', false)
-        .option('--json', 'machine-readable result', false)
-        .addHelpText('after', `
-Every command except this one and \`framework\` needs Framework.yaml, so on a markdown root this is the first thing to run. The markdown form's prose (section intros, comments) has no field to land in and is left behind; each collection's description travels. Blueprints are untouched.`)
+Output (--json): { root, file, format, eidos_version, naming, top_level[], collections[{ name, description, variants[{ name, template, description, default }], grouping{ label, property, groups[] } }], properties{ core[], custom[{ name, type, applies_to, meaning, <tool>… }], tools{ <tool>: [...] } }, vocabulary[{ term, means, not[], see? }] }
+A key past the standard's four on a property entry is a tool's, named for the tool (this CLI's is eidosmd, carrying a canvas hint); properties.tools.<tool> is a block of properties a tool declared and alone writes.`)
         .action((options) => {
-        run(() => runConvert(globals(options), options));
+        run(() => runFramework(loadRoot(globals(options), process.cwd()), options));
     });
     withRoot(program.command('list'))
         .argument('[collection]', 'only this collection')
         .description('list the blueprints in the root')
         .option('--group <name>', 'only this group (sub-folder)')
-        .option('--flavor <name>', 'only blueprints on this flavor (resolved, so the default counts)')
+        .option('--variant <name>', 'only blueprints on this variant (resolved, so the default counts)')
         .option('--where <key=value>', 'only blueprints whose property equals the value, case-insensitive (repeatable; a list matches any item)', collect, [])
-        .option('--json', 'one object per blueprint: id, title, summary, collection, group, flavor, path, properties', false)
+        .option('--json', 'one object per blueprint: id, title, summary, collection, group, variant, path, properties', false)
         .addHelpText('after', `
 Examples:
   eidos list
@@ -120,39 +118,39 @@ Examples:
     withRoot(program.command('show'))
         .argument('<blueprint>', 'an id, a filename, or a path')
         .description('print one blueprint as written; with --json, its properties and sections parsed out')
-        .option('--json', '{ id, title, summary, collection, group, flavor, path, absolute_path, properties, sections[{ heading, body }], body }', false)
+        .option('--json', '{ id, title, summary, collection, group, variant, path, absolute_path, properties, sections[{ heading, body }], body }', false)
         .action((ref, options) => {
         run(() => runShow(loadRoot(globals(options)), ref, options));
     });
     withRoot(program.command('new'))
         .argument('<collection>', 'the collection the blueprint belongs to')
         .argument('<title...>', 'the human-readable title')
-        .description("scaffold a blueprint that is born conforming: frontmatter from the Schema, body from the flavor's shape, filename in the naming convention, a permanent kebab-case id")
-        .option('--flavor <name>', "one of the collection's declared flavors (default: the collection's default)")
+        .description("scaffold a blueprint that is born conforming: frontmatter from the Properties table, body from the variant's template, filename in the naming convention, a permanent kebab-case id")
+        .option('--variant <name>', "one of the collection's declared variants (default: the collection's default)")
         .option('--group <name>', 'the sub-folder to place it in')
         .option('--id <kebab-case>', 'the permanent id (default: the title in kebab-case)')
         .option('--summary <line>', 'the one-line summary, so the index lists it at once')
         .option('--set <key=value>', 'a property value at creation (repeatable; lists are comma-separated)', collect, [])
-        .option('--date <YYYY-MM-DD>', 'the date written into date properties the Schema declares', today())
+        .option('--date <YYYY-MM-DD>', 'the date written into date properties the Properties table declares', today())
         .option('--dry-run', 'print the file instead of writing it', false)
-        .option('--json', '{ path, id, collection, group, flavor, notes[] }', false)
+        .option('--json', '{ path, id, collection, group, variant, notes[] }', false)
         .addHelpText('after', `
-The body keeps the shape's guidance prompts; fill them with the owner and delete them as you go. The CLI writes no prose.
+The body keeps the template's guidance prompts; fill them with the owner and delete them as you go. The CLI writes no prose.
 
 Examples:
   eidos new Specs "Session Management" --group Identity --summary "Keeps a signed-in user signed in across tabs and devices."
-  eidos new Specs "Passkeys" --flavor micro --set status=Intake --set tags=auth,security
+  eidos new Specs "Passkeys" --variant micro --set status=Intake --set tags=auth,security
   eidos new Frames Market --dry-run`)
         .action((collection, title, options) => {
         run(() => runNew(loadRoot(globals(options)), collection, title, options));
     });
     withRoot(program.command('check'))
         .argument('[blueprint...]', 'only these blueprints (paths); default: the whole root')
-        .description("validate the root against its own framework: the Framework.md and shapes, every blueprint's frontmatter and body, the layout, and the indexes")
+        .description("validate the root against its own framework: the framework document and templates, every blueprint's frontmatter and body, the layout, and the indexes")
         .option('--strict', 'warnings fail too', false)
         .option('--json', '{ ok, root, eidos_version, naming, blueprints, errors, warnings, findings[{ level, code, path, message }] }', false)
         .addHelpText('after', `
-Errors are wrong on any reading (unparseable frontmatter, a missing or duplicate id, an undeclared flavor, a broken link). Warnings are gaps the standard says to surface, never refuse (a missing property or section, a stale index, a version gap). Exit 1 on an error; with --strict, on a warning too.
+Errors are wrong on any reading (unparseable frontmatter, a missing or duplicate id, an undeclared variant, a broken link). Warnings are gaps the standard says to surface, never refuse (a missing property or section, a stale index, a version gap). Exit 1 on an error; with --strict, on a warning too.
 
 Examples:
   eidos check
@@ -162,28 +160,28 @@ Examples:
         run(() => runCheck(loadRoot(globals(options)), blueprints, options));
     });
     withRoot(program.command('index'))
-        .description("regenerate each collection's index.md: every blueprint as a link with its summary, grouped by sub-folder")
+        .description("regenerate each collection's index: every blueprint as a link with its summary, grouped by sub-folder")
         .option('--collection <name>', 'only this collection (repeatable)', collect, [])
         .option('--check', 'write nothing; exit 1 if any index is stale', false)
         .option('--json', '{ ok, indexes[{ collection, path, status, blueprints }], missing_summary[] }', false)
         .addHelpText('after', `
-Under a markdown framework each collection gets its own index.md, regenerated wholesale: nothing hand-written in it survives. Under a YAML framework every collection's index is written into the framework document under \`index\`, and the rest of the document is left as written. A blueprint without a summary is listed with a TODO marker (or a null summary) and named on stderr.`)
+Every collection's index is written into the framework document under \`index\`, and the rest of the document is left as written. A blueprint without a summary is listed with a null summary and named on stderr.`)
         .action((options) => {
         run(() => runIndex(loadRoot(globals(options)), options));
     });
     withRoot(program.command('roles'))
-        .description('list the roles the framework installed under _eidos/roles/')
+        .description('list the roles the framework installed under .eidos/roles/')
         .option('--json', 'machine-readable result', false)
         .action((options) => {
         run(() => runRoles(loadRoot(globals(options)), options));
     });
     withRoot(program.command('whoami'))
-        .description('show the actor in the seat (_eidos/me.md: role and calibration), or set it')
+        .description('show who is in the seat (.eidos/me.md: role and calibration), or set it')
         .option('--role <name>', 'a role from `eidos roles`')
         .option('--ownership <text>', 'what you own on this root, in your own words')
         .option('--experience <text>', 'your experience with the scope: new, familiar, deep')
         .option('--capacity <text>', 'your technical capacity: non-technical, some, fluent')
-        .option('--clear', 'blank the actor (full facilitation)', false)
+        .option('--clear', 'blank me.md (full facilitation)', false)
         .option('--json', 'machine-readable result', false)
         .addHelpText('after', `
 me.md is personal and gitignored: one per person, never shared. An agent reads it before acting and responds as the role file says.
@@ -194,6 +192,103 @@ Examples:
         .action((options) => {
         run(() => runWhoami(loadRoot(globals(options)), options));
     });
+    const canvas = program.command('canvas').description('the canvas maps under .eidos/plugins/eidosmd/maps/: the design tool the browser draws');
+    withRoot(canvas.command('list'))
+        .description('list the canvases and their pages')
+        .option('--json', 'machine-readable result', false)
+        .action((options) => {
+        run(() => runCanvasList(loadRoot(globals(options)), options));
+    });
+    withRoot(canvas.command('new'))
+        .argument('<title...>', 'the canvas title; its id is the title in kebab-case')
+        .description('create a canvas with one empty page; the browser is where it is drawn')
+        .option('--json', 'machine-readable result', false)
+        .action((title, options) => {
+        run(() => runCanvasNew(loadRoot(globals(options)), title.join(' '), options));
+    });
+    withRoot(canvas.command('show'))
+        .argument('<id>', 'the canvas id, its file name without .yaml')
+        .description('print a canvas file as it is, or one page of it, before editing it by hand')
+        .option('--page <id>', 'one page only')
+        .option('--json', 'machine-readable result', false)
+        .action((id, options) => {
+        run(() => runCanvasShow(loadRoot(globals(options)), id, options));
+    });
+    canvas
+        .command('schema')
+        .description('print the JSON Schema of a canvas file, for editing one without the browser')
+        .action(() => {
+        run(() => runCanvasSchema());
+    });
+    canvas.addHelpText('after', `
+A canvas is one YAML file in this tool's folder, .eidos/plugins/eidosmd/maps/<id>.yaml: a title and pages (each with frames, nodes, edges, layout, and comment threads).
+The file is the whole truth of a canvas: the browser draws it and writes it back, and a person or an agent edits it directly; \`eidos canvas schema\` prints what it may hold and \`eidos canvas show <id>\` prints one.
+A node is { id, blueprint: <id> }, { id, sketch: { label, note? } }, a sticky, a text, or an annotation, optionally attached to a frame; edges join node ids (or frame:<id> for a frame's border).
+Nodes are styled by the properties whose schema row carries this tool's hint, eidosmd.canvas (shape by value, color by value, show); a node's own style in the file wins over that.
+The search index the browser keeps is SQLite in memory, rebuilt on every start and never written to disk; nothing but the YAML is checked in.
+A snapshot of the root as a whole is a version: \`eidos version record\`.`);
+    const version = program.command('version').description("the root's own versions: snapshots taken on purpose, this CLI's own record under .eidos/plugins/eidosmd/ (they need git)");
+    withRoot(version.command('list', { isDefault: true }))
+        .description('list the recorded versions, newest first')
+        .option('--json', 'machine-readable result', false)
+        .action((options) => {
+        run(() => runVersionList(loadRoot(globals(options)), options));
+    });
+    withRoot(version.command('record'))
+        .argument('<version>', "the root's own number, e.g. 1.0.0 (not the product's release version)")
+        .description('record a snapshot: a row naming a commit that exists; --tag also tags it blueprints/<version>')
+        .option('--commit <ref>', 'the commit that is the snapshot (a sha, HEAD, a tag); HEAD when absent')
+        .option('--tag', 'create the tag blueprints/<version> on that commit', false)
+        .option('--json', 'machine-readable result', false)
+        .action((given, options) => {
+        run(() => runVersionRecord(loadRoot(globals(options)), given, options));
+    });
+    version.addHelpText('after', `
+A version is a fixed point a team holds the definition against later. Nothing proposes one; record one only when asked.
+The commit is the snapshot (git holds every blueprint as it was), nothing is copied, and the commit that adds the row is not the one it names.`);
+    program
+        .command('migrate')
+        .description('move a root to the standard this CLI carries: .eidos/, templates/, Framework.yaml, Properties, variants, the version; mechanical, nothing dropped')
+        .option('--root <path>', 'the root to migrate; default: the one found from here (.eidos/ or the older _eidos/)')
+        .option('--dry-run', 'list what would move and change nothing', false)
+        .option('--json', 'machine-readable result', false)
+        .addHelpText('after', `
+The 4.x → 5.0.0 hop: _eidos/ becomes .eidos/, shapes/ becomes templates/, the framework document takes the 5.0.0 keys (schema → properties, flavors → variants, shape → template), a root that kept Framework.md gets Framework.yaml in its place (the index inside it; Framework.md and each collection's index.md removed), every blueprint's flavor becomes variant, and eidos_version is set.
+A template that opens with frontmatter loses the block; one named off its unit (<unit>.<variant>.md) is reported for you to rename. Run eidos check afterwards.`)
+        .action((options) => {
+        run(() => runMigrate(options));
+    });
+    withRoot(program.command('setup'))
+        .description("the CLI's own settings for this root: whether git is read, the people who work here, and who this machine acts as")
+        .option('--git <on|off>', 'read git in the browser: history, authors, versions')
+        .option('--add-user <name>', 'add (or update) a user by display name (repeatable)', collect, [])
+        .option('--alias <alias>', 'the @mention handle of the user being added, no spaces')
+        .option('--role <name>', 'the role of the user being added, from `eidos roles`')
+        .option('--email <email>', 'the email of the user being added; ties them to a git identity')
+        .option('--as <alias>', 'act as this user on this machine (blank for the git identity)')
+        .option('--json', 'machine-readable result', false)
+        .addHelpText('after', `
+Without flags, asks in the terminal. Writes .eidos/plugins/eidosmd/settings.yaml (shared with the root) and local.yaml (yours, gitignored).
+
+Examples:
+  eidos setup
+  eidos setup --git on --add-user "Ada Lovelace" --alias ada --role developer --email ada@example.com --as ada
+  eidos setup --as client`)
+        .action(async (options) => {
+        try {
+            process.exitCode = await runSetup(loadRoot(globals(options)), options);
+        }
+        catch (cause) {
+            if (cause instanceof CliError) {
+                printError(`error: ${cause.message}`);
+                process.exitCode = cause.exitCode;
+            }
+            else {
+                printError(`error: ${cause instanceof Error ? cause.message : String(cause)}`);
+                process.exitCode = EXIT_USAGE;
+            }
+        }
+    });
     withRoot(program.command('browser'))
         .description('open the root in a local web page: browse and read blueprints, create one, edit one, run the check, rebuild the index')
         .option('-p, --port <port>', 'the port to serve on; the next free one is used if it is busy', (value) => Number.parseInt(value, 10), DEFAULT_PORT)

package/instructions/authoring.md

@@ -1,34 +1,35 @@
 ## Authoring a blueprint
 
-A blueprint is one markdown file defining one unit completely: a frontmatter contract plus a body that follows a shape. You scaffold it with the CLI and fill it with the owner.
+A blueprint is one markdown file defining one unit completely: a frontmatter contract plus a body that follows a template. You scaffold it with the CLI and fill it with the owner.
 
 ### 1. Place it
 
-Run `eidos framework`. Decide with the owner which collection the blueprint belongs to, which flavor (the collection's default unless they choose another), and which group if the collection groups its blueprints. If the idea is still rough, question it first: what it is, what it is not, and how it sits beside the blueprints already there (`eidos list`, `eidos show <id>`). Write nothing until that holds still.
+Run `eidos framework`. Decide with the owner which collection the blueprint belongs to, which variant (the collection's default unless they choose another), and which group if the collection groups its blueprints. If the idea is still rough, question it first: what it is, what it is not, and how it sits beside the blueprints already there (`eidos list`, `eidos show <id>`). Write nothing until that holds still.
 
 ### 2. Scaffold it
 
 ```bash
-eidos new <collection> "<Title>" [--flavor <flavor>] [--group <group>] [--summary "<one line>"]
+eidos new <collection> "<Title>" [--variant <variant>] [--group <group>] [--summary "<one line>"]
 ```
 
-`new` generates the frontmatter from the properties that apply to the collection, renders the body from the flavor's shape with its guidance kept, names the file in the framework's convention, and puts a permanent kebab-case `id` inside. Set a property at creation with `--set key=value`. Use `--dry-run` to see the file before writing it, and `--json` to get its path.
+`new` generates the frontmatter from the properties that apply to the collection, renders the body from the variant's template with its guidance kept, names the file in the framework's convention, and puts a permanent `id` inside (a kebab-case slug by default; any stable, unique form is allowed with `--id`). Set a property at creation with `--set key=value`. Use `--dry-run` to see the file before writing it, and `--json` to get its path.
 
 Write the `summary` at creation when you can: one plain line saying what the blueprint is, so the collection index lists it the moment it exists.
 
 ### 3. Fill it, with the owner
 
-Open the file. The shape's sections are in order, each with an italic prompt saying what belongs there. Work through them top to bottom:
+Open the file. The template's sections are in order, each with an italic prompt saying what belongs there. Work through them top to bottom:
 
 - Lead with the opening sections, the ones saying why the unit exists and what it observably does.
 - Press hardest on the section for what the blueprint deliberately will not do. That is where scope is held; a blueprint without it is rarely finished. Prompt for non-goals if the owner has not named them.
 - Where the owner is vague, ask. Do not fill the gap with plausible prose.
-- Keep the shape's section order and names. Leave a section out when it genuinely does not apply rather than leaving it empty. Beneath the sections, write it the way a person would read it: sub-headings, tables, lists.
-- Follow whatever labeling the shape asks for (for example `**AC1:**` on acceptance criteria) and keep checkable statements short.
+- Keep the template's section order and names. Leave a section out when it genuinely does not apply rather than leaving it empty. Beneath the sections, write it the way a person would read it: sub-headings, tables, lists.
+- Follow whatever labeling the template asks for (for example `**AC1:**` on acceptance criteria) and keep checkable statements short.
+- Write with the framework's declared terms (`vocabulary` in `eidos framework`). Where the owner reaches for a near-miss the Vocabulary names, say which term it declares and ask; never swap the word in silently.
 - Reference other blueprints with markdown links, never bare names, in prose and in properties alike: `[Session Management](../identity/session-management.md)`. If the target has no blueprint yet, name it plainly rather than fabricating a link.
 - Delete each italic prompt as its section is filled.
 
-Frontmatter stays what `new` generated. Fill values; do not add keys the Schema does not declare (`eidos instructions configuring` is how a property is added). Leave a property blank rather than guessing it.
+Frontmatter stays what `new` generated. Fill values; do not add keys the Properties table does not declare (`eidos instructions configuring` is how a property is added). Leave a property blank rather than guessing it.
 
 ### 4. Check and index
 
@@ -37,14 +38,14 @@ eidos check <path-to-blueprint>
 eidos index
 ```
 
-`check` reports what is missing or malformed against this framework and the blueprint's flavor. Surface the findings; the owner decides what to act on. `index` rebuilds the collection's `index.md` so the new blueprint is listed.
+`check` reports what is missing or malformed against this framework and the blueprint's variant. Surface the findings; the owner decides what to act on. `index` rebuilds the index so the new blueprint is listed.
 
 ### Frames and top-level docs
 
-A frame is a blueprint in the framing collection (the first one `eidos framework` lists): same procedure, kept as loose prose. Fill what is known and leave the rest; a declared frame left unwritten is a gap to surface, not a failure.
+A frame is a blueprint in the framing collection (the one `eidos framework` marks `framing`, its unit `frame`): same procedure, kept as loose prose. The standard requires no such collection; this CLI recommends one for every product and installs the seed's unless told `--no-framing`. Fill what is known and leave the rest; a declared frame left unwritten is a gap to surface, not a failure.
 
-A top-level doc (a Roadmap, a Vision) is one-of-a-kind and free-form: no shape, no validation, edited in place. Draft it with the owner, then register it under `top_level` in `_eidos/Framework.yaml`.
+A top-level doc (a Vision, a map a tool generates) is one-of-a-kind and free-form: no template, no validation, edited in place. Draft it with the owner, then register it under `top_level` in `.eidos/Framework.yaml`.
 
 ### Reshaping a draft the owner already wrote
 
-When the thinking is already on the page and only needs shape, scaffold nothing. Read the flavor's shape (`_eidos/shapes/<kind>.<flavor>.md`), move the author's own words under the right sections in the shape's order, keep their wording, add nothing, and run `eidos check` on the result. What does not fit any section stays in the file, under a note, for the owner to place.
+When the thinking is already on the page and only needs template, scaffold nothing. Read the variant's template (`.eidos/templates/<unit>.<variant>.md`), move the author's own words under the right sections in the template's order, keep their wording, add nothing, and run `eidos check` on the result. What does not fit any section stays in the file, under a note, for the owner to place.

package/instructions/configuring.md

@@ -1,65 +1,96 @@
 ## Configuring the framework
 
-The framework is the structure a root is written in: the framework document (version, naming, the Top-Level index, the Collections, and the property Schema) plus `_eidos/shapes/` (one file per flavor) and `_eidos/roles/`. This CLI reads it; changing it is an edit to those files, made with the owner and verified with `eidos check`.
+The framework is the structure a root is written in: the framework document (version, naming, the top-level index, the collections, the Properties table, and the Vocabulary) plus `.eidos/templates/` (one file per variant) and `.eidos/roles/`. This CLI reads it; changing it is an edit to those files, made with the owner and verified with `eidos check`.
 
-The document is `_eidos/Framework.yaml`: `top_level`, `collections[]` (each with `flavors`, `canvas`, `grouping`), and `schema.custom[]`, documented field by field in `eidos standard`. The procedures below show the markdown form the standard documents; the fields are the same. Never touch the `index` key: `eidos index` owns it.
+The document is `.eidos/Framework.yaml`: `top_level`, `collections[]` (each with `variants` and `grouping`), `properties.custom[]` (yours), `properties.tools.<tool>[]` (a tool's), and `vocabulary[]`, documented field by field in `eidos standard`. Never touch the `index` key: `eidos index` owns it. Never touch `.eidos/plugins/` (each folder is a tool's own) or a key on a Properties row past the standard's four (a tool's field, named for the tool); carry both across unchanged.
 
-Press the owner to decide. A collection, flavor, or property nobody thought through reads as meaningful while no one knows what it holds. If they offer only a name, ask for the rest.
+Press the owner to decide. A collection, variant, or property nobody thought through reads as meaningful while no one knows what it holds. If they offer only a name, ask for the rest.
 
-Never touch `### Eidos Core`: those properties move with the standard's version. And never change the naming convention on a root with files in it without renaming every file and link.
+Never touch `properties.core`: those properties move with the standard's version. Never touch a tool's block, `properties.tools.<tool>`: that tool alone writes it, the way Eidos alone writes the core; the one exception is retiring the block of a tool that has left the root, on the owner's say-so, its values surfaced first. And never change the naming convention on a root with files in it without renaming every file and link.
 
 ### Adding a collection
 
-Decide its **name** (the folder, in the naming convention `eidos framework` shows), a one-line **description**, how it **groups** its blueprints (one level of sub-folders, or flat), at least one **flavor** with a **default**, and how it **draws** on a canvas (`file` for prose read whole; `card from ## <Section>` for blueprints scanned by a headline; ask, do not assume the section).
+Decide its **name** (the folder, in the naming convention `eidos framework` shows), a one-line **description**, how it **groups** its blueprints (one level of sub-folders, or flat), and at least one **variant** with a **default**.
 
 1. Create the folder under the root.
-2. Create the default flavor's shape in `_eidos/shapes/<kind>.<flavor>.md`: body only, `# {{title}}` first, then the `##` sections in order, each with an italic guidance prompt. Pattern it on the shapes already there.
-3. Register it under `## Collections` in `Framework.md` with a `###` heading, the description, then bullets in this form (bullets, so the next flavor is a copied line):
-
-   ```markdown
-   ### Decisions
-
-   Architecture decision records, one per significant choice.
-
-   - **Leaf:** [Decisions/index.md](../Decisions/index.md)
-   - **Flavors:**
-     - [full](shapes/decision.full.md) — context, decision, consequences (default).
-   - **Canvas:** card from `## Decision`
-   - **Kinds:**
-     - **Runtime** — decisions about what runs where.
+2. Create the default variant's template in `.eidos/templates/<unit>.<variant>.md`: body only, `# {{title}}` first, then the `##` sections in order, each with an italic guidance prompt. Pattern it on the templates already there.
+3. Register it under `collections` in `Framework.yaml`: an entry with its name, description, variants (one default), and grouping, one variant per line so the next one is a copied line:
+
+   ```yaml
+   - name: Decisions
+     description: Architecture decision records, one per significant choice.
+     variants:
+       - { name: full, template: templates/decision.full.md, description: "context, decision, consequences", default: true }
+     grouping:
+       label: Kinds
+       groups:
+         - { name: Runtime, description: decisions about what runs where }
    ```
 
-   The grouping bullet (`**Kinds:**` above) is optional; its label is the collection's own, and each nested bullet is one group. A property carrying the group is a Schema change, below.
-4. Run `eidos index` for the new leaf and `eidos check` to confirm the framework parses as intended.
+   The `grouping` key is optional; its label is the collection's own, and each entry under `groups` is one group. A property carrying the group (`grouping.property`) is a Properties table change, below.
+4. Run `eidos index` so the new collection has its list, and `eidos check` to confirm the framework parses as intended.
 
-### Adding a flavor
+### Adding a variant
 
-Decide its **name** (lowercase), a one-line **description**, and its **shape**. A second flavor is a deliberate variant, a lighter one to grow out of or a genuine split in kind, never a fork per category label.
+Decide its **name** (lowercase), a one-line **description**, and its **template**. A second variant is a deliberate variant, a lighter one to grow out of or a genuine split in kind, never a fork per category label.
 
-1. Create `_eidos/shapes/<kind>.<flavor>.md`, starting from the collection's default flavor and trimming or extending it. Keep the order and names of whatever it shares with the default.
-2. Add it to the collection's **Flavors** bullets. Move `(default)` to it only if it should be the default; exactly one flavor carries the marker.
-3. Existing blueprints are untouched: an absent `flavor` still means the default. `eidos new --flavor <name>` scaffolds in it from here on.
+1. Create `.eidos/templates/<unit>.<variant>.md`, starting from the collection's default variant and trimming or extending it. Keep the order and names of whatever it shares with the default.
+2. Add it to the collection's `variants`, with its `template` path. Move `default: true` to it only if it should be the default; exactly one variant carries it.
+3. Existing blueprints are untouched: an absent `variant` still means the default. `eidos new --variant <name>` scaffolds in it from here on.
 
 ### Adding a property
 
-Decide all four: **name** (lowercase, words joined by underscores), **type** (Text, List, Number, Checkbox, Date, or Date & time; anything richer belongs in the body), **applies to** (`all`, or a list of collections), and **meaning** (one line).
+Decide all four: **name** (lowercase, words joined by underscores), **type** (Text, List, Number, Checkbox, Date, or Date & time; anything richer belongs in the body), **applies to** (`all`, or a list of collections), and **meaning** (one line). Every property has an owner, and the owner is the block it sits in: yours go in `properties.custom`; a tool's go in `properties.tools.<tool>`, written by the tool. How blueprints relate to each other is better said in the body, as links in prose, than as a frontmatter list; a `connects_to` a root still carries is the framework's own custom property, kept or retired like any other.
 
-1. Add a row to `### Custom Properties` in `## Schema`:
+1. Add an entry to `properties.custom`:
 
-   ```markdown
-   | team | Text | all | Owning team, for filtering. |
+   ```yaml
+   - { name: team, type: Text, applies_to: all, meaning: "Owning team, for filtering." }
    ```
 
 2. Backfill the blueprints it applies to with an empty or owner-supplied stub, so each is fillable; `eidos check` lists the ones still missing it as `property-missing`. New blueprints get it from `eidos new`.
 
+A tool's fields on the entry (this CLI's `eidosmd: { canvas: … }`, which styles a canvas node by the property's value) are not the standard's and not yours to fill in; keep whatever is there.
+
 ### Renaming or retiring a property
 
-Renaming: change the `Name` cell, then the key in every blueprint's frontmatter, carrying values across unchanged. Retiring: first show the owner every value that would be lost and ask whether to fold them somewhere or drop them; only then remove the row and the keys. Never silently drop values.
+Renaming: change the entry's `name`, then the key in every blueprint's frontmatter, carrying values across unchanged. Retiring: first show the owner every value that would be lost and ask whether to fold them somewhere or drop them; only then remove the entry and the keys. Never silently drop values.
+
+### Declaring a term
+
+The Vocabulary is the contract for words, beside the Properties table's contract for properties. Decide all three: the **term** (the word as prose uses it), what it **means** (one line), and what it is **not** (the near-misses, each opening with the word and saying why it is a different thing). A term with nothing in `not` is a dictionary entry, not an entry worth keeping; a concept that needs a body of its own is a blueprint, and the entry points at it with `see`.
+
+1. Add an entry under `vocabulary` in `Framework.yaml`:
+
+   ```yaml
+   vocabulary:
+     - term: team member
+       means: Someone on the product team, whatever their contract.
+       not:
+         - staff, who are the company's employees
+         - teammate, the informal word; use it in speech, not in a blueprint
+       see: ../specs/team-member.md   # optional
+   ```
+
+2. Run `eidos check`: every blueprint that uses a near-miss is listed as `term-near-miss` with the declared term beside it. Show the list; the edits are the owner's and yours in the file, never a silent swap.
+
+Renaming a term keeps the old word in `not` when the distinction is the point. Retiring one: show where the word is used first.
+
+### Recording a version
+
+Only when the owner asks. A version is a snapshot of the root a team holds the definition against later: the root's own number (not the product's release version), a commit that exists in the repository the root lives in, and, if wanted, a tag named `blueprints/<version>`. It is this CLI's own record, kept under `.eidos/plugins/eidosmd/versions.yaml`; the standard keeps no versions in the framework document.
+
+```bash
+eidos version record 1.0.0                     # HEAD, no tag
+eidos version record 1.0.0 --commit a1b2c3d --tag
+```
+
+Ask which commit (HEAD unless they name one) and whether to tag; create the tag only on a yes. The commit that adds the entry is not the one the entry names, the way a tag follows the commit it marks. Never propose a version, and never read an empty list as a gap.
 
-### Refreshing the Top-Level index
+### Refreshing the top-level index
 
-`## Top-Level` lists the root's one-of-a-kind documents, `README` first, one bullet each: `- [Title](../Title.md) — one-line description`. Frames are a collection, not top-level. Keep the owner's existing descriptions; a doc with none gets a `<!-- TODO: describe -->`, and you ask. `eidos check` reports an entry whose file does not exist.
+`top_level` lists the root's one-of-a-kind documents, `README` first, one entry each: `{ title: Vision, path: ../Vision.md, description: one line }`, the path relative to `.eidos/`. Frames are a collection, not top-level. Keep the owner's existing descriptions; a doc with none gets an empty description, and you ask. `eidos check` reports an entry whose file does not exist.
 
 ### After
 
-Run `eidos check`. It will tell you whether the collection, its flavors, its shapes, and its groups are declared consistently, and which blueprints the change left with a gap.
+Run `eidos check`. It will tell you whether the collection, its variants, its templates, and its groups are declared consistently, and which blueprints the change left with a gap.

package/instructions/init-required.md

@@ -1,6 +1,6 @@
 ## Eidos root required
 
-No root was found from this directory: nothing here holds a `_eidos/` folder with a `Framework.md` inside it. A root is found by that marker, never by its name.
+No root was found from this directory: nothing here holds a `.eidos/` folder with a `Framework.yaml` inside it. A root is found by that marker, never by its name.
 
 If the root lives elsewhere in the repository, pass it explicitly:
 
@@ -18,11 +18,11 @@ eidos init Blueprints --seed book --naming "Title Case" --group "Part One" --pro
 
 `init` asks the owner nothing: choose the seed, the root folder name, the naming convention, the first groups, and the product name with them first, then run it. Everything a seed ships is reshapeable later, so a seed that is merely close is the right choice. `--dry-run` prints every write and touches nothing.
 
-If there is a root but it keeps its framework as `_eidos/Framework.md`, the CLI's first job is to convert it:
+If there is a root but it is on an older standard (a `_eidos/` folder, or a markdown `Framework.md`), the CLI's first job is to move it:
 
 ```bash
-eidos convert --dry-run                      # the writes it would make
-eidos convert                                # Framework.yaml with the index inside; Framework.md and each index.md removed
+eidos migrate --dry-run                      # the moves it would make
+eidos migrate                                # .eidos/, templates/, Framework.yaml with the index inside, variant on every blueprint
 ```
 
 After that, run:

package/instructions/overview.md

@@ -1,6 +1,6 @@
 ## Eidos Overview (CLI)
 
-This repository keeps a root of Eidos blueprints. One markdown file is the complete source of truth for one unit of the thing being made, true whether or not it has been built. A blueprint captures state and intent, not work: no sprint, estimate, or assignee, and no progress notes in the body.
+This repository keeps a root of Eidos blueprints. One markdown file is the complete source of truth for one unit of the product being made, true whether or not it has been built. A blueprint captures state and intent, not work: no sprint, estimate, or assignee, and no progress notes in the body.
 
 ### The one rule: facilitate, do not author
 
@@ -8,8 +8,8 @@ Eidos is human-first. The owner holds the intent, the scope, and the decisions;
 
 ### Start every request here
 
-1. `eidos framework` reads the root's own framework: its collections, their flavors and groups, and the property Schema. Never assume a collection, flavor, or section name; read what this framework declares. The document behind it is `_eidos/Framework.yaml`; if a root still keeps `Framework.md` (the form for people), every command says so and `eidos convert` moves it first.
-2. `eidos whoami` says who is in the seat. Open the role file it names under `_eidos/roles/` and respond as that contract says (vocabulary, depth, what to surface, who decides). A blank actor means full, framework-owner-style facilitation.
+1. `eidos framework` reads the root's own framework: its collections, their variants and groups, the Properties table, and the Vocabulary (the root's own terms). Never assume a collection, variant, or section name; read what this framework declares. The document behind it is `.eidos/Framework.yaml`; a root still on the 4.x `Framework.md` is moved by `eidos migrate` first, and every command says so.
+2. `eidos whoami` says who is in the seat. Open the role file it names under `.eidos/roles/` and respond as that contract says (vocabulary, depth, what to surface, who decides). A blank me.md means full, framework-owner-style facilitation.
 3. `eidos list` and `eidos show <id>` read what already exists. Read before writing.
 4. `eidos instructions <guide>` before authoring, validating, or changing the framework. The overview says when to act; the guides say how.
 
@@ -17,21 +17,31 @@ Add `--json` to `framework`, `list`, `show`, and `check` when a script needs sta
 
 ### The CLI owns structure; the conversation owns the words
 
-- `eidos new <collection> "<Title>"` scaffolds a blueprint that is born conforming: frontmatter from the Schema, body from the flavor's shape, filename in the naming convention, a permanent kebab-case `id` inside. Never hand-assemble frontmatter.
+- `eidos new <collection> "<Title>"` scaffolds a blueprint that is born conforming: frontmatter from the Properties table (every block: the core, the framework's, a tool's), body from the variant's template, filename in the naming convention, a permanent `id` inside. Never hand-assemble frontmatter.
 - `eidos check` validates the root against its own framework. Its findings are a review the owner acts on; surface them, do not block on them.
 - `eidos index` regenerates the indexes, the `index` key inside `Framework.yaml`. Never edit it by hand.
 - The prose inside a blueprint is written in the file, with the owner, by you. The CLI never writes a sentence of it.
-- `eidos browser` opens the root in a local web page for a person. Everything the page can do runs the same code as a command (`new`, `check`, `index`), so it adds nothing you cannot do from the shell. Use the commands; leave the page to people.
+- `eidos browser` opens the root in a local web page for a person, landing on its canvas maps: the design tool where a sketch becomes a blueprint. A canvas is one YAML file, `.eidos/plugins/eidosmd/maps/<id>.yaml`, that an agent edits directly: `eidos canvas schema` prints its JSON Schema, `eidos canvas show <id>` prints one, `eidos canvas new` creates one, and the browser reflects the file as it changes (or take the same JSON API, `/api/canvas/`, while it runs). Everything the page can do runs the same code as a command (`new`, `check`, `index`), so it adds nothing you cannot do from the shell. Use the commands; leave the page to people.
+
+### 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 (`eidos check` flags one as `term-near-miss`). A word the owner keeps using that no row declares is worth naming as a candidate; declaring it is a framework change (`eidos instructions configuring`) and the owner's call.
 
 ### Version
 
-The framework records the standard it targets as `eidos_version` in `_eidos/Framework.yaml`; `eidos standard --version` prints the one this CLI carries. `eidos check` notes a gap once. A gap never blocks the work: the framework in front of you is the operative contract either way.
+The framework records the standard it targets as `eidos_version` in `.eidos/Framework.yaml`; `eidos standard --version` prints the one this CLI carries. `eidos check` notes a gap once. A gap never blocks the work: the framework in front of you is the operative contract either way.
+
+The root's own versions are this CLI's, not the standard's: snapshots taken on purpose, kept under `.eidos/plugins/eidosmd/versions.yaml` because they need git. Never propose one, never ask whether to take one, and never fault a root without any; an empty list is the normal state. When the owner asks, `eidos version record <version> [--commit <sha>] [--tag]` writes the row from a commit that exists; ask about the tag (`blueprints/<version>`) rather than assuming. To see the root as it was at a version, read the blueprint at that commit (`git show <commit>:<path>`).
+
+### What is not yours
+
+`.eidos/plugins/<name>/` is a tool's own folder (this CLI keeps its canvas maps under `plugins/eidosmd/`). Leave every folder there alone unless you are the tool that owns it; a folder you don't recognize is not a problem to report. On a Properties row, a key past the standard's four (`name`, `type`, `applies_to`, `meaning`) is a tool's, named for the tool; carry it across an edit unchanged and never fill it in. A whole block a tool declared, `properties.tools.<tool>`, is that tool's alone.
 
 ### Guides
 
 - `eidos instructions authoring`: read before creating or editing a blueprint
 - `eidos instructions validating`: read before reviewing a blueprint or reporting on a root
-- `eidos instructions configuring`: read before changing the framework (a collection, a flavor, a property, the Top-Level index)
+- `eidos instructions configuring`: read before changing the framework (a collection, a variant, a property, a term, a version, the Top-Level index)
 - `eidos instructions init-required`: when there is no root here yet
 
 `eidos <command> --help` explains any command's options and output.