eidosmd 0.1.0

package/LICENSE

@@ -0,0 +1,133 @@
+Required Notice: Copyright 2026 The Virtual Panda (https://eidosmd.com)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/NOTICE

@@ -0,0 +1,15 @@
+eidosmd
+Copyright 2026 The Virtual Panda
+
+The eidos CLI is licensed under the PolyForm Noncommercial License 1.0.0
+(see LICENSE): free to use, read, and change for any noncommercial purpose;
+commercial use needs a license from The Virtual Panda.
+
+This product includes material from the Eidos standard
+(https://github.com/BuildableWorks/Eidos), Copyright 2026 Buildable,
+licensed under the Apache License, Version 2.0
+(https://www.apache.org/licenses/LICENSE-2.0). The files under standard/
+(EIDOS.md and seeds/) are copied from the pinned checkout of that repository
+at the monorepo's standard/ submodule by scripts/sync-standard.mjs,
+unmodified except that each seed's .gitignore travels as _gitignore, and are
+installed into a root by `eidos init`. That material keeps its Apache license.

package/README.md

@@ -0,0 +1,146 @@
+# eidosmd
+
+The command line for [Eidos](https://github.com/BuildableWorks/Eidos/blob/main/README.md): a markdown standard in which one file is the complete source of truth for one unit of a thing, true whether or not it has been built.
+
+`eidos` scaffolds a root, generates blueprints that are born conforming, validates them against the root's own framework, regenerates the indexes, and hands any coding agent the workflow it needs to work in one. Plain files, no service, no hidden state. It carries **Eidos 4.4.3**.
+
+```bash
+npm install -g eidosmd
+eidos --help
+```
+
+Node 20 or newer. The package installs one binary, `eidos`, and three small pure-JavaScript dependencies with no dependencies of their own, so the install takes seconds and every command starts in well under a tenth of one.
+
+## Quick start
+
+```bash
+eidos seeds                                  # the bundled starting frameworks
+eidos init --group Identity --product "Care Connect"
+cd Blueprints
+eidos framework                              # what this root declares
+eidos new specs "Session Management" --group identity --summary "Keeps a signed-in user signed in."
+eidos check                                  # a review, not a gate
+eidos index                                  # each collection's index.md
+```
+
+`init` copies a seed into `Blueprints/_eidos/` (the framework: shapes, roles, `Framework.yaml`), creates a folder per collection, and scaffolds one blank frame per framing flavor. It writes no prose. Everything a seed ships is reshapeable afterwards.
+
+### The framework document
+
+The CLI works on `_eidos/Framework.yaml`: the framework as data, the same fields the standard's markdown form carries, comments where you want them, and every collection's index inside it under `index` (which `eidos index` rewrites and nothing else). The standard also allows `Framework.md`, the form for people, with a per-collection `index.md`; a root that keeps it is converted first, and every other command says so:
+
+```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
+```
+
+The markdown form's prose has no field to land in and is left behind; each collection's description travels.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `eidos init [root]` | Create a root from a seed: `--seed`, `--naming`, `--group` (repeatable), `--product`, `--dry-run` |
+| `eidos convert` | Move a markdown root to `Framework.yaml`, the form the CLI works in; `--dry-run` |
+| `eidos seeds` | List the bundled seeds (software, book, research) with their collections and flavors |
+| `eidos framework` | Show the root's framework: version, naming, top-level docs, collections, flavors, groups, Schema; `--as yaml` prints it as the document; the one command that also reads a `Framework.md` root |
+| `eidos list [collection]` | List blueprints; filter with `--group`, `--flavor`, `--where key=value` |
+| `eidos show <id\|file\|path>` | Print one blueprint, or its properties and sections with `--json` |
+| `eidos new <collection> <title>` | Scaffold a blueprint: frontmatter from the Schema, body from the flavor's shape, filename in convention |
+| `eidos check [paths...]` | Validate the root (or the named blueprints) against its own framework; `--strict`, `--json` |
+| `eidos index` | Regenerate the indexes, the `index` key inside `Framework.yaml`; `--check` verifies without writing |
+| `eidos browser` | Open the root in a local web page on 127.0.0.1: browse, read, create, edit, check, index |
+| `eidos roles` | The roles the framework installed under `_eidos/roles/` |
+| `eidos whoami` | Show or set the actor in `_eidos/me.md` (role and calibration) |
+| `eidos instructions [guide]` | The workflow an agent follows: overview, authoring, validating, configuring, init-required |
+| `eidos standard` | Print the text of the standard this CLI carries; `--version` for just the number |
+| `eidos agents` | Print the nudge that points agents at `eidos instructions`; `--write` puts it in `AGENTS.md` |
+
+Every command takes `--root <path>`; without it the root is found from the working directory by its `_eidos/` marker, looking up the tree and then two levels down, so the commands work from a repository root that keeps its blueprints in `Blueprints/`.
+
+`framework`, `list`, `show`, `check`, `index`, `new`, and `whoami` take `--json` for stable output. Exit codes: `0` done, `1` the check found errors (or an index is stale under `--check`), `2` the command could not run.
+
+## The browser
+
+```bash
+eidos browser            # http://127.0.0.1:6180, this machine only; Ctrl+C to stop
+eidos browser --no-open --port 7000
+```
+
+The root in a local web page: browse collections and groups, read a blueprint rendered with its properties and its findings, follow links between blueprints, create one from the same scaffold `new` uses, edit and save one (the check runs on save), run the check, rebuild the index, and read the framework, the standard, and the agent instructions. There is nothing in the page that is not a command: every write runs the same core function as `new`, `index`, or `check`, and the page re-reads the root on every request, so it stays honest while files change on disk.
+
+## What `check` reports
+
+Validation is framework-defined: every rule reads `_eidos/Framework.yaml` and the shapes in `_eidos/shapes/`, never a contract hardcoded in the tool.
+
+- **Errors** are 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 the framework points at but lacks.
+- **Warnings** are gaps the standard says to surface, never refuse: a property the Schema applies here but the blueprint lacks or leaves empty, a property the Schema does not declare, a work-tracking field, a section the flavor's shape declares but the body lacks, a section the shape does not know, sections out of order, a grouping value that does not match its folder, a declared frame nobody has written, a stale `index.md`, a version gap between the framework and the standard the CLI carries.
+
+Frontmatter that is not valid YAML (an unquoted summary with a colon in it) is read leniently and reported as a warning, because Obsidian will refuse it even though a person can read it. `--strict` fails on warnings too, for CI.
+
+## For agents
+
+Eidos is human-first: the owner holds the intent, the scope, and the decisions, and an agent facilitates. The CLI owns structure (`new`, `check`, `index`) so an agent never hand-assembles frontmatter or edits a generated index; the words in a blueprint are written with the owner.
+
+```bash
+eidos instructions overview      # required first read
+eidos agents --write             # a short pointer in AGENTS.md (or --file CLAUDE.md)
+```
+
+The guides are the operating contract, the same one the standard's [Claude skills](https://github.com/BuildableWorks/Eidos/tree/main/skills) carry, restated around the commands. An agent with a shell needs nothing else.
+
+## The standard and this tool
+
+Two things version separately.
+
+- **The standard** is [`EIDOS.md`](https://github.com/BuildableWorks/Eidos/blob/main/EIDOS.md), maintained by Buildable in its own repository. A root records the version it targets as `eidos_version` in its framework document.
+- **This CLI** follows its own semver, in [`package.json`](package.json) and [`CHANGELOG.md`](CHANGELOG.md). It ships one release of the standard under [`standard/`](standard) (`EIDOS.md` and the seeds), which is what `eidos init` installs and what `eidos check` compares a framework's version against. `eidos --version` names both.
+
+`standard/` is a committed copy of that repository's `EIDOS.md` and `seeds/`, refreshed from the monorepo's `standard/` submodule by `pnpm sync-standard` (`--check` exits 1 if it has drifted from the pin); `npm pack` ships only what sits inside this package, so the copy has to be here. Each seed's `.gitignore` travels as `_gitignore`, because npm never packs a file by that name, and `eidos init` renames it back. Never edit `standard/` by hand: sync it.
+
+A root on a newer or older standard still works: the framework in front of the tool is the operative contract, and the gap is reported once by `check`. Moving a root between versions is a judgment call this CLI does not automate; the `migrate` skill and [`versions/MIGRATIONS.md`](https://github.com/BuildableWorks/Eidos/blob/main/versions/MIGRATIONS.md) cover it.
+
+## Development
+
+From the monorepo root or from `cli/`:
+
+```bash
+pnpm install
+pnpm build          # tsc → dist/
+pnpm test           # builds, then runs the suite with node --test
+pnpm check          # type-check
+node dist/src/cli.js --help
+```
+
+```txt
+src/
+  cli.ts            the executable entry
+  program.ts        every command, its options, and its help (commander)
+  context.ts        find the root, load its framework and blueprints
+  commands/         one module per command: what each prints and returns
+browser/            the one HTML page `eidos browser` serves
+  core/             the testable model, no printing:
+    root.ts           finding a root by its _eidos/ marker
+    framework.ts      finding and loading the framework document
+    framework-model.ts  the model: collections, flavors, groups, Schema
+    framework-markdown.ts   parsing Framework.md, for convert and framework --as yaml
+    framework-structured.ts parsing and writing Framework.yaml, and the index inside it
+    shape.ts          reading a shape file's sections and template
+    blueprint.ts      loading blueprints from a collection's folder
+    frontmatter.ts    YAML in, house-style frontmatter out
+    check.ts          every validation rule
+    index-leaf.ts     the index inside Framework.yaml
+    convert.ts        moving a markdown root to Framework.yaml
+    seed.ts           installing a seed into a new root
+    server.ts         the browser's http server and JSON API, over the same core
+    scaffold.ts       generating one conforming blueprint
+    me.ts             roles and the actor
+instructions/       the guides `eidos instructions` prints
+standard/           the committed copy of EIDOS.md and seeds/ (synced from Buildable's repo, never hand-edited)
+scripts/            sync-standard.mjs
+test/               node:test suites; temp roots are installed from the seeds
+```
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE). Copyright The Virtual Panda. The source is here to read, run, and change for any noncommercial purpose; using it at work needs a commercial license, the way Obsidian does it. `standard/` is material from the [Eidos](https://github.com/BuildableWorks/Eidos) repository, copyright Buildable, under Apache-2.0; see [NOTICE](NOTICE).

package/browser/index.html

@@ -0,0 +1,268 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Eidos</title>
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #fbfaf7; --panel: #f3f1ec; --line: #ddd8cf; --text: #1f1d1a; --muted: #6b665e;
+    --accent: #7a4a1f; --accent-soft: #f1e4d6; --error: #b23a2a; --warn: #9a6a12; --ok: #2f6b3a;
+    --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    --sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #1b1916; --panel: #232019; --line: #3a352c; --text: #ebe6dc; --muted: #a39d92; --accent: #d9a56b; --accent-soft: #3a2d1f; --error: #e2705f; --warn: #d8a437; --ok: #7bc48a; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 15px/1.5 var(--sans); color: var(--text); background: var(--bg); }
+  a { color: var(--accent); }
+  button, select, input, textarea { font: inherit; color: inherit; }
+  button { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 4px 10px; cursor: pointer; }
+  button:hover { border-color: var(--accent); }
+  button.primary { background: var(--accent); color: var(--bg); border-color: var(--accent); }
+  input, select, textarea { background: var(--bg); border: 1px solid var(--line); border-radius: 6px; padding: 5px 8px; width: 100%; }
+  code, pre { font-family: var(--mono); font-size: 0.92em; }
+  pre { background: var(--panel); padding: 10px 12px; border-radius: 6px; overflow-x: auto; }
+  .layout { display: grid; grid-template-columns: 290px 1fr; min-height: 100vh; }
+  aside { background: var(--panel); border-right: 1px solid var(--line); padding: 14px; overflow-y: auto; position: sticky; top: 0; height: 100vh; }
+  main { padding: 20px 32px 60px; max-width: 980px; }
+  .brand { display: flex; align-items: baseline; gap: 8px; margin-bottom: 10px; }
+  .brand strong { font-size: 18px; }
+  .brand small { color: var(--muted); }
+  .nav a { display: block; padding: 3px 6px; border-radius: 4px; color: inherit; text-decoration: none; }
+  .nav a.active, .nav a:hover { background: var(--accent-soft); }
+  .nav h3 { margin: 14px 0 4px; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); display: flex; justify-content: space-between; align-items: center; }
+  .nav h3 button { font-size: 12px; padding: 1px 7px; }
+  .nav h4 { margin: 8px 0 2px 6px; font-size: 12px; color: var(--muted); font-weight: 600; }
+  .nav .bp { font-size: 14px; padding-left: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .nav .bp.flagged::after { content: " •"; color: var(--warn); }
+  .search { margin: 6px 0 4px; }
+  .toolbar { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 18px; align-items: center; }
+  .toolbar .spacer { flex: 1; }
+  .meta { color: var(--muted); font-size: 13px; margin: 0 0 6px; }
+  .meta code { color: var(--text); }
+  h1.title { margin: 0 0 6px; font-size: 26px; }
+  table.props { border-collapse: collapse; margin: 14px 0 22px; font-size: 14px; }
+  table.props td { padding: 3px 12px 3px 0; vertical-align: top; }
+  table.props td:first-child { color: var(--muted); font-family: var(--mono); font-size: 13px; white-space: nowrap; }
+  .body { border-top: 1px solid var(--line); padding-top: 12px; }
+  .body h1 { font-size: 24px; } .body h2 { font-size: 20px; margin-top: 28px; border-bottom: 1px solid var(--line); padding-bottom: 4px; } .body h3 { font-size: 16px; }
+  .body table { border-collapse: collapse; } .body th, .body td { border: 1px solid var(--line); padding: 4px 8px; }
+  .body em:only-child { color: var(--muted); }
+  .findings { margin: 10px 0 16px; padding: 0; list-style: none; font-size: 14px; }
+  .findings li { padding: 4px 8px; border-left: 3px solid var(--warn); background: var(--panel); margin-bottom: 4px; border-radius: 0 4px 4px 0; }
+  .findings li.error { border-left-color: var(--error); }
+  .findings code { color: var(--muted); }
+  .badge { display: inline-block; font-size: 12px; padding: 1px 8px; border-radius: 10px; background: var(--panel); border: 1px solid var(--line); color: var(--muted); margin-left: 6px; }
+  .badge.error { color: var(--error); border-color: var(--error); } .badge.warn { color: var(--warn); border-color: var(--warn); } .badge.ok { color: var(--ok); border-color: var(--ok); }
+  textarea.editor { min-height: 60vh; font-family: var(--mono); font-size: 13px; line-height: 1.45; white-space: pre; }
+  .form { display: grid; grid-template-columns: 140px 1fr; gap: 10px 14px; max-width: 640px; align-items: center; margin: 16px 0; }
+  .form label { color: var(--muted); font-size: 14px; }
+  .toast { position: fixed; right: 20px; bottom: 20px; background: var(--text); color: var(--bg); padding: 10px 16px; border-radius: 8px; max-width: 420px; font-size: 14px; white-space: pre-wrap; box-shadow: 0 6px 24px rgba(0,0,0,.25); }
+  .file-group { margin: 18px 0 6px; font-family: var(--mono); font-size: 14px; }
+  .file-group a { text-decoration: none; }
+  .hint { color: var(--muted); font-size: 13px; }
+  .empty { color: var(--muted); padding: 40px 0; }
+  .fw h2 { margin-top: 26px; }
+  .fw dl { display: grid; grid-template-columns: max-content 1fr; gap: 4px 14px; }
+  .fw dt { color: var(--muted); }
+  @media (max-width: 760px) { .layout { grid-template-columns: 1fr; } aside { position: static; height: auto; } main { padding: 16px; } }
+</style>
+</head>
+<body>
+<div class="layout">
+  <aside>
+    <div class="brand"><strong id="rootName">Eidos</strong><small id="rootVersion"></small></div>
+    <input class="search" id="search" type="search" placeholder="Find a blueprint…" autocomplete="off">
+    <nav class="nav" id="nav"></nav>
+  </aside>
+  <main id="main"><div class="empty">Loading…</div></main>
+</div>
+<script>
+(() => {
+  const $ = (sel, el = document) => el.querySelector(sel);
+  const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+  const api = async (method, url, body) => {
+    const res = await fetch(url, { method, headers: body ? { 'content-type': 'application/json' } : {}, body: body ? JSON.stringify(body) : undefined });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(data.error || res.statusText);
+    return data;
+  };
+  let state = { root: null, filter: '', flagged: new Set() };
+  let toastTimer;
+  const toast = (msg, ms = 4200) => {
+    let el = $('.toast'); if (!el) { el = document.createElement('div'); el.className = 'toast'; document.body.appendChild(el); }
+    el.textContent = msg; clearTimeout(toastTimer); toastTimer = setTimeout(() => el.remove(), ms);
+  };
+  const route = () => { const h = location.hash.replace(/^#\/?/, ''); const [view, ...rest] = h.split('/'); return { view: view || 'framework', arg: rest.join('/') }; };
+  const go = (path) => { location.hash = '#/' + path; };
+  const bpHref = (p) => '#/blueprint/' + p.split('/').map(encodeURIComponent).join('/');
+
+  async function loadRoot() {
+    state.root = await api('GET', '/api/root');
+    $('#rootName').textContent = state.root.name;
+    $('#rootVersion').textContent = `Eidos ${state.root.framework.eidos_version ?? '?'} · ${state.root.framework.file}`;
+    document.title = `${state.root.name} · Eidos`;
+    renderNav();
+  }
+
+  function renderNav() {
+    const { framework, blueprints } = state.root;
+    const q = state.filter.toLowerCase();
+    const cur = route();
+    const active = (h) => location.hash === h ? ' active' : '';
+    let html = `<a href="#/framework" class="${active('#/framework') || (cur.view === 'framework' ? 'active' : '')}">Framework</a>
+      <a href="#/check" class="${cur.view === 'check' ? 'active' : ''}">Check</a>
+      <a href="#/standard" class="${cur.view === 'standard' ? 'active' : ''}">The standard</a>
+      <a href="#/instructions/overview" class="${cur.view === 'instructions' ? 'active' : ''}">Agent instructions</a>`;
+    for (const c of framework.collections) {
+      const own = blueprints.filter((b) => b.collection === c.name && (!q || [b.title, b.id, b.summary, b.path].some((v) => (v || '').toLowerCase().includes(q))));
+      html += `<h3><span>${esc(c.name)}</span><button data-new="${esc(c.name)}" title="New blueprint in ${esc(c.name)}">+ new</button></h3>`;
+      const groups = [...new Set(own.map((b) => b.group).filter(Boolean))].sort();
+      const item = (b) => `<a class="bp${state.flagged.has(b.path) ? ' flagged' : ''}${cur.view === 'blueprint' && decodeURIComponent(cur.arg) === b.path ? ' active' : ''}" href="${bpHref(b.path)}" title="${esc(b.summary || b.path)}">${esc(b.title)}</a>`;
+      html += own.filter((b) => !b.group).map(item).join('');
+      for (const g of groups) html += `<h4>${esc(g)}</h4>` + own.filter((b) => b.group === g).map(item).join('');
+      if (own.length === 0) html += `<div class="hint" style="padding-left:12px">${q ? 'no match' : 'empty'}</div>`;
+    }
+    $('#nav').innerHTML = html;
+  }
+
+  const findingsHtml = (findings) => findings.length ? `<ul class="findings">${findings.map((f) => `<li class="${f.level}"><code>${esc(f.code)}</code> ${esc(f.message)}</li>`).join('')}</ul>` : '';
+
+  async function viewBlueprint(pathArg) {
+    const p = decodeURIComponent(pathArg);
+    const main = $('#main');
+    let b;
+    try { b = await api('GET', '/api/blueprints/' + p.split('/').map(encodeURIComponent).join('/')); }
+    catch (e) { main.innerHTML = `<div class="empty">${esc(e.message)}</div>`; return; }
+    const errors = b.findings.filter((f) => f.level === 'error').length, warns = b.findings.length - errors;
+    const badge = errors ? `<span class="badge error">${errors} error${errors > 1 ? 's' : ''}</span>` : '';
+    const wbadge = warns ? `<span class="badge warn">${warns} warning${warns > 1 ? 's' : ''}</span>` : '';
+    // a property value that is a markdown link opens the blueprint it points at
+    const val = (x) => { const m = typeof x === 'string' && /^\s*\[([^\]]*)\]\(([^)]+)\)\s*$/.exec(x); if (!m) return `<code>${esc(x)}</code>`; const hit = state.root.blueprints.find((y) => y.path === resolveRel(p, m[2].split('#')[0])); return hit ? `<a href="${bpHref(hit.path)}">${esc(m[1])}</a>` : `<span title="not a blueprint in this root: ${esc(m[2])}">${esc(m[1])}</span> <span class="badge error">broken</span>`; };
+    const props = Object.entries(b.properties).map(([k, v]) => `<tr><td>${esc(k)}</td><td>${Array.isArray(v) ? (v.length ? v.map(val).join(', ') : '<span class="hint">[]</span>') : (v === null || v === '' ? '<span class="hint">—</span>' : esc(v))}</td></tr>`).join('');
+    const missing = b.shape_sections.filter((s) => !b.sections.map((x) => x.toLowerCase()).includes(s.toLowerCase()));
+    main.innerHTML = `
+      <div class="toolbar"><span class="meta">${esc(b.collection)}${b.group ? ' / ' + esc(b.group) : ''} · <code>${esc(b.path)}</code> · ${esc(b.flavor || '')}</span><span class="spacer"></span>
+        <button id="edit">Edit</button></div>
+      <h1 class="title">${esc(b.title)}${badge}${wbadge}</h1>
+      <p class="meta">id <code>${esc(b.id || '(none)')}</code>${b.summary ? ' · ' + esc(b.summary) : ' · <span class="hint">no summary yet</span>'}</p>
+      ${findingsHtml(b.findings)}
+      ${missing.length ? `<p class="hint">Sections the ${esc(b.flavor)} shape declares and this blueprint lacks: ${missing.map((s) => `<code>${esc(s)}</code>`).join(', ')}</p>` : ''}
+      <table class="props">${props}</table>
+      <div class="body" id="body">${b.html}</div>
+      <div id="editor" hidden><textarea class="editor" id="text"></textarea>
+        <div class="toolbar" style="margin-top:10px"><button class="primary" id="save">Save</button><button id="cancel">Cancel</button><span class="hint">Saving runs the check on this file; the result shows above.</span></div></div>`;
+    if (b.findings.length) state.flagged.add(p); else state.flagged.delete(p);
+    renderNav();
+    // relative .md links open the blueprint they point at
+    for (const a of main.querySelectorAll('#body a[href]')) {
+      const href = a.getAttribute('href');
+      if (/^[a-z]+:/i.test(href) || href.startsWith('#')) continue;
+      const target = resolveRel(p, href.split('#')[0]);
+      const hit = state.root.blueprints.find((x) => x.path === target);
+      if (hit) { a.href = bpHref(hit.path); } else { a.title = 'not a blueprint in this root: ' + target; a.addEventListener('click', (e) => { e.preventDefault(); toast('Not a blueprint in this root: ' + target); }); }
+    }
+    $('#edit').onclick = () => { $('#body').hidden = true; $('#editor').hidden = false; $('#text').value = b.raw; $('#edit').hidden = true; $('#text').focus(); };
+    $('#cancel').onclick = () => viewBlueprint(pathArg);
+    $('#save').onclick = async () => {
+      try { const r = await api('PUT', '/api/blueprints/' + p.split('/').map(encodeURIComponent).join('/'), { text: $('#text').value }); toast(r.findings.length ? `Saved. ${r.findings.length} finding${r.findings.length > 1 ? 's' : ''} on this file.` : 'Saved. No findings.'); await loadRoot(); viewBlueprint(pathArg); }
+      catch (e) { toast('Save failed: ' + e.message); }
+    };
+  }
+  function resolveRel(from, href) {
+    const parts = from.split('/').slice(0, -1);
+    for (const seg of decodeURIComponent(href).split('/')) { if (seg === '..') parts.pop(); else if (seg !== '.' && seg !== '') parts.push(seg); }
+    return parts.join('/');
+  }
+
+  function viewFramework() {
+    const f = state.root.framework, a = state.root.actor;
+    const flav = (c) => c.flavors.map((x) => `<code>${esc(x.name)}</code>${x.default ? ' (default)' : ''}${x.description ? ' — ' + esc(x.description) : ''}`).join('<br>');
+    const canvas = (c) => !c.canvas ? '' : typeof c.canvas === 'string' ? c.canvas : `card from ## ${esc(c.canvas.section)}`;
+    $('#main').innerHTML = `<div class="fw">
+      <h1 class="title">${esc(state.root.name)}</h1>
+      <p class="meta">Eidos ${esc(f.eidos_version ?? 'unversioned')} · naming <code>${esc(f.naming)}</code> · <code>${esc(f.file)}</code> · CLI ${esc(state.root.cli_version)} (standard ${esc(state.root.standard_version)})</p>
+      ${f.problems.length ? findingsHtml(f.problems.map((m) => ({ level: 'error', code: 'framework-invalid', message: m }))) : ''}
+      <div class="toolbar"><button id="reindex">Rebuild index</button><button id="runcheck">Run check</button><span class="hint">Both run exactly what <code>eidos index</code> and <code>eidos check</code> run.</span></div>
+      <h2>Actor</h2><p>${a.exists && a.role ? `<strong>${esc(a.role)}</strong> · ownership: ${esc(a.ownership || '—')} · experience: ${esc(a.experience || '—')} · capacity: ${esc(a.capacity || '—')}` : `<span class="hint">unset (full facilitation) — set it with <code>eidos whoami --role &lt;name&gt;</code></span>`}</p>
+      <p class="hint">Roles installed: ${state.root.roles.map((r) => `<code>${esc(r.name)}</code>`).join(', ') || 'none'}</p>
+      <h2>Collections</h2>
+      ${f.collections.map((c, i) => `<h3>${esc(c.name)}${i === 0 ? ' <span class="badge">framing</span>' : ''}${c.grouping ? ` <span class="badge">grouped by ${esc(c.grouping.label)}${c.grouping.property ? ' (' + esc(c.grouping.property) + ')' : ''}</span>` : ''}</h3>
+        ${c.description ? `<p>${esc(c.description)}</p>` : ''}
+        <dl><dt>flavors</dt><dd>${flav(c)}</dd>${c.canvas ? `<dt>canvas</dt><dd>${canvas(c)}</dd>` : ''}${c.grouping && c.grouping.groups ? `<dt>groups</dt><dd>${c.grouping.groups.map((g) => `<code>${esc(g.name)}</code>${g.description ? ' — ' + esc(g.description) : ''}`).join('<br>')}</dd>` : ''}</dl>`).join('')}
+      <h2>Schema</h2>
+      <table class="props"><tr><td>core</td><td>${f.schema.core.map((p) => `<code>${esc(p.name)}</code>`).join(' ')}</td></tr>
+      ${f.schema.custom.map((p) => `<tr><td>${esc(p.name)}</td><td><span class="badge">${esc(p.type)}</span> <span class="badge">${Array.isArray(p.applies_to) ? esc(p.applies_to.join(', ')) : 'all'}</span> ${esc(p.meaning)}</td></tr>`).join('')}</table>
+      ${f.top_level && f.top_level.length ? `<h2>Top-level docs</h2><ul>${f.top_level.map((d) => `<li><strong>${esc(d.title)}</strong> <code>${esc(d.path)}</code>${d.description ? ' — ' + esc(d.description) : ''}</li>`).join('')}</ul>` : ''}
+    </div>`;
+    $('#reindex').onclick = async () => { try { const r = await api('POST', '/api/index'); toast(r.indexes.map((i) => `${i.collection}: ${i.status} (${i.blueprints})`).join('\n') + (r.missing_summary.length ? `\n${r.missing_summary.length} blueprint(s) still need a summary` : '')); } catch (e) { toast(e.message); } };
+    $('#runcheck').onclick = () => go('check');
+  }
+
+  async function viewCheck() {
+    const main = $('#main'); main.innerHTML = '<div class="empty">Checking…</div>';
+    const r = await api('GET', '/api/check');
+    state.flagged = new Set(r.findings.map((f) => f.path).filter(Boolean));
+    renderNav();
+    const byFile = new Map();
+    for (const f of r.findings) { const k = f.path || '(root)'; if (!byFile.has(k)) byFile.set(k, []); byFile.get(k).push(f); }
+    const isBp = (k) => state.root.blueprints.some((b) => b.path === k);
+    main.innerHTML = `<h1 class="title">Check <span class="badge ${r.errors ? 'error' : r.warnings ? 'warn' : 'ok'}">${r.errors} error${r.errors === 1 ? '' : 's'}, ${r.warnings} warning${r.warnings === 1 ? '' : 's'}</span></h1>
+      <p class="meta">${r.blueprints} blueprints in ${r.collections} collections · Eidos ${esc(r.eidos_version ?? '?')} · ${esc(r.naming)} · the same report as <code>eidos check</code></p>
+      ${r.findings.length === 0 ? '<p class="empty">No findings.</p>' : ''}
+      ${[...byFile.entries()].map(([k, fs]) => `<div class="file-group">${isBp(k) ? `<a href="${bpHref(k)}">${esc(k)}</a>` : esc(k)}</div>${findingsHtml(fs)}`).join('')}`;
+  }
+
+  async function viewDoc(url, title) {
+    const main = $('#main'); main.innerHTML = '<div class="empty">Loading…</div>';
+    const r = await api('GET', url);
+    main.innerHTML = `<div class="body" style="border:0">${r.html}</div>`;
+  }
+
+  function viewNew(collectionName) {
+    const f = state.root.framework;
+    const c = f.collections.find((x) => x.name === collectionName) || f.collections[0];
+    const groups = (c.grouping && c.grouping.groups) ? c.grouping.groups.map((g) => g.name) : [];
+    $('#main').innerHTML = `<h1 class="title">New blueprint</h1>
+      <p class="hint">Runs <code>eidos new</code>: frontmatter from the Schema, body from the flavor's shape, filename in the naming convention. You fill the prose afterwards.</p>
+      <div class="form">
+        <label>Collection</label><select id="n-col">${f.collections.map((x) => `<option ${x.name === c.name ? 'selected' : ''}>${esc(x.name)}</option>`).join('')}</select>
+        <label>Title</label><input id="n-title" placeholder="Session Management" autofocus>
+        <label>Flavor</label><select id="n-flavor">${c.flavors.map((x) => `<option ${x.default ? 'selected' : ''}>${esc(x.name)}</option>`).join('')}</select>
+        <label>Group</label><input id="n-group" list="n-groups" placeholder="${groups.length ? 'one of the declared groups, or a new one' : c.grouping ? c.grouping.label : 'optional sub-folder'}"><datalist id="n-groups">${groups.map((g) => `<option value="${esc(g)}">`).join('')}</datalist>
+        <label>Summary</label><input id="n-summary" placeholder="One plain line: what this blueprint is.">
+        <span></span><div class="toolbar"><button class="primary" id="n-create">Create</button><button id="n-cancel">Cancel</button></div>
+      </div>`;
+    $('#n-col').onchange = () => viewNew($('#n-col').value);
+    $('#n-cancel').onclick = () => history.back();
+    $('#n-create').onclick = async () => {
+      try {
+        const r = await api('POST', '/api/blueprints', { collection: $('#n-col').value, title: $('#n-title').value, flavor: $('#n-flavor').value, group: $('#n-group').value, summary: $('#n-summary').value });
+        toast(`Created ${r.path}` + (r.notes.length ? '\n' + r.notes.join('\n') : ''), 6000);
+        await loadRoot(); go('blueprint/' + r.path.split('/').map(encodeURIComponent).join('/'));
+      } catch (e) { toast(e.message, 6000); }
+    };
+  }
+
+  async function render() {
+    const { view, arg } = route();
+    renderNav();
+    if (view === 'blueprint') return viewBlueprint(arg);
+    if (view === 'check') return viewCheck();
+    if (view === 'standard') return viewDoc('/api/standard');
+    if (view === 'instructions') return viewDoc('/api/instructions/' + (arg || 'overview'));
+    if (view === 'new') return viewNew(decodeURIComponent(arg));
+    return viewFramework();
+  }
+
+  $('#search').addEventListener('input', (e) => { state.filter = e.target.value; renderNav(); });
+  $('#nav').addEventListener('click', (e) => { const b = e.target.closest('button[data-new]'); if (b) go('new/' + encodeURIComponent(b.dataset.new)); });
+  window.addEventListener('hashchange', render);
+  loadRoot().then(render).catch((e) => { $('#main').innerHTML = `<div class="empty">${esc(e.message)}</div>`; });
+})();
+</script>
+</body>
+</html>

package/dist/src/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The executable entry point: one root of Eidos blueprints, scaffolded,
+// validated, and indexed from the shell.
+import { buildProgram } from './program.js';
+buildProgram().parse(process.argv);

package/dist/src/commands/agents.js

@@ -0,0 +1,47 @@
+// `eidos agents`: the short nudge that points an agent at `eidos instructions`,
+// printed, or written into an instruction file such as AGENTS.md or CLAUDE.md.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { EXIT_OK, print } from '../output.js';
+export const NUDGE_START = '<!-- eidos:instructions:start -->';
+export const NUDGE_END = '<!-- eidos:instructions:end -->';
+export function nudge() {
+    return [
+        NUDGE_START,
+        '## Eidos',
+        '',
+        'This repository keeps its blueprints in an Eidos root. Before creating, editing, reviewing, or discussing a blueprint or the framework, run `eidos instructions overview` and follow it; it names the guide to read for each kind of work. Use the `eidos` CLI for structure (`eidos new`, `eidos check`, `eidos index`); never hand-assemble frontmatter or edit an `index.md`.',
+        NUDGE_END,
+    ].join('\n');
+}
+export function runAgents(options, cwd = process.cwd()) {
+    const block = nudge();
+    if (!options.write) {
+        print(block, '', `write it: eidos agents --write [--file ${options.file}]`);
+        return EXIT_OK;
+    }
+    const file = path.resolve(cwd, options.file);
+    const rel = path.relative(cwd, file) || options.file;
+    if (!existsSync(file)) {
+        writeFileSync(file, block + '\n', 'utf8');
+        print(`✓ created ${rel} with the Eidos nudge`);
+        return EXIT_OK;
+    }
+    const current = readFileSync(file, 'utf8');
+    const start = current.indexOf(NUDGE_START);
+    const end = current.indexOf(NUDGE_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        const updated = current.slice(0, start) + block + current.slice(end + NUDGE_END.length);
+        if (updated === current) {
+            print(`✓ ${rel} already carries the current nudge`);
+            return EXIT_OK;
+        }
+        writeFileSync(file, updated, 'utf8');
+        print(`✓ refreshed the Eidos nudge in ${rel}`);
+        return EXIT_OK;
+    }
+    const separator = current.endsWith('\n') ? (current.endsWith('\n\n') ? '' : '\n') : '\n\n';
+    writeFileSync(file, current + separator + block + '\n', 'utf8');
+    print(`✓ appended the Eidos nudge to ${rel}`);
+    return EXIT_OK;
+}