eidosmd 0.1.0

package/dist/src/paths.js

@@ -0,0 +1,28 @@
+// Where the package keeps the files it ships beside its code: the vendored
+// standard (EIDOS.md and the seeds) and the agent instructions.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+// dist/src/paths.js sits two levels below the package root.
+export const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+export const standardDir = path.join(packageRoot, 'standard');
+export const seedsDir = path.join(standardDir, 'seeds');
+export const standardFile = path.join(standardDir, 'EIDOS.md');
+export const instructionsDir = path.join(packageRoot, 'instructions');
+export const browserDir = path.join(packageRoot, 'browser');
+export function readStandard() {
+    return readFileSync(standardFile, 'utf8');
+}
+// The version of the standard this CLI carries, read off EIDOS.md's own header
+// so the vendored copy is the single source of it.
+export function standardVersion() {
+    const match = /^\*\*Version:\*\*\s*(\S+)/m.exec(readStandard());
+    if (!match || !match[1]) {
+        throw new Error(`no **Version:** header in ${standardFile}`);
+    }
+    return match[1];
+}
+export function packageVersion() {
+    const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return manifest.version;
+}

package/dist/src/program.js

@@ -0,0 +1,242 @@
+// The eidos command line, assembled: every command, its options, and its help.
+// `cli.ts` is the executable entry; this module is what tests build.
+import { Command } from 'commander';
+import { loadRoot } from './context.js';
+import { runAgents } from './commands/agents.js';
+import { DEFAULT_PORT, runBrowser } from './commands/browser.js';
+import { runCheck } from './commands/check.js';
+import { runConvert } from './commands/convert.js';
+import { runFramework } from './commands/framework.js';
+import { runIndex } from './commands/index.js';
+import { runInit } from './commands/init.js';
+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 { runShow } from './commands/show.js';
+import { runRoles, runWhoami } from './commands/whoami.js';
+import { CliError, EXIT_USAGE, printError, today } from './output.js';
+import { packageVersion, standardVersion } from './paths.js';
+const collect = (value, previous) => [...previous, value];
+function run(action) {
+    try {
+        process.exitCode = action();
+    }
+    catch (cause) {
+        if (cause instanceof CliError) {
+            printError(`error: ${cause.message}`);
+            process.exitCode = cause.exitCode;
+            return;
+        }
+        const message = cause instanceof Error ? cause.message : String(cause);
+        printError(`error: ${message}`);
+        process.exitCode = EXIT_USAGE;
+    }
+}
+export function buildProgram() {
+    const program = new Command();
+    // --root is accepted before or after the command name.
+    const globals = (local = {}) => ({ root: local.root ?? program.opts().root });
+    const withRoot = (command) => command.option('--root <path>', 'the root to work in');
+    program
+        .name('eidos')
+        .description(`Eidos: one markdown file is the complete source of truth for one unit of a thing.\nScaffold, validate, and index a root of blueprints; hand an agent the workflow with \`eidos instructions\`.`)
+        .version(`eidosmd ${packageVersion()} (standard ${standardVersion()})`, '-v, --version', 'print the CLI version and the standard it carries')
+        .option('--root <path>', 'the root to work in (default: found from the working directory by its _eidos/ marker)')
+        .enablePositionalOptions()
+        .showHelpAfterError('(run with --help for usage)')
+        .addHelpText('after', `
+Exit codes: 0 done · 1 the check found errors, or an index is stale · 2 the command could not run
+
+Start with \`eidos instructions\` for the workflow, or \`eidos seeds\` and \`eidos init\` to create a root.`);
+    program
+        .command('init')
+        .argument('[root]', 'the root folder to create', 'Blueprints')
+        .description('create a root from a bundled seed: its framework as _eidos/Framework.yaml, a folder per collection, a blank blueprint per framing flavor')
+        .option('--seed <name>', 'the seed to install (see `eidos seeds`)', 'software')
+        .option('--naming <convention>', 'kebab-case | TitleCase | "Title Case"; governs every human-facing name, settled once', 'kebab-case')
+        .option('--group <name>', 'a starting group under the grouped collection (repeatable)', collect, [])
+        .option('--product <name>', "fills the README's {{Product}} placeholder")
+        .option('--date <YYYY-MM-DD>', 'the date written into the scaffolded frames', today())
+        .option('--dry-run', 'print every write and touch nothing', false)
+        .option('--json', 'machine-readable result', false)
+        .addHelpText('after', `
+Writes no prose: the README one-liner, each group's description, and every frame's summary and body stay the owner's.
+
+Examples:
+  eidos init
+  eidos init Blueprints --seed software --group Identity --group Billing --product "Care Connect"
+  eidos init docs/product --seed research --naming TitleCase --dry-run
+
+Writes Framework.yaml, the form the CLI works in. A root that keeps Framework.md (the form for people) is converted with \`eidos convert\`.`)
+        .action((root, options) => {
+        run(() => runInit(root, options));
+    });
+    program
+        .command('seeds')
+        .description('list the bundled seeds: each one a complete starting framework, with its collections and flavors')
+        .option('--json', 'machine-readable result', false)
+        .action((options) => {
+        run(() => runSeeds(options));
+    });
+    withRoot(program.command('framework'))
+        .description("show the root's framework: version, naming, top-level docs, collections (flavors, canvas, groups), and the property Schema")
+        .option('--json', 'the framework as JSON: the document form plus root, file, and format', false)
+        .option('--as <format>', 'print the framework as the yaml document a scriptable root keeps in _eidos/')
+        .addHelpText('after', `
+Read this before assuming any collection, flavor, section, or property name; the framework declares its own.
+The document is _eidos/Framework.md (for people) or Framework.yaml (for scripts and agents): the same fields in each.
+
+Output (--json): { root, file, format, eidos_version, naming, top_level[], collections[{ name, description, canvas, flavors[{ name, shape, description, default }], grouping{ label, property, groups[] } }], schema{ core[], custom[{ name, type, applies_to, meaning }] } }
+
+This is the one command that also reads a Framework.md root, so a root can be inspected before \`eidos convert\` moves it.`)
+        .action((options) => {
+        run(() => runFramework(loadRoot(globals(options), process.cwd(), { allowMarkdown: true }), options));
+    });
+    withRoot(program.command('convert'))
+        .description('move a markdown root to Framework.yaml, the form the CLI works in: the same framework with the index inside it; Framework.md and each index.md removed')
+        .option('--dry-run', 'print the writes and touch nothing', false)
+        .option('--json', 'machine-readable result', false)
+        .addHelpText('after', `
+Every command except this one and \`framework\` needs Framework.yaml, so on a markdown root this is the first thing to run. The markdown form's prose (section intros, comments) has no field to land in and is left behind; each collection's description travels. Blueprints are untouched.`)
+        .action((options) => {
+        run(() => runConvert(globals(options), options));
+    });
+    withRoot(program.command('list'))
+        .argument('[collection]', 'only this collection')
+        .description('list the blueprints in the root')
+        .option('--group <name>', 'only this group (sub-folder)')
+        .option('--flavor <name>', 'only blueprints on this flavor (resolved, so the default counts)')
+        .option('--where <key=value>', 'only blueprints whose property equals the value, case-insensitive (repeatable; a list matches any item)', collect, [])
+        .option('--json', 'one object per blueprint: id, title, summary, collection, group, flavor, path, properties', false)
+        .addHelpText('after', `
+Examples:
+  eidos list
+  eidos list Specs --group Identity
+  eidos list --where status=Draft --json`)
+        .action((collection, options) => {
+        run(() => runList(loadRoot(globals(options)), collection, options));
+    });
+    withRoot(program.command('show'))
+        .argument('<blueprint>', 'an id, a filename, or a path')
+        .description('print one blueprint as written; with --json, its properties and sections parsed out')
+        .option('--json', '{ id, title, summary, collection, group, flavor, path, absolute_path, properties, sections[{ heading, body }], body }', false)
+        .action((ref, options) => {
+        run(() => runShow(loadRoot(globals(options)), ref, options));
+    });
+    withRoot(program.command('new'))
+        .argument('<collection>', 'the collection the blueprint belongs to')
+        .argument('<title...>', 'the human-readable title')
+        .description("scaffold a blueprint that is born conforming: frontmatter from the Schema, body from the flavor's shape, filename in the naming convention, a permanent kebab-case id")
+        .option('--flavor <name>', "one of the collection's declared flavors (default: the collection's default)")
+        .option('--group <name>', 'the sub-folder to place it in')
+        .option('--id <kebab-case>', 'the permanent id (default: the title in kebab-case)')
+        .option('--summary <line>', 'the one-line summary, so the index lists it at once')
+        .option('--set <key=value>', 'a property value at creation (repeatable; lists are comma-separated)', collect, [])
+        .option('--date <YYYY-MM-DD>', 'the date written into date properties the Schema declares', today())
+        .option('--dry-run', 'print the file instead of writing it', false)
+        .option('--json', '{ path, id, collection, group, flavor, notes[] }', false)
+        .addHelpText('after', `
+The body keeps the shape's guidance prompts; fill them with the owner and delete them as you go. The CLI writes no prose.
+
+Examples:
+  eidos new Specs "Session Management" --group Identity --summary "Keeps a signed-in user signed in across tabs and devices."
+  eidos new Specs "Passkeys" --flavor micro --set status=Intake --set tags=auth,security
+  eidos new Frames Market --dry-run`)
+        .action((collection, title, options) => {
+        run(() => runNew(loadRoot(globals(options)), collection, title, options));
+    });
+    withRoot(program.command('check'))
+        .argument('[blueprint...]', 'only these blueprints (paths); default: the whole root')
+        .description("validate the root against its own framework: the Framework.md and shapes, every blueprint's frontmatter and body, the layout, and the indexes")
+        .option('--strict', 'warnings fail too', false)
+        .option('--json', '{ ok, root, eidos_version, naming, blueprints, errors, warnings, findings[{ level, code, path, message }] }', false)
+        .addHelpText('after', `
+Errors are wrong on any reading (unparseable frontmatter, a missing or duplicate id, an undeclared flavor, a broken link). Warnings are gaps the standard says to surface, never refuse (a missing property or section, a stale index, a version gap). Exit 1 on an error; with --strict, on a warning too.
+
+Examples:
+  eidos check
+  eidos check Specs/Identity/login.md
+  eidos check --strict --json`)
+        .action((blueprints, options) => {
+        run(() => runCheck(loadRoot(globals(options)), blueprints, options));
+    });
+    withRoot(program.command('index'))
+        .description("regenerate each collection's index.md: every blueprint as a link with its summary, grouped by sub-folder")
+        .option('--collection <name>', 'only this collection (repeatable)', collect, [])
+        .option('--check', 'write nothing; exit 1 if any index is stale', false)
+        .option('--json', '{ ok, indexes[{ collection, path, status, blueprints }], missing_summary[] }', false)
+        .addHelpText('after', `
+Under a markdown framework each collection gets its own index.md, regenerated wholesale: nothing hand-written in it survives. Under a YAML framework every collection's index is written into the framework document under \`index\`, and the rest of the document is left as written. A blueprint without a summary is listed with a TODO marker (or a null summary) and named on stderr.`)
+        .action((options) => {
+        run(() => runIndex(loadRoot(globals(options)), options));
+    });
+    withRoot(program.command('roles'))
+        .description('list the roles the framework installed under _eidos/roles/')
+        .option('--json', 'machine-readable result', false)
+        .action((options) => {
+        run(() => runRoles(loadRoot(globals(options)), options));
+    });
+    withRoot(program.command('whoami'))
+        .description('show the actor in the seat (_eidos/me.md: role and calibration), or set it')
+        .option('--role <name>', 'a role from `eidos roles`')
+        .option('--ownership <text>', 'what you own on this root, in your own words')
+        .option('--experience <text>', 'your experience with the scope: new, familiar, deep')
+        .option('--capacity <text>', 'your technical capacity: non-technical, some, fluent')
+        .option('--clear', 'blank the actor (full facilitation)', false)
+        .option('--json', 'machine-readable result', false)
+        .addHelpText('after', `
+me.md is personal and gitignored: one per person, never shared. An agent reads it before acting and responds as the role file says.
+
+Examples:
+  eidos whoami
+  eidos whoami --role developer --experience "new to this product" --capacity fluent`)
+        .action((options) => {
+        run(() => runWhoami(loadRoot(globals(options)), options));
+    });
+    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)
+        .option('--no-open', 'print the URL without opening a browser')
+        .addHelpText('after', `
+Serves on 127.0.0.1 only. Every change the page makes runs the same code as the command it mirrors (new, index, check), so an agent should use the commands and leave the page to people. Press Ctrl+C to stop.`)
+        .action(async (options) => {
+        try {
+            process.exitCode = await runBrowser(globals(options), options);
+        }
+        catch (cause) {
+            if (cause instanceof CliError) {
+                printError(`error: ${cause.message}`);
+                process.exitCode = cause.exitCode;
+            }
+            else {
+                printError(`error: ${cause instanceof Error ? cause.message : String(cause)}`);
+                process.exitCode = EXIT_USAGE;
+            }
+        }
+    });
+    program
+        .command('instructions')
+        .argument('[guide]', 'overview | authoring | validating | configuring | init-required')
+        .description('print the workflow an agent follows in a root; no argument lists the guides')
+        .action((guide) => {
+        run(() => runInstructions(guide));
+    });
+    program
+        .command('standard')
+        .description('print the text of the Eidos standard this CLI carries (EIDOS.md)')
+        .option('--version', 'print only its version', false)
+        .action((options) => {
+        run(() => runStandard(options));
+    });
+    program
+        .command('agents')
+        .description('print the short nudge that points agents at `eidos instructions`, or write it into an instruction file')
+        .option('--write', 'append the nudge to the file (or refresh the one already there)', false)
+        .option('--file <path>', 'the instruction file', 'AGENTS.md')
+        .addHelpText('after', '\nExamples:\n  eidos agents\n  eidos agents --write\n  eidos agents --write --file CLAUDE.md')
+        .action((options) => {
+        run(() => runAgents(options));
+    });
+    return program;
+}

package/instructions/authoring.md

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

package/instructions/configuring.md

@@ -0,0 +1,65 @@
+## Configuring the framework
+
+The framework is the structure a root is written in: the framework document (version, naming, the Top-Level index, the Collections, and the property Schema) plus `_eidos/shapes/` (one file per flavor) and `_eidos/roles/`. This CLI reads it; changing it is an edit to those files, made with the owner and verified with `eidos check`.
+
+The document is `_eidos/Framework.yaml`: `top_level`, `collections[]` (each with `flavors`, `canvas`, `grouping`), and `schema.custom[]`, documented field by field in `eidos standard`. The procedures below show the markdown form the standard documents; the fields are the same. Never touch the `index` key: `eidos index` owns it.
+
+Press the owner to decide. A collection, flavor, or property nobody thought through reads as meaningful while no one knows what it holds. If they offer only a name, ask for the rest.
+
+Never touch `### Eidos Core`: those properties move with the standard's version. And never change the naming convention on a root with files in it without renaming every file and link.
+
+### Adding a collection
+
+Decide its **name** (the folder, in the naming convention `eidos framework` shows), a one-line **description**, how it **groups** its blueprints (one level of sub-folders, or flat), at least one **flavor** with a **default**, and how it **draws** on a canvas (`file` for prose read whole; `card from ## <Section>` for blueprints scanned by a headline; ask, do not assume the section).
+
+1. Create the folder under the root.
+2. Create the default flavor's shape in `_eidos/shapes/<kind>.<flavor>.md`: body only, `# {{title}}` first, then the `##` sections in order, each with an italic guidance prompt. Pattern it on the shapes already there.
+3. Register it under `## Collections` in `Framework.md` with a `###` heading, the description, then bullets in this form (bullets, so the next flavor is a copied line):
+
+   ```markdown
+   ### Decisions
+
+   Architecture decision records, one per significant choice.
+
+   - **Leaf:** [Decisions/index.md](../Decisions/index.md)
+   - **Flavors:**
+     - [full](shapes/decision.full.md) — context, decision, consequences (default).
+   - **Canvas:** card from `## Decision`
+   - **Kinds:**
+     - **Runtime** — decisions about what runs where.
+   ```
+
+   The grouping bullet (`**Kinds:**` above) is optional; its label is the collection's own, and each nested bullet is one group. A property carrying the group is a Schema change, below.
+4. Run `eidos index` for the new leaf and `eidos check` to confirm the framework parses as intended.
+
+### Adding a flavor
+
+Decide its **name** (lowercase), a one-line **description**, and its **shape**. A second flavor is a deliberate variant, a lighter one to grow out of or a genuine split in kind, never a fork per category label.
+
+1. Create `_eidos/shapes/<kind>.<flavor>.md`, starting from the collection's default flavor and trimming or extending it. Keep the order and names of whatever it shares with the default.
+2. Add it to the collection's **Flavors** bullets. Move `(default)` to it only if it should be the default; exactly one flavor carries the marker.
+3. Existing blueprints are untouched: an absent `flavor` still means the default. `eidos new --flavor <name>` scaffolds in it from here on.
+
+### Adding a property
+
+Decide all four: **name** (lowercase, words joined by underscores), **type** (Text, List, Number, Checkbox, Date, or Date & time; anything richer belongs in the body), **applies to** (`all`, or a list of collections), and **meaning** (one line).
+
+1. Add a row to `### Custom Properties` in `## Schema`:
+
+   ```markdown
+   | team | Text | all | Owning team, for filtering. |
+   ```
+
+2. Backfill the blueprints it applies to with an empty or owner-supplied stub, so each is fillable; `eidos check` lists the ones still missing it as `property-missing`. New blueprints get it from `eidos new`.
+
+### Renaming or retiring a property
+
+Renaming: change the `Name` cell, then the key in every blueprint's frontmatter, carrying values across unchanged. Retiring: first show the owner every value that would be lost and ask whether to fold them somewhere or drop them; only then remove the row and the keys. Never silently drop values.
+
+### Refreshing the Top-Level index
+
+`## Top-Level` lists the root's one-of-a-kind documents, `README` first, one bullet each: `- [Title](../Title.md) — one-line description`. Frames are a collection, not top-level. Keep the owner's existing descriptions; a doc with none gets a `<!-- TODO: describe -->`, and you ask. `eidos check` reports an entry whose file does not exist.
+
+### After
+
+Run `eidos check`. It will tell you whether the collection, its flavors, its shapes, and its groups are declared consistently, and which blueprints the change left with a gap.

package/instructions/init-required.md

@@ -0,0 +1,32 @@
+## Eidos root required
+
+No root was found from this directory: nothing here holds a `_eidos/` folder with a `Framework.md` inside it. A root is found by that marker, never by its name.
+
+If the root lives elsewhere in the repository, pass it explicitly:
+
+```bash
+eidos --root path/to/Blueprints framework
+```
+
+To create one, pick a seed (a complete starting framework) and install it:
+
+```bash
+eidos seeds                                  # what each seed is for, and its collections
+eidos init                                   # Blueprints/ from the software seed, kebab-case
+eidos init Blueprints --seed book --naming "Title Case" --group "Part One" --product "My Book"
+```
+
+`init` asks the owner nothing: choose the seed, the root folder name, the naming convention, the first groups, and the product name with them first, then run it. Everything a seed ships is reshapeable later, so a seed that is merely close is the right choice. `--dry-run` prints every write and touches nothing.
+
+If there is a root but it keeps its framework as `_eidos/Framework.md`, the CLI's first job is to convert it:
+
+```bash
+eidos convert --dry-run                      # the writes it would make
+eidos convert                                # Framework.yaml with the index inside; Framework.md and each index.md removed
+```
+
+After that, run:
+
+```bash
+eidos instructions overview
+```

package/instructions/overview.md

@@ -0,0 +1,37 @@
+## Eidos Overview (CLI)
+
+This repository keeps a root of Eidos blueprints. One markdown file is the complete source of truth for one unit of the thing being made, true whether or not it has been built. A blueprint captures state and intent, not work: no sprint, estimate, or assignee, and no progress notes in the body.
+
+### The one rule: facilitate, do not author
+
+Eidos is human-first. The owner holds the intent, the scope, and the decisions; you format, structure, ask, and press on scope. Do not generate a finished blueprint from a one-line prompt, invent a purpose or a behavior, resolve an open question on the owner's behalf, or set direction. A blueprint no one thought through is worse than none. When unsure, ask rather than write.
+
+### Start every request here
+
+1. `eidos framework` reads the root's own framework: its collections, their flavors and groups, and the property Schema. Never assume a collection, flavor, or section name; read what this framework declares. The document behind it is `_eidos/Framework.yaml`; if a root still keeps `Framework.md` (the form for people), every command says so and `eidos convert` moves it first.
+2. `eidos whoami` says who is in the seat. Open the role file it names under `_eidos/roles/` and respond as that contract says (vocabulary, depth, what to surface, who decides). A blank actor means full, framework-owner-style facilitation.
+3. `eidos list` and `eidos show <id>` read what already exists. Read before writing.
+4. `eidos instructions <guide>` before authoring, validating, or changing the framework. The overview says when to act; the guides say how.
+
+Add `--json` to `framework`, `list`, `show`, and `check` when a script needs stable fields.
+
+### The CLI owns structure; the conversation owns the words
+
+- `eidos new <collection> "<Title>"` scaffolds a blueprint that is born conforming: frontmatter from the Schema, body from the flavor's shape, filename in the naming convention, a permanent kebab-case `id` inside. Never hand-assemble frontmatter.
+- `eidos check` validates the root against its own framework. Its findings are a review the owner acts on; surface them, do not block on them.
+- `eidos index` regenerates the indexes, the `index` key inside `Framework.yaml`. Never edit it by hand.
+- The prose inside a blueprint is written in the file, with the owner, by you. The CLI never writes a sentence of it.
+- `eidos browser` opens the root in a local web page for a person. Everything the page can do runs the same code as a command (`new`, `check`, `index`), so it adds nothing you cannot do from the shell. Use the commands; leave the page to people.
+
+### Version
+
+The framework records the standard it targets as `eidos_version` in `_eidos/Framework.yaml`; `eidos standard --version` prints the one this CLI carries. `eidos check` notes a gap once. A gap never blocks the work: the framework in front of you is the operative contract either way.
+
+### Guides
+
+- `eidos instructions authoring`: read before creating or editing a blueprint
+- `eidos instructions validating`: read before reviewing a blueprint or reporting on a root
+- `eidos instructions configuring`: read before changing the framework (a collection, a flavor, a property, the Top-Level index)
+- `eidos instructions init-required`: when there is no root here yet
+
+`eidos <command> --help` explains any command's options and output.

package/instructions/validating.md

@@ -0,0 +1,33 @@
+## Validating blueprints
+
+Validation is framework-defined. `eidos check` reads the root's own `_eidos/Framework.yaml` and shapes and enforces those, never a contract of its own.
+
+```bash
+eidos check                      # the whole root: framework, layout, every blueprint
+eidos check <path> [<path>...]   # only these blueprints
+eidos check --json               # stable fields for a script
+eidos check --strict             # warnings fail too (CI)
+```
+
+Exit code 0 means no errors; 1 means at least one error (or, with `--strict`, any warning); 2 means the command could not run.
+
+### What the levels mean
+
+- An **error** is wrong on any reading: frontmatter that does not parse, a missing `id` or `title`, an `id` that is not kebab-case or is used twice, a `flavor` the collection does not declare, a link to a file that does not exist, a shape file the framework points at but does not have.
+- A **warning** is a gap the standard says to note and offer, never refuse: a missing or empty property the Schema applies to this collection, a property the Schema does not declare, a work-tracking field, a body section the flavor's shape declares but the blueprint lacks, a section the shape does not know, sections out of the shape's order, a grouping value that does not match its folder, a declared frame nobody has written, a stale `index.md`, a version gap.
+
+### Reporting a review
+
+The output is a review the owner acts on. When you report:
+
+- Lead with the errors, then the warnings, grouped by file, as `check` prints them.
+- Flag an absent non-goals section first among the section gaps: it is the one the standard leans on hardest.
+- Offer to add a missing core property with a note on why it exists; never refuse the file.
+- Confirm no work-tracking fields crept in, and that any section describing approach reads as intent, not progress.
+- A version gap is worth one line and an offer to migrate, once per session; then carry on with the framework as it stands.
+
+Do not fix silently. Show the finding, propose the change, and let the owner decide, unless the change is purely mechanical and they have asked for it (regenerating an index, adding a blank property stub).
+
+### Things `check` cannot judge
+
+Whether the prose is true, whether the scope is right, and whether an open question should be settled are the owner's. `check` tells you the file is well-formed against its framework; it says nothing about whether the thing described is the thing they mean. Read the blueprint with the frames in mind and raise what does not fit.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "eidosmd",
+  "version": "0.1.0",
+  "description": "The Eidos CLI: scaffold, validate, index, and browse a root of Eidos blueprints, and hand any agent the workflow it needs to work in one.",
+  "keywords": [
+    "eidos",
+    "blueprints",
+    "specs",
+    "markdown",
+    "cli",
+    "product-management",
+    "documentation"
+  ],
+  "homepage": "https://eidosmd.com/docs/cli",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/the-virtual-panda/eidosmd.git",
+    "directory": "cli"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "author": "The Virtual Panda",
+  "type": "module",
+  "bin": {
+    "eidos": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "browser",
+    "instructions",
+    "standard",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "marked": "^18.0.13",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
+  },
+  "bugs": "https://gitlab.com/the-virtual-panda/eidosmd/-/issues",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "test": "pnpm build && node --test \"dist/test/**/*.test.js\"",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "sync-standard": "node scripts/sync-standard.mjs"
+  }
+}