diarium 0.1.0

package/FLOW.md

@@ -0,0 +1,209 @@
+# The flow
+
+Every command output below is real, copied from a live run against a repo with a bd tracker and a GitHub tracker — not
+an illustration.
+
+## Install
+
+```
+npm i -D diarium
+```
+
+First run creates a `diarium/` folder next to your code and generates a signing key into `.env`:
+
+```
+diarium/
+  rules.md        prose. The agent reads it before every entry. Yours to rewrite — we do not care how you word it.
+  settings.json   structure. Code reads it: which trackers to watch, where the cursors are.
+  .pending/       closures that owe an entry
+  *.ust.json      one sealed entry per file
+```
+
+The key lives in `.env` as `DIARIUM_SEED` and is never printed — not even by the tool that made it. Lose it and the
+chain can no longer be extended, though every existing entry still verifies. Leak it and someone else can write entries
+as you, and every one of those will verify. So the tool checks, on every run, whether git actually ignores `.env`:
+
+```
+  · generated a signing key into .env — gitignore it. The seed is never printed, not even here.
+  ! .env is NOT gitignored — add it now. The seed in there is the identity of this store;
+    anyone who has it can write entries as you, and every one of them will verify.
+```
+
+The key is generated at install rather than at the first entry, so that warning arrives while you are setting up — not
+half an hour later, mid-flow, when the store already exists.
+
+## Wire it to your agent
+
+There is no plugin, no MCP server, no GitHub Action. Your agent already runs shell commands, so one paragraph in
+whatever file it reads as standing instructions — `CLAUDE.md`, `AGENTS.md`, a Cursor rule — is the whole integration.
+The suggested wording is in `INTEGRATE.md`.
+
+## The loop
+
+### 1. Start of a session — what did I learn last time
+
+```
+$ diarium read --depth 3
+  walking back 3 hop(s) from the head of 9 entries
+
+  ── ust:20260725.154843  ·  task diarium-ixr  ·  20260725.154843_diarium-ixr_be8ef642.ust.json
+  Nothing here to learn: this task existed only to prove the trigger fires on a real closure. Recording that
+  plainly rather than inventing an insight.
+```
+
+It walks the chain N hops back from the head rather than loading the whole corpus, so a store with a thousand entries
+costs the same to read as one with three.
+
+### 2. Work. Close a task — in whichever tracker you use
+
+```
+$ bd close UST-l0a
+```
+or
+```
+$ gh issue close 90
+```
+
+Nothing special: close it the way you always do.
+
+### 3. `scan` — what closed since last time
+
+```
+$ diarium scan
+  bd:..: 1 closure(s) since 2026-07-25T15:56
+  github:thelabmd/UST-Protocol: 0 closure(s) since 2026-07-25T15:56
+
+  1 new obligation(s) — run status
+```
+
+Both trackers answer the same question — *what closed after this cursor* — so adding a tracker is an adapter, not an
+integration. A tracker that is unreachable says so and its cursor is left untouched, so nothing is skipped quietly.
+
+**The very first scan sets a baseline instead of a backlog:**
+
+```
+  bd:..: BASELINE set — 79 historical closure(s) skipped (a memory you did not live is an invention, not a memory)
+```
+
+Asking an agent to write seventy-nine entries about work it does not remember would manufacture recollection. What is
+skipped is printed, not dropped in silence.
+
+### 4. `status` — what owes an entry
+
+```
+$ diarium status
+  store: 9 entries  ·  cap 560  ·  diarium/
+  ✗ 1 closure(s) owe an entry — a closure without an entry is what this catches:
+    UST-l0a        done      2026-07-25T16:09  flow doc demo — a real closure in this repo tracker
+```
+
+Exit code is 1 while anything is owed, so it can gate a commit if you want it to.
+
+This is the load-bearing part of the design: **the agent does not choose when to write.** A closure creates the
+obligation; only the agent can discharge it. It cannot skip a closure it would rather not record, and it cannot bury
+one entry under ten others.
+
+### 5. The agent writes the recap
+
+What it should write: **what it understood and what it learned** — not what it did. Git already keeps what it did, and
+keeps it better.
+
+If it no longer holds the task, the honest entry is exactly that, and it is a first-class record:
+
+```
+$ diarium write UST-l0a recap.md --nothing-learned
+```
+
+Absence of a result is a result. It is recorded structurally rather than left inside a sentence, so a corpus that is
+mostly *nothing learned* can be counted — and that count tells you something about the work, or about the trigger.
+
+```
+$ diarium write UST-l0a recap.md
+✓ entry sealed + stored
+  file        : 20260725.160942_UST-l0a_6e96103b.ust.json
+  task        : UST-l0a (tracker-local)
+  content_hash: sha256:6e96103b582a92dc7312ccea9d86d03adc186c818f76bde8da51569beddaf975
+  prev        : sha256:be8ef64235d1919de4bd88f2d78c32b27c2373328fbd83c8fa8e44d705d4dcae
+```
+
+The entry is verified **before** it is stored, chained to the head of the chain (not to the last filename), and the
+obligation is discharged. The cap declared in `rules.md` is enforced here; everything else in that file the tool can
+only ask for, which is honest as long as asking is not dressed up as enforcement.
+
+```
+$ diarium status
+  store: 10 entries  ·  cap 560  ·  diarium/
+  ✓ no closure is waiting for an entry
+```
+
+### 6. `verify` — nobody rewrote anything
+
+```
+$ diarium verify
+✓ 10 entries: every seal verifies, one genesis, one head, no fork, no orphan
+  (order from the chain — filenames are cosmetic)
+```
+
+This is the only reason the entries are UST documents rather than lines in a text file. It catches, with the sealed
+bytes alone:
+
+| what happened | what verify says |
+| --- | --- |
+| an entry's text was edited | that seal does not verify |
+| an entry was deleted from the middle | no genesis, and a `prev` that resolves to nothing |
+| entries were reordered by renaming | nothing — names carry no meaning, and that is by design |
+| an entry was duplicated | a fork: two entries claim the same `prev` |
+| the whole folder was moved | nothing — a seal is not bound to where it is stored |
+
+An entry cannot be rewritten afterwards **including by the agent that wrote it**, and anyone can check that offline
+without trusting you. Hand someone a single file and they can verify it with the public web verifier or `npm i
+ust-protocol` — no server, no account, no call back to us.
+
+## What a stored entry actually is
+
+A plain UST document. Not a diarium format:
+
+```json
+{
+  "ust": "1.0",
+  "state": {
+    "id":   { "domain_shard": "sha256:9075…", "ust_id": "ust:20260725.160942",
+              "key_id": "sha256:9075…", "class": "observation" },
+    "time": { "generated_at": "2026-07-25T16:09:42Z", "valid_from": "…", "valid_to": "…" },
+    "data": { "entry": { "kind": "captured", "value": {
+                "text": "…the recap…",
+                "task": { "ref": "thelabmd/UST-Protocol#91", "id": "4975299807",
+                          "node_id": "I_kwDO…", "source": "github",
+                          "closed_at": "2026-07-25T16:09:12Z" } } } },
+    "hashes":     { "entry": "sha256:aaa7…" },
+    "provenance": { "prev": "sha256:be8e…" }
+  },
+  "sig": { "alg": "Ed25519", "key_id": "sha256:9075…", "pub": "56tM…", "sig": "pIsn…" }
+}
+```
+
+Two details worth knowing:
+
+**The task reference carries a durable id.** `owner/repo#N` is a path, and paths go stale — rename or transfer the repo
+and the reference inside an already-sealed entry becomes unresolvable, with no way to fix it. So the seal carries the
+readable ref *and* the identifier that survives a rename. Where no global id exists — bd, any local tracker — that is
+recorded as `source: tracker-local` rather than implied, and nothing is invented when a lookup fails.
+
+**Lived and reconstructed are told apart by evidence, not by claim.** The seal carries the closure time next to the
+write time, so the interval is observable: an entry written three minutes after the closure was lived, one written
+three days later was reconstructed. Nobody declares which — declaring your own reliability is exactly the self-asserted
+assurance this design refuses everywhere else.
+
+## Filenames
+
+```
+20260725.160942_UST-l0a_6e96103b.ust.json
+└── address ──┘ └ task ┘ └ hash ┘
+```
+
+Underscore separates fields and hyphen lives inside them, because repo names carry hyphens (`UST-Protocol`) and a
+separator that can also appear in the data is not a separator. The address has no `ust:` prefix because a colon cannot
+be checked out on Windows.
+
+None of this carries meaning. Order comes from the chain, identity from the `content_hash` — rename every file and
+`verify` stays green. The name is there so a human can find something by eye.

package/INTEGRATE.md

@@ -0,0 +1,13 @@
+# Wire it to your agent
+
+There is no plugin, no MCP server, no GitHub Action. Your agent already runs shell commands, so one instruction is
+enough. Paste this into whatever file your agent reads as standing instructions — `CLAUDE.md`, `AGENTS.md`, a Cursor
+rule, a system prompt. We suggest the wording; how you wire it is yours.
+
+> **Diary.** At the start of a session run `diarium scan` — it lists tasks that closed since you last looked. Each one
+> owes an entry. Write what you UNDERSTOOD and what you LEARNED, not what you did, and seal it with
+> `diarium write <task-ref> <file>`. If you no longer hold the task, say exactly that and pass `--nothing-learned` —
+> absence of a result is a result. Do not read the issue and the diff to reconstruct an insight; git already keeps
+> summaries better than you will. Before starting work, `diarium read --depth 3` to see what you last learned.
+
+That is the whole integration.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,63 @@
+# diarium
+
+Agent memory as a verifiable UST stream.
+
+```
+npm i -D diarium
+```
+
+A task closes in your tracker. The agent writes what it understood and what it learned from it — a few sentences, its own voice. That text is sealed as a UST `observation`, `prev`-chained to the entry before it, and appended to `diarium/`. The agent reads it back later as its own memory, walking the chain instead of loading the whole corpus.
+
+Nothing here proves the work was done well. A sealed entry proves **the agent said this, then**, and that nobody — including the agent — rewrote it afterwards. Fixation, not truth. Ordering and non-repudiation are the product; correctness is not on offer.
+
+The full walkthrough, with real command output, is in [FLOW.md](./FLOW.md). Wiring it to your agent is one paragraph: [INTEGRATE.md](./INTEGRATE.md).
+
+## Why it is not just a log file
+
+A log can be edited. A tracker comment can be edited. A closed issue can be reopened and its history rewritten. A `prev`-chained stream of signed entries cannot: change one entry and every later `prev` stops resolving, so the tampering is visible to anyone holding a later entry — no server, no trust in the author.
+
+Hand someone a single file and they can check it offline with `npm i ust-protocol` or the public web verifier. Nothing calls back to us; there is no us to call.
+
+## What holds it together
+
+Nobody reviews an entry before it lands. That is deliberate, so the discipline cannot be review — it is the **trigger**: the agent does not choose when to write. A task closes, an entry is owed. It cannot skip a closure it would rather not record, and it cannot bury one entry under ten others. One closure, one entry, and a closure without an entry is detectable — that is what `status` is, and why it exits non-zero while anything is owed.
+
+The rest is mechanical, and split honestly between what code can enforce and what only prose can ask for:
+
+| enforced by code | asked for by the rules |
+| --- | --- |
+| character cap | write the failures too, not just the wins |
+| `prev` chain, signature | one entry, one moment |
+| one entry per closure | no performed feelings |
+| a broken store cannot be extended | do not reconstruct a task you no longer hold |
+
+The rules live in `diarium/rules.md` as prose, and the agent reads them before writing. Rewrite that file and the agent's behaviour changes — configuration by prose. The cap is yours to set. The append-only chain is not: without it this is a text file.
+
+`"Nothing to learn"` is a first-class entry, recorded structurally rather than buried in a sentence, so a corpus that is mostly *nothing learned* can be counted. Absence of a result is a result.
+
+## Commands
+
+```
+diarium scan                what closed since last time (first run sets a baseline, not a backlog)
+diarium status              closures owing an entry — exit 1 while any is owed, so it can gate
+diarium write <ref> <file>  seal + chain + store        [--nothing-learned]
+diarium read [--depth N]    walk the chain N hops back from the head
+diarium verify              every seal, one genesis, one head, no fork, no orphan
+diarium render              markdown to stdout, derived, never stored
+```
+
+Trackers are detected on first run — a `.beads/` directory, a GitHub remote — and written into `diarium/settings.json` for you to edit. Both answer one question, *what closed after this cursor*, so another tracker is an adapter, not an integration.
+
+## Keys
+
+A signing key is generated into `.env` as `DIARIUM_SEED` on first run and is never printed, not even by the tool that made it. Every run checks that git actually ignores it. Lose it and the chain can no longer be extended, though every existing entry still verifies. Leak it and someone else can write entries as you — and every one of those will verify too, which is the point of checking.
+
+## Tier
+
+`VALID:LIGHT`, key-form identity, and that is the right ceiling. Everyone keeps their own memories, so there is no third party to convince — no domain-bound identity to prove *who*, no external clock to prove *when*. Adding those would be selling assurance nobody asked for.
+
+## Status
+
+`0.1.0`, and the version is deliberate: everything else in this repository is protocol surface on the `1.0.0-rc` line, while this is a product built on top of it. Treat the CLI surface as unsettled and the sealed entries as permanent — an entry written today verifies under any later version, because what makes it verifiable is the protocol, not this tool.
+
+Built on [`ust-protocol`](../ust-protocol), which is its only dependency, and which has none of its own.

package/bin/diarium.mjs

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// diarium — a task closes, the agent writes what it learned, the entry is sealed as a UST and chained into diarium/.
+//
+// The crypto is not here: it is `ust-protocol`, and this tool calls five functions from it. What lives here is the
+// DISCIPLINE the library cannot hold — prev taken from the head of the chain rather than the last filename, the entry
+// verified before it is stored, the cap enforced, one closure one entry, and a refusal to extend a broken store. Those
+// are exactly the invariants an agent re-deriving them each session gets wrong.
+//
+// Everything is relative to the directory you run it in, so the store lands next to your code and the tool itself can
+// live in node_modules.
+import * as P from 'ust-protocol';
+import { createPrivateKey, createPublicKey, randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+
+const CWD = process.cwd();
+const STORE = join(CWD, 'diarium');
+const PENDING = join(STORE, '.pending');
+const RULES = join(STORE, 'rules.md');
+const SETTINGS = join(STORE, 'settings.json');
+const ENV = join(CWD, '.env');
+
+// rules.md is PROSE and it is the agent's prompt — yours to rewrite, and the tool does not care how you word it.
+// Only `cap` is parsed and enforced; the rest it can ask for, which is honest as long as asking is not presented as
+// enforcement. settings.json is STRUCTURE, read by code: a typo there fails loudly instead of being ignored.
+const DEFAULT_RULES = `# Rules
+
+Yours to rewrite. The tool reads this file before every entry and enforces \`cap\`; the rest it can only ask for.
+
+cap: 560
+
+- Write what you UNDERSTOOD and what you LEARNED from the task that just closed. Not what you did — git already keeps that.
+- Write the failures too. A task that went wrong, a fix that did not hold, a call you got wrong. Never dress a loss up as a win.
+- One entry, one thing. If it does not fit the cap, cut it; do not split it.
+- No performed feelings. If it reads like marketing, delete it and write what actually happened.
+- Do NOT reconstruct. If you no longer hold the task, say so and stop — reading the issue and the diff to manufacture an
+  insight produces a summary, and git already keeps summaries better than you will. Read enough to RECOGNISE whether you
+  remember it; never enough to invent it.
+- "Nothing to learn" is a real entry. Absence of a result is a result. Write it plainly and pass --nothing-learned.
+- Nobody reviews this before it lands. The discipline is the trigger, not review: you do not choose when to write.
+`;
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = (n, d) => { const i = args.indexOf('--' + n); return i > 0 && args[i + 1] ? args[i + 1] : d; };
+const die = (m) => { console.error('✗ ' + m); process.exit(1); };
+
+// First run detects the trackers this repo actually has rather than asking you to describe them.
+function detectSources() {
+  const out = [];
+  if (existsSync(join(CWD, '.beads'))) out.push({ type: 'bd', cwd: '.' });
+  try {
+    const url = execSync('git remote get-url origin', { cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const m = /[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/.exec(url);
+    if (m) out.push({ type: 'github', repo: `${m[1]}/${m[2]}` });
+  } catch { /* no remote: leave it out rather than guess */ }
+  return out;
+}
+
+// The seed is generated at INIT, not lazily on the first entry: the developer must see the "gitignore this" warning
+// while installing, not in the middle of writing. A leaked seed lets someone else write entries as you.
+function ignored() {
+  try { execSync('git check-ignore -q .env', { cwd: CWD, stdio: 'ignore' }); return true; } catch { return false; }
+}
+
+function ensure() {
+  mkdirSync(PENDING, { recursive: true });
+  if (!existsSync(RULES)) writeFileSync(RULES, DEFAULT_RULES);
+  if (!existsSync(SETTINGS)) {
+    const sources = detectSources();
+    writeFileSync(SETTINGS, JSON.stringify({ sources, cursors: {} }, null, 2) + '\n');
+    console.log(`  · created ${STORE.replace(CWD + '/', '')}/ with ${sources.length} detected tracker(s): ${sources.map((s) => s.type).join(', ') || 'none — add them to settings.json'}`);
+  }
+  key();
+  if (!ignored()) console.log('  ! .env is NOT gitignored — add it now. The seed in there is the identity of this store;\n    anyone who has it can write entries as you, and every one of them will verify.');
+}
+const cap = () => { const m = (existsSync(RULES) ? readFileSync(RULES, 'utf8') : DEFAULT_RULES).match(/^cap:\s*(\d+)/m); return m ? Number(m[1]) : 560; };
+const files = () => (existsSync(STORE) ? readdirSync(STORE).filter((f) => f.endsWith('.ust.json')).sort() : []);
+const load = (f) => JSON.parse(readFileSync(join(STORE, f), 'utf8'));
+
+// Order comes from the CHAIN, never from the filesystem: filenames are cosmetic and renaming every file must change
+// nothing. Deriving order from `prev` also sees forks and orphans, which a filename sort never can.
+function chain() {
+  const docs = files().map((f) => ({ f, d: load(f) }));
+  const problems = [];
+  if (!docs.length) return { ordered: [], problems };
+  const hashOf = (x) => P.contentHash(x.d);
+  const prevOf = (x) => x.d.state.provenance?.prev;
+  const byHash = new Map(docs.map((x) => [hashOf(x), x]));
+
+  const genesis = docs.filter((x) => !prevOf(x));
+  if (!genesis.length) problems.push('no genesis: every entry carries a prev, so the oldest one is missing');
+  if (genesis.length > 1) problems.push(`${genesis.length} entries carry no prev — a stream has exactly one genesis: ${genesis.map((x) => x.f).join(', ')}`);
+
+  const claimed = new Map();
+  for (const x of docs) {
+    const p = prevOf(x); if (!p) continue;
+    if (!byHash.has(p)) problems.push(`${x.f}: prev ${p.slice(0, 20)}… resolves to no entry here — a gap, or the chain leaves this store`);
+    claimed.set(p, (claimed.get(p) || []).concat(x.f));
+  }
+  for (const [p, fs2] of claimed) if (fs2.length > 1) problems.push(`FORK: ${fs2.length} entries claim the same prev ${p.slice(0, 20)}… — ${fs2.join(', ')}`);
+
+  const heads = docs.filter((x) => !claimed.has(hashOf(x)));
+  if (heads.length > 1) problems.push(`${heads.length} heads — nothing follows any of: ${heads.map((x) => x.f).join(', ')}`);
+
+  const ordered = []; const seen = new Set();
+  let cur = heads[0], guard = docs.length + 1;
+  while (cur && guard-- > 0) {
+    if (seen.has(cur.f)) { problems.push(`cycle detected at ${cur.f}`); break; }
+    seen.add(cur.f); ordered.unshift(cur);
+    const p = prevOf(cur); cur = p ? byHash.get(p) : null;
+  }
+  for (const x of docs) if (!seen.has(x.f)) problems.push(`${x.f}: unreachable from the head — an orphan the chain does not include`);
+  return { ordered, problems };
+}
+
+function key() {
+  const env = existsSync(ENV) ? readFileSync(ENV, 'utf8') : '';
+  let m = env.match(/^DIARIUM_SEED=(\S+)/m);
+  if (!m) {
+    const seed = randomBytes(32).toString('base64url');
+    appendFileSync(ENV, `${env.endsWith('\n') || !env ? '' : '\n'}DIARIUM_SEED=${seed}\n`);
+    m = [null, seed];
+    console.log('  · generated a signing key into .env — gitignore it. The seed is never printed, not even here.');
+  }
+  const seed = Buffer.from(m[1], 'base64url');
+  const priv = createPrivateKey({ key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), seed]), format: 'der', type: 'pkcs8' });
+  const pub = createPublicKey(priv).export({ format: 'der', type: 'spki' }).slice(-32).toString('base64url');
+  return { priv, pub, kid: P.keyId(pub) };
+}
+
+// A task reference is a PATH and paths go stale: rename or transfer the repo and the reference inside an already-sealed
+// entry is unresolvable, unfixable because the seal is immutable. So the seal carries the readable ref AND the id that
+// survives a rename. Where no global id exists that is RECORDED, never implied, and nothing is invented on failure.
+function resolveTask(ref) {
+  const m = /^(?:([\w.-]+)\/([\w.-]+))?#?(\d+)$/.exec(String(ref).trim());
+  if (!m) return { ref, source: /^[A-Za-z][\w.-]*-[a-z0-9]+$/.test(ref) ? 'tracker-local' : 'raw' };
+  let [, owner, repo, num] = m;
+  if (!owner || !repo) {
+    try {
+      const url = execSync('git remote get-url origin', { cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      const rm = /[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/.exec(url);
+      if (rm) { owner = rm[1]; repo = rm[2]; }
+    } catch { /* stay unqualified rather than guess */ }
+  }
+  if (!owner || !repo) return { ref, source: 'raw' };
+  const qualified = `${owner}/${repo}#${num}`;
+  try {
+    const j = JSON.parse(execSync(`gh api repos/${owner}/${repo}/issues/${num} --jq '{id:.id,node_id:.node_id}'`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }));
+    return { ref: qualified, id: String(j.id), node_id: j.node_id, source: 'github' };
+  } catch { return { ref: qualified, source: 'github-unresolved' }; }
+}
+const field = (s) => String(s).replace(/_/g, '-').replace(/[^\w.-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+const slug = (t) => { const m = /^(?:[\w.-]+\/)?([\w.-]+)#(\d+)$/.exec(t.ref); return m ? `${field(m[1])}_${field(m[2])}` : field(t.ref); };
+const pendingPath = (ref) => join(PENDING, String(ref).replace(/[^\w.-]/g, '_') + '.json');
+
+// ── scan ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+// Every source answers ONE question — what closed after this cursor — so a new tracker is an adapter, not an
+// integration. Polling is what makes the trigger real: measured on a live day, it caught every closure while a
+// commit-keyword hook caught none, because the closures went through `gh issue close` and the commits said "Refs #90".
+if (cmd === 'scan') {
+  ensure();
+  let cfg; try { cfg = JSON.parse(readFileSync(SETTINGS, 'utf8')); } catch (e) { die(`settings.json does not parse — a typo there fails loudly on purpose: ${e.message}`); }
+  cfg.cursors = cfg.cursors || {};
+  let found = 0;
+  for (const s of (cfg.sources || []).filter((x) => x.enabled !== false)) {
+    const id = `${s.type}:${s.repo || s.cwd || '.'}`;
+    const cold = !cfg.cursors[id];
+    const since = cfg.cursors[id] || '1970-01-01T00:00:00Z';
+    let rows = [];
+    try {
+      if (s.type === 'github') {
+        rows = JSON.parse(execSync(`gh issue list -R ${s.repo} --state closed --limit 100 --json number,closedAt,title`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }))
+          .filter((x) => x.closedAt > since).map((x) => ({ ref: `${s.repo}#${x.number}`, at: x.closedAt, title: x.title }));
+      } else if (s.type === 'bd') {
+        rows = JSON.parse(execSync('bd list --status=closed --limit 400 --json', { cwd: join(CWD, s.cwd || '.'), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }))
+          .filter((x) => (x.closed_at || '') > since).map((x) => ({ ref: x.id, at: x.closed_at, title: x.title }));
+      } else { console.log(`  ? ${id}: unknown source type — skipped, never guessed`); continue; }
+    } catch (e) {
+      // The CAUSE lives in stderr; e.message only repeats the command back, which is the least informative line there is.
+      const why = (String(e.stderr || '').split('\n').filter(Boolean)[0] || String(e.message).split('\n')[1] || 'no output').trim();
+      console.log(`  ! ${id}: unreachable — cursor untouched, so nothing is skipped quietly\n      ${why.slice(0, 120)}`); continue;
+    }
+
+    // A cold start sets a BASELINE, not a backlog. Asking an agent to write dozens of entries about work it does not
+    // remember manufactures recollection, and a corpus of invented memories is worse than an empty one.
+    if (cold) {
+      cfg.cursors[id] = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+      console.log(`  ${id}: BASELINE set — ${rows.length} historical closure(s) skipped (a memory you did not live is an invention, not a memory)`);
+      continue;
+    }
+    for (const r of rows.sort((a, b) => a.at.localeCompare(b.at))) {
+      if (!existsSync(pendingPath(r.ref))) { writeFileSync(pendingPath(r.ref), JSON.stringify({ ref: r.ref, kind: 'done', title: r.title || '', at: r.at }, null, 2) + '\n'); found++; }
+      if (r.at > (cfg.cursors[id] || '')) cfg.cursors[id] = r.at;
+    }
+    console.log(`  ${id}: ${rows.length} closure(s) since ${since.slice(0, 16)}`);
+  }
+  writeFileSync(SETTINGS, JSON.stringify(cfg, null, 2) + '\n');
+  console.log(found ? `\n  ${found} new obligation(s) — run: diarium status` : '\n  nothing new');
+  process.exit(0);
+}
+
+if (cmd === 'closed') {
+  const ref = args[1]; if (!ref) die('usage: diarium closed <ref> [--kind done|cancelled] [--title "..."]');
+  ensure();
+  if (existsSync(pendingPath(ref))) { console.log(`· ${ref} already owes an entry`); process.exit(0); }
+  writeFileSync(pendingPath(ref), JSON.stringify({ ref, kind: flag('kind', 'done'), title: flag('title', ''), at: new Date().toISOString() }, null, 2) + '\n');
+  console.log(`· ${ref} closed — an entry is owed:  diarium write ${ref} <file>`);
+  process.exit(0);
+}
+
+// ── status: the gate. A closure without an entry is the thing this catches, so it exits non-zero while any is owed.
+if (cmd === 'status') {
+  ensure();
+  const owed = readdirSync(PENDING).filter((f) => f.endsWith('.json')).map((f) => JSON.parse(readFileSync(join(PENDING, f), 'utf8')));
+  console.log(`  store: ${files().length} entries  ·  cap ${cap()}  ·  diarium/`);
+  if (!owed.length) { console.log('  ✓ no closure is waiting for an entry'); process.exit(0); }
+  console.log(`  ✗ ${owed.length} closure(s) owe an entry:`);
+  for (const o of owed.sort((a, b) => a.at.localeCompare(b.at))) console.log(`    ${String(o.ref).padEnd(16)} ${o.kind.padEnd(9)} ${o.at.slice(0, 16)}  ${(o.title || '').slice(0, 60)}`);
+  process.exit(1);
+}
+
+if (cmd === 'write') {
+  const ref = args[1], bodyPath = args[2];
+  if (!ref || !bodyPath || !existsSync(bodyPath)) die('usage: diarium write <task-ref> <file> [--nothing-learned]');
+  ensure();
+  const body = readFileSync(bodyPath, 'utf8').trim();
+  if (!body) die('empty entry');
+  const limit = cap();
+  if (body.length > limit) die(`entry is ${body.length} characters — the cap declared in diarium/rules.md is ${limit}. Cut it, do not split it.`);
+  // "Nothing to learn" is first-class and recorded STRUCTURALLY so it can be counted: a corpus that is mostly this is
+  // telling you something, and that signal is lost if the fact hides inside a sentence.
+  const nothing = args.includes('--nothing-learned');
+
+  const task = resolveTask(ref);
+  // The closure time travels into the seal so the closure→entry INTERVAL is observable: an entry written minutes after
+  // the closure was lived, one written days later was reconstructed. Nobody declares which — declaring your own
+  // reliability is the self-asserted assurance this design refuses everywhere else.
+  if (existsSync(pendingPath(ref))) { try { task.closed_at = JSON.parse(readFileSync(pendingPath(ref), 'utf8')).at; } catch { /* keep going without it */ } }
+
+  const { ordered, problems } = chain();
+  if (problems.length) { console.error('✗ refusing to extend a broken store — fix it first:'); for (const p of problems) console.error('   • ' + p); process.exit(1); }
+  const prev = ordered.length ? P.contentHash(ordered[ordered.length - 1].d) : undefined;
+
+  const { priv, pub, kid } = key();
+  const now = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const ust_id = `ust:${now.slice(0, 4)}${now.slice(5, 7)}${now.slice(8, 10)}.${now.slice(11, 13)}${now.slice(14, 16)}${now.slice(17, 19)}`;
+  const state = P.buildState({ domain_shard: kid, ust_id, key_id: kid, class: 'observation' },
+    { generated_at: now, valid_from: now, valid_to: now },
+    { entry: { kind: 'captured', value: nothing ? { text: body, task, learned: 'none' } : { text: body, task } } },
+    prev ? { prev } : undefined);
+  const doc = P.seal(state, priv, pub);
+  const v = P.verify(doc, { context: 'data' });
+  if (v.result !== 'VALID:LIGHT') die(`entry did not seal VALID:LIGHT: ${v.result || v.error}`);
+
+  // Underscore separates fields, hyphen lives inside them: repo names carry hyphens, and a separator that can also
+  // appear in the data is not a separator. No `ust:` prefix — a colon cannot be checked out on Windows. The name
+  // carries no meaning; order is the chain's and identity is the content_hash.
+  const name = `${ust_id.slice(4)}_${slug(task)}_${P.contentHash(doc).slice(7, 15)}.ust.json`;
+  writeFileSync(join(STORE, name), JSON.stringify(doc) + '\n');
+  if (existsSync(pendingPath(ref))) unlinkSync(pendingPath(ref));
+  console.log('✓ entry sealed + stored');
+  console.log('  file        :', name);
+  if (nothing) console.log('  learned     : none (recorded as such, and countable)');
+  console.log('  task        :', task.ref, `(${task.source}${task.id ? ', id ' + task.id : ''})`);
+  console.log('  content_hash:', P.contentHash(doc));
+  console.log('  prev        :', prev || '(genesis)');
+  process.exit(0);
+}
+
+if (cmd === 'read') {
+  const depth = Number(flag('depth', '3'));
+  const { ordered, problems } = chain();
+  if (!ordered.length) { console.log('  (no entries yet)'); process.exit(0); }
+  if (problems.length) console.log(`  ! ${problems.length} structural problem(s) — run: diarium verify\n`);
+  console.log(`  walking back ${depth} hop(s) from the head of ${ordered.length} entries\n`);
+  for (const { f, d } of ordered.slice(-depth).reverse()) {
+    const st = d.state, v = st.data.entry?.value ?? {};
+    console.log(`  ── ${st.id.ust_id}  ·  task ${v.task?.ref ?? v.task ?? '?'}${v.learned === 'none' ? '  ·  learned: none' : ''}`);
+    console.log('  ' + String(v.text ?? '').split('\n').join('\n  ') + '\n');
+  }
+  process.exit(0);
+}
+
+if (cmd === 'verify') {
+  const { ordered, problems } = chain();
+  const present = files();
+  if (!present.length) { console.log('  (no entries yet)'); process.exit(0); }
+  // Every file PRESENT, not just the chain-reachable ones: a tampered entry falls out of the chain, and verifying only
+  // what is reachable would leave its broken seal unreported.
+  const broken = [];
+  for (const f of present) {
+    let d; try { d = load(f); } catch { broken.push(`${f}: not parseable JSON`); continue; }
+    const v = P.verify(d, { context: 'data' });
+    if (v.result !== 'VALID:LIGHT') broken.push(`${f}: seal does NOT verify — ${v.result || v.error}`);
+  }
+  // Broken seals lead. A tampered entry is the FINDING; the orphans and extra heads it produces are consequences, and
+  // printing them first buries the one line that says what actually happened.
+  const fails = [...broken, ...problems];
+  if (fails.length) {
+    console.error(`✗ verify FAILED (${ordered.length} in chain, ${present.length} file(s) present):`);
+    for (const x of broken) console.error('   • ' + x);
+    if (broken.length && problems.length) console.error('   — and the structural consequences of that:');
+    for (const x of problems) console.error('   • ' + x);
+    process.exit(1);
+  }
+  console.log(`✓ ${ordered.length} entries: every seal verifies, one genesis, one head, no fork, no orphan (order from the chain — filenames are cosmetic)`);
+  process.exit(0);
+}
+
+if (cmd === 'render') {
+  for (const { f, d } of chain().ordered) {
+    const st = d.state, v = st.data.entry?.value ?? {};
+    console.log(`${v.text}\n\n<sub>${f} · task ${v.task?.ref ?? v.task} · ${st.time.generated_at}</sub>\n\n---\n`);
+  }
+  process.exit(0);
+}
+
+console.log(`diarium — a task closes, you write what you learned, it is sealed and chained
+
+  diarium scan                      what closed since last time (first run sets a baseline)
+  diarium status                    closures owing an entry (exit 1 while any is owed)
+  diarium write <ref> <file>        seal + chain + store   [--nothing-learned]
+  diarium read [--depth N]          walk the chain N hops back from the head
+  diarium verify                    every seal, one genesis, one head, no fork, no orphan
+  diarium render                    markdown to stdout, derived, never stored
+
+The store is ./diarium/ — rules.md is prose you may rewrite, settings.json is structure.`);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "diarium",
+  "version": "0.1.0",
+  "description": "Agent memory as a verifiable UST stream — a task closes, the agent writes what it learned, the entry is sealed and prev-chained. Tamper-evident, offline-verifiable, no server.",
+  "type": "module",
+  "bin": {
+    "diarium": "./bin/diarium.mjs"
+  },
+  "files": [
+    "bin/",
+    "LICENSE",
+    "README.md",
+    "FLOW.md",
+    "INTEGRATE.md"
+  ],
+  "keywords": [
+    "ust",
+    "agent",
+    "agent-memory",
+    "journal",
+    "tamper-evident",
+    "ed25519",
+    "provenance"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ust-protocol": "^1.0.0-rc.32"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thelabmd/UST-Protocol.git",
+    "directory": "packages/diarium"
+  },
+  "homepage": "https://github.com/thelabmd/UST-Protocol/tree/main/packages/diarium#readme",
+  "scripts": {
+    "test": "node --test"
+  }
+}