eidosmd 0.2.0 → 0.3.1

package/dist/src/core/store.js

@@ -6,7 +6,8 @@
 // runtime without node:sqlite (Node 20) gets a plain substring scorer with
 // the same shape of result, so the page behaves the same everywhere.
 import { createRequire } from 'node:module';
-import { watch } from 'node:fs';
+import { readdirSync, statSync, watch } from 'node:fs';
+import path from 'node:path';
 import { loadRoot } from '../context.js';
 import { blueprintId, blueprintTitle, propertyString, resolveVariant } from './blueprint.js';
 const IGNORED = new Set(['.git', 'node_modules', '.DS_Store']);
@@ -192,7 +193,10 @@ export class Store {
     dirty = true;
     search_;
     watcher = null;
+    poller = null;
     pending = null;
+    // the root-relative paths that changed since the last event went out
+    changed = new Set();
     listeners = new Set();
     constructor(options) {
         this.root = options.root;
@@ -221,7 +225,8 @@ export class Store {
         this.context();
         return this.search_.search(query, limit);
     }
-    // Called after the disk settles, for the page to refetch what it shows.
+    // Called after the disk settles, with the root-relative paths that
+    // changed, so a view can tell whether the file it holds is one of them.
     onChange(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -229,31 +234,82 @@ export class Store {
     close() {
         this.watcher?.close();
         this.watcher = null;
+        if (this.poller)
+            clearInterval(this.poller);
+        this.poller = null;
         if (this.pending)
             clearTimeout(this.pending);
         this.search_.close();
     }
+    noticed(name) {
+        if (name.split(/[\\/]/).some((part) => IGNORED.has(part)))
+            return;
+        this.dirty = true;
+        if (name !== '')
+            this.changed.add(name.split(path.sep).join('/'));
+        if (this.pending)
+            clearTimeout(this.pending);
+        this.pending = setTimeout(() => {
+            this.pending = null;
+            const paths = [...this.changed].sort();
+            this.changed.clear();
+            for (const listener of this.listeners)
+                listener(paths);
+        }, 150);
+    }
+    // Recursive watching where the platform has it (macOS, Windows, recent
+    // Linux); elsewhere a poll of the tree's mtimes every two seconds does the
+    // same job, so the page behaves the same on every machine.
     startWatching() {
         try {
-            this.watcher = watch(this.root, { recursive: true }, (_event, filename) => {
-                const name = typeof filename === 'string' ? filename : '';
-                if (name.split(/[\\/]/).some((part) => IGNORED.has(part)))
-                    return;
-                this.dirty = true;
-                if (this.pending)
-                    clearTimeout(this.pending);
-                this.pending = setTimeout(() => {
-                    this.pending = null;
-                    for (const listener of this.listeners)
-                        listener();
-                }, 150);
-            });
+            this.watcher = watch(this.root, { recursive: true }, (_event, filename) => this.noticed(typeof filename === 'string' ? filename : ''));
             this.watcher.unref();
         }
         catch {
-            // No recursive watching here: reads still see every write made through
-            // this server, and a change made elsewhere shows on the next reload.
             this.watcher = null;
+            let last = snapshotTree(this.root);
+            this.poller = setInterval(() => {
+                const next = snapshotTree(this.root);
+                for (const [file, stamp] of next)
+                    if (last.get(file) !== stamp)
+                        this.noticed(file);
+                for (const file of last.keys())
+                    if (!next.has(file))
+                        this.noticed(file);
+                last = next;
+            }, 2000);
+            this.poller.unref();
         }
     }
 }
+// Every file under the root with its mtime, root-relative, for the poll.
+function snapshotTree(root) {
+    const out = new Map();
+    const walk = (dir) => {
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED.has(entry))
+                continue;
+            const full = path.join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(full);
+            else
+                out.set(path.relative(root, full).split(path.sep).join('/'), stat.mtimeMs);
+        }
+    };
+    walk(root);
+    return out;
+}

package/dist/src/core/versions.js

@@ -3,14 +3,19 @@
 // plugin's folder, and since 5.0.0 keeps no `versions` key of its own). A
 // version is a name the owner chose and a commit that already exists in the
 // repository the root lives in; the commit is the snapshot, nothing is copied.
-// A tag, when wanted, is `blueprints/<version>`. Nothing here proposes a
-// version: it is written only when asked, and it needs git.
+// A tag, when wanted, is the root's tag prefix (settings.yaml
+// `versions.tag_prefix`, `blueprints/` unless changed) before the version.
+// Nothing here proposes a version: it is written only when asked, and it
+// needs git.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { parse, stringify } from 'yaml';
 import { FRAMEWORK_DIR, TOOL_KEY } from './framework-model.js';
 import { gitResolve, gitTag, gitTagExists } from './git.js';
-export const TAG_PREFIX = 'blueprints/';
+import { DEFAULT_TAG_PREFIX, readSettings } from './settings.js';
+export const TAG_PREFIX = DEFAULT_TAG_PREFIX;
+// What a tag on this root starts with, as its settings say.
+export const tagPrefix = (root) => readSettings(root).shared.versions.tag_prefix;
 export class VersionError extends Error {
     constructor(message) {
         super(message);
@@ -18,7 +23,7 @@ export class VersionError extends Error {
     }
 }
 export const versionsFile = (root) => path.join(root, FRAMEWORK_DIR, 'plugins', TOOL_KEY, 'versions.yaml');
-const GUIDANCE = "# The root's own versions, kept by the eidos CLI (`eidos version`): snapshots taken on purpose, newest first.\n# version is the root's own number, commit the sha that is the snapshot, tag blueprints/<version> when one was made.\n";
+const GUIDANCE = "# The root's own versions, kept by the eidos CLI (`eidos version`): snapshots taken on purpose, newest first.\n# version is the root's own number, commit the sha that is the snapshot, tag <prefix><version> when one was made.\n";
 // Newest first, as recorded; none when the file is absent.
 export function readVersions(root) {
     const file = versionsFile(root);
@@ -62,7 +67,7 @@ export function recordVersion(root, options) {
         throw new VersionError(`'${ref}' is not a commit in the repository this root lives in; a version names a commit that exists`);
     }
     const short = sha.slice(0, 12);
-    const tag = options.tag ? `${TAG_PREFIX}${version}` : null;
+    const tag = options.tag ? `${options.tagPrefix ?? tagPrefix(root)}${version}` : null;
     let tagged = false;
     if (tag) {
         if (gitTagExists(root, tag)) {

package/dist/src/program.js

@@ -15,7 +15,10 @@ 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 { 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';
@@ -37,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.
@@ -63,10 +71,13 @@ Start with \`eidos instructions\` for the workflow, or \`eidos seeds\` and \`eid
         .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
@@ -76,9 +87,9 @@ Examples:
 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'));
+        // 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')
@@ -88,14 +99,15 @@ Writes the seed's Framework.yaml into the root with its guidance as comments, th
         run(() => runSeeds(options));
     });
     withRoot(program.command('framework'))
-        .description("show the root's framework: version, naming, top-level docs, collections (variants, groups), the Properties table, and the Vocabulary")
+        .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, normalized, with this CLI\'s guidance as comments')
         .addHelpText('after', `
 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, 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? }] }
+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(() => runFramework(loadRoot(globals(options), process.cwd()), options));
@@ -147,10 +159,12 @@ Examples:
     withRoot(program.command('check'))
         .argument('[blueprint...]', 'only these blueprints (paths); default: the whole root')
         .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)
+        .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 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.
+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
@@ -236,9 +250,9 @@ A snapshot of the root as a whole is a version: \`eidos version record\`.`);
     });
     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>')
+        .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 blueprints/<version> on that commit', false)
+        .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));
@@ -254,6 +268,7 @@ The commit is the snapshot (git holds every blueprint as it was), nothing is cop
         .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));
@@ -261,6 +276,7 @@ A template that opens with frontmatter loses the block; one named off its unit (
     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`')
@@ -289,6 +305,275 @@ Examples:
             }
         }
     });
+    // ---- 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)

package/instructions/authoring.md

@@ -12,7 +12,7 @@ Run `eidos framework`. Decide with the owner which collection the blueprint belo
 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 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.
+`new` generates the frontmatter from the required properties that apply to the collection, adding an optional one only when it is given a value (`--set`, `--summary`), 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.
 
@@ -29,7 +29,9 @@ Open the file. The template's sections are in order, each with an italic prompt
 - 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 Properties table 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. Set a value with the command, never by opening the file: `eidos property set @<id> <property> <value>` (a List comma-separated, a Checkbox true or false, a Date YYYY-MM-DD; `eidos property get @<id>` reads, `unset` removes). It is typed by the Properties table, applies the root's on-save rules, and refuses a key the table does not declare for the collection. Where a property declares `options` (`eidos framework` lists them, in order), offer the owner that list and set one of them, exactly as declared, case included; the command refuses a value off the list unless `--force`, and `check` reports one it finds. Leave a required property blank rather than guessing it; an optional one absent is not a gap.
+
+A span between `<!-- <tool>:<region> <args> -->` and `<!-- /<tool>:<region> -->`, each marker alone on its line, is a region that tool owns: leave its contents alone, and when you edit the file around it, carry it across as found. `eidosmd` is this CLI's name; a region under it is the CLI's.
 
 ### 4. Check and index