eidosmd 0.1.0 → 0.3.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,12 @@ 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 { offerSetup, runSetup } from './commands/setup.js';
+import { runPlan, showCollection, showFolder, showProperty, showRole } from './commands/configure.js';
+import { runPropertyGet, runPropertySet, runPropertyUnset } from './commands/property.js';
+import { planCollectionAdd, planDocAdd, planDocRemove, planDocRename, planDocSet, planCollectionRemove, planCollectionRename, planFolderAdd, planFolderRemove, planFolderRename, planFolderSet, planGroupAdd, planGroupRemove, planGroupRename, planPropertyAdd, planPropertyRemap, planPropertyRemove, planPropertyRename, planPropertySet, planRoleAdd, planRoleRename, planRoleRemove, planTermAdd, planTermRemove, planTermSet, planVariantAdd, planVariantRemove, planVariantRename, planVariantSetDefault } from './core/edits.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';
@@ -33,6 +40,11 @@ function run(action) {
         process.exitCode = EXIT_USAGE;
     }
 }
+// `--options A,B,C` as the list it names, in the order typed.
+const splitValues = (given) => given
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '');
 export function buildProgram() {
     const program = new Command();
     // --root is accepted before or after the command name.
@@ -42,7 +54,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,63 +64,61 @@ 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('--strict', 'a warning fails `eidos check` in this root (kept in settings.yaml, with the root)')
+        .option('--no-strict', 'only an error fails `eidos check` in this root')
         .option('--dry-run', 'print every write and touch nothing', false)
         .option('--json', 'machine-readable result', false)
         .addHelpText('after', `
 Writes no prose: the README one-liner, each group's description, and every frame's summary and body stay the owner's.
+In a terminal, asks the two settings a framework owner decides once and commits with the root: whether the browser reads git, and whether a warning fails the check (--strict / --no-strict answers it without the question).
 
 Examples:
   eidos init
   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));
+        // The owner's two settings: a flag answers, a terminal asks, the rest is `eidos setup`.
+        if (process.exitCode === 0 && !options.dryRun)
+            await offerSetup(path.resolve(root ?? 'Blueprints'), { strict: options.strict });
     });
     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, folders (a collection's variants and 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[], folders[{ name, type: collection | assets | other, 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 folder's variants and grouping are a collection's; an assets or other folder carries only its name, type, and description.
+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 +130,41 @@ 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")
-        .option('--strict', 'warnings fail too', false)
-        .option('--json', '{ ok, root, eidos_version, naming, blueprints, errors, warnings, findings[{ level, code, path, message }] }', false)
+        .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, for this run (the root\'s own setting is settings.yaml check.strict)')
+        .option('--no-strict', 'warnings do not fail, for this run')
+        .option('--json', '{ ok, strict, 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; on a warning too when the root is strict.
+Strictness is the framework owner's decision for the root, asked by \`eidos init\` and set by \`eidos setup --strict on|off\`, kept in .eidos/plugins/eidosmd/settings.yaml so CI and every machine agree; --strict and --no-strict override one run.
 
 Examples:
   eidos check
@@ -162,28 +174,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 +206,374 @@ 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 <prefix><version>')
+        .option('--commit <ref>', 'the commit that is the snapshot (a sha, HEAD, a tag); HEAD when absent')
+        .option('--tag', 'create the tag <prefix><version> on that commit (the prefix is settings.yaml versions.tag_prefix, blueprints/ by default)', 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.
+From 5.0.0 on nothing moves on disk: the version is bumped, the core block is rewritten, and .eidos/.gitignore gains the one line every tool's personal file needs (plugins/*/local.yaml).
+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('--strict <on|off>', 'a warning fails `eidos check` in this root, the way an error does; the framework owner\'s decision, kept with the root')
+        .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;
+            }
+        }
+    });
+    // ---- configure:<noun>: the framework edited from the shell, each a plan shown before it runs
+    const runAsync = async (action) => {
+        try {
+            process.exitCode = await action();
+        }
+        catch (cause) {
+            if (cause instanceof CliError) {
+                printError(`error: ${cause.message}`);
+                process.exitCode = cause.exitCode;
+                return;
+            }
+            printError(`error: ${cause instanceof Error ? cause.message : String(cause)}`);
+            process.exitCode = EXIT_USAGE;
+        }
+    };
+    const planned = (command) => withRoot(command)
+        .option('--dry-run', 'print the plan and write nothing', false)
+        .option('-y, --yes', 'proceed without asking', false)
+        .option('--force', 'proceed through what needs forcing: values or files that will be gone, a conflict the plan names', false)
+        .option('--json', 'the plan, its conflicts, and once applied every result, as one object', false);
+    const PLAN_HELP = `
+The plan is printed whole, then the command asks in a terminal; --dry-run prints it and stops, --yes proceeds, --force proceeds where values or files would be gone. Without a terminal and without a switch the command exits 2 and names the switch.
+After any change the index is rewritten and the check runs; a command never leaves the root with a finding it caused, unless --preserve, the owner's choice, says so.`;
+    const configure = (noun, description) => program.command(`configure:${noun}`).description(description).addHelpText('after', PLAN_HELP);
+    const configureProperty = configure('property', "the Properties table's custom block: add, show, rename, set, remap, or remove a property, every blueprint it touches following");
+    planned(configureProperty.command('add'))
+        .argument('<name>', 'the frontmatter key: letters, digits, _ and -')
+        .requiredOption('--type <type>', 'Text | List | Number | Checkbox | Date | "Date & time"')
+        .option('--applies-to <all|collection,...>', 'all, or a comma-separated list of collections', 'all')
+        .option('--required', 'generated into every blueprint it applies to, blank, and noted when missing', false)
+        .option('--options <value,...>', 'the closed set a Text value is one of, or a List\'s elements are, comma-separated in the order they run; absent, any value is valid')
+        .option('--meaning <text>', 'one line: what it holds and why', '')
+        .description('declare a custom property; required, it is backfilled blank into the blueprints it applies to')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planPropertyAdd(edit, { name, type: options.type, appliesTo: options.appliesTo === 'all' ? 'all' : options.appliesTo.split(',').map((entry) => entry.trim()).filter((entry) => entry !== ''), required: options.required, meaning: options.meaning, options: options.options === undefined ? null : splitValues(options.options) }), options)));
+    withRoot(configureProperty.command('show'))
+        .argument('[name]', 'one property; none lists every block')
+        .option('--json', 'machine-readable result', false)
+        .description('print a property as the table declares it')
+        .action((name, options) => run(() => showProperty(loadRoot(globals(options)), name, options.json)));
+    planned(configureProperty.command('rename'))
+        .argument('<name>', 'the property')
+        .argument('<new>', 'its new key')
+        .description('rename a custom property: the entry, the key in every blueprint, a grouping that names it, and this CLI\'s settings')
+        .action((name, to, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planPropertyRename(edit, name, to), options)));
+    planned(configureProperty.command('set'))
+        .argument('<name>', 'the property')
+        .option('--type <type>', 'a new type')
+        .option('--applies-to <all|collection,...>', 'a new scope; a blueprint now out of scope loses the key unless --preserve')
+        .option('--required', 'make it required: backfilled blank where missing')
+        .option('--optional', 'make it optional')
+        .option('--options <value,...>', 'the closed set of values, comma-separated in order; narrowing a list surfaces every blueprint value off it and needs --force')
+        .option('--open', 'drop the options: any value is valid again')
+        .option('--meaning <text>', 'a new meaning')
+        .option('--preserve', 'leave keys in blueprints now out of scope, for check to report', false)
+        .description("change a custom property's type, scope, required, options, or meaning")
+        .action((name, options) => {
+        if (options.required && options.optional)
+            return runAsync(async () => Promise.reject(new CliError('--required and --optional exclude each other')));
+        if (options.options !== undefined && options.open)
+            return runAsync(async () => Promise.reject(new CliError('--options and --open exclude each other')));
+        return runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planPropertySet(edit, name, {
+            ...(options.type !== undefined ? { type: options.type } : {}),
+            ...(options.appliesTo !== undefined ? { appliesTo: options.appliesTo === 'all' ? 'all' : options.appliesTo.split(',').map((entry) => entry.trim()).filter((entry) => entry !== '') } : {}),
+            ...(options.required ? { required: true } : options.optional ? { required: false } : {}),
+            ...(options.options !== undefined ? { options: splitValues(options.options) } : options.open ? { options: null } : {}),
+            ...(options.meaning !== undefined ? { meaning: options.meaning } : {}),
+        }, { preserve: options.preserve }), options));
+    });
+    planned(configureProperty.command('remap'))
+        .argument('<name>', 'the property')
+        .argument('<old=new...>', 'each value to rewrite, and what to')
+        .description('rewrite a value in every blueprint where it equals old, and the canvas style keyed by it')
+        .action((name, pairs, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planPropertyRemap(edit, name, pairs.map((pair) => {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            throw new CliError(`expected old=new, got '${pair}'`);
+        return [pair.slice(0, eq), pair.slice(eq + 1)];
+    })), options)));
+    planned(configureProperty.command('remove'))
+        .argument('<name>', 'the property')
+        .option('--preserve', 'leave the key in every blueprint, for check to report as undeclared', false)
+        .description('retire a custom property: the entry and, unless --preserve, the key in every blueprint, its values shown first')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planPropertyRemove(edit, name, { preserve: options.preserve }), options)));
+    const configureCollection = configure('collection', 'the collections: add, show, rename, or remove one, its folder, templates, properties, and links following');
+    planned(configureCollection.command('add'))
+        .argument('<name>', 'the collection, which is its folder')
+        .requiredOption('--unit <unit>', 'the word for one of its blueprints (spec, chapter, decision); its templates are named for it')
+        .option('--description <text>', 'one line', '')
+        .option('--grouping <label>', 'group its blueprints one level deep under this label (Domains, Products)')
+        .description("declare a collection with one default variant, its folder, and that variant's template (a title and an Intent section)")
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planCollectionAdd(edit, { name, unit: options.unit, description: options.description, grouping: options.grouping ?? null }), options)));
+    withRoot(configureCollection.command('show'))
+        .argument('[name]', 'one collection; none lists them all')
+        .option('--json', 'machine-readable result', false)
+        .description('print a collection as the framework declares it')
+        .action((name, options) => run(() => showCollection(loadRoot(globals(options)), name, options.json)));
+    planned(configureCollection.command('rename'))
+        .argument('<name>', 'the collection')
+        .argument('[new]', 'its new name; omit to rename only the unit')
+        .option('--unit <unit>', 'a new unit: the template files are renamed for it')
+        .description('rename a collection: the folder, the entry, every applies_to that names it, and every link in the root that crosses the folder')
+        .action((name, to, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planCollectionRename(edit, name, to ?? name, options.unit ?? null), options)));
+    planned(configureCollection.command('remove'))
+        .argument('<name>', 'the collection')
+        .option('--preserve', 'leave the folder and its blueprints on disk, for check to report as undeclared', false)
+        .description('remove a collection: the entry, its templates, the properties scoped only to it, and, unless --preserve, its folder and blueprints')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planCollectionRemove(edit, name, { preserve: options.preserve }), options)));
+    const folderType = (given) => {
+        if (given === 'assets' || given === 'other')
+            return given;
+        throw new CliError('--type takes assets or other; a collection is declared with configure:collection add');
+    };
+    const configureFolder = configure('folder', 'the folders at the root that are not collections (assets, other): add, show, rename, set, or remove one, its folder and the links into it following');
+    planned(configureFolder.command('add'))
+        .argument('<name>', 'the folder at the root, in the naming convention')
+        .requiredOption('--type <type>', 'assets (files that are not markdown) or other (whatever the description says)')
+        .option('--description <text>', 'one line: what the folder holds', '')
+        .description('declare a folder and create it')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planFolderAdd(edit, { name, type: folderType(options.type), description: options.description }), options)));
+    withRoot(configureFolder.command('show'))
+        .argument('[name]', 'one folder; none lists every folder at the root with its type')
+        .option('--json', 'machine-readable result', false)
+        .description('print a folder as the framework declares it')
+        .action((name, options) => run(() => showFolder(loadRoot(globals(options)), name, options.json)));
+    planned(configureFolder.command('rename'))
+        .argument('<name>', 'the folder')
+        .argument('<new>', 'its new name')
+        .description('rename a folder: the entry, the folder on disk, and every link in the root into it')
+        .action((name, to, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planFolderRename(edit, name, to), options)));
+    planned(configureFolder.command('set'))
+        .argument('<name>', 'the folder')
+        .option('--type <type>', 'assets or other')
+        .option('--description <text>', 'a new description')
+        .description("change a folder's type or description")
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planFolderSet(edit, name, { ...(options.type !== undefined ? { type: folderType(options.type) } : {}), ...(options.description !== undefined ? { description: options.description } : {}) }), options)));
+    planned(configureFolder.command('remove'))
+        .argument('<name>', 'the folder')
+        .option('--preserve', 'leave the folder and its files on disk, for check to report as undeclared', false)
+        .description('remove a folder: the entry and, unless --preserve, the folder and every file in it, each listed first')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planFolderRemove(edit, name, { preserve: options.preserve }), options)));
+    const configureGroup = configure('group', "a collection's groups: add, rename, or remove one, its sub-folder, the grouping values, and the links following");
+    planned(configureGroup.command('add'))
+        .argument('<collection>', 'the collection, which must declare a grouping')
+        .argument('<name>', 'the group, which is its sub-folder')
+        .option('--description <text>', 'one line', '')
+        .description('declare a group and create its sub-folder')
+        .action((collection, name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planGroupAdd(edit, collection, name, options.description), options)));
+    planned(configureGroup.command('rename'))
+        .argument('<collection>', 'the collection')
+        .argument('<name>', 'the group')
+        .argument('<new>', 'its new name')
+        .description('rename a group: the sub-folder, the entry, the grouping value in every blueprint inside, and every link in the root into or out of it')
+        .action((collection, name, to, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planGroupRename(edit, collection, name, to), options)));
+    planned(configureGroup.command('remove'))
+        .argument('<collection>', 'the collection')
+        .argument('<name>', 'the group')
+        .option('--preserve', 'leave the sub-folder and its blueprints on disk, for check to report as undeclared', false)
+        .description('remove a group: the entry and, unless --preserve, its sub-folder and blueprints')
+        .action((collection, name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planGroupRemove(edit, collection, name, { preserve: options.preserve }), options)));
+    const configureVariant = configure('variant', "a collection's variants: add, rename, set the default, or remove one, its template and the blueprints on it following");
+    planned(configureVariant.command('add'))
+        .argument('<collection>', 'the collection')
+        .argument('<name>', 'the variant (full, micro, api)')
+        .option('--description <text>', 'one line', '')
+        .option('--from <variant>', "copy this variant's template; default: the collection's default variant")
+        .description('declare a variant and write its template')
+        .action((collection, name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planVariantAdd(edit, collection, name, options.description, options.from ?? null), options)));
+    planned(configureVariant.command('rename'))
+        .argument('<collection>', 'the collection')
+        .argument('<name>', 'the variant')
+        .argument('<new>', 'its new name')
+        .description('rename a variant: the entry, its template file, and the variant value in every blueprint on it')
+        .action((collection, name, to, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planVariantRename(edit, collection, name, to), options)));
+    planned(configureVariant.command('set-default'))
+        .argument('<collection>', 'the collection')
+        .argument('<name>', 'the variant that becomes the default')
+        .description("make a variant the collection's default")
+        .action((collection, name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planVariantSetDefault(edit, collection, name), options)));
+    planned(configureVariant.command('remove'))
+        .argument('<collection>', 'the collection')
+        .argument('<name>', 'the variant')
+        .description('remove a variant and its template; refused while a blueprint names it unless --force, which clears their variant')
+        .action((collection, name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planVariantRemove(edit, collection, name, { force: options.force }), options)));
+    const configureTerm = configure('term', "the Vocabulary: add, set, or remove a term");
+    planned(configureTerm.command('add'))
+        .argument('<term>', 'the word, as prose uses it')
+        .requiredOption('--means <text>', 'one line: what it means')
+        .option('--not <clause>', 'a near-miss, opening with the word and saying why it differs (repeatable)', collect, [])
+        .option('--see <path>', 'the blueprint that defines it in full, relative to .eidos/')
+        .description('declare a term')
+        .action((term, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planTermAdd(edit, { term, means: options.means, not: options.not, see: options.see ?? null }), options)));
+    planned(configureTerm.command('set'))
+        .argument('<term>', 'the term')
+        .option('--term <word>', 'a new spelling')
+        .option('--means <text>', 'a new meaning')
+        .option('--not <clause>', 'the near-misses, replacing the list (repeatable)', collect, [])
+        .option('--see <path>', "where it is defined in full; '' clears it")
+        .description("change a term's word, meaning, near-misses, or see")
+        .action((term, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planTermSet(edit, term, { ...(options.term !== undefined ? { term: options.term } : {}), ...(options.means !== undefined ? { means: options.means } : {}), ...(options.not.length > 0 ? { not: options.not } : {}), ...(options.see !== undefined ? { see: options.see } : {}) }), options)));
+    planned(configureTerm.command('remove'))
+        .argument('<term>', 'the term')
+        .description('remove a term')
+        .action((term, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planTermRemove(edit, term), options)));
+    const configureDoc = configure('doc', "the top-level docs under top_level: add, rename, set, or remove one, its file at the root following its title");
+    planned(configureDoc.command('add'))
+        .argument('<title>', 'the title; the file is named for it in the naming convention')
+        .option('--description <text>', 'one line: what the document is', '')
+        .description('declare a top-level doc and write its file when there is none')
+        .action((title, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planDocAdd(edit, title, options.description), options)));
+    planned(configureDoc.command('rename'))
+        .argument('<doc>', 'the title or the file')
+        .argument('<title>', 'its new title; the file is renamed to match and every link follows (the same title brings a drifted file in line)')
+        .description('retitle a top-level doc and rename its file')
+        .action((ref, title, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planDocRename(edit, ref, title), options)));
+    planned(configureDoc.command('set'))
+        .argument('<doc>', 'the title or the file')
+        .option('--description <text>', 'a new description')
+        .description("change a top-level doc's description")
+        .action((ref, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planDocSet(edit, ref, { ...(options.description !== undefined ? { description: options.description } : {}) }), options)));
+    planned(configureDoc.command('remove'))
+        .argument('<doc>', 'the title or the file')
+        .option('--preserve', 'leave the file at the root, undeclared', false)
+        .description('remove a top-level doc: the entry, and the file unless --preserve')
+        .action((ref, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planDocRemove(edit, ref, { preserve: options.preserve }), options)));
+    const configureRole = configure('role', 'the roles under .eidos/roles/: add, show, rename, or remove one');
+    planned(configureRole.command('add'))
+        .argument('<name>', 'the role, lowercase words joined by hyphens')
+        .option('--from <role>', 'copy this role\'s file; default: a bare skeleton')
+        .description('write a role file')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planRoleAdd(edit, name, options.from ?? null), options)));
+    withRoot(configureRole.command('show'))
+        .argument('[name]', 'one role, printed whole; none lists them')
+        .option('--json', 'machine-readable result', false)
+        .description('print a role')
+        .action((name, options) => run(() => showRole(loadRoot(globals(options)), name, options.json)));
+    planned(configureRole.command('rename'))
+        .argument('<name>', 'the role')
+        .argument('<new>', 'its new name, lowercase words joined by hyphens; the file, me.md, and the users who hold it follow')
+        .description('rename a role: the file moves, and every reference to it follows')
+        .action((name, to, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planRoleRename(edit, name, to), options)));
+    planned(configureRole.command('remove'))
+        .argument('<name>', 'the role')
+        .description('remove a role file; refused while me.md names it unless --force')
+        .action((name, options) => runAsync(() => runPlan(loadRoot(globals(options)), (edit) => planRoleRemove(edit, name, { force: options.force }), options)));
+    // ---- property: one blueprint's frontmatter
+    const property = program.command('property').description("one blueprint's frontmatter: get, set, or unset a property, typed by the Properties table, so nobody opens a file to flip a value");
+    withRoot(property.command('get'))
+        .argument('<blueprint>', '@<id>, a path, or a filename')
+        .argument('[property]', 'one property; none prints them all')
+        .option('--json', 'machine-readable result', false)
+        .description("print a blueprint's property, or all of them")
+        .action((ref, key, options) => run(() => runPropertyGet(loadRoot(globals(options)), ref, key, options)));
+    withRoot(property.command('set'))
+        .argument('<blueprint>', '@<id>, a path, or a filename')
+        .argument('<property>', 'the property, as the Properties table declares it for the collection')
+        .argument('<value>', 'the value; a List is comma-separated, a Checkbox true or false, a Date YYYY-MM-DD, one of the options where the property declares them')
+        .option('--force', 'write a property the table does not declare for this collection, a tool\'s own, or a value off its options', false)
+        .option('--dry-run', 'print the frontmatter as it would be, writing nothing', false)
+        .option('--json', 'machine-readable result', false)
+        .description('set one property, coerced to its declared type, with the root\'s on-save rules applied')
+        .action((ref, key, value, options) => run(() => runPropertySet(loadRoot(globals(options)), ref, key, value, options)));
+    withRoot(property.command('unset'))
+        .argument('<blueprint>', '@<id>, a path, or a filename')
+        .argument('<property>', 'the property to remove from the file')
+        .option('--dry-run', 'print the frontmatter as it would be, writing nothing', false)
+        .option('--json', 'machine-readable result', false)
+        .description('remove one property from a blueprint')
+        .action((ref, key, options) => run(() => runPropertyUnset(loadRoot(globals(options)), ref, key, options)));
+    property.addHelpText('after', '\nExamples:\n  eidos property get @login\n  eidos property set @login status Done\n  eidos property set specs/identity/login.md tags auth,security\n  eidos property unset @login depends_on');
     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)