From 82094e1bd0a244504f67ceca325813be7b1d19d8 Mon Sep 17 00:00:00 2001
From: MGrin <mr6r1n@gmail.com>
Date: Wed, 9 Sep 2026 18:33:22 +1200
Subject: [PATCH] AGENTS.md: one-source instruction file (MX-846)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AGENTS.md is the only instruction source; CLAUDE.md is the 11-byte
pointer `@AGENTS.md`; no `.bb/AGENTS.md`; the ceiling is stamped at the
file's current line count (MX-846).

New AGENTS.md; no instruction file before.

Verified by running, 2026-09-09:
  - npm install (rc=0)
  - bb plugin build . (rc=0, six artifacts)

Found, not fixed (out of scope for this pass):
  - `package.json` declares no `scripts` block at all — `npm test` and `npm run typecheck` both fail with `Missing script`. The managed-install workflow is the entire gate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 62 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..feccf63
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,61 @@
+<!-- agents-md ceiling: 61 lines -->
+# AGENTS.md — bb-plugin-memory-ui
+
+A browsing and curation UI over bb's agent memory: search, per-record history, forget-with-
+a-reason, and a **Sweep** view of what has been rewriting the store.
+[`README.md`](README.md) is the user-facing document and carries the design arguments —
+why there is no duplicate finder, why there is no pinning, why reasons are required. Read
+it before adding a view; two obvious features were measured and deliberately not built.
+
+## Commands, all run 2026-09-09
+
+```sh
+npm install          # rc=0
+bb plugin build .    # dist/{server,app}.js + .meta.json + app.css, rc=0
+```
+
+**There is no test suite and no typecheck in this repo.** `npm test` and
+`npm run typecheck` both fail with `Missing script` — `package.json` declares no `scripts`
+block at all. So the whole gate is the build above plus
+`.github/workflows/managed-install.yml`, which reproduces bb's managed git install
+(`npm install --omit=dev --omit=optional --ignore-scripts`, then `bb plugin build`) and
+asserts the six artifacts are non-empty. That workflow is the only thing standing between
+a runtime import parked in `devDependencies` and every real user's install.
+
+Adding a suite would be an improvement, not a formality: every claim in the Sweep and
+Conflicts views is a computation over real history with no automated check on it.
+
+## It reads another plugin's store
+
+This plugin requires the official `memory` plugin and **reads its store** — it is not the
+owner of that schema. A change here that assumes a column, a `kind` value or a
+`memory_history` shape is coupled to a repo you do not control; verify against the
+installed memory plugin rather than against this repo's expectations.
+
+## Layout
+
+| path | what it is |
+|---|---|
+| `server.ts` | every read and mutation, the FTS search, the Sweep and Conflicts queries |
+| `lib/` | shared helpers for the panel |
+| `app.tsx`, `components/`, `hooks/` | the panel, the record view, the homepage section |
+| `components.json` | shadcn config — `components/ui/**` is generated, do not hand-edit |
+
+## Conventions that differ from the defaults
+
+- **Every mutation takes a reason and writes a history entry.** Matching
+  `bb memory forget --reason`, not a silent delete. A path that drops a record without one
+  breaks the only thing that makes pruning safe.
+- **A view answers a question; it does not expose schema fields.** Standing, Unused 7d+,
+  Forgotten and Sweep are named after what a human wants to know.
+- **An empty list must say why it is empty.** Conflicts compares numbers, so two records
+  contradicting each other in words alone will never appear — the view says so, because
+  otherwise an empty list reads as "no contradictions".
+- **Sweep groups runs by author and gap, never by calendar day**, which would cut a 23:50
+  run in half and merge a day's scattered edits into one run that never happened.
+
+**Nothing about who may merge, how agents are spawned, or how the maintainer's
+machine handles secrets belongs in this file, and none of it is stated here.**
+Those are properties of a working environment, not of this project; if you are
+contributing, your own conventions apply and nothing in this repo depends on
+the maintainer's.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md