eidosmd 0.1.0 → 0.2.0

package/dist/src/core/check.js

@@ -1,17 +1,18 @@
-// Validation, framework-defined: every rule reads the root's own Framework.md
-// and shapes, never a contract hardcoded here. Findings surface; a human acts
+// Validation, framework-defined: every rule reads the root's own Framework.yaml
+// and templates, never a contract hardcoded here. Findings surface; a human acts
 // on them. Errors are things that are wrong on any reading (a malformed file,
 // an id used twice, a link to nowhere); warnings are gaps the standard says to
 // note and offer, never refuse.
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { blueprintId, blueprintTitle, propertyString, resolveFlavor } from './blueprint.js';
-import { appliesTo } from './framework.js';
+import { blueprintId, blueprintTitle, propertyString, resolveVariant } from './blueprint.js';
+import { appliesTo, unitOf } from './framework.js';
 import { renderEmbeddedEntries } from './index-leaf.js';
 import { embeddedIndexOf } from './framework-structured.js';
+import { FRAME_REF, isFrameRef, listCanvases } from './canvas.js';
 import { normalizeNewlines } from './markdown.js';
-import { isKebab, kebab } from './naming.js';
-import { loadShape } from './shape.js';
+import { kebab } from './naming.js';
+import { loadTemplate } from './template.js';
 const WORK_TRACKING_FIELDS = new Set(['sprint', 'estimate', 'assignee', 'story_points']);
 const SKIPPED_DIRS = new Set(['node_modules', 'dist', 'build']);
 function compareVersions(a, b) {
@@ -99,8 +100,8 @@ function propertyLinks(value) {
 }
 class Collector {
     findings = [];
-    error(code, file, message) {
-        this.findings.push({ level: 'error', code, path: file, message });
+    error(code, file, message, fix) {
+        this.findings.push({ level: 'error', code, path: file, message, ...(fix ? { fix } : {}) });
     }
     warn(code, file, message) {
         this.findings.push({ level: 'warning', code, path: file, message });
@@ -123,14 +124,17 @@ function checkFramework(framework, out, options) {
     else {
         const diff = compareVersions(framework.eidosVersion, options.standardVersion);
         if (diff < 0) {
-            out.warn('version-behind', frameworkRel, `targets Eidos ${framework.eidosVersion}; this CLI carries ${options.standardVersion} (migrate when ready)`);
+            out.warn('version-behind', frameworkRel, `targets Eidos ${framework.eidosVersion}; this CLI carries ${options.standardVersion}: run \`eidos migrate\` when ready`);
         }
         else if (diff > 0) {
             out.warn('version-ahead', frameworkRel, `targets Eidos ${framework.eidosVersion}, newer than the ${options.standardVersion} this CLI carries`);
         }
     }
     if (framework.collections.length === 0) {
-        out.error('no-collections', frameworkRel, 'declares no collections under ## Collections; a framework needs at least a framing collection');
+        out.error('no-collections', frameworkRel, 'declares no collections; a framework needs at least one');
+    }
+    if (/^versions:/m.test(readFileSync(framework.file, 'utf8'))) {
+        out.warn('versions-legacy', frameworkRel, 'carries a versions key; since Eidos 5.0.0 a root\'s versions are a tool\'s own, and `eidos migrate` moves them to .eidos/plugins/eidosmd/versions.yaml');
     }
     if (!existsSync(path.join(framework.root, 'README.md'))) {
         out.warn('readme-missing', null, 'no README.md at the root; the visible front door is missing');
@@ -140,23 +144,30 @@ function checkFramework(framework, out, options) {
             out.warn('top-level-missing', frameworkRel, `## Top-Level lists ${doc.title} at ${doc.path}, which does not exist`);
         }
     }
-    const shapes = new Map();
+    // A collection's templates are named for its unit, `<unit>.<variant>.md`;
+    // a file named otherwise is faulted, as is one that opens with frontmatter.
+    const templates = new Map();
     for (const collection of framework.collections) {
-        if (collection.flavors.length === 0) {
-            out.error('flavor-none', frameworkRel, `collection ${collection.name} declares no flavors`);
-        }
-        for (const flavor of collection.flavors) {
-            const shape = loadShape(framework, flavor);
-            shapes.set(`${collection.name}/${flavor.name}`, shape);
-            if (!shape) {
-                out.error('shape-missing', frameworkRel, `${collection.name}/${flavor.name} points at _eidos/${flavor.shape}, which does not exist`);
+        const unit = unitOf(collection);
+        for (const variant of collection.variants) {
+            const template = loadTemplate(framework, variant);
+            templates.set(`${collection.name}/${variant.name}`, template);
+            if (template?.frontmatter) {
+                out.error('template-frontmatter', rel(framework.root, template.path), 'carries a frontmatter block; a template is body only, its frontmatter is generated from the Properties table', 'Remove the block');
+            }
+            if (!template) {
+                out.error('template-missing', frameworkRel, `${collection.name}/${variant.name} points at .eidos/${variant.template}, which does not exist`);
+            }
+            const expected = unit ? `${unit}.${variant.name}.md` : null;
+            if (expected && !variant.template.endsWith(`/${expected}`) && variant.template !== expected) {
+                out.error('template-name', frameworkRel, `${collection.name}/${variant.name} is at .eidos/${variant.template}; a template file is templates/${expected} (its unit, then its variant)`);
             }
         }
         if (!existsSync(path.join(framework.root, collection.name))) {
             out.warn('collection-folder-missing', null, `collection ${collection.name} is declared but has no folder`);
         }
     }
-    return shapes;
+    return templates;
 }
 function checkLayout(framework, blueprints, out) {
     const declared = new Set(framework.collections.map((collection) => collection.name));
@@ -169,7 +180,7 @@ function checkLayout(framework, blueprints, out) {
         entries = [];
     }
     for (const entry of entries.sort()) {
-        if (entry.startsWith('.') || entry === '_eidos' || SKIPPED_DIRS.has(entry) || declared.has(entry)) {
+        if (entry.startsWith('.') || entry === '.eidos' || SKIPPED_DIRS.has(entry) || declared.has(entry)) {
             continue;
         }
         let isDir = false;
@@ -180,7 +191,7 @@ function checkLayout(framework, blueprints, out) {
             isDir = false;
         }
         if (isDir) {
-            out.warn('folder-undeclared', entry, 'a folder at the root that no collection declares; declare it in Framework.md or move it');
+            out.warn('folder-undeclared', entry, 'a folder at the root that no collection declares; declare it in the framework document or move it');
         }
     }
     for (const collection of framework.collections) {
@@ -194,7 +205,7 @@ function checkLayout(framework, blueprints, out) {
             const declaredGroups = new Map(collection.grouping.groups.map((group) => [group.name.toLowerCase(), group.name]));
             for (const group of groupsOnDisk) {
                 if (!declaredGroups.has(group.toLowerCase())) {
-                    out.warn('group-undeclared', `${collection.name}/${group}`, `not declared under ${collection.grouping.label} in Framework.md`);
+                    out.warn('group-undeclared', `${collection.name}/${group}`, `not declared under ${collection.grouping.label} in the framework document`);
                 }
             }
             for (const group of collection.grouping.groups) {
@@ -209,10 +220,10 @@ function checkLayout(framework, blueprints, out) {
             }
         }
         if (collection.framing) {
-            for (const flavor of collection.flavors) {
-                const written = own.some((blueprint) => resolveFlavor(blueprint).flavor === flavor);
+            for (const variant of collection.variants) {
+                const written = own.some((blueprint) => resolveVariant(blueprint).variant === variant);
                 if (!written) {
-                    out.warn('frame-unwritten', collection.name, `no ${flavor.name} frame yet; a gap to surface, not a failure`);
+                    out.warn('frame-unwritten', collection.name, `no ${variant.name} frame yet; a gap to surface, not a failure`);
                 }
             }
         }
@@ -223,7 +234,25 @@ function checkLayout(framework, blueprints, out) {
         }
     }
 }
-function checkBlueprint(framework, blueprint, shapes, out) {
+// Rule 19: a near-miss the Vocabulary names is flagged with the declared term
+// beside it, never refused. The near-miss is the clause's opening phrase.
+function checkVocabulary(framework, blueprint, out) {
+    if (framework.vocabulary.length === 0 || blueprint.body.trim() === '')
+        return;
+    const body = blueprint.body.toLowerCase();
+    for (const entry of framework.vocabulary) {
+        for (const clause of entry.not) {
+            const phrase = clause.split(/[,;:(]/)[0]?.trim().toLowerCase() ?? '';
+            if (phrase === '' || phrase === entry.term.toLowerCase())
+                continue;
+            const pattern = new RegExp(`(^|[^a-z0-9])${phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![a-z0-9])`, 'i');
+            if (pattern.test(body)) {
+                out.warn('term-near-miss', blueprint.rel, `uses "${phrase}"; the Vocabulary declares "${entry.term}"${entry.means ? ` (${entry.means})` : ''}`);
+            }
+        }
+    }
+}
+function checkBlueprint(framework, blueprint, templates, out) {
     const file = blueprint.rel;
     if (blueprint.properties === null) {
         if (blueprint.frontmatterError) {
@@ -241,13 +270,7 @@ function checkBlueprint(framework, blueprint, shapes, out) {
     const collection = blueprint.collection;
     const id = propertyString(blueprint, 'id');
     if (id === null) {
-        out.error('id-missing', file, 'no `id`; add a permanent kebab-case identity');
-    }
-    else if (!isKebab(id)) {
-        out.error('id-format', file, `id '${id}' is not kebab-case`);
-    }
-    else if (framework.naming === 'kebab-case' && blueprint.stem !== id) {
-        out.warn('id-filename', file, `in a kebab-case root the filename is the id; expected ${id}.md`);
+        out.error('id-missing', file, 'no `id`; add a permanent identity (a slug, a number, a GUID)');
     }
     if (propertyString(blueprint, 'title') === null) {
         out.error('title-missing', file, 'no `title`');
@@ -255,13 +278,14 @@ function checkBlueprint(framework, blueprint, shapes, out) {
     if (propertyString(blueprint, 'summary') === null) {
         out.warn('summary-missing', file, 'no `summary`; the collection index will flag it');
     }
-    const { flavor, declared, known } = resolveFlavor(blueprint);
+    const { variant, declared, known } = resolveVariant(blueprint);
     if (!known) {
-        const names = collection.flavors.map((candidate) => candidate.name).join(', ');
-        out.error('flavor-unknown', file, `flavor '${declared ?? ''}' is not one of ${collection.name}'s declared flavors (${names})`);
+        const names = collection.variants.map((candidate) => candidate.name).join(', ');
+        out.error('variant-unknown', file, `variant '${declared ?? ''}' is not one of ${collection.name}'s declared variants (${names})`);
     }
     const core = new Set(framework.schema.core.map((property) => property.name));
-    const applicable = framework.schema.custom.filter((property) => appliesTo(property, collection.name));
+    const schemaProperties = [...framework.schema.custom, ...Object.values(framework.schema.tools).flat()];
+    const applicable = schemaProperties.filter((property) => appliesTo(property, collection.name));
     const applicableNames = new Set(applicable.map((property) => property.name));
     for (const property of applicable) {
         if (!(property.name in properties)) {
@@ -275,7 +299,7 @@ function checkBlueprint(framework, blueprint, shapes, out) {
         if (core.has(key) || applicableNames.has(key)) {
             continue;
         }
-        const elsewhere = framework.schema.custom.find((property) => property.name === key);
+        const elsewhere = schemaProperties.find((property) => property.name === key);
         if (elsewhere) {
             const scope = elsewhere.appliesTo === 'all' ? 'all' : elsewhere.appliesTo.join(', ');
             out.warn('property-scope', file, `\`${key}\` applies to ${scope}, not ${collection.name}`);
@@ -284,7 +308,7 @@ function checkBlueprint(framework, blueprint, shapes, out) {
             out.warn('work-tracking-field', file, `\`${key}\` is a work-tracking field; a blueprint captures state and intent, not work (link to a tracker instead)`);
         }
         else {
-            out.warn('property-unknown', file, `\`${key}\` is not in the Schema; declare it under ### Custom Properties or drop it`);
+            out.warn('property-unknown', file, `\`${key}\` is in no block of the Properties table; declare it among the custom properties or drop it`);
         }
     }
     for (const property of [...framework.schema.core, ...applicable]) {
@@ -327,38 +351,89 @@ function checkBlueprint(framework, blueprint, shapes, out) {
     if (h1 && h1.text !== title && kebab(h1.text) !== kebab(title)) {
         out.warn('title-mismatch', file, `the heading '${h1.text}' differs from title '${title}'`);
     }
-    const shape = flavor ? (shapes.get(`${collection.name}/${flavor.name}`) ?? loadShape(framework, flavor)) : null;
-    if (!shape || !flavor) {
+    const template = variant ? (templates.get(`${collection.name}/${variant.name}`) ?? loadTemplate(framework, variant)) : null;
+    if (!template || !variant) {
         return;
     }
     const present = blueprint.sections.map((section) => section.heading.text);
     const presentLower = present.map((text) => text.toLowerCase());
-    const shapeLower = shape.sections.map((text) => text.toLowerCase());
-    for (const name of shape.sections) {
+    const templateLower = template.sections.map((text) => text.toLowerCase());
+    for (const name of template.sections) {
         if (!presentLower.includes(name.toLowerCase())) {
-            out.warn('section-missing', file, `no \`## ${name}\` (${flavor.kind}.${flavor.name} declares it; leave it out only if it genuinely does not apply)`);
+            out.warn('section-missing', file, `no \`## ${name}\` (${variant.unit}.${variant.name} declares it; leave it out only if it genuinely does not apply)`);
         }
     }
     if (!collection.framing) {
         for (const name of present) {
-            if (!shapeLower.includes(name.toLowerCase())) {
-                out.warn('section-unknown', file, `\`## ${name}\` is not a section of ${flavor.kind}.${flavor.name}; nest it under one that is, or add it to the shape`);
+            if (!templateLower.includes(name.toLowerCase())) {
+                out.warn('section-unknown', file, `\`## ${name}\` is not a section of ${variant.unit}.${variant.name}; nest it under one that is, or add it to the template`);
             }
         }
     }
-    const order = presentLower.filter((name) => shapeLower.includes(name)).map((name) => shapeLower.indexOf(name));
+    const order = presentLower.filter((name) => templateLower.includes(name)).map((name) => templateLower.indexOf(name));
     for (let index = 1; index < order.length; index += 1) {
         if ((order[index] ?? 0) < (order[index - 1] ?? 0)) {
-            out.warn('section-order', file, `sections are not in ${flavor.kind}.${flavor.name}'s order (${shape.sections.join(' → ')})`);
+            out.warn('section-order', file, `sections are not in ${variant.unit}.${variant.name}'s order (${template.sections.join(' → ')})`);
             break;
         }
     }
 }
+function checkCanvases(framework, blueprints, out) {
+    const ids = new Set(blueprints.map((blueprint) => blueprintId(blueprint)).filter((id) => id !== null));
+    const canvases = listCanvases(framework);
+    const canvasIds = new Set(canvases.map((canvas) => canvas.id));
+    for (const canvas of canvases) {
+        const file = rel(framework.root, canvas.file);
+        for (const problem of canvas.problems) {
+            out.error('canvas-invalid', file, problem);
+        }
+        for (const page of canvas.pages) {
+            const nodeIds = new Set(page.nodes.map((node) => node.id));
+            const frameIds = new Set(page.frames.map((frame) => frame.id));
+            for (const node of page.nodes) {
+                if (node.blueprint && !ids.has(node.blueprint)) {
+                    out.error('canvas-node-missing', file, `page ${page.id}, node ${node.id}: no blueprint with id '${node.blueprint}'`);
+                }
+                if (node.frame && !frameIds.has(node.frame)) {
+                    out.warn('canvas-frame-missing', file, `page ${page.id}, node ${node.id}: no frame '${node.frame}' on this page`);
+                }
+                if (node.link?.page && !canvas.pages.some((candidate) => candidate.id === node.link?.page)) {
+                    out.error('canvas-link-missing', file, `page ${page.id}, node ${node.id}: links to page '${node.link.page}', which this canvas does not have`);
+                }
+                if (node.link?.canvas && !canvasIds.has(node.link.canvas)) {
+                    out.error('canvas-link-missing', file, `page ${page.id}, node ${node.id}: links to canvas '${node.link.canvas}', which does not exist`);
+                }
+            }
+            for (const comment of page.comments) {
+                if (comment.node && !page.nodes.some((node) => node.id === comment.node)) {
+                    out.warn('canvas-comment-orphan', file, `page ${page.id}, comment ${comment.id}: pinned to node '${comment.node}', which the page no longer has`);
+                }
+            }
+            const endpoint = (id) => (isFrameRef(id) ? frameIds.has(id.slice(FRAME_REF.length)) : nodeIds.has(id));
+            for (const edge of page.edges) {
+                if (!endpoint(edge.from) || !endpoint(edge.to)) {
+                    out.error('canvas-edge-missing', file, `page ${page.id}: edge ${edge.from} → ${edge.to} names a node or frame the page does not have`);
+                }
+            }
+            for (const node of page.nodes) {
+                if (node.annotation && !page.edges.some((edge) => edge.from === node.id)) {
+                    out.warn('canvas-annotation-unpointed', file, `page ${page.id}, annotation ${node.id}: points at nothing; an annotation exists to point`);
+                }
+            }
+            for (const frame of page.frames) {
+                if (frame.frame && !frameIds.has(frame.frame)) {
+                    out.warn('canvas-frame-missing', file, `page ${page.id}, frame ${frame.id}: attached to frame '${frame.frame}', which the page does not have`);
+                }
+            }
+        }
+    }
+}
 export function checkRoot(framework, blueprints, options) {
     const out = new Collector();
-    const shapes = checkFramework(framework, out, options);
+    const templates = checkFramework(framework, out, options);
     if (!options.only) {
         checkLayout(framework, blueprints, out);
+        checkCanvases(framework, blueprints, out);
     }
     const seen = new Map();
     for (const blueprint of blueprints) {
@@ -381,7 +456,8 @@ export function checkRoot(framework, blueprints, options) {
     }
     const targets = options.only ? blueprints.filter((blueprint) => options.only?.has(blueprint.path)) : blueprints;
     for (const blueprint of targets) {
-        checkBlueprint(framework, blueprint, shapes, out);
+        checkBlueprint(framework, blueprint, templates, out);
+        checkVocabulary(framework, blueprint, out);
     }
     const findings = out.findings.sort((a, b) => {
         const left = a.path ?? '';

package/dist/src/core/convert.js

@@ -1,8 +1,9 @@
-// Converting a markdown root to the form the CLI works in: the same framework
-// written as `Framework.yaml` with the guidance as comments and the index
-// inside it, `Framework.md` and each collection's `index.md` removed. The
-// markdown form's prose (section intros, HTML comments) has no field to land
-// in and is left behind; each collection's own description travels.
+// Converting a 4.x markdown root to Framework.yaml, the framework document
+// since 5.0.0: the same framework written as data with this CLI's guidance
+// as comments and the index inside it, `Framework.md` and each collection's
+// `index.md` removed. `migrate` runs this on the way up. The markdown form's
+// prose (section intros, HTML comments) has no field to land in and is left
+// behind; each collection's own description travels.
 import { existsSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { listBlueprints } from './blueprint.js';
@@ -10,7 +11,7 @@ import { loadFramework } from './framework.js';
 import { frameworkToDocument, serializeDocument } from './framework-structured.js';
 import { buildIndexes } from './index-leaf.js';
 export function convertToYaml(framework, dryRun) {
-    const yamlFile = path.join(framework.root, '_eidos', 'Framework.yaml');
+    const yamlFile = path.join(framework.root, '.eidos', 'Framework.yaml');
     const actions = [];
     const removed = [];
     const text = serializeDocument(frameworkToDocument(framework));

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

@@ -1,13 +1,15 @@
-// The markdown framework document, `_eidos/Framework.md`: frontmatter for the
+// The markdown framework document, `.eidos/Framework.md`: frontmatter for the
 // version and naming convention, and a body indexing the Top-Level docs, the
-// Collections (each a `###` with Leaf, Flavors, Canvas, and grouping bullets),
-// and the property Schema as two tables.
+// Collections (each a `###` with Leaf, Variants, and grouping bullets), the
+// Properties table per owner, the Vocabulary, and the Versions. The 4.x
+// spellings (Schema, Flavors, shape) still read, so `migrate` can load a root
+// it is about to move.
 import { parseFrontmatter } from './frontmatter.js';
-import { groupingProperty, STANDARD_CORE } from './framework-model.js';
+import { groupingProperty, STANDARD_CORE, unitOf } from './framework-model.js';
 import { DEFAULT_NAMING, isNaming } from './naming.js';
 import { section, sections, stripInlineCode } from './markdown.js';
 import path from 'node:path';
-const DECLARED_BULLETS = new Set(['leaf', 'flavors', 'canvas']);
+const DECLARED_BULLETS = new Set(['leaf', 'unit', 'variants', 'flavors', 'canvas']);
 function cleanText(text) {
     return text.replace(/^_+|_+$/g, '').trim();
 }
@@ -46,13 +48,13 @@ function parseCanvas(value) {
     }
     return { mode: 'card', section: null };
 }
-function flavorFromShape(label, shapeRel) {
-    const file = path.posix.basename(shapeRel.replace(/\\/g, '/')).replace(/\.md$/i, '');
+function variantFromTemplate(label, templateRel) {
+    const file = path.posix.basename(templateRel.replace(/\\/g, '/')).replace(/\.md$/i, '');
     const dot = file.indexOf('.');
-    const kind = dot === -1 ? file : file.slice(0, dot);
+    const unit = dot === -1 ? file : file.slice(0, dot);
     const fromFile = dot === -1 ? file : file.slice(dot + 1);
     const name = /\.md$/i.test(label) ? fromFile : label;
-    return { name, kind };
+    return { name, unit };
 }
 function parseCollections(body) {
     const block = section(body, 2, 'Collections');
@@ -64,20 +66,20 @@ function parseCollections(body) {
         const collection = {
             name: heading.text,
             description: firstParagraph(text),
-            framing: out.length === 0,
+            framing: false,
             leaf: null,
-            flavors: [],
+            variants: [],
             canvas: null,
             grouping: null,
         };
-        let inFlavors = false;
+        let inVariants = false;
         let inGrouping = false;
         for (const line of text.split('\n')) {
             const bullet = /^-\s+\*\*(.+?):\*\*\s*(.*)$/.exec(line);
             if (bullet && bullet[1] !== undefined) {
                 const label = bullet[1].trim();
                 const rest = (bullet[2] ?? '').trim();
-                inFlavors = label.toLowerCase() === 'flavors';
+                inVariants = label.toLowerCase() === 'variants' || label.toLowerCase() === 'flavors';
                 inGrouping = false;
                 if (label.toLowerCase() === 'leaf') {
                     collection.leaf = parseLink(rest)?.target ?? null;
@@ -96,18 +98,18 @@ function parseCollections(body) {
                 continue;
             }
             const item = nested[1].trim();
-            if (inFlavors) {
-                const flavorLine = /^\[(.+?)\]\((.+?)\)\s*(?:—\s*(.*))?$/.exec(item);
-                if (flavorLine && flavorLine[1] && flavorLine[2]) {
-                    // `(default)` in the description marks the default flavor; it is a flag, not prose.
-                    const described = (flavorLine[3] ?? '').trim();
+            if (inVariants) {
+                const variantLine = /^\[(.+?)\]\((.+?)\)\s*(?:—\s*(.*))?$/.exec(item);
+                if (variantLine && variantLine[1] && variantLine[2]) {
+                    // `(default)` in the description marks the default variant; it is a flag, not prose.
+                    const described = (variantLine[3] ?? '').trim();
                     const isDefault = /\(default\)/i.test(described);
                     const description = described.replace(/\s*\(default\)\.?$/i, '').replace(/\s*\(default\)/i, '').trim();
-                    const { name, kind } = flavorFromShape(flavorLine[1].trim(), flavorLine[2].trim());
-                    collection.flavors.push({
+                    const { name, unit } = variantFromTemplate(variantLine[1].trim(), variantLine[2].trim());
+                    collection.variants.push({
                         name,
-                        kind,
-                        shape: flavorLine[2].trim(),
+                        unit,
+                        template: variantLine[2].trim(),
                         description,
                         isDefault,
                     });
@@ -120,12 +122,13 @@ function parseCollections(body) {
                 }
             }
         }
-        if (collection.flavors.length > 0 && !collection.flavors.some((flavor) => flavor.isDefault)) {
-            const first = collection.flavors[0];
+        if (collection.variants.length > 0 && !collection.variants.some((variant) => variant.isDefault)) {
+            const first = collection.variants[0];
             if (first) {
                 first.isDefault = true;
             }
         }
+        collection.framing = unitOf(collection) === 'frame';
         out.push(collection);
     }
     return out;
@@ -152,23 +155,86 @@ function parseAppliesTo(value) {
     }
     return plain.split(/[,/]/).map((name) => name.trim()).filter((name) => name !== '');
 }
-function parseProperties(block, core) {
+// The standard's columns come first (Name, Type, Meaning for the core; Name,
+// Type, Applies To, Meaning for custom properties); any column past them is a
+// tool's, headed with the tool's name, and rides along as that tool's field.
+function parseProperties(block, core, owner = core ? 'eidos' : 'custom') {
     if (block === null) {
         return [];
     }
     const out = [];
+    const standard = core ? 3 : 4;
+    let header = [];
     for (const cells of parseTable(block)) {
         const name = stripInlineCode(cells[0] ?? '').trim();
-        if (name === '' || name.toLowerCase() === 'name') {
+        if (name === '') {
+            continue;
+        }
+        if (name.toLowerCase() === 'name') {
+            header = cells.map((cell) => stripInlineCode(cell).trim());
             continue;
         }
         const type = (cells[1] ?? 'Text').trim();
-        if (core || cells.length < 4) {
-            out.push({ name, type, appliesTo: 'all', meaning: (cells[cells.length - 1] ?? '').trim(), core });
+        const property = core || cells.length < 4
+            ? { name, type, appliesTo: 'all', meaning: (cells[Math.min(cells.length, standard) - 1] ?? '').trim(), core, owner }
+            : { name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), meaning: (cells[3] ?? '').trim(), core, owner };
+        const tools = {};
+        for (let index = standard; index < cells.length; index += 1) {
+            const tool = header[index];
+            const cell = (cells[index] ?? '').trim();
+            if (tool && cell !== '') {
+                tools[tool] = cell;
+            }
         }
-        else {
-            out.push({ name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), meaning: (cells[3] ?? '').trim(), core });
+        if (Object.keys(tools).length > 0) {
+            property.tools = tools;
         }
+        out.push(property);
+    }
+    return out;
+}
+// `## Vocabulary`: Term · Means · Not, one row per term. A Term cell may be a
+// link to the blueprint that defines it; the Not cell lists near-misses, `;` apart.
+function parseVocabulary(body) {
+    const block = section(body, 2, 'Vocabulary');
+    if (block === null)
+        return [];
+    const out = [];
+    for (const row of parseTable(block)) {
+        const [termCell = '', means = '', notCell = ''] = row;
+        const link = parseLink(termCell.trim());
+        const term = (link ? link.title : stripInlineCode(termCell.replace(/\*\*/g, ''))).trim();
+        // the header row, a placeholder row, and a blank row are not terms
+        if (term === '' || term.toLowerCase() === 'term' || /^<.*>$/.test(term) || /^-+$/.test(term))
+            continue;
+        out.push({
+            term,
+            means: cleanText(means),
+            not: notCell
+                .split(';')
+                .map((entry) => cleanText(entry))
+                .filter((entry) => entry !== ''),
+            see: link ? link.target : null,
+        });
+    }
+    return out;
+}
+// `## Versions`: Version · Commit · Tag, newest first, as written. The key
+// left the standard in 5.0.0; `migrate` moves what a 4.x root recorded.
+export function parseVersions(body) {
+    const block = section(body, 2, 'Versions');
+    if (block === null) {
+        return [];
+    }
+    const out = [];
+    for (const cells of parseTable(block)) {
+        const version = stripInlineCode(cells[0] ?? '').replace(/^\*\*|\*\*$/g, '').trim();
+        if (version === '' || version.toLowerCase() === 'version') {
+            continue;
+        }
+        const commit = stripInlineCode(cells[1] ?? '').trim();
+        const tag = stripInlineCode(cells[2] ?? '').trim();
+        out.push({ version, commit, tag: tag === '' || tag === '—' || tag === '-' ? null : tag });
     }
     return out;
 }
@@ -207,11 +273,23 @@ export function parseFrameworkMarkdown(text, root, file) {
         }
     }
     const version = properties?.['eidos_version'];
-    const schemaBlock = section(body, 2, 'Schema') ?? '';
-    const coreBlock = section(schemaBlock, 3, 'Eidos Core');
-    const customBlock = section(schemaBlock, 3, 'Custom Properties');
+    const schemaBlock = section(body, 2, 'Properties') ?? section(body, 2, 'Schema') ?? '';
+    const coreBlock = section(schemaBlock, 3, 'Eidos') ?? section(schemaBlock, 3, 'Eidos Core');
+    const customBlock = section(schemaBlock, 3, 'Custom') ?? section(schemaBlock, 3, 'Custom Properties');
     const core = parseProperties(coreBlock, true);
     const custom = parseProperties(customBlock, false);
+    // `### <tool>` (`### <tool> Properties` before 5.0.0): a block a tool declared and alone writes.
+    const tools = {};
+    for (const { heading, body: block } of sections(schemaBlock, 3)) {
+        const name = heading.text.trim();
+        if (/^(eidos( core)?|custom( properties)?)$/i.test(name))
+            continue;
+        const match = /^(.+?)(?:\s+Properties)?$/i.exec(name);
+        const tool = match?.[1]?.trim() ?? '';
+        if (!match || tool === '' || tool.toLowerCase() === 'custom' || /^<.*>$/.test(tool))
+            continue;
+        tools[tool] = parseProperties(block, false, tool);
+    }
     const collections = parseCollections(body);
     for (const collection of collections) {
         if (collection.grouping) {
@@ -227,7 +305,8 @@ export function parseFrameworkMarkdown(text, root, file) {
         namingError,
         topLevel: parseTopLevel(body),
         collections,
-        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom },
+        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom, tools },
+        vocabulary: parseVocabulary(body),
         problems: [],
     };
 }