clavarium-binder 0.0.1 → 0.1.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Clavarium Docket authors
+
+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

@@ -1 +1,48 @@
-# Clavarium Binder (name reserved)
+# Clavarium Binder
+
+Lists of records, kept together by people and AI agents, each with its id.
+
+A binder holds lists: batches of work, development tasks, customers, people,
+a roadmap, anything followed over time. A list starts from a template (its
+states, its fields, the view it opens in) and everything is changed afterwards.
+A record has a title, a state, its fields, short notes, as many things attached
+as wanted (messages of a chat, files, assets, branches, links, other records),
+owners, a due date, and its history.
+
+    binder                         your lists
+    binder show Batches            the records of a list, by state
+    binder add Batches "Dark mode"
+    binder note 12 "the login page only"
+    binder attach 12 branch site:dark-mode
+    binder move 12 Doing           past a gate, only once a person approved it
+
+An MCP server gives the same verbs to an AI agent. A person sees the binder on
+its screen (`ui/`), drawn by Binder in the page of the application that runs it.
+
+A sibling of [Clavarium Parley](https://github.com/clavarium/clavarium-parley) and
+[Clavarium Docket](https://github.com/clavarium/clavarium-docket), built the same
+way, universal (nothing in it is specific to Clavarium).
+
+## What an agent cannot do
+
+- **Rewrite the binder.** It is held by its keeper (the application, or
+  `binder serve`), out of the agent's reach. An agent asks through its own
+  folder; the keeper answers, and says who asked by that folder.
+- **Approve.** A list may have a gate (Batches: "Approved"): a record reaches
+  it, or any state after it, only once a person ticked it. An agent proposes,
+  and works on what was approved.
+- **See what it was not given.** Access is given per list: read, or change.
+- **Delete.** It archives; a person deletes, and deleted is deleted.
+
+## Without an application
+
+    binder serve --store ~/binder-data --side ./.binder=Assistant --lang fr
+
+keeps a binder and shows its page on `http://127.0.0.1:4180/`. Put the store
+where the agents cannot write.
+
+See [docs/protocol.md](docs/protocol.md). No dependency; Node 22 or later.
+
+**Status:** first version (0.1), not yet published.
+
+License: MIT.

package/bin/binder.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/* THE COMMAND: Binder's verbs for any agent or script that can run a command.
+ * It asks through the same folder as the MCP server (server/binder.mjs), and
+ * prints the keeper's answer. `binder serve` IS a keeper: the binder and its
+ * page, for use without an application.
+ */
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { ask, findFolder, FOLDER, VERSION } from '../server/binder.mjs';
+
+export const HELP = `binder: the lists you were given, and their records.
+
+  binder                               your lists
+  binder show LIST [--state S] [--mine] [--archived]
+                                       the records of a list, by state
+  binder get ID                        one record: fields, notes, what is attached, its history
+  binder search "text"                 in every list you can see
+  binder add LIST "title" [--state S] [--due DATE] [--owner me] [--note "text"] [--field name=value]
+  binder edit ID [--title "t"] [--due DATE|none] [--owner me|ID|none] [--field name=value]
+  binder move ID STATE                 past a gate, only what a person approved
+  binder note ID "text"                a short note: a decision, a fact, a result
+  binder attach ID KIND REF ["title"]  KIND: message, file, asset, branch, link, record
+  binder detach ID WHAT
+  binder archive ID | binder restore ID
+  binder serve [--store DIR] [--port N] [--side FOLDER=NAME]
+                                       keep a binder yourself, with its page (no application)
+
+ID: a record's number, 12 or #12. DATE: 2026-11-04, or "2026-11-04 09:00".
+You never approve: a person ticks what may go on. Talking with them stays in the chat.
+The folder used is --dir FOLDER, else $BINDER_DIR, else the nearest ${FOLDER} folder from here up.
+binder ${VERSION}`;
+
+const VERBS = ['lists', 'show', 'get', 'search', 'add', 'edit', 'move', 'note', 'attach', 'detach', 'archive', 'restore'];
+
+/* A command line, read: [op, args] or a refusal. */
+export function read(argv) {
+    const args = [...argv];
+    const flags = {}; const fields = {}; const words = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--mine' || a === '--archived') { flags[a.slice(2)] = true; continue; }
+        if (a === '--field') { const v = args[++i] ?? ''; const at = v.indexOf('='); if (at < 1) return { refused: '--field takes name=value' }; fields[v.slice(0, at)] = v.slice(at + 1); continue; }
+        if (a.startsWith('--')) { if (args[i + 1] === undefined) return { refused: `${a} needs a value` }; flags[a.slice(2)] = args[++i]; continue; }
+        words.push(a);
+    }
+    const [verb = 'lists', ...rest] = words;
+    if (!VERBS.includes(verb)) return { refused: `Unknown: ${verb}. Run "binder --help".` };
+    const owners = flags.owner === undefined ? undefined : flags.owner === 'none' ? [] : [flags.owner];
+    const due = flags.due === 'none' ? '' : flags.due;
+    const has = Object.keys(fields).length ? { fields } : {};
+    switch (verb) {
+        case 'lists': return ['lists', {}];
+        case 'show': return rest[0] ? ['show', { list: rest[0], state: flags.state, mine: !!flags.mine, archived: !!flags.archived }] : { refused: 'say which list: binder show LIST' };
+        case 'get': return rest[0] ? ['get', { id: rest[0] }] : { refused: 'say which record: binder get ID' };
+        case 'search': return rest.length ? ['search', { text: rest.join(' ') }] : { refused: 'say what to look for' };
+        case 'add': return rest.length >= 2 ? ['add', { list: rest[0], title: rest.slice(1).join(' '), state: flags.state, due, owners, note: flags.note, ...has }] : { refused: 'binder add LIST "title"' };
+        case 'edit': return rest[0] ? ['edit', { id: rest[0], title: flags.title, due, owners, ...has }] : { refused: 'say which record: binder edit ID' };
+        case 'move': return rest.length === 2 ? ['move', { id: rest[0], state: rest[1] }] : { refused: 'binder move ID STATE' };
+        case 'note': return rest.length >= 2 ? ['note', { id: rest[0], text: rest.slice(1).join(' ') }] : { refused: 'binder note ID "text"' };
+        case 'attach': return rest.length >= 3 ? ['attach', { id: rest[0], kind: rest[1], ref: rest[2], title: rest.slice(3).join(' ') }] : { refused: 'binder attach ID KIND REF ["title"]' };
+        case 'detach': return rest.length === 2 ? ['detach', { id: rest[0], what: rest[1] }] : { refused: 'binder detach ID WHAT' };
+        case 'archive': case 'restore': return rest[0] ? ['archive', { id: rest[0], restore: verb === 'restore' }] : { refused: `binder ${verb} ID` };
+        default: return { refused: 'not understood' };
+    }
+}
+
+/* Runs one command line. Resolves with { code, out, err }: nothing is printed here. */
+export async function run(argv, { env = process.env, cwd = process.cwd(), wait } = {}) {
+    const args = [...argv];
+    let dir;
+    const at = args.indexOf('--dir');
+    if (at >= 0) { dir = args[at + 1]; if (!dir) return { code: 64, out: '', err: '--dir needs a folder.\n' }; args.splice(at, 2); }
+    if (['--help', '-h', 'help'].includes(args[0])) return { code: 0, out: `${HELP}\n`, err: '' };
+    if (args[0] === '--version') return { code: 0, out: `${VERSION}\n`, err: '' };
+    const what = read(args);
+    if (what.refused) return { code: 64, out: '', err: `${what.refused}\n` };
+    const folder = findFolder({ dir, env, from: cwd });
+    if (!folder) return { code: 2, out: '', err: `No ${FOLDER} folder here or above. Run it from your work folder, or give --dir FOLDER.\n` };
+    const r = await ask(folder, what[0], what[1], wait ? { wait } : {});
+    if (r.ok) return { code: 0, out: `${r.text}\n`, err: '' };
+    return { code: r.nokeeper ? 3 : 1, out: '', err: `Not done: ${r.text}\n` };
+}
+
+const main = (() => { try { return realpathSync(process.argv[1] ?? '') === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (main) {
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'serve') {
+        const { serveBinder } = await import('../host/binder-serve.mjs');
+        await serveBinder(argv.slice(1));
+    } else {
+        const r = await run(argv);
+        if (r.out) process.stdout.write(r.out);
+        if (r.err) process.stderr.write(r.err);
+        process.exitCode = r.code;
+    }
+}

package/docs/protocol.md

@@ -0,0 +1,61 @@
+# The protocol
+
+Binder is four small things: a command and an MCP server for agents, a keeper
+that holds the binder, and a screen for people.
+
+## The store: the keeper's alone
+
+| File | What it holds |
+|---|---|
+| `state.json` | every list and record as it is now, rewritten whole (by a rename) after each change |
+| `log.jsonl` | every change, one per line: `{at, by, op, list?, record?, change?}` |
+
+`by` is who did it: `{id, kind, name}`, kind `person` or `agent`. A record
+deleted is deleted: its lines in the log are emptied down to who and when, and
+one `delete` line says by whom.
+
+## An agent's folder
+
+| File | Written by | What it holds |
+|---|---|---|
+| `asks.jsonl` | the agent | `{id, at, op, args}`, one per ask |
+| `answers.jsonl` | the keeper | `{ask, at, ok, text}`: the answer to an ask, by its id |
+
+The folder is `--dir`, else `$BINDER_DIR`, else the nearest `.binder` from
+where the command stands. The keeper knows who asks by the folder: the
+application gives each folder its `who`. An ask waits for its answer up to 20
+seconds; an ask older than a minute is answered "too late" and never done.
+Exit codes of the command: 0 done, 1 refused, 2 no folder, 3 nobody keeps the
+binder, 64 not understood.
+
+## The verbs
+
+| Command | MCP tool | Who |
+|---|---|---|
+| `binder` | `lists()` | anyone: the lists given to them |
+| `binder show LIST [--state S] [--mine] [--archived]` | `show` | read |
+| `binder get ID` | `get` | read |
+| `binder search TEXT` | `search` | read |
+| `binder add LIST TITLE [...]` | `add` | change |
+| `binder edit ID [...]` | `edit` | change |
+| `binder move ID STATE` | `move` | change; past a gate, only an approved record |
+| `binder note ID TEXT` | `note` | change |
+| `binder attach ID KIND REF [TITLE]` | `attach` | change |
+| `binder detach ID WHAT` | `detach` | change |
+| `binder archive ID`, `binder restore ID` | `archive` | change |
+
+A person's alone (from the screen): `approve`, `delete`, `create-list`,
+`edit-list`, `grant`, `archive-list`, `delete-list`; a note is changed by
+whoever wrote it (`edit-note`).
+
+## The application's side
+
+    import { keeper } from 'clavarium-binder/host';
+    const k = keeper(storeDir, { sides: () => [{ dir, who }] });
+    setInterval(() => k.pump(), 1000);      // answer the agents
+    k.act(op, args, person);                // a person's change: { ok, text, data }
+    k.due();                                // records whose due time came: tell their owners
+    k.store.onChange((line) => ...);        // every change, as the log says it
+
+And the screen: `mount(element, { call, words, lang, people, picture, openAttached })`
+from `clavarium-binder/ui`, with `ui/binder-ui.css` and `ui/texts/*.json`.

package/host/binder-host.mjs

@@ -0,0 +1,127 @@
+/* THE KEEPER: the side that holds the binder and answers. An application that
+ * runs Binder (or `binder serve`) keeps one store, and reads the asks of each
+ * agent's folder; a person's changes come straight from the application's page.
+ *
+ *   const k = keeper(storeDir, { sides: () => [{ dir, who }] });
+ *   k.pump();                     answer what was asked since (every second or so)
+ *   k.act(op, args, who)          a person's change, from the page: { ok, text, data }
+ *   k.due()                       records whose due time came: tell their owners
+ *   k.store.onChange(fn)          every change, as the log says it
+ *
+ * WHO ASKS IS SAID BY THE FOLDER. The application gives each folder its who
+ * ({ id, kind: "agent", name }); what an ask says of itself is never believed.
+ *
+ * An ask too old is answered "too late", never done: the command that sent it
+ * gave up waiting and said nothing was changed.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { openStore, Refused, oneLine } from '../server/store.mjs';
+import { lines } from '../server/binder.mjs';
+import { TEMPLATES } from '../server/templates.mjs';
+
+export { openStore, Refused, TEMPLATES };
+/* Older than this, an ask is not done: its command stopped waiting (WAIT_MS) a while ago. */
+export const TOO_LATE_MS = 60_000;
+
+const day = (iso) => String(iso ?? '').slice(0, 10);
+const owners = (r) => (r.owners.length ? ` @${r.owners.join(' @')}` : '');
+const due = (r) => (r.due ? ` (due ${r.due})` : '');
+
+/* ---- what an agent reads: plain lines ---- */
+export function say(op, data, list) {
+    switch (op) {
+        case 'lists': return data.length === 0 ? 'You were given no list.'
+            : ['Your lists:', ...data.map((l) => `  ${l.title} [${l.id}]: ${l.count} record${l.count === 1 ? '' : 's'}, ${l.access === 'write' ? 'you may change it' : 'read only'}`),
+                'See one: binder show LIST'].join('\n');
+        case 'show': {
+            const { list: l, records } = data;
+            const out = [`${l.title} [${l.id}]${l.access === 'write' ? '' : ' (read only)'}: ${records.length} record${records.length === 1 ? '' : 's'}`];
+            for (const st of l.states) {
+                const here = records.filter((r) => r.state === st.id);
+                if (!here.length) continue;
+                out.push(`${st.name}${st.gate ? ' (a person approves)' : ''}:`);
+                for (const r of here) out.push(`  #${r.id} ${r.title}${owners(r)}${due(r)}${r.attached.length ? ` [${r.attached.length} attached]` : ''}`);
+            }
+            if (l.states.some((x) => x.gate)) out.push('Past a gate, only what a person approved.');
+            return out.join('\n');
+        }
+        case 'get': {
+            const { record: r, list: l, history } = data;
+            const st = l.states.find((x) => x.id === r.state);
+            const out = [`#${r.id} ${r.title}`, `  list: ${l.title}; state: ${st?.name ?? r.state}${r.approved ? ' (approved)' : ''}${r.archived ? '; archived' : ''}${owners(r) ? `; owners:${owners(r)}` : ''}${due(r)}`];
+            for (const f of l.fields) if (r.fields[f.id] !== undefined) out.push(`  ${f.name}: ${r.fields[f.id]}`);
+            if (r.notes.length) { out.push('Notes:'); for (const n of r.notes) out.push(`  ${day(n.at)} ${n.by.name}: ${n.text.replace(/\n/g, '\n    ')}${n.edited ? ' (edited)' : ''}`); }
+            if (r.attached.length) { out.push('Attached:'); for (const a of r.attached) out.push(`  ${a.kind} ${a.kind === 'record' ? `#${a.ref}` : a.ref}${a.title ? ` "${a.title}"` : ''}`); }
+            out.push(`History: ${history.length} change${history.length === 1 ? '' : 's'}, the last ${history.length ? `${day(history.at(-1).at)} by ${history.at(-1).by.name}` : 'none'}.`);
+            return out.join('\n');
+        }
+        case 'search': return data.length === 0 ? 'Nothing found.' : data.map((r) => `#${r.id} ${r.title} (${list(r.list)})`).join('\n');
+        case 'add': return `Added #${data.id}: ${data.title}.`;
+        case 'edit': return `Changed #${data.id}.`;
+        case 'move': return `#${data.id} is now ${data.stateName}.`;
+        case 'note': return 'Noted.';
+        case 'attach': return 'Attached.';
+        case 'detach': return 'Taken off.';
+        case 'archive': return data.archived ? `Archived #${data.id}.` : `Restored #${data.id}.`;
+        default: return 'Done.';
+    }
+}
+
+export function keeper(dir, { sides = () => [], now = () => Date.now() } = {}) {
+    const store = openStore(dir, { now });
+    const titleOf = (id) => store.lists({ id: 'keeper', kind: 'person' }).find((l) => l.id === id)?.title ?? id;
+    /* ONE ASK, as `who`: { ok, text, data }. An agent's "me" is its own id. */
+    const perform = (op, a = {}, who) => {
+        try {
+            const me = (list) => (Array.isArray(list) ? list.map((x) => (x === 'me' ? who.id : x)) : list);
+            let data;
+            switch (op) {
+                case 'lists': data = store.lists(who); break;
+                case 'show': data = store.list(a.list, who, { state: a.state, mine: a.mine, archived: a.archived, text: a.text }); break;
+                case 'get': data = store.record(a.id, who); break;
+                case 'search': data = store.search(a.text, who); break;
+                case 'add': data = store.add(a.list, { title: a.title, state: a.state, fields: a.fields, owners: me(a.owners), due: a.due, note: a.note }, who); break;
+                case 'edit': data = store.edit(a.id, { title: a.title, fields: a.fields, owners: me(a.owners), due: a.due }, who); break;
+                case 'move': { const r = store.move(a.id, a.state, who); data = { ...r, stateName: store.record(r.id, who).list.states.find((x) => x.id === r.state)?.name }; break; }
+                case 'note': data = store.note(a.id, a.text, who); break;
+                case 'attach': data = store.attach(a.id, { kind: a.kind, ref: a.ref, title: a.title }, who); break;
+                case 'detach': data = store.detach(a.id, a.what, who); break;
+                case 'archive': data = store.archive(a.id, !a.restore, who); break;
+                /* A person's, from the page. */
+                case 'approve': data = store.approve(a.id, a.yes !== false, who); break;
+                case 'delete': data = store.delete(a.id, who); break;
+                case 'edit-note': data = store.editNote(a.id, a.note, a.text, who); break;
+                case 'create-list': data = store.createList({ template: a.template, title: a.title, lang: a.lang }, who); break;
+                case 'edit-list': data = store.editList(a.list, { title: a.title, view: a.view, states: a.states, fields: a.fields }, who); break;
+                case 'grant': data = store.grant(a.list, a.to, a.access ?? null, who); break;
+                case 'archive-list': data = store.archiveList(a.list, a.archived !== false, who); break;
+                case 'delete-list': data = store.deleteList(a.list, who); break;
+                case 'templates': data = Object.fromEntries(Object.entries(TEMPLATES).map(([k, t]) => [k, t.name])); break;
+                default: return { ok: false, text: `there is no ${oneLine(op, 40)}` };
+            }
+            return { ok: true, text: say(op, data, titleOf), data };
+        } catch (error) {
+            if (error instanceof Refused) return { ok: false, text: error.message };
+            throw error;
+        }
+    };
+    /* What each folder asked and was not answered yet. Answered asks are known by the answers file. */
+    const pump = () => {
+        let n = 0;
+        for (const side of sides()) {
+            const answered = new Set(lines(join(side.dir, 'answers.jsonl')).map((a) => a.ask));
+            for (const q of lines(join(side.dir, 'asks.jsonl'))) {
+                if (typeof q.id !== 'string' || answered.has(q.id)) continue;
+                const late = !(now() - Date.parse(q.at) < TOO_LATE_MS);
+                const answer = late ? { ok: false, text: 'too late: this ask waited too long and was not done' }
+                    : perform(oneLine(q.op, 40), q.args && typeof q.args === 'object' ? q.args : {}, side.who);
+                mkdirSync(side.dir, { recursive: true });
+                appendFileSync(join(side.dir, 'answers.jsonl'), `${JSON.stringify({ ask: q.id, at: new Date(now()).toISOString(), ok: answer.ok, text: answer.text })}\n`);
+                answered.add(q.id); n++;
+            }
+        }
+        return n;
+    };
+    return { store, pump, act: perform, due: () => store.due() };
+}

package/host/binder-serve.mjs

@@ -0,0 +1,99 @@
+/* BINDER WITHOUT AN APPLICATION: `binder serve` keeps a binder itself, and
+ * shows its page to the person on this machine.
+ *
+ *   binder serve [--store DIR] [--port N] [--side FOLDER=NAME]... [--lang fr]
+ *
+ * The store is DIR (default: $BINDER_STORE, else ~/.local/share/clavarium-binder):
+ * put it where the agents cannot write -- another user's, or outside what they
+ * are given -- since whoever can write the store can rewrite the binder.
+ * Each --side is an agent's folder (its .binder) and the name it is shown by;
+ * without one, the .binder of the folder it is started from, as "Agent".
+ *
+ * The page listens on 127.0.0.1 only: who reaches it is the person. Nothing here
+ * is meant to face a network; an application that does gives its own door.
+ */
+import { createServer } from 'node:http';
+import { readFileSync, mkdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { keeper } from './binder-host.mjs';
+import { FOLDER } from '../server/binder.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const UI = resolve(HERE, '../ui');
+const PERSON = { id: 'person:you', kind: 'person', name: 'You' };
+const BODY_MAX = 256 * 1024;
+
+const PAGE = (lang) => `<!doctype html><html lang="${lang}"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Binder</title><link rel="stylesheet" href="/ui/binder-ui.css">
+<style>html,body{margin:0;background:#0f1115}@media (prefers-color-scheme:light){html,body{background:#fff}}body{font:15px/1.4 system-ui,sans-serif;padding:16px;max-width:1200px;margin:auto}</style>
+<div id="binder"></div>
+<script type="module">
+import { mount } from '/ui/binder-ui.js';
+const words = await (await fetch('/ui/texts/${lang}.json')).json();
+const people = await (await fetch('/api/people')).json();
+const call = async (op, args) => (await fetch('/api', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ op, args }) })).json();
+const b = mount(document.getElementById('binder'), { call, words, lang: '${lang}', people: () => people });
+new EventSource('/api/changes').onmessage = () => b.refresh();
+</script></html>`;
+
+export function options(argv, { env = process.env, cwd = process.cwd() } = {}) {
+    const o = { store: env.BINDER_STORE || join(homedir(), '.local', 'share', 'clavarium-binder'), port: 4180, sides: [], lang: 'en' };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i]; const v = argv[i + 1];
+        if (a === '--store' && v) { o.store = resolve(cwd, v); i++; }
+        else if (a === '--port' && v) { o.port = Number(v); i++; }
+        else if (a === '--lang' && v) { o.lang = v === 'fr' ? 'fr' : 'en'; i++; }
+        else if (a === '--side' && v) {
+            const at = v.lastIndexOf('='); const dir = resolve(cwd, at > 0 ? v.slice(0, at) : v); const name = at > 0 ? v.slice(at + 1) : 'Agent';
+            o.sides.push({ dir, who: { id: `agent:${name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`, kind: 'agent', name } }); i++;
+        } else throw new Error(`not understood: ${a}`);
+    }
+    if (!o.sides.length) o.sides.push({ dir: join(cwd, FOLDER), who: { id: 'agent:agent', kind: 'agent', name: 'Agent' } });
+    if (!Number.isInteger(o.port) || o.port < 1 || o.port > 65535) throw new Error('--port takes a number');
+    return o;
+}
+
+export function start(o, { quiet = false } = {}) {
+    for (const s of o.sides) mkdirSync(s.dir, { recursive: true });
+    const k = keeper(o.store, { sides: () => o.sides });
+    const watchers = new Set();
+    k.store.onChange(() => { for (const res of watchers) res.write('data: change\n\n'); });
+    const pump = setInterval(() => { try { k.pump(); } catch (error) { if (!quiet) process.stderr.write(`binder: ${error.message}\n`); } }, 500);
+    const files = { '/ui/binder-ui.js': 'text/javascript', '/ui/binder-ui.css': 'text/css', '/ui/texts/en.json': 'application/json', '/ui/texts/fr.json': 'application/json' };
+    const server = createServer((req, res) => {
+        const url = new URL(req.url, 'http://local');
+        const send = (code, type, body) => { res.writeHead(code, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' }); res.end(body); };
+        if (req.method === 'GET' && url.pathname === '/') return send(200, 'text/html', PAGE(o.lang));
+        if (req.method === 'GET' && files[url.pathname]) return send(200, files[url.pathname], readFileSync(join(UI, url.pathname.slice('/ui/'.length))));
+        if (req.method === 'GET' && url.pathname === '/api/people') return send(200, 'application/json', JSON.stringify([PERSON, ...o.sides.map((s) => s.who)]));
+        if (req.method === 'GET' && url.pathname === '/api/changes') {
+            res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store' }); res.write(': on\n\n');
+            watchers.add(res); req.on('close', () => watchers.delete(res)); return undefined;
+        }
+        if (req.method === 'POST' && url.pathname === '/api') {
+            /* A page of another site cannot post here: the type it would need is not one a form sends. */
+            if (!String(req.headers['content-type'] ?? '').startsWith('application/json')) return send(415, 'text/plain', 'json only');
+            let body = '';
+            req.on('data', (c) => { body += c; if (body.length > BODY_MAX) req.destroy(); });
+            req.on('end', () => {
+                let q; try { q = JSON.parse(body); } catch { return send(400, 'application/json', JSON.stringify({ ok: false, text: 'not understood' })); }
+                const r = k.act(String(q?.op ?? ''), q?.args && typeof q.args === 'object' ? q.args : {}, PERSON);
+                return send(200, 'application/json', JSON.stringify(r));
+            });
+            return undefined;
+        }
+        return send(404, 'text/plain', 'not here');
+    });
+    return new Promise((ok) => server.listen(o.port, '127.0.0.1', () => {
+        if (!quiet) process.stdout.write(`Binder kept in ${o.store}\nPage: http://127.0.0.1:${server.address().port}/\nAgents: ${o.sides.map((s) => `${s.who.name} (${s.dir})`).join(', ')}\n`);
+        ok({ server, keeper: k, port: server.address().port, close: () => { clearInterval(pump); for (const r of watchers) r.end(); server.close(); } });
+    }));
+}
+
+export async function serveBinder(argv) {
+    let o;
+    try { o = options(argv); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 64; return; }
+    await start(o);
+}

package/package.json

@@ -1 +1,51 @@
-{"name":"clavarium-binder","version":"0.0.1","description":"Clavarium Binder: name reserved; published from github.com/clavarium/clavarium-binder.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/clavarium/clavarium-binder.git"}}
+{
+  "name": "clavarium-binder",
+  "version": "0.1.0-next.1",
+  "description": "Clavarium Binder: lists of records kept together by people and AI agents, each with its id (a command and an MCP server for agents, a keeper and a screen for the application). No dependency.",
+  "license": "MIT",
+  "homepage": "https://github.com/clavarium/clavarium-binder#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clavarium/clavarium-binder.git"
+  },
+  "type": "module",
+  "bin": {
+    "binder": "bin/binder.mjs",
+    "binder-mcp": "server/binder.mjs"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "host/",
+    "ui/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run check:hooks && npm run check:shapes && npm run check:names && npm run check:shell && npm test",
+    "check:shapes": "node tools/check-shapes.mjs",
+    "check:names": "node tools/check-ai-names.mjs",
+    "check:shell": "node tools/check-shell.mjs",
+    "check:hooks": "node tools/check-hooks.mjs",
+    "hooks": "git config core.hooksPath hooks",
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "exports": {
+    "./host": "./host/binder-host.mjs",
+    "./serve": "./host/binder-serve.mjs",
+    "./server": "./server/binder.mjs",
+    "./store": "./server/store.mjs",
+    "./templates": "./server/templates.mjs",
+    "./ui": "./ui/binder-ui.js",
+    "./ui.css": "./ui/binder-ui.css",
+    "./ui/texts/*": "./ui/texts/*"
+  }
+}

package/server/binder.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/* THE ASKING SIDE OF BINDER: how an agent, or a script, reads and changes the
+ * lists it was given. One file, no dependency.
+ *
+ *   a command    `binder`, `binder show LIST`, `binder add LIST "title"`...
+ *                (bin/binder.mjs imports this file)
+ *   MCP          `node binder.mjs [--dir FOLDER]`: the same verbs as tools,
+ *                over standard input and output (JSON-RPC 2.0, one message per line)
+ *
+ * IT ASKS, IT NEVER WRITES THE BINDER. The binder is held by its keeper (binder
+ * serve, or the application that runs Binder), out of the agent's reach: what
+ * an agent could write, it could rewrite. Here, the agent's own folder:
+ *
+ *   asks.jsonl      the agent's: what it asks, one line each
+ *   answers.jsonl   the keeper's: the answer to each ask, by its id
+ *
+ * The keeper says who asks by the folder the ask came from: an agent cannot
+ * speak as another one, nor as a person. See docs/protocol.md.
+ */
+import { appendFileSync, readFileSync, mkdirSync, statSync, lstatSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline';
+
+export const VERSION = '0.1.0-next.1';
+export const FOLDER = '.binder';
+/* How long an ask waits for its answer. The keeper answers within a second or two. */
+export const WAIT_MS = 20_000;
+export const NO_KEEPER = 'No answer: nobody keeps this binder right now (its application, or "binder serve", is not running). Nothing was changed.';
+
+const parsed = (line) => { try { const j = JSON.parse(line); return j && typeof j === 'object' && !Array.isArray(j) ? j : null; } catch { return null; } };
+export function lines(file) {
+    try { if (lstatSync(file).isSymbolicLink()) return []; return readFileSync(file, 'utf8').split('\n').filter(Boolean).map(parsed).filter(Boolean); } catch { return []; }
+}
+const isFolder = (path) => { try { return statSync(path).isDirectory(); } catch { return false; } };
+
+/* The folder: `dir`, else $BINDER_DIR, else the nearest .binder from `from` up. */
+export function findFolder({ dir, env = process.env, from = process.cwd() } = {}) {
+    if (dir) return resolve(from, dir);
+    if (env.BINDER_DIR) return resolve(from, env.BINDER_DIR);
+    for (let at = resolve(from); ; at = dirname(at)) {
+        if (isFolder(join(at, FOLDER))) return join(at, FOLDER);
+        if (dirname(at) === at) return null;
+    }
+}
+
+/* One ask, and its answer: { ok, text, data? }. */
+export async function ask(dir, op, args = {}, { wait = WAIT_MS, every = 150 } = {}) {
+    mkdirSync(dir, { recursive: true });
+    const id = randomUUID();
+    appendFileSync(join(dir, 'asks.jsonl'), `${JSON.stringify({ id, at: new Date().toISOString(), op, args })}\n`);
+    const until = Date.now() + wait;
+    for (;;) {
+        const answer = lines(join(dir, 'answers.jsonl')).find((a) => a.ask === id);
+        if (answer) return { ok: answer.ok === true, text: String(answer.text ?? ''), ...(answer.data !== undefined ? { data: answer.data } : {}) };
+        if (Date.now() >= until) return { ok: false, text: NO_KEEPER, nokeeper: true };
+        await new Promise((r) => setTimeout(r, every));
+    }
+}
+
+/* ---- MCP ---- */
+const S = (description) => ({ type: 'string', description });
+export const TOOLS = [
+    { name: 'lists', description: 'The lists you were given, with how many records each holds and whether you may change them.', inputSchema: { type: 'object', properties: {} } },
+    { name: 'show', description: 'The records of a list, by state. Filter by state, or only yours.', inputSchema: { type: 'object', properties: { list: S('its name or id'), state: S('a state of the list'), mine: { type: 'boolean' }, archived: { type: 'boolean' } }, required: ['list'] } },
+    { name: 'get', description: 'One record whole: its fields, notes, what is attached, its history.', inputSchema: { type: 'object', properties: { id: S('the record number, as #12 or 12') }, required: ['id'] } },
+    { name: 'search', description: 'Records whose title, notes or fields hold a text, in every list you can see.', inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } },
+    { name: 'add', description: 'Add a record to a list (in its first state unless you say). You cannot add it approved: a person ticks it.', inputSchema: { type: 'object', properties: { list: S('its name or id'), title: { type: 'string' }, state: { type: 'string' }, due: S('2026-11-04 or 2026-11-04 09:00'), owner: S('"me", or an id'), note: { type: 'string' }, fields: { type: 'object', description: '{ field name: value }' } }, required: ['list', 'title'] } },
+    { name: 'edit', description: 'Change a record: title, fields, owners, due date (empty to remove it).', inputSchema: { type: 'object', properties: { id: { type: 'string' }, title: { type: 'string' }, due: { type: 'string' }, owner: S('"me", or an id; empty for nobody'), fields: { type: 'object' } }, required: ['id'] } },
+    { name: 'move', description: 'Put a record in another state of its list. Past a gate (an approval), only once a person approved it.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, state: { type: 'string' } }, required: ['id', 'state'] } },
+    { name: 'note', description: 'Add a short note to a record: a decision, a fact, a result. Talking with the person stays in the chat.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, text: { type: 'string' } }, required: ['id', 'text'] } },
+    { name: 'attach', description: 'Attach something to a record: a message of the chat, a file, an asset, a branch, a link, another record.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['message', 'file', 'asset', 'branch', 'link', 'record'] }, ref: S('what it is: a path, a URL, repository:branch, a message id, a record number'), title: { type: 'string' } }, required: ['id', 'kind', 'ref'] } },
+    { name: 'detach', description: 'Take back something attached to a record.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, what: S('what get shows of it: its ref or its id') }, required: ['id', 'what'] } },
+    { name: 'archive', description: 'Archive a record (it leaves the list; found again with archived), or restore it.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, restore: { type: 'boolean' } }, required: ['id'] } },
+];
+/* A tool's arguments as the keeper reads them. */
+export function asked(name, a = {}) {
+    const owners = a.owner === undefined ? undefined : a.owner === '' ? [] : [a.owner];
+    switch (name) {
+        case 'lists': return ['lists', {}];
+        case 'show': return ['show', { list: a.list, state: a.state, mine: !!a.mine, archived: !!a.archived }];
+        case 'get': return ['get', { id: a.id }];
+        case 'search': return ['search', { text: a.text }];
+        case 'add': return ['add', { list: a.list, title: a.title, state: a.state, due: a.due, owners, note: a.note, fields: a.fields }];
+        case 'edit': return ['edit', { id: a.id, title: a.title, due: a.due, owners, fields: a.fields }];
+        case 'move': return ['move', { id: a.id, state: a.state }];
+        case 'note': return ['note', { id: a.id, text: a.text }];
+        case 'attach': return ['attach', { id: a.id, kind: a.kind, ref: a.ref, title: a.title }];
+        case 'detach': return ['detach', { id: a.id, what: a.what }];
+        case 'archive': return ['archive', { id: a.id, restore: !!a.restore }];
+        default: return null;
+    }
+}
+export function serve(dir, { input = process.stdin, output = process.stdout, wait } = {}) {
+    const reply = (id, result, error) => output.write(`${JSON.stringify({ jsonrpc: '2.0', id, ...(error ? { error } : { result }) })}\n`);
+    const rl = createInterface({ input });
+    rl.on('line', async (line) => {
+        const m = parsed(line);
+        if (!m || m.id === undefined) return;
+        if (m.method === 'initialize') return reply(m.id, { protocolVersion: m.params?.protocolVersion ?? '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'binder', version: VERSION } });
+        if (m.method === 'tools/list') return reply(m.id, { tools: TOOLS });
+        if (m.method === 'ping') return reply(m.id, {});
+        if (m.method === 'tools/call') {
+            const { name, arguments: a = {} } = m.params ?? {};
+            const what = asked(name, a);
+            if (!what) return reply(m.id, undefined, { code: -32601, message: `no tool ${name}` });
+            const r = await ask(dir, what[0], what[1], wait ? { wait } : {});
+            return reply(m.id, { content: [{ type: 'text', text: r.ok ? r.text : `Not done: ${r.text}` }], ...(r.ok ? {} : { isError: true }) });
+        }
+        return reply(m.id, undefined, { code: -32601, message: `no method ${m.method}` });
+    });
+    return rl;
+}
+
+const HERE = fileURLToPath(import.meta.url);
+const main = (() => { try { return realpathSync(process.argv[1] ?? '') === realpathSync(HERE); } catch { return false; } })();
+if (main) {
+    const at = process.argv.indexOf('--dir');
+    const dir = findFolder({ dir: at >= 0 ? process.argv[at + 1] : undefined });
+    if (!dir) { process.stderr.write(`No ${FOLDER} folder: give --dir FOLDER.\n`); process.exit(2); }
+    serve(dir);
+}