create-evda 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -4,15 +4,123 @@ Plain-English notes on how Iris behaves differently after each version. Not a co
 
 ## Unreleased
 
+When a filing names pages your EVÐA already has (a person, a project, a topic) or open tickets on your
+board, and the conversation adds to none of them, Iris is now asked once, naming them, whether what you said adds to one; adding
+nothing is a fine answer. In Claude Code the record's Stop hook asks before the session stops, and in
+the chat apps the next tool result asks. A record with the Stop hook installed shows it as older in
+`evda doctor` until `evda hook install` refreshes it.
+
+Claude Cowork can reach your EVÐA now. Cowork does not start the servers in the desktop app's
+config and does not read your folder's hooks, so `evda plugin` builds a plugin for your record (its
+evda tools, the hooks that keep it, and a skill that has Iris read the operating layer first), and
+you upload the zip in Customize, then Plugins, then Upload plugin. `create-evda` and `evda connect`
+print the command. The plugin's hooks act only in Cowork, so the same plugin syncing into Claude Code
+files nothing twice.
+
+`evda secret migrate` moves the passwords in Credentials/ files sealed before they went to the
+Keychain: each value goes into the Keychain, and the file keeps a pointer in its place, the same as a
+new gather does. A file whose Keychain write fails stays exactly as it was, an item already in the
+Keychain is never overwritten, and running it again changes nothing. `--dry` says what it would move.
+Two lines with the same label in one file (two "Password:" lines) now get separate Keychain items,
+where before the second overwrote the first.
+
+The EVÐA app's setup now asks how to organize your EVÐA right after what you want it for, offering
+the same presets as `create-evda`, or starting plain. `evda preset list --json` prints the list it
+reads.
+
+`create-evda --help`, `create-evda -h`, `evda init --help` and `evda mcp --help` now print how to use
+them and stop. Before, `create-evda -h` made a folder named `-h` and `evda mcp --help` started serving
+your record. On a Mac, `create-evda` now says it is installing the daily morning organize as a
+launchd job before it does, with `--yes` too, and names `--no-routines` to skip it. Gathering a pile
+now skips what apps leave behind (Office lock files, empty files, a Recently Deleted folder, Google
+Takeout's `archive_browser.html`) and lists each one, with why, in the proposal.
+
+`evda publish public` now leaves a markdown file's `sources:` frontmatter out of what it exports. That
+field lists the private files a public page was written from, so it never belonged in public, and it
+was making the publish refuse every run once a page carried one. A private path in a page's body
+still refuses the publish exactly as before.
+
+When Iris files something, it is now told which pages you already have that the words name (a person,
+a topic, a project) and which shared circles that reaches, such as a public entry derived from the
+folder it just wrote to. It is information for Iris to judge, so it still decides what to write, and
+nothing noted, sealed, or set for a different AI is ever named.
+
+When your work lives on a board (`"work": "harlequin:"`), filing also names the open tickets the
+words reference, by `HQ-` number or by a distinctive run of a ticket's title, at most five, so a
+conversation about a ticket's subject points Iris at the ticket. A done or obsolete ticket is never
+named. The board is read in the background with the same credentials as `evda work` (or the env file
+`EVDA_WORK_ENV_FILE` names), so a slow or unreachable board never slows a filing.
+
+A people folder now keeps one file per person, and `evda doctor` says so when it does not: a folder
+inside it, a name with a parenthetical when nobody else shares the name, and a stub that only
+points at another page each fail, and so does a page with no person-profile frontmatter, which
+doctor cannot read. Gathering a pile writes every page it puts in a people folder as a profile, and
+migrating people now types a page with no dated section (its one observation is the day it was
+typed) and a page that already has frontmatter, keeping what that frontmatter says. Applying a preset that makes a people folder also makes `Processing/` beside it
+for the docs where you work something through, and a README in the folder saying the rule.
+
+In the Claude app, Iris starts a chat knowing what your last days were about, not only when you
+wrote: each recent entry comes with its one line of context and the opening of your words, and the
+people whose pages gained a dated section this week are listed with those sections. Searching your
+record shows the most recent matches first. Iris answers you in the reply itself and says what it
+filed in one line after, instead of writing its answer into a page. And the Claude app now reads
+your whole instructions file at the start of a chat, up to about 100,000 characters, where it used
+to get some sections as a heading to fetch. Noted and sealed entries still never appear.
+
+In a chat app, Iris now writes where it writes from a terminal. A correction you give it lands in
+the file you keep corrections in, when `evda.json` names it as `"corrections"`, as a dated section
+in your words; before, a record without a "What I have been taught" heading lost every one. Iris can
+add a row to a log kept as a table (a food log, a spike log, a weekends board) with
+`evda_append_row`, and put a new section inside the part of a file it belongs in with
+`evda_append`'s `under`, so a queued idea no longer lands under "Completed". When Iris offers to
+start a page, a person's page or a folder and you say yes, `evda_create` makes it, and never where
+something already is.
+
+When two of your machines share one record through iCloud, one of them can be the only one that
+writes the daily note. Set EVDA_DAY_WRITER on every other machine and add hooks/evda-day-writer-guard.mjs
+to that machine's own Claude Code settings: an agent there that tries to write the note directly is
+stopped and told to file through evda_write on the writing machine, because two machines writing the
+same note within seconds lose one of the writes with no conflict copy.
+
+The first time you talk to your EVÐA from a chat app (Claude, ChatGPT, or any other), Iris gives
+you one line to add to that app's every-chat instructions, and says where that setting is. With it
+there, every chat starts as Iris, even one that never opens your record. Tell Iris it is set, or
+that you don't want it, and that app never asks again; a second app asks once for itself. If you
+file only when you ask, the line loads Iris and asks for nothing more. `create-evda` and `evda
+connect` print the same line.
+
+The EVÐA app is one sidebar and the page you are reading. Today's Journal is first, there even
+before you have written today, and what you type at the end of it is added to today's note,
+verbatim, the way your AI's evda_write does. Below it, Journal, Captures, People and your project,
+area and knowledge folders are pinned from your mapping, then Instructions (CLAUDE.md, AGENTS.md,
+evda.json and any file the agents block is written into), then every folder of the record. Devices,
+Connect your AI and Switch EVÐA sit quietly at the foot. A file's circle shows only when it is not
+your record's usual one, and markdown reads formatted. Entries you noted or sealed, and parts you
+set so no AI reads, stay closed. Tooling (dot-files, lockfiles, scripts, licenses, backups, empty
+files) is left out, with one line per folder counting it. The window drags by its top edge. Large
+files open whole: `evda browse` and `evda capture` wait for their answer to reach the app before
+exiting, where before a file past 64 KB arrived cut off.
+
 Your phone can join your EVÐA. `evda pair` on the computer your record is on shows a one-time code
 and a QR link; it works once, for 10 minutes, and the phone gets only the parts you name (the
 journal by default). `evda sync` adds the phone once it has used the code, takes in what it wrote,
 and sends what changed; a note written on the phone lands under the day, in your words. `evda
 devices` lists what is paired and `evda remove <device>` removes one: it adds nothing more and
-receives nothing new. You can also ask your AI to pair a phone (`evda_pair_device`). Pairing goes
+receives nothing new. You can also ask your AI to do all of it (`evda_pair`, `evda_devices`, `evda_sync_status`,
+`evda_remove_device`): it shows a QR code to scan, adds the phone on its own once it scans, says
+when each device was last heard from and what is still on its way to it, and removes a device only
+after you say yes to what removing does. A phone paired this way pairs to the computer the AI's
+EVÐA server runs on, and the answer names that computer. A second computer of yours (Hestia) speaks
+as its own device and never as the laptop: until a grant makes it owner of a part it refuses to
+pair, and once it owns one it pairs a phone to itself. Pairing goes
 through a relay that cannot read what it carries, and needs Node 22.13 or newer; everything else
 still runs on Node 20.
 
+One sync of a record runs at a time. The Mac app syncing on its own, a launchd job and `evda sync`
+at a terminal wait for each other; if a sync is still running after twenty seconds, the second says
+"A sync of this EVÐA is already running. Try again in a moment." and changes nothing. A sync that
+crashed leaves nothing in the way: the next one sees the process is gone and goes ahead.
+
 Organizing is on from the start. Setup installs the morning organize on a Mac (a launchd job that
 runs your own Claude each morning at 8:00, or when the computer wakes), says so in one line, and
 offers off: answer no during setup, pass `--no-routines`, or later run `evda routine morning

package/README.md

@@ -76,6 +76,7 @@ apply places only what is new, in the record's own folders.
     evda_operating_layer   AGENTS.md, read first every session
     evda_recent            the last few days of the record
     evda_write             your words, verbatim, appended to today's daily file, with one line of context labeled as not yours. It takes no path and never edits
+    evda_record_correction one dated line appended to AGENTS.md's "What I have been taught", outside the installer's block. Never edits an earlier entry
     evda_import            what another AI said about you, filed under record/imports with its source and date
     evda_search            plain text search inside the record, on this machine
     evda_circles           your circles and their policies
@@ -91,9 +92,12 @@ apply places only what is new, in the record's own folders.
     evda_write_skill       writes or revises a skill at .claude/skills/<name>/SKILL.md. Never outside that folder, never a rule about your life
     evda_create_subrecord  an EVÐA inside this one, with the four roles and its own AGENTS.md, then doctor. Your evda.json changes only on bounded with confirmed: true
     evda_doctor            evda doctor, as a report
-    evda_pair_device       a one-time code and QR link for your phone, and what to do on it; the phone gets only the parts named
+    evda_pair              a one-time code and a QR code to scan for your phone, paired to the computer this server runs on; the phone gets only the parts named, and is added on its own once it uses the code
+    evda_finish_pairing    waits, at most two minutes, for the phone to use its code, and says when it is in
     evda_sync_devices      adds a phone that used its code, takes in what your devices wrote, sends what changed
-    evda_devices           the devices paired with your EVÐA and what each reads
+    evda_devices           the devices paired with your EVÐA on this computer, what each reads, and when it was last heard from
+    evda_sync_status       per device what is waiting, sent and confirmed, and whether a sync is running. Reads only
+    evda_remove_device     removes a device; without confirm: true it only says what removing would do, for your yes
     evda_check_update      whether newer EVDA tooling exists
 
 Every write appends, refuses anything shaped like a password, key or token, and says the path it wrote. Two kinds of call leave this machine. `evda_check_update` asks the npm registry for a version number; it carries nothing from the record and installs nothing, and the update itself is a command you run in a terminal. The device tools talk to the relay that carries your EVÐA between your own devices, and everything they send is sealed here first: the relay cannot read it. `evda connect` prints the setup for your record, with its path filled in:
@@ -103,11 +107,18 @@ claude mcp add --scope user evda -- /path/to/node /path/to/evda.mjs mcp ~/my-evd
 codex mcp add evda -- /path/to/node /path/to/evda.mjs mcp ~/my-evda                 # Codex
 ```
 
-For the Claude desktop app, add the same command under `mcpServers` in `claude_desktop_config.json` (Settings, then Developer, then Edit Config) and restart the app. `create-evda` prints all three at the end of setup.
+**One layer, sized per app.** `evda_operating_layer` serves the core and AGENTS.md to every app, but a section that only makes sense with a shell (scripts to run, hosts to ssh to, local MCP servers) is noise in a chat app. Put `<!-- evda:surface terminal -->` on the line right after a `## ` heading and that section, with its subsections, goes only to coding agents (Claude Code, Codex). Every other app, including one the server has never heard of, gets the rest, in as few parts as its tool result limit allows, and is told which sections were left out. A record with no marker reads the same everywhere. The server knows the app by `initialize`'s `clientInfo` name, and the remote server logs that name and version, nothing else of it.
+
+**Each surface reaches a record its own way.** `create-evda` and `evda connect` print every one of these with your record's path filled in.
+
+- **Claude Code** (terminal, IDE, the desktop app's Code tab): `claude mcp add` above for every folder, and in sessions opened in the record its own `.claude/settings.json` hooks and `.claude/skills/` load on their own.
+- **The Claude desktop app's chat**: add the same command under `mcpServers` in `claude_desktop_config.json` (Settings, then Developer, then Edit Config) and restart the app. That file reaches only the chat: Cowork does not start its servers.
+- **Claude Cowork**: `evda plugin <dir>` builds a plugin for this one record, a folder and a zip under `.evda/plugin/` (or `--out <zip>`), and the upload is the one step left to you: in the Claude app, Customize, then Plugins, then Add, then Upload plugin, and choose the zip. Cowork reads no folder's `CLAUDE.md`, `AGENTS.md` or hooks, so the plugin carries all three ways in: the record's MCP server (`evda mcp <dir>`, the path baked in, because Cowork does not ask for plugin settings), a skill that loads the operating layer before the first reply, and hooks that run the record's own keep-record hook, prompt-filing hook (with "everything") and read guard, the files `evda hook install` keeps current. It works in Cowork tasks that run on your computer. The plugin also loads in Claude Code sessions signed in to the same account; its hooks stay quiet there (they act only when Claude Code runs a Cowork task), and `claude plugin disable <name>@synced` takes it out of Claude Code. Move the folder and you build and upload it again.
+- **claude.ai** (web and phone): no local server reaches it. `evda mcp --http` serves the record over HTTPS behind OAuth, through a tunnel, as a connector you add in Settings, then Connectors.
 
 **The skill.** `skills/evda/SKILL.md` (Agent Skills format) tells Claude Code to act as Iris through the tools: load the operating layer first, file verbatim, never quiz, circles only on your yes. `evda skill install` copies it to `~/.claude/skills/evda/`; setup offers it.
 
-**The record keeps itself.** You never have to say "save this". In Claude Code, setup (when you pick Claude) installs a Stop hook in the record's own `.claude/settings.json`: a session that read the record or heard you out and filed nothing to the day's record is asked once, before it stops, to file your words. It runs only in sessions opened in the record; your global settings are not touched. `evda hook install` adds it to a record made earlier, and `evda doctor` says whether it is installed and current. In apps with no hooks (the Claude desktop app, ChatGPT), the MCP server itself adds one line to its tool results once a conversation has read the record and filed nothing, and goes quiet after the first write.
+**The record keeps itself.** You never have to say "save this". In Claude Code, setup (when you pick Claude) installs a Stop hook in the record's own `.claude/settings.json`: a session that read the record or heard you out and filed nothing to the day's record is asked once, before it stops, to file your words. It runs only in sessions opened in the record; your global settings are not touched. `evda hook install` adds it to a record made earlier, and `evda doctor` says whether it is installed and current. In Cowork the plugin from `evda plugin` runs the same hooks. In apps with no hooks (the Claude desktop app's chat, ChatGPT), the MCP server itself adds one line to its tool results once a conversation has read the record and filed nothing, and goes quiet after the first write. A second check rides on both: a write's answer names the existing entries its words bear on, and a conversation that was named some and added to none of them is asked once, naming them (and any open board tickets it named), with adding nothing as a fine answer. It goes quiet after a write to one of them or once asked. The Stop hook reads those names back out of the Claude Code transcript and the MCP server keeps them per chat, so nothing about it is stored in your files.
 
 **Filing is the owner's answer.** Setup asks once whether to file everything they say automatically (the default) or only when they ask, and writes it to `evda.json` as `"filing": "everything"` or `"asked"`; a record with no answer is asked at first connect, and `evda_filing` records the reply. `evda_write`'s description leads with when to call it, because a deferred tool in the Claude app shows only that first line. One conversation is one `## HH:MM` section of the day. With "everything", Claude Code also gets a UserPromptSubmit hook, `.claude/hooks/evda-file-prompt.mjs`, that files each message verbatim as it is sent. `evda gather scan <conversations.json> --into <record>` reads a Claude.ai or ChatGPT export and, on apply, adds the owner's own messages the record lacks under each conversation's date and time.
 
@@ -121,7 +132,7 @@ For the Claude desktop app, add the same command under `mcpServers` in `claude_d
 
 How a record is organized comes from a library, so an agent proposes a folder that already exists in it instead of inventing one. Each preset is `presets/<id>/preset.json`: an `id`, a `title`, `for` (who it suits), `folders` (each a path, and for a typed folder its `type`, `connectors` and `views`, validated by the same code as `folder.evda.json`), optional `circles` (proposed as proposal files, never created), optional `routines` (offered, never scheduled), and `mapping`, the folders that fill the four roles. Every folder a preset makes fills a role, and a preset that has one filling none fails its test. Two ship: `projects-and-areas` (numbered folders for projects, areas with courses under Academics, resources, work, captures, the daily journal and attachments) and `journal`. A course is a collection, so there is no student preset, and there is no archive folder: finished is a status. Setup offers them after purpose, with "none, start plain". Applying one adds the role paths the record lacks to `evda.json`; a role key the record already uses keeps its path, and the preset's folder fills the same role under a facet key named for it.
 
-    evda preset list
+    evda preset list [--json]        --json: one line, [{id, title, for}], what the EVÐA app's setup offers
     evda preset show <id>
     evda preset apply <id> [--dry] [dir]
     evda preset diff <id> [dir]      what the preset has that this record does not
@@ -163,11 +174,11 @@ Writes:
                              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 4096 bytes
+      .evda/digest.md        derived from the fenced block of AGENTS.md, under 6144 bytes
 
 The training instructions in the scaffolded README and in setup come from one table, `lib/setup.mjs`, with a link to each provider's page.
 
-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 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. `evda adopt <dir>` writes that mapping: an Iris Vault (`00_Inbox` through `06_Metadata`) maps without a question, any other folder is placed by its name or named back to the owner to answer with `--map <folder>=<role>`, and it adds `AGENTS.md`, `.evda/`, the Claude Code hooks and one `@AGENTS.md` line at the end of the owner's `CLAUDE.md`. Every other file stays byte for byte, and `evda adopt --revert <manifest>` puts the folder back exactly as it was. A chat app runs it through `evda_adopt`, which writes nothing without `confirmed: true`.
 
 ### Four roles, and records inside records
 
@@ -208,6 +219,8 @@ An `evda.json` anywhere below the root starts a sub-record, with no depth limit.
     evda use <dir>                 point ~/.evda/current at a record
     evda mcp [dir]                 serve the record over MCP on stdio for Claude Code, Codex or the Claude app
     evda connect [dir]             the MCP setup for each client, with this record's path
+    evda plugin [dir] [--out <zip>]
+                                   a Claude plugin for this record, for Cowork: its server, hooks and skill
     evda skill install [--project <dir>]
                                    install the evda skill for Claude Code
     evda hook install [dir]        the keep-record Stop hook and the read guard, in the record's .claude/settings.json,