eidosmd 0.1.0 → 0.2.0

package/dist/src/core/framework-model.js

@@ -1,9 +1,15 @@
 // The framework model: everything a framework document declares, whichever
-// of `_eidos/Framework.md`, `.yaml`, or `.json` it is. The version and naming
-// convention, the Top-Level docs, the Collections (each with flavors, canvas
-// style, and grouping), and the property Schema.
+// of `.eidos/Framework.md` or `.yaml` it is. The version and naming
+// convention, the Top-Level docs, the Collections (each with variants and
+// grouping), the Properties table (`schema` here, `properties` on disk), the
+// Vocabulary, and the root's own Versions.
 import { kebab } from './naming.js';
-export const FRAMEWORK_DIR = '_eidos';
+export const FRAMEWORK_DIR = '.eidos';
+// This tool's name, as the standard has a tool sign what it keeps in a
+// framework: its folder under `.eidos/plugins/<name>/`, and its fields on a
+// Properties row (a key on the YAML entry, a column in the markdown table).
+export const TOOL_KEY = 'eidosmd';
+export const PLUGINS_DIR = 'plugins';
 export function isFrameworkFormat(value) {
     return value === 'md' || value === 'yaml';
 }
@@ -13,20 +19,31 @@ export const FRAMEWORK_FILES = [
     { name: 'Framework.yml', format: 'yaml' },
 ];
 export const PROPERTY_TYPES = ['Text', 'List', 'Number', 'Checkbox', 'Date', 'Date & time'];
+// The unit a collection speaks in, the word for one of its blueprints: what
+// its template files are named for (`<unit>.<variant>.md`), read off the
+// default variant. A collection whose unit is `frame` is the framing one, this
+// CLI's recommendation for every product; the standard names no collection.
+export function unitOf(collection) {
+    const variant = collection.variants.find((entry) => entry.isDefault) ?? collection.variants[0];
+    return variant && variant.unit !== '' ? variant.unit : null;
+}
 export class FrameworkError extends Error {
     constructor(message) {
         super(message);
         this.name = 'FrameworkError';
     }
 }
-// The standard's own five, used when a Framework.md carries no core block.
+// The standard's own four (Eidos 5.0.0), used when a Framework.md carries no core block.
 export const STANDARD_CORE = [
-    { name: 'id', type: 'Text', appliesTo: 'all', meaning: 'Stable, unique, kebab-case identity. Assigned once, never renamed.', core: true },
-    { name: 'title', type: 'Text', appliesTo: 'all', meaning: 'Human-readable name.', core: true },
-    { name: 'summary', type: 'Text', appliesTo: 'all', meaning: 'One plain line: what this blueprint is. The source for the collection index.', core: true },
-    { name: 'flavor', type: 'Text', appliesTo: 'all', meaning: 'Which flavor this blueprint follows. Absent = the collection default.', core: true },
-    { name: 'connects_to', type: 'List', appliesTo: 'all', meaning: 'Blueprints this one connects to on the canvas, each a link.', core: true },
+    { name: 'id', type: 'Text', appliesTo: 'all', meaning: 'Stable, unique identity, in any form: a slug, a number, a GUID. Assigned once, never changed.', core: true, owner: 'eidos' },
+    { name: 'title', type: 'Text', appliesTo: 'all', meaning: 'Human-readable name.', core: true, owner: 'eidos' },
+    { name: 'summary', type: 'Text', appliesTo: 'all', meaning: 'One plain line: what this blueprint is. The source for the collection index.', core: true, owner: 'eidos' },
+    { name: 'variant', type: 'Text', appliesTo: 'all', meaning: 'Which variant this blueprint follows. Absent = the collection default.', core: true, owner: 'eidos' },
 ];
+// Every property of the Properties table, whichever block owns it, core first.
+export function allProperties(schema) {
+    return [...schema.core, ...schema.custom, ...Object.values(schema.tools).flat()];
+}
 // `Domains` -> `domain`: the custom property that carries a collection's group,
 // matched by the grouping label's singular against the properties scoped to it.
 export function groupingProperty(collection, custom) {

package/dist/src/core/framework-structured.js

@@ -1,13 +1,14 @@
-// The YAML framework document, `_eidos/Framework.yaml`: the same model as the
+// The YAML framework document, `.eidos/Framework.yaml`: the same model as the
 // markdown form, as fields in the frontmatter's snake_case, for a root that
 // scripts and agents read.
-// Paths are relative to `_eidos/`, as the markdown links are. A structured
+// Paths are relative to `.eidos/`, as the markdown links are. A structured
 // document also carries the generated index under `index`, one list per
 // collection, which `eidos index` rewrites in place without disturbing
 // anything a person wrote around it.
 import { Document, isMap, isPair, isScalar, parse as parseYaml, parseDocument } from 'yaml';
-import { groupingProperty, STANDARD_CORE, } from './framework-model.js';
+import { groupingProperty, STANDARD_CORE, TOOL_KEY, unitOf } from './framework-model.js';
 import { DEFAULT_NAMING, isNaming } from './naming.js';
+const STANDARD_PROPERTY_KEYS = new Set(['name', 'type', 'applies_to', 'meaning']);
 function isPlain(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -51,23 +52,43 @@ function readCanvas(value, where, problems) {
     problems.push(`${where}: canvas must be file, card, or { mode: card, section: <Section> }`);
     return null;
 }
-function readFlavor(value, where, problems) {
-    if (!isPlain(value) || text(value['name']) === '' || text(value['shape']) === '') {
-        problems.push(`${where}: every flavor needs a name and a shape`);
+// `template` (`shape` before 5.0.0) is the file's path relative to `.eidos/`.
+function readVariant(value, where, problems) {
+    const given = isPlain(value) ? text(value['template']) || text(value['shape']) : '';
+    if (!isPlain(value) || text(value['name']) === '' || given === '') {
+        problems.push(`${where}: every variant needs a name and a template`);
         return null;
     }
-    const shape = text(value['shape']).replace(/\\/g, '/');
-    const file = shape.split('/').pop() ?? shape;
+    const template = given.replace(/\\/g, '/');
+    const file = template.split('/').pop() ?? template;
     const stem = file.replace(/\.md$/i, '');
     const dot = stem.indexOf('.');
     return {
         name: text(value['name']),
-        kind: dot === -1 ? stem : stem.slice(0, dot),
-        shape,
+        unit: dot === -1 ? stem : stem.slice(0, dot),
+        template,
         description: text(value['description']),
         isDefault: value['default'] === true,
     };
 }
+// `vocabulary`: one entry per term; `not` is a list (a single string reads as one entry).
+function readVocabulary(value, problems) {
+    const out = [];
+    list(value).forEach((entry, index) => {
+        if (!isPlain(entry) || text(entry['term']) === '') {
+            problems.push(`vocabulary[${index}]: a term needs a term`);
+            return;
+        }
+        const nots = Array.isArray(entry['not']) ? entry['not'] : entry['not'] === undefined || entry['not'] === null ? [] : [entry['not']];
+        out.push({
+            term: text(entry['term']),
+            means: text(entry['means']),
+            not: nots.map((item) => text(item)).filter((item) => item !== ''),
+            see: text(entry['see']) === '' ? null : text(entry['see']),
+        });
+    });
+    return out;
+}
 function readCollection(value, index, problems) {
     const where = `collections[${index}]`;
     if (!isPlain(value) || text(value['name']) === '') {
@@ -75,11 +96,11 @@ function readCollection(value, index, problems) {
         return null;
     }
     const name = text(value['name']);
-    const flavors = list(value['flavors'])
-        .map((flavor, position) => readFlavor(flavor, `${where} (${name}) flavors[${position}]`, problems))
-        .filter((flavor) => flavor !== null);
-    if (flavors.length > 0 && !flavors.some((flavor) => flavor.isDefault)) {
-        const first = flavors[0];
+    const variants = list(value['variants'] ?? value['flavors'])
+        .map((variant, position) => readVariant(variant, `${where} (${name}) variants[${position}]`, problems))
+        .filter((variant) => variant !== null);
+    if (variants.length > 0 && !variants.some((variant) => variant.isDefault)) {
+        const first = variants[0];
         if (first) {
             first.isDefault = true;
         }
@@ -87,12 +108,13 @@ function readCollection(value, index, problems) {
     const collection = {
         name,
         description: text(value['description']),
-        framing: index === 0,
+        framing: false,
         leaf: null,
-        flavors,
+        variants,
         canvas: readCanvas(value['canvas'], `${where} (${name})`, problems),
         grouping: null,
     };
+    collection.framing = unitOf(collection) === 'frame';
     const grouping = value['grouping'];
     if (grouping !== undefined && grouping !== null) {
         if (!isPlain(grouping) || text(grouping['label']) === '') {
@@ -111,7 +133,7 @@ function readCollection(value, index, problems) {
     }
     return collection;
 }
-function readProperty(value, where, core, problems) {
+function readProperty(value, where, core, problems, owner = core ? 'eidos' : 'custom') {
     if (!isPlain(value) || text(value['name']) === '') {
         problems.push(`${where}: a property needs a name`);
         return null;
@@ -132,7 +154,54 @@ function readProperty(value, where, core, problems) {
             problems.push(`${where}: applies_to must be all or a list of collections`);
         }
     }
-    return { name: text(value['name']), type: text(value['type']) || 'Text', appliesTo: applies, meaning: text(value['meaning']), core };
+    const property = { name: text(value['name']), type: text(value['type']) || 'Text', appliesTo: applies, meaning: text(value['meaning']), core, owner };
+    const tools = {};
+    for (const [key, field] of Object.entries(value)) {
+        if (!STANDARD_PROPERTY_KEYS.has(key) && key !== 'canvas' && field !== undefined && field !== null) {
+            tools[key] = field;
+        }
+    }
+    if (Object.keys(tools).length > 0) {
+        property.tools = tools;
+    }
+    // This tool's hint sits under its own key; a bare `canvas` (how the first
+    // canvases were written) still reads.
+    const own = isPlain(tools[TOOL_KEY]) ? tools[TOOL_KEY]['canvas'] : undefined;
+    const hint = readCanvasHint(own) ?? readCanvasHint(value['canvas']);
+    if (hint) {
+        property.canvas = hint;
+    }
+    return property;
+}
+function readStringMap(value) {
+    if (!isPlain(value)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item === 'string' || typeof item === 'number') {
+            out[key] = String(item);
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export function readCanvasHint(value) {
+    if (!isPlain(value)) {
+        return null;
+    }
+    const hint = {};
+    if (value['show'] === true) {
+        hint.show = true;
+    }
+    const shape = readStringMap(value['shape']);
+    if (shape) {
+        hint.shape = shape;
+    }
+    const color = readStringMap(value['color']);
+    if (color) {
+        hint.color = color;
+    }
+    return Object.keys(hint).length > 0 ? hint : null;
 }
 export function readEmbeddedIndex(value) {
     if (!isPlain(value)) {
@@ -182,15 +251,23 @@ export function parseFrameworkStructured(source, root, file) {
         .map((collection, index) => readCollection(collection, index, problems))
         .filter((collection) => collection !== null);
     if (!Array.isArray(document['collections']) && !error && isPlain(value)) {
-        problems.push('collections must be a list; the first is the framing collection');
+        problems.push('collections must be a list');
     }
-    const schema = isPlain(document['schema']) ? document['schema'] : {};
+    const schema = isPlain(document['properties']) ? document['properties'] : isPlain(document['schema']) ? document['schema'] : {};
     const core = list(schema['core'])
         .map((property, index) => readProperty(property, `schema.core[${index}]`, true, problems))
         .filter((property) => property !== null);
     const custom = list(schema['custom'])
         .map((property, index) => readProperty(property, `schema.custom[${index}]`, false, problems))
         .filter((property) => property !== null);
+    const tools = {};
+    if (isPlain(schema['tools'])) {
+        for (const [tool, block] of Object.entries(schema['tools'])) {
+            tools[tool] = list(block)
+                .map((property, index) => readProperty(property, `schema.tools.${tool}[${index}]`, false, problems, tool))
+                .filter((property) => property !== null);
+        }
+    }
     for (const collection of collections) {
         if (collection.grouping && collection.grouping.property === null) {
             collection.grouping.property = groupingProperty(collection, custom);
@@ -209,7 +286,8 @@ export function parseFrameworkStructured(source, root, file) {
         namingError,
         topLevel,
         collections,
-        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom },
+        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom, tools },
+        vocabulary: readVocabulary(document['vocabulary'], problems),
         problems,
     };
 }
@@ -249,12 +327,12 @@ export function frameworkToDocument(framework) {
                 entry.canvas = { mode: 'card', section: collection.canvas.section };
             }
         }
-        entry.flavors = collection.flavors.map((flavor) => {
-            const item = { name: flavor.name, shape: flavor.shape };
-            if (flavor.description) {
-                item.description = flavor.description;
+        entry.variants = collection.variants.map((variant) => {
+            const item = { name: variant.name, template: variant.template };
+            if (variant.description) {
+                item.description = variant.description;
             }
-            if (flavor.isDefault) {
+            if (variant.isDefault) {
                 item.default = true;
             }
             return item;
@@ -276,23 +354,44 @@ export function frameworkToDocument(framework) {
         }
         return entry;
     });
-    document.schema = {
-        core: framework.schema.core.map(({ name, type, meaning }) => ({ name, type, meaning })),
-        custom: framework.schema.custom.map(({ name, type, appliesTo: applies, meaning }) => ({ name, type, applies_to: applies, meaning })),
+    const entry = ({ name, type, appliesTo: applies, meaning, canvas, tools }) => {
+        const fields = { ...(tools ?? {}) };
+        if (canvas) {
+            const own = isPlain(fields[TOOL_KEY]) ? fields[TOOL_KEY] : {};
+            fields[TOOL_KEY] = { ...own, canvas };
+        }
+        return { name, type, applies_to: applies, meaning, ...fields };
     };
+    document.properties = {
+        core: framework.schema.core.map(({ name, type, meaning, tools }) => ({ name, type, meaning, ...(tools ?? {}) })),
+        custom: framework.schema.custom.map(entry),
+    };
+    if (Object.keys(framework.schema.tools).length > 0) {
+        document.properties.tools = Object.fromEntries(Object.entries(framework.schema.tools).map(([tool, block]) => [tool, block.map(entry)]));
+    }
+    if (framework.vocabulary.length > 0) {
+        document.vocabulary = framework.vocabulary.map((term) => {
+            const entry = { term: term.term, means: term.means, not: term.not };
+            if (term.see)
+                entry.see = term.see;
+            return entry;
+        });
+    }
     return document;
 }
 const YAML_GUIDANCE = {
     eidos_version: ' The Eidos version this framework targets; migrate reads and bumps it.',
     naming: ' How files, folders, and links are named: kebab-case | TitleCase | Title Case. Settled once.',
     top_level: ' The top-level documents, README first: one entry per one-of-a-kind doc (a Roadmap, a Vision).',
-    collections: " The collections, the first of them the framing one. Each declares its flavors (one default), how a canvas draws it, and its grouping.\n Add a group under `grouping.groups` with a one-line description; add a flavor with a shape file in shapes/.",
-    schema: ' The property contract. `core` is the standard\'s and moves with eidos_version; `custom` is yours: name, type (Text | List | Number | Checkbox | Date | Date & time), applies_to (all or a list), meaning.',
+    collections: " The collections. Each declares its variants (one default; each a template file named <unit>.<variant>.md under templates/, the unit being the word for one of its blueprints) and its grouping.\n Add a group under `grouping.groups` with a one-line description; add a variant with a template file in templates/.",
+    properties: " The Properties table, one block per owner. `core` is the standard's and moves with eidos_version; `custom` is yours: name, type (Text | List | Number | Checkbox | Date | Date & time), applies_to (all or a list), meaning; `tools.<tool>` is a block a tool declared and alone writes.\n A key past those four on a row is a tool's, named for the tool; `eidosmd.canvas` is how this CLI styles a canvas node by the property's value.",
+    vocabulary: " The root's own terms, one entry each: term, means (one line), not (the near-misses, each with why it is a different thing), and see (the blueprint that defines it in full) when one does. Absent = none declared.",
+    versions: " Snapshots of the root, taken on purpose, newest first: version (the root's own number), commit (the sha that is the snapshot), tag (blueprints/<version>, when made). Absent = none recorded, the normal state.",
     index: ' Generated by `eidos index`; never hand-edited. One list per collection, in the order the markdown index would use.',
 };
 // A YAML document a person will edit gets the guidance the markdown seed
 // keeps as prose, as comments above each top-level key.
-function annotateYaml(document) {
+export function annotateYaml(document) {
     if (!isMap(document.contents)) {
         return;
     }

package/dist/src/core/framework.js

@@ -1,6 +1,6 @@
-// Finding and loading the root's framework document: exactly one of
-// `_eidos/Framework.md` or `Framework.yaml`, parsed into
-// the one model every command reads.
+// Finding and loading the root's framework document, `.eidos/Framework.yaml`,
+// parsed into the one model every command reads. A 4.x root's Framework.md
+// is found and parsed too, only so `migrate` can move it.
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseFrameworkMarkdown } from './framework-markdown.js';
@@ -8,7 +8,7 @@ import { parseFrameworkStructured } from './framework-structured.js';
 import { appliesTo, FRAMEWORK_DIR, FRAMEWORK_FILES, FrameworkError } from './framework-model.js';
 import { kebab } from './naming.js';
 export * from './framework-model.js';
-// The one framework document in a folder's `_eidos/`, or null; two is an error.
+// The one framework document in a folder's `.eidos/`, or null; two is an error.
 export function findFrameworkFile(dir) {
     const present = FRAMEWORK_FILES.map((candidate) => ({ file: path.join(dir, FRAMEWORK_DIR, candidate.name), format: candidate.format })).filter((candidate) => existsSync(candidate.file));
     if (present.length > 1) {
@@ -28,7 +28,7 @@ export function parseFramework(text, format, root, file) {
 export function loadFramework(root) {
     const found = findFrameworkFile(root);
     if (!found) {
-        throw new FrameworkError(`${path.join(root, FRAMEWORK_DIR)} holds no framework document (Framework.md or Framework.yaml)`);
+        throw new FrameworkError(`${path.join(root, FRAMEWORK_DIR)} holds no framework document (Framework.yaml)`);
     }
     return parseFramework(readFileSync(found.file, 'utf8'), found.format, root, found.file);
 }
@@ -38,19 +38,19 @@ export function findCollection(framework, name) {
         framework.collections.find((collection) => kebab(collection.name) === kebab(name)) ??
         null);
 }
-export function findFlavor(collection, name) {
+export function findVariant(collection, name) {
     const wanted = name.trim().toLowerCase();
-    return (collection.flavors.find((flavor) => flavor.name.toLowerCase() === wanted) ??
-        collection.flavors.find((flavor) => kebab(flavor.name) === kebab(name)) ??
+    return (collection.variants.find((variant) => variant.name.toLowerCase() === wanted) ??
+        collection.variants.find((variant) => kebab(variant.name) === kebab(name)) ??
         null);
 }
-export function defaultFlavor(collection) {
-    return collection.flavors.find((flavor) => flavor.isDefault) ?? collection.flavors[0] ?? null;
+export function defaultVariant(collection) {
+    return collection.variants.find((variant) => variant.isDefault) ?? collection.variants[0] ?? null;
 }
 // The properties a blueprint in this collection carries, core first.
 export function propertiesFor(framework, collectionName) {
-    return [...framework.schema.core, ...framework.schema.custom.filter((property) => appliesTo(property, collectionName))];
+    return [...framework.schema.core, ...[...framework.schema.custom, ...Object.values(framework.schema.tools).flat()].filter((property) => appliesTo(property, collectionName))];
 }
-export function shapePath(framework, flavor) {
-    return path.join(framework.root, FRAMEWORK_DIR, flavor.shape);
+export function templatePath(framework, variant) {
+    return path.join(framework.root, FRAMEWORK_DIR, variant.template);
 }

package/dist/src/core/git.js

@@ -0,0 +1,59 @@
+// The little git the CLI needs: the commit a root sits at, whether a commit
+// exists, and a tag on one. Every call is read-only except `gitTag`, and
+// every one answers null or false rather than throwing where git is absent
+// or the root is not in a repository.
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+function git(root, args) {
+    try {
+        return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function gitHead(root) {
+    return git(root, ['rev-parse', 'HEAD']);
+}
+// The full sha of a commit named any way git accepts (a short sha, HEAD, a
+// tag), or null when nothing by that name is a commit here.
+export function gitResolve(root, ref) {
+    return git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+}
+export function gitTagExists(root, tag) {
+    return git(root, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`]) !== null;
+}
+export function gitTag(root, tag, sha) {
+    return git(root, ['tag', tag, sha]) !== null || gitTagExists(root, tag);
+}
+// Who git says is committing here: the repository's configured user, falling
+// back to the global one the way git itself does. Null outside a repository
+// or where no name is set.
+export function gitUser(root) {
+    if (gitHead(root) === null && git(root, ['rev-parse', '--git-dir']) === null)
+        return null;
+    const name = git(root, ['config', 'user.name']);
+    if (name === null)
+        return null;
+    return { name, email: git(root, ['config', 'user.email']) };
+}
+// The commits that touched one file, newest first, following renames.
+export function gitLog(root, file, limit = 50) {
+    const out = git(root, ['log', `--max-count=${limit}`, '--follow', '--format=%H%x1f%h%x1f%an%x1f%ae%x1f%aI%x1f%s', '--', file]);
+    if (out === null)
+        return [];
+    return out
+        .split('\n')
+        .map((line) => line.split('\x1f'))
+        .filter((parts) => parts.length === 6)
+        .map(([sha, short, author, email, date, subject]) => ({ sha: sha ?? '', short: short ?? '', author: author ?? '', email: email ?? '', date: date ?? '', subject: subject ?? '' }));
+}
+// The file as one commit held it, or null when that commit has no such file.
+export function gitShowFile(root, sha, file) {
+    try {
+        return execFileSync('git', ['show', `${sha}:${file.split(path.sep).join('/')}`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/core/index-leaf.js

@@ -2,8 +2,8 @@
 // `summary`, kept inside the YAML framework document under `index`, one list
 // per collection, regenerated wholesale. `eidos index` rewrites that key and
 // nothing else in the document, so the comments and layout a person chose
-// survive. (A markdown root keeps a per-collection `index.md` instead; the
-// CLI converts such a root rather than maintaining that form.)
+// survive. (A 4.x markdown root kept a per-collection `index.md` instead;
+// `migrate` converts such a root.)
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { blueprintId, blueprintTitle, propertyString } from './blueprint.js';

package/dist/src/core/me.js

@@ -1,14 +1,14 @@
-// The actor: `_eidos/me.md`, personal and gitignored, naming a role from
-// `_eidos/roles/` and calibrating it on three axes.
+// The actor: `.eidos/me.md`, personal and gitignored, naming a role from
+// `.eidos/roles/` and calibrating it on three axes.
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { headings, section } from './markdown.js';
 import { kebab } from './naming.js';
 export function rolesDir(root) {
-    return path.join(root, '_eidos', 'roles');
+    return path.join(root, '.eidos', 'roles');
 }
 export function meFile(root) {
-    return path.join(root, '_eidos', 'me.md');
+    return path.join(root, '.eidos', 'me.md');
 }
 export function listRoles(root) {
     const dir = rolesDir(root);
@@ -27,6 +27,11 @@ export function listRoles(root) {
         return { name: entry.replace(/\.md$/i, ''), file, title, summary };
     });
 }
+// A role's file name is its kebab-case name, one level under roles/.
+export const isRoleName = (name) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+export function roleFile(root, name) {
+    return path.join(rolesDir(root), `${name}.md`);
+}
 export function findRole(root, name) {
     const wanted = kebab(name);
     return listRoles(root).find((role) => role.name === wanted || kebab(role.title) === wanted) ?? null;
@@ -65,13 +70,16 @@ export function parseActor(text) {
     actor.capacity = axis('Technical capacity');
     return actor;
 }
-export function renderActor(role, custom, axes) {
-    const lines = ['# Me', '', 'Personal and per-actor — gitignored, never shared. The agent reads it before acting.', ''];
+// `note` is anything the person adds under their role, in their own words.
+export function renderActor(role, custom, axes, note = null) {
+    const lines = ['# Me', '', 'Personal and per-actor, gitignored, never shared. The agent reads it before acting.', ''];
     if (role) {
-        lines.push(`## You are: ${role.title}`, '', `Role: [_eidos/roles/${role.name}.md](roles/${role.name}.md).`, '');
+        lines.push(`## You are: ${role.title}`, '', `Role: [.eidos/roles/${role.name}.md](roles/${role.name}.md).`, '');
+        if (note)
+            lines.push(note, '');
     }
     else if (custom) {
-        lines.push(`## You are: ${custom}`, '', 'A custom role: describe how you want to be helped here.', '');
+        lines.push(`## You are: ${custom}`, '', note ?? 'A custom role: describe how you want to be helped here.', '');
     }
     else {
         lines.push('## You are:', '', '<!-- Name your role, or pick one with `eidos whoami --role <role>`. -->', '');