create-evda 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Veson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @evda/person-record
+
+The person layer over the substrate. An EVÐA is a directory that knows what it is: a person's record in their own words, a ledger of claims about them and what happened to each claim, and the operating instructions beside them, so that any agent on any model can open it and act correctly with no outside context.
+
+This package scaffolds one and ships the optional tooling. The files are the truth. Nothing here is required to read or write a record; `evda doctor` says whether one is well-formed and `evda reindex` rebuilds the derived directory, and both can be thrown away. It has no runtime dependencies (`test/deps.test.mjs` asserts it) and never makes a network call.
+
+Design contract: Spec 04 (the hypothesis ledger), Spec 05 (the data layer) and Spec 07 (holders, circles, references and views) in the EVÐA project. A short copy of what this package settles is in `docs/canon/person-record.md`.
+
+## Where it sits
+
+Block tier, domain neutral. It imports nothing from the workspace at runtime. What it shares with the substrate is a file format: a circle is an eco, declared by the same `eco.yaml` that `@evda/common` parses and `@evda/vault-core` stores, and `test/eco-parity.test.mjs` runs every manifest this package writes through the substrate's own parser. Grants, entity addressing, changes and sync stay the substrate's; this package reads and writes plain files and leaves those to it.
+
+## Scaffold
+
+```bash
+node create-evda.mjs my-evda --owner "Dana"
+```
+
+Writes:
+
+    my-evda/
+      evda.json              schema version, layers, and the MAPPING of roles to paths
+      AGENTS.md              the operating layer. One installer-owned fence; the rest is the owner's
+      CLAUDE.md              one line: @AGENTS.md (Claude Code does not read AGENTS.md on its own)
+      record/daily/          YYYY-MM-DD.md, verbatim. Day one holds one file: today's, recording
+                             that the record was created. Everything after it is the owner's.
+      record/captures/       each record folder carries folder.evda.json: what its entries are
+      record/people/         (record, capture, person), which connectors feed its references,
+                             and which views render it
+      ledger/hypotheses.md   the entry shape and the six rules are at the top of the file
+      circles/, grants/      with --layers record,ledger,circles: each circle's eco.yaml, and one
+                             grant file per reader and circle
+      .evda/version          the schema version actually on disk
+      .evda/due.jsonl        derived from the ledger's Due lines
+      .evda/digest.md        derived from the fenced block of AGENTS.md, under 2048 bytes
+
+Then open the directory in Claude Code, or any agent that reads AGENTS.md, and say something true about today. It goes into `record/daily/` in your words. Nothing is proposed about you until the record holds something to be wrong about.
+
+The tree above is what the scaffolder creates and not a requirement. `evda.json` carries a `mapping` from roles to paths, and every tool reads roles. An existing folder of notes becomes an EVÐA by adding `evda.json` with a mapping that names where things already are, and nothing moves.
+
+## The CLI
+
+    evda doctor [dir]              validate, and say what was examined
+    evda reindex [dir] [--adopt]   rebuild .evda/
+    evda due [dir]                 what is due, soonest first
+    evda chain <H-id> [dir]        the supersession chain through one hypothesis
+    evda current [dir]             the derived "current" view of the ledger
+    evda moment <from> [to] [dir]  what was written between two dates
+    evda upgrade [dir]             replace the installer-owned block of AGENTS.md, touch nothing else
+    evda digest [dir]              the instruction-only digest of AGENTS.md
+    evda migrate [dir]             forward migrations, each saying what it cannot reverse
+    evda vector <vdir> [--check]   the conformance projection of one ledger
+    evda references [dir] [--resolve]
+                                   every reference, its folder's connector, and what each source answers
+    evda folder <dir> --type T [--connectors a,b]
+                                   write a folder's folder.evda.json
+    evda grant <circle> --to <record-id> --kind person|agent|company [--name N]
+                                   let another record read a circle; an agent gets viewer only
+    evda grants [dir]              every grant, who holds it and on what
+    evda revoke <circle> --to <record-id>
+    evda access <circle> --as <record-id>
+                                   may that record read the circle? exit 0 or 2, with why
+    evda status [dir]              one screen
+    evda where                     which record the locator resolves to, and by which rule
+    evda use <dir>                 point ~/.evda/current at a record
+
+The record is found through the locator: a directory argument, then `$EVDA_HOME`, then the nearest ancestor of the working directory holding `evda.json`, then `~/.evda/current`. Nothing assumes it was launched inside one.
+
+`evda doctor` prints `CHECKED <n> <noun>` for everything it examined, or `SKIPPED <noun>: why`. `CHECKED 0` is a failure. A run that exits 0 without a `CHECKED` line of `n > 0` is itself a failure. Exit codes: 0 ok, 1 the record has a named problem, 2 refused with nothing written.
+
+## Circles are ecos
+
+A circle is a subdirectory of the `circles` role holding `eco.yaml`, the substrate's eco manifest. The manifest declares it; a directory without one is not a circle and `evda doctor` fails on it.
+
+```yaml
+id: ecos/public
+kind: eco
+schemaVersion: "0.1"
+namespace: public.eco
+title: Public
+description: Anyone may read this circle. It holds what Dana publishes on purpose.
+public: true
+maintainers:
+  - name: Dana
+    role: holder
+members:
+  writing:
+    path: record/writing
+  posts:
+    table: posts
+    where:
+      published: true
+policy:
+  - rule: only what is published, or approved to publish, is in public
+    since: 2026-09-16
+    from: '"if it is not in the list it is not public, full stop" (Dana, record/daily/2026-09-16.md)'
+    passes: a post under record/writing
+    fails: a daily file that mentions the post
+    check: every file the circle covers sits under a path this manifest names; anything else fails
+    status: live
+```
+
+The first six keys are the substrate's, and `id` and `namespace` follow from the directory name so the three cannot disagree. `maintainers` are the holders. `members` is the mapping principle one level down: each member names where the circle's bytes already live, relative to the record root, and nothing moves. A `path` member must exist on disk. A `table` member names rows on a host selected by equality, and is allowed only in a public circle, because a private circle's host may not read it. `public: true` is the whole of what makes a circle public; the reader takes the same path and needs no key. Reading an encrypted circle is not built; a private circle is validated for shape and never read.
+
+`policy` is a list of rules, and a rule behaves like a test: one line in the owner's words, the date, the correction that made it (verbatim, quoted), an example that passes, one that fails, a check written so it could come back false, and a status of `live`, `revised` or `retired`. A rule is never edited in place; a revision is a new rule with `revisedBy` written on the old one. A number in a rule line is warned about: the check may count, the rule may not.
+
+Every entry resolves to exactly one circle. `evda doctor` counts the record's entries (every file in a record role, plus the ledger) against the path members of every circle, prints `CHECKED <n> entries across <m> circles`, and fails on an entry no circle covers or two circles cover.
+
+`circle.json`, the manifest this package wrote before circles became ecos, is still read with a warning so a record written against it keeps working. Nothing writes it any more.
+
+`lib/circles.mjs` is the reader and writer: `readCircles`, `publicCircle`, `member`, `holders`, `coverage`, `circleManifest`, `rule`, `writeCircle`. `lib/yaml.mjs` is the YAML subset it reads and writes, checked against the `yaml` package over the substrate's own manifests in `test/yaml.test.mjs`.
+
+## Holders and grants
+
+A record is held by a person, an agent, or a company (Spec 07, section 1). `evda.json` says which: `owner.kind`, a person unless said otherwise, and `id`, the record's atlas id (`<name>.atlas` unless given), which is how another record names this one in a grant or a reference. `create-evda my-agent --kind agent --id iris.atlas` scaffolds an agent's record; it has the same shape as a person's.
+
+Who may read a circle is a set of grants, one file each under the `grants` role, in the substrate's own Member shape (`SCHEMA-member`), at `grants/peers/<record-id>--<circle>.eco.yaml`:
+
+```yaml
+id: members/peers/iris.atlas--workshop.eco
+kind: member
+schemaVersion: "0.1"
+principalKind: peer
+principalId: iris.atlas
+eco: workshop.eco
+role: viewer
+grantedAt: 2026-09-16T15:00:00.000Z
+grantedBy: dana.atlas
+holder:
+  kind: agent
+  name: Iris
+```
+
+Every grantee is a `peer` (Spec 00 #65): a holder owns a record, a record is an atlas, and `peer` is the substrate's principal kind for another atlas. `holder` is the person-layer key the substrate's parser preserves, so a circle can say what kind of holder reads it without opening the peer's record. An agent holds `viewer` and nothing else; a grant giving it more is refused. A public circle needs no grant and a grant on one is refused. Grants live outside the circles they govern, as the substrate keeps `members/` outside `ecos/`: the access answer cannot sit inside the bytes it protects. `test/grants.test.mjs` hands every grant this package writes to `parseMember` and `Member.fromJSON` from `@evda/common`.
+
+    evda grant <circle> --to <record-id> --kind agent --name Iris    viewer, the only role an agent gets
+    evda access <circle> --as <record-id>                           exit 0 allowed, 2 refused, with why
+    evda grants                                                     every grant, who holds it and on what
+    evda revoke <circle> --to <record-id>
+
+`access` never answers with a bare yes or no: a pass names the grant that allowed it, a refusal names what is missing. `readCircleAs(evda, circle, id)` in `lib/grants.mjs` is the same gate for code, and throws `REFUSED` with exit 2 on a circle the reader was not granted. `evda doctor` prints `CHECKED <n> grants across <m> circle(s)` and fails a grant on a circle that does not exist, one that gives an agent more than viewer, and one whose filename disagrees with its content. Reading an encrypted circle's bytes is still not built; the gate decides, and what is behind it is declared by path.
+
+## References instead of copies
+
+A reference is a stable pointer to something the record does not hold: a Contacts entry, a password manager item, a page, an entry in another EVÐA. It is written once, in the entry's frontmatter, and resolved when read. What is stored is the pointer, a label to render when the source is unreachable, and the date it last resolved. Never the payload, and never a secret.
+
+```yaml
+---
+references:
+  - ref: contacts:2F1A-77
+    label: Sam Rivera
+    resolved: 2026-09-10
+  - ref: 1password:op://Personal/Bank
+    label: Bank login
+  - ref: url:https://example.org/paper
+    label: The paper
+  - ref: "@north.atlas/people.eco/person/sam@example.org"
+    label: Sam, in their own record
+---
+```
+
+Four schemes: `contacts:<identifier>`, `1password:op://<vault>/<item>` (the item, never a field), `url:<http(s)://...>`, and `@<atlasId>/<eco>/<kind>/<id>`, the substrate's federated `EntityRef` unchanged (`test/entity-ref-parity.test.mjs` runs this package's parser against `parseEntityRef` from `@evda/common`). A key beyond `ref`, `label` and `resolved` is a copy of what the source holds and fails. A key named like a secret, or a value shaped like one (a private key block, a JWT, the prefixes the common services stamp on tokens, a bearer header, a password or credential in a URL, a long high-entropy token), is `REFUSED` with exit 2 and the value is never echoed.
+
+Each record folder carries `folder.evda.json`:
+
+```json
+{
+  "type": "person",
+  "connectors": ["contacts", "url"],
+  "views": [{ "view": "everyone", "of": "person", "in": "people.eco", "path": "record/people/Everyone.md" }]
+}
+```
+
+`type` is what the entries are (one of the Spec 07 types). `connectors` are the schemes the folder's references may resolve through; the registry reads this list first and skips a scheme the folder does not name. `views` are the folder's view declarations (Spec 07, section 5): each is the object `@evda/views` renders from, with `view` (its name), `of` (the entity kind), `in` (the eco), `path` (the markdown file it renders to, relative to the record root), and optionally `status` and `group`. This package checks the shape, that the file at `path` exists, and that its header names the same view; what the header means is the renderer's to refuse. The manifest never names a circle. A file inherits the nearest manifest above it. `evda doctor` prints `CHECKED <n> folder manifests`, `CHECKED <n> views` and `CHECKED <n> references across <m> file(s)`, and fails on a declared view with no file or a file whose header names another view, and on a reference with no manifest above it, one whose scheme the folder does not declare, one carrying a copy, and one carrying a secret. Doctor never touches the network.
+
+`lib/resolvers.mjs` is the registry, one resolver per scheme. Resolving returns `resolved` (with the date and the source's own name for the thing, offered as a label and nothing more), `unreachable` (asked, no answer, with why), or `skipped` (not asked, with why). Never nothing, and never the payload. The `url` resolver is Node's `fetch` with a timeout and a capped read for the page's title; `test/resolvers.test.mjs` runs it against a local server. `contacts`, `1password` and the EVÐA address say `SKIPPED` with the reason, because this tool has no connector to the device's Contacts, to the password manager, or to another record's grants. A reference renders as its label, and an unresolved one says so and since when; `renderReference` never returns an empty string. `evda references --resolve` is the command that asks.
+
+## Versioning
+
+`evda.json` declares a schema version. `.evda/version` records what a tool last left on disk. A disagreement refuses loudly rather than guessing. Migrations live in `migrations/`, forward-only, one version step per file, each required to say what it cannot reverse.
+
+A tool reading a manifest newer than itself operates the layers it knows and writes back every key it did not understand, in the order it read them. `test/manifest.test.mjs` is the proof.
+
+## Generated files
+
+`templates/AGENTS.md`, `templates/evda-digest.md`, `templates/hypotheses.md` and `vectors/007-empty-with-header/ledger.md` are generated from the spec (`AGENTS-template.md`, `04 - The Hypothesis Ledger.md`) by `scripts/build-templates.mjs`. Do not edit them; edit the source and rebuild. The spec is owned outside this repository; `EVDA_SPEC_DIR` names its directory. `pnpm templates:check` fails on drift when it is set and prints `SKIPPED` when it is not.
+
+## What stays outside the repository
+
+Nothing in this package belongs to one person's record. Two things that do are reached by environment variable and are `SKIPPED` when unset, which is the normal state on every machine but the owner's:
+
+- `EVDA_LEDGER_PY`: the second reader of the ledger format, in Python. `scripts/vectors-both.sh` runs both readers over every vector and compares when it is set.
+- `EVDA_EXTRA_VECTORS`: a directory of conformance vectors cut from a real record. `test/vectors.test.mjs` and `vectors-both.sh` read it when set.
+
+## Checks
+
+```bash
+pnpm --filter @evda/person-record test          # node --test, 101 tests
+pnpm --filter @evda/person-record lint          # no em or en dashes; generated templates match the spec when reachable
+pnpm --filter @evda/person-record vectors:both  # both readers over every vector; SKIPPED for the one not reachable
+```
+
+The package tests need `@evda/common` built first (`pnpm --filter @evda/common... build`), for the one test that hands this package's manifests to the substrate's parser. `pnpm test` at the root does that ordering.
+
+## Publishing
+
+Not published. The bins are `create-evda` and `evda`; a public package under the `create-evda` name so that `npx create-evda my-evda` works is the owner's decision and its own ticket.

package/bin/evda.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+// evda: operate an EVDA from the command line. Optional. The files are the contract.
+//
+// Every command finds the record through the locator (lib/locate.mjs): an explicit directory,
+// then $EVDA_HOME, then the nearest ancestor of the working directory holding evda.json, then
+// ~/.evda/current. Nothing assumes it was launched inside one.
+
+import { resolve, join, relative } from "node:path";
+import { readFileSync, writeFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { openEvda, readManifest, readVersion, writeVersion, findRoot, SCHEMA_VERSION } from "../lib/manifest.mjs";
+import { locate, setPointer, pointerPath } from "../lib/locate.mjs";
+import { resolveAll, agentsFile } from "../lib/roles.mjs";
+import { doctor } from "../lib/doctor.mjs";
+import { reindex, currentIndex, expectedIndex, expectedDigest } from "../lib/index.mjs";
+import { readLedger, chain, current } from "../lib/ledger.mjs";
+import { moment } from "../lib/record.mjs";
+import { migrate } from "../lib/migrate.mjs";
+import { splitFence, replaceFence, shippedGenerated } from "../lib/agents.mjs";
+import { mdFiles } from "../lib/record.mjs";
+import { folderManifests, folderFor, writeFolderManifest, FOLDER_MANIFEST } from "../lib/folders.mjs";
+import { referencesIn, renderReference } from "../lib/references.mjs";
+import { resolveReference } from "../lib/resolvers.mjs";
+import { grant, revoke, readGrants, access } from "../lib/grants.mjs";
+import { holderOf, HOLDER_KINDS } from "../lib/manifest.mjs";
+import { EvdaError, isEntry } from "../lib/errors.mjs";
+
+const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
+
+  evda doctor [dir]              validate, and say what was examined (CHECKED n ...)
+  evda reindex [dir] [--adopt]   rebuild .evda/ (due.jsonl, digest.md) from the files
+  evda due [dir]                 what is due, soonest first
+  evda chain <H-id> [dir]        the supersession chain through one hypothesis
+  evda current [dir]             the derived "current" view of the ledger
+  evda moment <from> [to] [dir]  what was written between two dates
+  evda upgrade [dir]             replace the installer-owned block of the operating layer; touch nothing else
+  evda digest [dir]              print the instruction-only digest of the operating layer
+  evda migrate [dir]             forward migrations, each saying what it cannot reverse
+  evda vector <vdir> [--check]   the conformance projection of <vdir>/ledger.md (Spec 04 vectors)
+  evda references [dir] [--resolve] [--timeout ms]
+                                 every reference in the record, its folder's connector, and with
+                                 --resolve what each source answers (url fetches; the rest say SKIPPED)
+  evda folder <dir> --type T [--connectors a,b] [--force]
+                                 write <dir>/folder.evda.json: what the folder holds and what feeds it
+  evda grant <circle> --to <record-id> --kind person|agent|company [--name N] [--role viewer] [dir]
+                                 let another record read a circle. An agent gets viewer only
+  evda grants [dir]              every grant, who holds it and on what
+  evda revoke <circle> --to <record-id> [dir]
+  evda access <circle> --as <record-id> [dir]
+                                 may that record read the circle? exit 0 yes, 2 refused, with why
+  evda status [dir]              one screen summary
+  evda where                     which EVDA the locator resolves to, and by which rule
+  evda use <dir>                 point ~/.evda/current at a record
+  evda init <dir> [--name N] [--owner O] [--layers record,ledger]
+
+Locator order: directory argument, $EVDA_HOME, the working directory's ancestors, ~/.evda/current.
+Exit codes: 0 ok, 1 the record has a problem and it was named, 2 refused (nothing written).`;
+
+// A positional argument is the record when it looks like a path or IS a directory on disk. A bare
+// name that exists (`evda doctor my-evda`) must not fall through to the pointer: on 2026-09-16 it
+// did, and `evda doctor scratch` read the record ~/.evda/current pointed at instead of `scratch/`.
+function isDirArg(a) {
+  if (a.includes("/") || a === "." || a === "..") return true;
+  try { return statSync(a).isDirectory(); } catch { return false; }
+}
+
+// `--name value` or `--name=value`. The value of a `--name value` pair is not a positional.
+const VALUE_FLAGS = ["to", "kind", "name", "role", "by", "as"];
+function flagValue(args, name) {
+  const eq = args.find((a) => a.startsWith(`--${name}=`));
+  if (eq) return eq.slice(name.length + 3);
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+
+function pickDir(args) {
+  const flags = args.filter((a) => a.startsWith("--"));
+  const values = new Set(VALUE_FLAGS.map((n) => { const i = args.indexOf(`--${n}`); return i >= 0 ? i + 1 : -1; }).filter((i) => i >= 0));
+  const positional = args.filter((a, i) => !a.startsWith("--") && !values.has(i));
+  const explicit = positional.find(isDirArg);
+  const rest = positional.filter((a) => a !== explicit);
+  const found = locate({ explicit });
+  return { dir: found.dir, via: found.via, flags, rest };
+}
+
+async function main(argv) {
+  const [cmd, ...args] = argv;
+  switch (cmd) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP);
+      return 0;
+
+    case "version":
+    case "--version":
+      console.log(`evda tool schema ${SCHEMA_VERSION}`);
+      return 0;
+
+    case "init": {
+      const mod = await import("../create-evda.mjs");
+      return mod.main(args);
+    }
+
+    case "where": {
+      const found = locate({});
+      console.log(`${found.dir}  (via ${found.via})`);
+      return 0;
+    }
+
+    case "use": {
+      const dir = args.find((a) => !a.startsWith("--"));
+      if (!dir) throw new EvdaError("use needs a directory", { exit: 2 });
+      const p = setPointer(dir);
+      console.log(`${p} -> ${resolve(dir)}`);
+      return 0;
+    }
+
+    case "doctor": {
+      const { dir, via } = pickDir(args);
+      return doctor(dir, { via }).exit;
+    }
+
+    case "reindex": {
+      const { dir, flags } = pickDir(args);
+      if (flags.includes("--adopt")) {
+        const manifest = readManifest(dir);
+        if (readVersion(dir) !== null) throw new EvdaError("REFUSED: .evda/version already exists; --adopt is only for a record that lost it.", { exit: 2 });
+        if (manifest.evda > SCHEMA_VERSION) throw new EvdaError(`REFUSED: evda.json declares ${manifest.evda}, newer than this tool (${SCHEMA_VERSION}); cannot vouch for a layout it does not know.`, { exit: 2 });
+        const evda = { dir, manifest, version: null };
+        const missing = resolveAll(evda).filter((r) => r.mapped && r.known && (!r.exists || (r.file && !r.fileExists)));
+        if (missing.length) throw new EvdaError(`REFUSED to adopt: mapped role(s) missing on disk: ${missing.map((r) => `${r.role} -> ${r.rel}`).join("; ")}`, { exit: 2 });
+        writeVersion(dir, manifest.evda);
+        console.log(`adopted: wrote .evda/version = ${manifest.evda} after every mapped role resolved`);
+      }
+      const evda = openEvda(dir);
+      const r = reindex(evda);
+      console.log(`reindex: ${r.ledger ? `${r.rows} row(s) in .evda/due.jsonl` : "no ledger role, .evda/due.jsonl is empty"}; digest ${r.digest ? "rebuilt" : "not written (AGENTS.md has no generated fence)"}`);
+      return 0;
+    }
+
+    case "due": {
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const expected = expectedIndex(evda);
+      if (!expected) { console.log("no ledger role in this record"); return 0; }
+      const actual = currentIndex(evda);
+      if (actual !== null && actual !== expected.text) console.error("note: .evda/due.jsonl is stale; showing the derived view. Run `evda reindex`.");
+      if (!expected.text) { console.log("nothing is due"); return 0; }
+      for (const line of expected.text.trimEnd().split("\n")) {
+        const r = JSON.parse(line);
+        console.log(`${r.due}  ${r.id}  [${r.status}]  ${r.hypothesis}`);
+      }
+      return 0;
+    }
+
+    case "chain": {
+      const { dir, rest } = pickDir(args);
+      const id = rest.find((a) => /^H-\d{4}$/.test(a));
+      if (!id) throw new EvdaError("chain needs an id like H-0004");
+      const evda = openEvda(dir);
+      const ledger = readLedger(evda);
+      if (!ledger) throw new EvdaError("no ledger role in this record");
+      const c = chain(ledger.parsed, id);
+      if (!c) throw new EvdaError(`${id} is not in ${ledger.rel}`);
+      for (const e of c) console.log(`${e.id === id ? ">" : " "} ${e.id}  [${e.statusWord}]  ${e.title}`);
+      return 0;
+    }
+
+    case "current": {
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const ledger = readLedger(evda);
+      if (!ledger) throw new EvdaError("no ledger role in this record");
+      const cur = current(ledger.parsed);
+      if (!cur.length) console.log("no current hypotheses");
+      for (const e of cur) console.log(`${e.id}  [${e.status}]  ${e.title}`);
+      return 0;
+    }
+
+    case "moment": {
+      const { dir, rest } = pickDir(args);
+      const [from, to] = rest;
+      const evda = openEvda(dir);
+      console.log(JSON.stringify(moment(evda, { from, to: to ?? from }), null, 2));
+      return 0;
+    }
+
+    case "upgrade": {
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const a = agentsFile(evda);
+      if (!a) throw new EvdaError('no "agents" role in the mapping, so there is no operating layer to upgrade.');
+      const text = readFileSync(a.abs, "utf8");
+      const parts = splitFence(text);
+      if (!parts) throw new EvdaError(`${a.rel} has no evda:generated fence. The owner has taken the whole file; there is nothing the installer owns to replace, and nothing was changed.`);
+      const shipped = shippedGenerated();
+      if (parts.generated === shipped) { console.log("upgrade: the generated block already matches what this tool ships. Nothing outside it was read."); return 0; }
+      writeFileSync(a.abs, replaceFence(text, shipped));
+      reindex(evda);
+      console.log(`upgrade: replaced the generated block of ${a.rel} (${Buffer.byteLength(parts.generated)} -> ${Buffer.byteLength(shipped)} bytes). Everything outside the fence is untouched. Digest rebuilt.`);
+      return 0;
+    }
+
+    case "digest": {
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const d = expectedDigest(evda);
+      if (d === null) throw new EvdaError("the operating layer is unmapped, missing, or has no evda:generated fence, so there is nothing to digest.");
+      process.stdout.write(d);
+      return 0;
+    }
+
+    case "vector": {
+      // The conformance projection of one ledger file, for another implementation to diff against.
+      //   evda vector <dir-with-ledger.md>          print the projection as JSON
+      //   evda vector <dir> --check                 compare to <dir>/expected.json, exit 1 on drift
+      const { vectorMain } = await import("../lib/vectorcli.mjs");
+      return vectorMain(args);
+    }
+
+    case "references": {
+      // Every reference in every record file, with the folder that governs it. With --resolve,
+      // each is asked of its source through the registry; a url is fetched, the rest say SKIPPED
+      // and why. Exit 1 when any reference is malformed, carries a secret, or has no connector.
+      //
+      // FALSIFIED 2026-09-16 on a scratch record whose record/people/sam.md carried two references,
+      // one with `password: hunter2` and one through a connector the folder did not declare ->
+      //   "FAIL  REFUSED: record/people/sam.md: references[0] carries a field named "password". ..."
+      //   "FAIL  record/people/sam.md  contacts:2F1A-77  Sam Rivera (unresolved, never resolved)
+      //    (record/people/folder.evda.json does not declare contacts)"
+      //   "CHECKED 2 references", exit 1. The secret's value was not printed.
+      const { dir, flags } = pickDir(args);
+      const evda = openEvda(dir);
+      const doResolve = flags.includes("--resolve");
+      const t = flags.find((f) => f.startsWith("--timeout="));
+      const timeoutMs = t ? Number(t.slice("--timeout=".length)) : 5000;
+      const folders = folderManifests(evda);
+      let n = 0;
+      let bad = 0;
+      for (const r of resolveAll(evda).filter((x) => x.known && x.mapped && x.layer === "record" && x.exists && x.isDir)) {
+        for (const p of mdFiles(r.abs)) {
+          const rel = relative(dir, p);
+          const found = referencesIn(readFileSync(p, "utf8"), rel);
+          for (const pr of found.problems) { bad += 1; n += 1; console.log(`FAIL  ${pr.message}`); }
+          const folder = folderFor(p, folders);
+          for (const ref of found.references) {
+            n += 1;
+            let result = null;
+            let gate = null;
+            if (!folder) { bad += 1; gate = `no ${FOLDER_MANIFEST} above it`; }
+            else if (!folder.connectors.includes(ref.scheme)) { bad += 1; gate = `${folder.rel} does not declare ${ref.scheme}`; }
+            if (doResolve) result = await resolveReference(ref, { connectors: folder ? folder.connectors : [], timeoutMs });
+            const shown = renderReference(ref, result);
+            console.log(`${gate ? "FAIL " : "     "} ${rel}  ${ref.ref}  ${shown}${gate ? `  (${gate})` : ""}${result?.status === "resolved" ? `  resolved ${result.at}` : ""}`);
+          }
+        }
+      }
+      if (n === 0) console.log("SKIPPED references: no record file carries a references list");
+      else console.log(`CHECKED ${n} references${doResolve ? ", each asked of its source" : ""}`);
+      return bad ? 1 : 0;
+    }
+
+    case "folder": {
+      // evda folder <dir> --type T [--connectors a,b] [--force]
+      // Views are declared by editing the manifest: a declaration is an object with a path, not a
+      // name, so it has no comma-list flag. The scaffold writes `views: []`.
+      const positional = args.filter((a) => !a.startsWith("--"));
+      const target = positional[0];
+      if (!target) throw new EvdaError("folder needs a directory inside the record", { exit: 2 });
+      const opt = (name) => { const f = args.find((a) => a.startsWith(`--${name}=`)); return f ? f.slice(name.length + 3) : (args.includes(`--${name}`) ? args[args.indexOf(`--${name}`) + 1] : undefined); };
+      const type = opt("type");
+      if (!type) throw new EvdaError("folder needs --type", { exit: 2 });
+      const list = (v) => (v ? v.split(",").map((s) => s.trim()).filter(Boolean) : []);
+      const root = findRoot(resolve(target));
+      if (!root) throw new EvdaError(`REFUSED: no evda.json above ${resolve(target)}; the folder is not inside a record.`, { code: "NO_MANIFEST", exit: 2 });
+      const evda = openEvda(root);
+      const p = writeFolderManifest(evda, resolve(target), { type, connectors: list(opt("connectors")) }, { overwrite: args.includes("--force") });
+      console.log(`wrote ${relative(evda.dir, p)}`);
+      return 0;
+    }
+
+    case "grant": {
+      const { dir, rest } = pickDir(args);
+      const circle = rest[0];
+      if (!circle) throw new EvdaError("grant needs a circle name", { exit: 2 });
+      const to = flagValue(args, "to");
+      const kind = flagValue(args, "kind");
+      if (!to || !kind) throw new EvdaError(`grant needs --to <record-id> and --kind ${HOLDER_KINDS.join("|")}`, { exit: 2 });
+      const evda = openEvda(dir);
+      const p = grant(evda, { circle, to: { id: to, kind, name: flagValue(args, "name") }, role: flagValue(args, "role") ?? "viewer", by: flagValue(args, "by") }, { overwrite: args.includes("--force") });
+      console.log(`granted ${flagValue(args, "role") ?? "viewer"} on ${circle} to ${kind} ${to}: ${relative(evda.dir, p)}`);
+      return 0;
+    }
+
+    case "grants": {
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const gs = readGrants(evda);
+      if (gs === null) { console.log("SKIPPED grants: no grants role in this record"); return 0; }
+      let bad = 0;
+      for (const g of gs) {
+        for (const p of g.problems) { if (p.level === "fail") bad += 1; console.log(`${p.level === "fail" ? "FAIL " : "WARN "} ${p.message}`); }
+        if (g.principalId) console.log(`      ${g.principalId}  ${g.role ?? "?"} on ${g.circle ?? "?"}  ${g.holder ? `${g.holder.kind}${g.holder.name ? ` ${g.holder.name}` : ""}` : "holder unknown"}  ${g.rel}`);
+      }
+      if (gs.length === 0) console.log("SKIPPED grants: no grant files");
+      else console.log(`CHECKED ${gs.length} grants`);
+      return bad ? 1 : 0;
+    }
+
+    case "revoke": {
+      const { dir, rest } = pickDir(args);
+      const circle = rest[0];
+      const to = flagValue(args, "to");
+      if (!circle || !to) throw new EvdaError("revoke needs a circle name and --to <record-id>", { exit: 2 });
+      const evda = openEvda(dir);
+      console.log(revoke(evda, { circle, id: to }) ? `revoked ${to} on ${circle}` : `nothing to revoke: ${to} had no grant on ${circle}`);
+      return 0;
+    }
+
+    case "access": {
+      const { dir, rest } = pickDir(args);
+      const circle = rest[0];
+      const as = flagValue(args, "as");
+      if (!circle) throw new EvdaError("access needs a circle name", { exit: 2 });
+      const evda = openEvda(dir);
+      const a = access(evda, circle, as ?? null);
+      console.log(`${a.allowed ? "ALLOWED" : "REFUSED"}  ${as ?? "(nobody named)"} on ${circle}: ${a.why}`);
+      return a.allowed ? 0 : 2;
+    }
+
+    case "migrate": {
+      const { dir } = pickDir(args);
+      const r = await migrate(dir, { out: console.log });
+      console.log(r.ran.length ? `migrated ${r.from} -> ${r.to}` : `nothing to do: on disk ${r.from}, tool ${SCHEMA_VERSION}`);
+      return 0;
+    }
+
+    case "status": {
+      const { dir, via } = pickDir(args);
+      const evda = openEvda(dir);
+      const m = evda.manifest;
+      const h = holderOf(evda);
+      console.log(`${m.name ?? "(unnamed)"}  schema ${m.evda}  held by a ${h.kind}${h.id ? ` (${h.id})` : ""}  layers [${m.layers.join(", ")}]  ${evda.dir}  (via ${via})`);
+      for (const r of resolveAll(evda)) {
+        if (!r.known) { console.log(`  ${r.role.padEnd(16)} -> ${r.rel}  (unknown role, preserved)`); continue; }
+        if (!r.mapped) { console.log(`  ${r.role.padEnd(16)} absent`); continue; }
+        console.log(`  ${r.role.padEnd(16)} -> ${r.rel}  ${r.exists ? "" : "MISSING"}`);
+      }
+      const ledger = readLedger(evda);
+      if (ledger) {
+        const es = ledger.parsed.entries;
+        const last = es[es.length - 1];
+        console.log(`  ledger: ${es.length} entries, ${current(ledger.parsed).length} current, last ${last ? last.id : "none"}`);
+      }
+      const expected = expectedIndex(evda);
+      if (expected && expected.text) console.log(`  due: ${expected.text.trimEnd().split("\n").length} row(s); \`evda due\` lists them`);
+      console.log(`  pointer: ${pointerPath()}`);
+      return 0;
+    }
+
+    default:
+      console.error(`unknown command: ${cmd}\n`);
+      console.log(HELP);
+      return 2;
+  }
+}
+
+// Through realpath: an installed bin is a symlink and resolve() does not follow it (see the same
+// guard in create-evda.mjs, and test/bins.test.mjs).
+if (process.argv[1] && isEntry(process.argv[1], import.meta.url)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (e) => {
+      console.error(e instanceof EvdaError ? e.message : e.stack ?? String(e));
+      process.exit(e instanceof EvdaError ? e.exit : 1);
+    }
+  );
+}
+
+export { main };