eidosmd 0.2.0 → 0.3.0

package/instructions/configuring.md

@@ -1,8 +1,8 @@
 ## Configuring the framework
 
-The framework is the structure a root is written in: the framework document (version, naming, the top-level index, the collections, the Properties table, and the Vocabulary) plus `.eidos/templates/` (one file per variant) 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 framework is the structure a root is written in: the framework document (version, naming, the top-level index, the folders, the Properties table, and the Vocabulary) plus `.eidos/templates/` (one file per variant) 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 `variants` and `grouping`), `properties.custom[]` (yours), `properties.tools.<tool>[]` (a tool's), and `vocabulary[]`, documented field by field in `eidos standard`. Never touch the `index` key: `eidos index` owns it. Never touch `.eidos/plugins/` (each folder is a tool's own) or a key on a Properties row past the standard's four (a tool's field, named for the tool); carry both across unchanged.
+The document is `.eidos/Framework.yaml`: `top_level` (every file at the root), `folders[]` (every folder at the root, each with a `type`: a `collection` with its `variants` and `grouping`, an `assets` folder of files that are not markdown, or an `other` folder described and left alone), `properties.custom[]` (yours), `properties.tools.<tool>[]` (a tool's), and `vocabulary[]`, documented field by field in `eidos standard`. Everything at the root is declared: a folder under `folders`, a file under `top_level`, and `eidos check` names what is missing on either side. Never touch the `index` key: `eidos index` owns it. Never touch `.eidos/plugins/` (each folder is a tool's own; its `local.yaml` is one person's and never committed) or a key on a Properties row past the standard's six (a tool's field, named for the tool); carry both across unchanged.
 
 Press the owner to decide. A collection, variant, 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.
 
@@ -14,10 +14,11 @@ Decide its **name** (the folder, in the naming convention `eidos framework` show
 
 1. Create the folder under the root.
 2. Create the default variant's template in `.eidos/templates/<unit>.<variant>.md`: body only, `# {{title}}` first, then the `##` sections in order, each with an italic guidance prompt. Pattern it on the templates already there.
-3. Register it under `collections` in `Framework.yaml`: an entry with its name, description, variants (one default), and grouping, one variant per line so the next one is a copied line:
+3. Register it under `folders` in `Framework.yaml`: an entry with its name, `type: collection`, description, variants (one default), and grouping, one variant per line so the next one is a copied line:
 
    ```yaml
    - name: Decisions
+     type: collection
      description: Architecture decision records, one per significant choice.
      variants:
        - { name: full, template: templates/decision.full.md, description: "context, decision, consequences", default: true }
@@ -30,6 +31,19 @@ Decide its **name** (the folder, in the naming convention `eidos framework` show
    The `grouping` key is optional; its label is the collection's own, and each entry under `groups` is one group. A property carrying the group (`grouping.property`) is a Properties table change, below.
 4. Run `eidos index` so the new collection has its list, and `eidos check` to confirm the framework parses as intended.
 
+`eidos configure:collection add <name> --unit <unit> [--description <text>] [--grouping <label>]` does all four in one plan.
+
+### Declaring a folder that is not a collection
+
+A folder at the root that holds no blueprints is declared too, with a type: `assets` for files that are not markdown (the images, diagrams, and documents blueprints link to, each by a relative markdown link, as `![Login flow](../assets/login-flow.png)`), or `other` for whatever the owner's description says. Nothing inside either is read or checked, and the files keep the names their tools gave them. Decide the **name** (in the naming convention) and the one-line **description**, then run it:
+
+```bash
+eidos configure:folder add assets --type assets --description "Images and diagrams the blueprints link to." --yes
+eidos configure:folder show
+```
+
+`configure:folder rename` moves the folder and rewrites every link into it; `set` changes the type or the description; `remove` removes the entry and, unless `--preserve`, the folder and every file in it, each listed before the question. A folder or file `eidos check` reports as undeclared (`folder-undeclared`, `file-undeclared`) is the owner's to declare or move; never delete one.
+
 ### Adding a variant
 
 Decide its **name** (lowercase), a one-line **description**, and its **template**. A second variant is a deliberate variant, a lighter one to grow out of or a genuine split in kind, never a fork per category label.
@@ -40,21 +54,23 @@ Decide its **name** (lowercase), a one-line **description**, and its **template*
 
 ### 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). Every property has an owner, and the owner is the block it sits in: yours go in `properties.custom`; a tool's go in `properties.tools.<tool>`, written by the tool. How blueprints relate to each other is better said in the body, as links in prose, than as a frontmatter list; a `connects_to` a root still carries is the framework's own custom property, kept or retired like any other.
+Decide all five: **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), **required** (`true` or `false`, absent meaning `false`: a required property is generated into every new blueprint it applies to and a missing one is a gap `eidos check` notes; an optional one is written when it has a value, left out otherwise, and never a gap; default to optional, and require only what the owner says every blueprint must answer), and **meaning** (one line). And the sixth, **options**, only when the value is one of a closed set the owner controls (a lifecycle, a tier): the list, non-empty, on a Text or List property, in the order the values run, so a lifecycle reads first stage to last and a dropdown or a board keeps that order. The comparison is exact, case included. A value off the list is surfaced by `eidos check` (`property-option`, with the list beside it), never refused. Without `options` any value is valid, so a label the owner wants open takes none; a `meaning` that lists values in prose is a set the entry should declare, and `meaning` then says what the property is for. No default rides with it: a required property with options is generated blank and the author picks. `variant` and a grouping property never carry it; their sets are the collection's declared variants and groups. Every property has an owner, and the owner is the block it sits in: yours go in `properties.custom`; a tool's go in `properties.tools.<tool>`, written by the tool. How blueprints relate to each other is better said in the body, as links in prose, than as a frontmatter list; a `connects_to` a root still carries is the framework's own custom property, kept or retired like any other.
 
-1. Add an entry to `properties.custom`:
+Run it, never hand-edit it:
 
-   ```yaml
-   - { name: team, type: Text, applies_to: all, meaning: "Owning team, for filtering." }
-   ```
+```bash
+eidos configure:property add team --type Text --applies-to all --required --meaning "Owning team, for filtering." --dry-run
+eidos configure:property add team --type Text --applies-to all --required --meaning "Owning team, for filtering." --yes
+eidos configure:property add tier --type Text --applies-to all --options Core,Extended,Experimental --meaning "How central the unit is to the product." --yes
+```
 
-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`.
+The command appends the entry and, when required, backfills the key blank into every blueprint it applies to; an optional property backfills nothing. New blueprints get a required one from `eidos new`, and an optional one when `--set` gives it a value. Every `configure:` command prints its plan first: `--dry-run` shows it and stops, `--yes` proceeds, and without a terminal you need one or the other (the error names it).
 
 A tool's fields on the entry (this CLI's `eidosmd: { canvas: … }`, which styles a canvas node by the property's value) are not the standard's and not yours to fill in; keep whatever is there.
 
 ### Renaming or retiring a property
 
-Renaming: change the entry's `name`, 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 entry and the keys. Never silently drop values.
+Renaming is `eidos configure:property rename <name> <new>`: the entry, the key in every blueprint, a grouping that names it, and the CLI's settings, in one plan. Changing a value everywhere is `configure:property remap <name> old=new`, and a value the property's `options` declare follows the rename in the list. Declaring or changing a list is `configure:property set <name> --options A,B,C` (`--open` drops it): widening a list touches no blueprint; declaring one, or narrowing one, is retiring values, so the plan names every blueprint carrying a value off the new list and needs `--force`, and `check` reports each afterwards. Show the owner that list and settle where each value goes before narrowing. Retiring is `configure:property remove <name>`: the plan lists every value that would be gone before it asks, and without a terminal it needs `--force`; show the owner that list and ask whether anything should be folded into a body first. `--preserve` leaves the keys in the files, which `check` then reports as `property-unknown`. The same family edits a collection (`configure:collection add|rename|remove`, the folder, templates, `applies_to`, and links following), a folder that is not a collection (`configure:folder`), a group (`configure:group`), a variant (`configure:variant`), a term (`configure:term`), and a role (`configure:role`). Never make these moves by hand or with a script when the command exists; every one rewrites the index and runs `check` afterwards and reports anything it introduced.
 
 ### Declaring a term
 
@@ -89,7 +105,7 @@ Ask which commit (HEAD unless they name one) and whether to tag; create the tag
 
 ### Refreshing the top-level index
 
-`top_level` lists the root's one-of-a-kind documents, `README` first, one entry each: `{ title: Vision, path: ../Vision.md, description: one line }`, the path relative to `.eidos/`. Frames are a collection, not top-level. Keep the owner's existing descriptions; a doc with none gets an empty description, and you ask. `eidos check` reports an entry whose file does not exist.
+`top_level` lists every file at the root, the one-of-a-kind documents, in the order they are read, one entry each: `{ title: Vision, path: ../Vision.md, description: one line }`, the path relative to `.eidos/`. The order is the owner's, the way a property's options are: the browser lists the docs in it and lands on the first, so an orientation doc (a README, when the root has one; every seed ships one and lists it first, and nothing requires it) goes first. Frames are a collection, not top-level. Keep the owner's existing descriptions; a doc with none gets an empty description, and you ask. `eidos check` reports an entry whose file does not exist (`top-level-missing`) and a file at the root no entry lists (`file-undeclared`); `eidos configure:doc add|rename|set|remove` edits the list.
 
 ### After
 

package/instructions/overview.md

@@ -8,19 +8,21 @@ Eidos is human-first. The owner holds the intent, the scope, and the decisions;
 
 ### Start every request here
 
-1. `eidos framework` reads the root's own framework: its collections, their variants and groups, the Properties table, and the Vocabulary (the root's own terms). Never assume a collection, variant, or section name; read what this framework declares. The document behind it is `.eidos/Framework.yaml`; a root still on the 4.x `Framework.md` is moved by `eidos migrate` first, and every command says so.
+1. `eidos framework` reads the root's own framework: its folders (each with a type: a collection with its variants and groups, an assets folder, an other folder), the Properties table, and the Vocabulary (the root's own terms). Never assume a collection, variant, or section name; read what this framework declares. The document behind it is `.eidos/Framework.yaml`; a root still on the 4.x `Framework.md` is moved by `eidos migrate` first, and every command says so.
 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 me.md 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.
+Add `--json` to `framework`, `list`, `show`, `check`, `property`, and every `configure:` command when a script needs stable fields. `eidos list` filters with `--group`, `--variant`, and `--where key=value` (any property, case-insensitive; a list matches any item).
 
 ### The CLI owns structure; the conversation owns the words
 
 - `eidos new <collection> "<Title>"` scaffolds a blueprint that is born conforming: frontmatter from the Properties table (every block: the core, the framework's, a tool's), body from the variant's template, filename in the naming convention, a permanent `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 property set @<id> <property> <value>` sets one property on one blueprint (`get` reads it, `unset` removes it), typed by the Properties table, with the root's on-save rules applied. Never open a file to change a frontmatter value; a key the table does not declare for the collection is refused, which is the answer, not a reason to edit the file.
+- `eidos configure:<noun> <operation>` changes the framework: `configure:property add|show|rename|set|remap|remove`, `configure:collection add|show|rename|remove`, `configure:folder add|show|rename|set|remove` (a folder at the root that is not a collection: `assets` or `other`), `configure:group add|rename|remove`, `configure:variant add|rename|set-default|remove`, `configure:term add|set|remove`, `configure:doc add|rename|set|remove`, `configure:role add|show|rename|remove`. Each prints its plan (every entry, key, file, and link it will touch, and every value that will be gone) and asks; run it first with `--dry-run` to show the owner the plan, then with `--yes` once they agree, and `--force` only where the plan says values or files go. Without a terminal a command refuses and names the switch. Never rename a property, move a group, or retire anything by editing files: the command reaches every blueprint and link and reruns the check, and a hand edit misses some.
+- The rule behind all of it: anything mechanical is the CLI's. 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, landing on its canvas maps: the design tool where a sketch becomes a blueprint. A canvas is one YAML file, `.eidos/plugins/eidosmd/maps/<id>.yaml`, that an agent edits directly: `eidos canvas schema` prints its JSON Schema, `eidos canvas show <id>` prints one, `eidos canvas new` creates one, and the browser reflects the file as it changes (or take the same JSON API, `/api/canvas/`, while it runs). 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.
 
 ### Speak the root's terms
@@ -35,7 +37,7 @@ The root's own versions are this CLI's, not the standard's: snapshots taken on p
 
 ### What is not yours
 
-`.eidos/plugins/<name>/` is a tool's own folder (this CLI keeps its canvas maps under `plugins/eidosmd/`). Leave every folder there alone unless you are the tool that owns it; a folder you don't recognize is not a problem to report. On a Properties row, a key past the standard's four (`name`, `type`, `applies_to`, `meaning`) is a tool's, named for the tool; carry it across an edit unchanged and never fill it in. A whole block a tool declared, `properties.tools.<tool>`, is that tool's alone.
+`.eidos/plugins/<name>/` is a tool's own folder (this CLI keeps its canvas maps under `plugins/eidosmd/`); the one file in it named `local.yaml` is one person's on one machine, never committed, kept out by the `plugins/*/local.yaml` line in `.eidos/.gitignore`. Leave every folder there alone unless you are the tool that owns it; a folder you don't recognize is not a problem to report. At the root, a folder declared as `assets` or `other` is the owner's too: nothing inside it is read, checked, or held to the naming convention, and a blueprint links into it with a relative markdown link like any other. On a Properties row, a key past the standard's six (`name`, `type`, `applies_to`, `required`, `options`, `meaning`) is a tool's, named for the tool; carry it across an edit unchanged and never fill it in. A whole block a tool declared, `properties.tools.<tool>`, is that tool's alone. Inside a markdown file, a span between `<!-- <tool>:<region> <args> -->` and `<!-- /<tool>:<region> -->` is a region that tool owns, the same name as its plugin folder: read it if it helps, write in it only if you are that tool, carry it across as found when you edit around it, and never fault its contents.
 
 ### Guides
 

package/instructions/validating.md

@@ -6,15 +6,15 @@ Validation is framework-defined. `eidos check` reads the root's own `.eidos/Fram
 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)
+eidos check --strict             # this run only: warnings fail too; the root's own setting is check.strict in settings.yaml
 ```
 
-Exit code 0 means no errors; 1 means at least one error (or, with `--strict`, any warning); 2 means the command could not run.
+Exit code 0 means no errors; 1 means at least one error, or any warning when the root is strict; 2 means the command could not run. Strictness is the framework owner's decision for the root, `check.strict` in `.eidos/plugins/eidosmd/settings.yaml` (set by `eidos init` or `eidos setup --strict on|off`), so read it from `--json`'s `strict` rather than assuming; `--strict` and `--no-strict` change one run only.
 
 ### What the levels mean
 
-- An **error** is wrong on any reading: frontmatter that does not parse, a missing `id` or `title`, an `id` used twice (its form is free: a slug, a number, a GUID), a `variant` the collection does not declare, a link to a file that does not exist, a template 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 Properties table applies to this collection (every block of it: the core, yours, a tool's), a property no block declares, a work-tracking field, a body section the variant's template declares but the blueprint lacks, a section the template does not know, sections out of the template's order, a grouping value that does not match its folder, a declared frame nobody has written, a stale index, a version gap, a near-miss the Vocabulary names (`term-near-miss`, with the declared term beside it).
+- An **error** is wrong on any reading: frontmatter that does not parse, a missing `id` or `title`, an `id` used twice (its form is free: a slug, a number, a GUID), a `variant` the collection does not declare, a link to a file that does not exist, a template file the framework points at but does not have, a region opener with no closer (`region-unclosed`, whichever tool it names).
+- A **warning** is a gap the standard says to note and offer, never refuse: a required property the Properties table applies to this collection but the blueprint lacks or leaves empty (every block of it: the core, yours, a tool's; an optional property absent is nothing, and present it is checked only by type), a property no block declares, a value off a property's declared `options` (`property-option`, exact match, the list beside it), a work-tracking field, a body section the variant's template declares but the blueprint lacks, a section the template does not know, sections out of the template's order, a grouping value that does not match its folder, a declared frame nobody has written, a stale index, a version gap, a near-miss the Vocabulary names (`term-near-miss`, with the declared term beside it), and, at the root, anything the framework document does not declare: a folder no entry under `folders` declares (`folder-undeclared`), a file `top_level` does not list (`file-undeclared`), a declared folder or document with nothing behind it (`folder-missing`, `collection-folder-missing`, `top-level-missing`), a sub-folder of a collection that is not a declared group (`group-undeclared`), and a folder inside a group (`folder-nested`; a group holds blueprints and nothing deeper). Nothing inside an `assets` or `other` folder is read, and a file that is not markdown inside a collection is not a blueprint.
 
 ### Reporting a review
 
@@ -26,6 +26,8 @@ The output is a review the owner acts on. When you report:
 - 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.
 - A `term-near-miss` is a suggestion: name the declared term, ask, and leave the word to the owner. Never swap it in.
+- A `property-option` is the same footing: show the value and the list, ask which option it is, and set it with `eidos property set`; never swap a value in silently. A value that belongs on no option is the owner's case for widening the list (`configure:property set --options`).
+- A `folder-undeclared` or `file-undeclared` is the owner's decision: declare it (`configure:folder add`, `configure:collection add`, `configure:doc add`) or move it. Never delete a file or folder, and never invent a description for one.
 
 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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eidosmd",
-  "version": "0.2.0",
+  "version": "0.3.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",