@dreamforgestudiollc/emet 0.0.0-stage → 0.2.4

package/docs/GUIDED-SETUP.md

@@ -0,0 +1,296 @@
+# Guided setup — let your AI set EMET up for you
+
+This is the path for someone who has never deployed anything. You do three things in a
+browser when asked. Your AI does everything else — installs, configures, deploys, verifies —
+and tells you what it did at each stage.
+
+**Part A** is for you. It is short. **Part B** is for your AI; you do not need to read it.
+
+---
+
+## Part A — for the person
+
+### What you are setting up
+
+A memory your AI keeps between conversations, on every device you use — it is a small server
+plus a database, and your AI will hold the whole thing together from here. When it is done,
+you say **"initialize"** at the start of a conversation and your AI picks up where it left
+off.
+
+### What you need before you start
+
+- **Claude** (or another MCP-capable assistant) — and a way for it to run commands on your
+  computer. See *Giving your AI a shell* below. This is the one step you do yourself.
+- **About 30–45 minutes**, mostly waiting.
+- **An email address** for two free accounts: MongoDB Atlas (the database) and Railway (the
+  host). Atlas's free tier needs no card. Railway may ask for a card or a small plan for an
+  always-on server — check what it shows you at sign-up; your AI will tell you the moment it
+  needs you there.
+
+### Giving your AI a shell
+
+Your AI can only set things up if it can run commands. Pick whichever of these matches what
+you have:
+
+| You use | What to do |
+|---|---|
+| **Claude Desktop (the app)** | Install **Desktop Commander**, an MCP server that gives Claude a terminal and file access. Run this in a terminal: `npx @wonderwhy-er/desktop-commander@latest setup` (needs Node.js — <https://nodejs.org>, LTS). Then **fully quit and restart Claude Desktop.** Other installers: <https://github.com/wonderwhy-er/DesktopCommanderMCP>. |
+| **Claude Code (the terminal tool)** | Nothing. It already has a shell. |
+| **Claude Cowork** | Nothing. It has its own shell. |
+
+One honest note about Desktop Commander: it can run any command you could run. That is what
+makes guided setup possible, and it is also why you should read what your AI says it is about
+to do. Per-step approval in Claude Desktop is the safety net — keep it on.
+
+### Starting
+
+Paste this into a new conversation:
+
+> Set up EMET for me. Fetch `https://raw.githubusercontent.com/dreamforgestudiollc/EMET/main/docs/GUIDED-SETUP.md`, read Part B, and follow it stage by stage. Ask me only when a step needs me — I will sign in to things when you tell me to. I want the remote (phone-reachable) server too.
+
+(Drop the last sentence if you only want it on this one computer. If the link does not open
+for your AI — the repository may be private — download this file and paste Part B into the
+conversation instead.)
+
+### The three moments you will be asked to act
+
+1. **Sign in to MongoDB Atlas** — a browser window opens; create an account or sign in. Your AI waits.
+2. **Sign in to Railway** — same shape. If Railway asks for a card or a plan, that is between you and Railway; your AI will pause until you are through.
+3. **Add the connector in Claude** — Settings → Connectors → *Add custom connector* → paste the URL your AI gives you → enter the passphrase it gives you. Enable it in your conversation from the **+** menu.
+
+Then say **"initialize"**. Your AI will ask you a few questions about who it should be and who you are. That is the setup interview, and it is the part that turns a database into a memory.
+
+### Keep two things
+
+Your AI will hand you a **passphrase** and a **URL** at the end. Keep both somewhere safe. The passphrase is the whole perimeter of your memory — there is no second factor.
+
+### Every conversation from now on: two words
+
+**"initialize"** as your first message — your AI loads who it is, who you are, and where you
+left off. **"wrap up"** as your last — it writes the handoff, the state, a session entry and
+the word-for-word transcript, then confirms with `emet_session_close` that everything landed.
+Wait for it to say **complete** before you close the window. Skip the first and it answers from
+guesswork; skip the second and the next session inherits a hole. The README's *Every session
+after that* section says why.
+
+---
+
+## Part B — for the AI
+
+You are setting up EMET for a person who may never have done anything like this. Your job is to
+do every step you can, ask for exactly the steps you cannot, verify each stage before the next,
+and report plainly. Read all of Part B before running anything.
+
+### Rules that hold for the whole procedure
+
+1. **Never put a secret in the conversation.** Not the connection string, not the passphrase,
+   not a token. Write them to files and environment variables with your tools. When you must
+   hand the person a value (the passphrase, once), say what it is for and where to keep it.
+   EMET masks secrets in anything written to its own store; the chat you are in is not that store.
+2. **Generate the passphrase yourself.** 24+ characters, letters and digits, no ambiguous
+   glyphs — `node -e "console.log(require('crypto').randomBytes(18).toString('base64url'))"`.
+   Do not ask the person to invent one.
+3. **Verify before proceeding.** Every stage ends with a check. If the check fails, stop, show
+   the person the actual output, and say what you think it means — marked as your reading, not
+   as fact. Do not retry blindly and do not invent a cause.
+4. **Ask only at the three human moments** (Atlas sign-in, Railway sign-in, connector add) and
+   when a command genuinely needs something only they have. Everything else is yours.
+5. **One machine at a time.** If you are running in a cloud sandbox rather than on the person's
+   computer, say so, and know that local-server config (stage 2) must be written on *their*
+   machine, not yours.
+6. **Report each stage in two or three sentences.** What you did, what you verified, what is next.
+
+### Stage 0 — check the ground
+
+```
+node --version        # need 20+ (package.json engines); 22 preferred
+npm --version
+git --version
+```
+
+If `node` is missing: on Windows `winget install OpenJS.NodeJS.LTS`; macOS `brew install node`;
+Linux via the distribution package or <https://nodejs.org>. If `git` is missing, download the
+repository as a zip instead of cloning.
+
+Then get the code:
+
+```
+git clone https://github.com/dreamforgestudiollc/EMET.git
+cd EMET
+npm install
+```
+
+**Verify:** `node -e "import('./src/layers.js').then(m => console.log(Object.keys(m.LAYER_CHARTER).length + ' layers'))"` prints `6 layers`.
+
+### Stage 1 — the database (MongoDB Atlas)
+
+**Install the Atlas CLI.** Windows: download and run the `.msi` from
+<https://www.mongodb.com/docs/atlas/cli/current/install-atlas-cli/> (you can open the download
+for the person and ask them to click through; then open a fresh shell so PATH updates). macOS:
+`brew install mongodb-atlas-cli`. Linux: the apt/yum instructions on that same page. Verify with
+`atlas --version`.
+
+**Human moment 1.** Run:
+
+```
+atlas auth login
+```
+
+A browser opens. Tell the person: *"A MongoDB window has opened. Create an account or sign in — the free tier needs no card. Tell me when you are back."* Wait. Then `atlas auth whoami` must print their account.
+
+**Create everything in one command.** Generate a database password first (same method as the
+passphrase; keep it out of the chat). Then:
+
+```
+atlas setup --clusterName emet --tier M0 --username emet_app --password <generated> \
+  --accessListIp 0.0.0.0/0 --skipSampleData --skipMongosh --force
+```
+
+`--accessListIp 0.0.0.0/0` is deliberate: a hosted server's egress IP is dynamic, so it cannot
+be allowlisted, and security rests on the scoped user plus the OAuth passphrase. If the person
+wants a **local-only** setup, use `--currentIp` instead. `--force` accepts defaults for
+anything unspecified (provider and region — fine). If `atlas setup` reports it needs a project
+or organization, follow its prompt; it creates them.
+
+Cluster creation takes a few minutes. Poll:
+
+```
+atlas clusters describe emet --output json
+```
+
+until `"stateName": "IDLE"`.
+
+**Get the connection string and write `.env`:**
+
+```
+atlas clusters connectionStrings describe emet --output json
+```
+
+Take the `standardSrv` value (`mongodb+srv://emet.xxxxx.mongodb.net`) and insert the user and
+password: `mongodb+srv://emet_app:<password>@emet.xxxxx.mongodb.net/?retryWrites=true&w=majority`.
+**Percent-encode the password if it contains `@ : / ? # [ ] %`** — a generated base64url
+password will not. Copy `.env.example` to `.env` and set:
+
+```
+MONGODB_URI=<the string above>
+MONGODB_DB=emet
+EMET_SOURCE_TAG=<this computer's name, e.g. laptop>
+```
+
+**Verify:** `node -e "import('mongodb').then(async ({MongoClient}) => { const c = new MongoClient(process.env.MONGODB_URI); await c.connect(); console.log('ok', (await c.db('emet').command({ping:1})).ok); await c.close(); })"` — run with the `.env` loaded (`node --env-file=.env -e "..."` on Node 20.6+). Expect `ok 1`. If it times out, the access list has not propagated yet; wait a minute and retry once.
+
+**Skip the vector index for now.** `semantic_recall` is optional; keyword recall works without
+it, and Atlas Automated Embedding is not available on every tier. It is a later step, in
+[SETUP.md](SETUP.md) stage 1, item 7, once everything else works.
+
+### Stage 2 — the local server (this computer)
+
+This is what the person's desktop assistant talks to. It runs from the repo folder.
+
+Write the MCP client entry. For Claude Desktop, merge into `claude_desktop_config.json`
+(Windows `%APPDATA%\Claude\claude_desktop_config.json`; macOS
+`~/Library/Application Support/Claude/claude_desktop_config.json`; Linux `~/.config/Claude/claude_desktop_config.json`).
+**Read the file first and merge — do not overwrite other servers** (Desktop Commander's own
+entry is in there):
+
+```json
+"emet": {
+  "command": "node",
+  "args": ["<absolute path to repo>/src/index.js"],
+  "env": { "MONGODB_URI": "<from .env>", "MONGODB_DB": "emet", "EMET_SOURCE_TAG": "<same tag>" }
+}
+```
+
+Absolute path, forward slashes are fine on Windows. For Claude Code: `claude mcp add emet -e MONGODB_URI=<...> -e MONGODB_DB=emet -e EMET_SOURCE_TAG=<tag> -- node <absolute path>/src/index.js`, or the `.mcp.json` equivalent.
+
+**Human moment (small):** *"Fully quit Claude Desktop — from the system tray, not just the window — and open it again. Tell me when it is back."* Then, in the new conversation, the `emet` tools appear. Call `emet_status`: expect `initialized: false` and a live database. Call it again with `probe: true`: it writes a probe and reads it back — expect every check passed.
+
+If the person only wanted this computer, skip to stage 4.
+
+### Stage 3 — the remote server (phone and everything else)
+
+```
+npm i -g @railway/cli
+railway --version
+```
+
+On Windows, if the shim fails with `'"node"' is not recognized`, call the binary directly:
+`%APPDATA%\npm\node_modules\@railway\cli\bin\railway.exe`.
+
+**Human moment 2.** Run `railway login` (plain — not `--browserless`, which only works when
+approved on the same machine). Tell the person: *"A Railway window has opened. Create an account
+or sign in. If it asks for a card or a plan, that is Railway's requirement for an always-on
+server — decide there and tell me when you are through."* Wait. `railway whoami` must print them.
+
+**Create the project and set variables BEFORE the first deploy** — a server that boots once
+misconfigured leaves residue:
+
+```
+railway init                      # from the repo root; name it emet
+railway variables --set MONGODB_URI=<from .env> --set MONGODB_DB=emet \
+  --set EMET_OAUTH_PASSPHRASE=<generated passphrase> --set EMET_SOURCE_TAGS=<every host's tag, e.g. laptop,phone>
+railway up --detach
+railway domain                    # prints https://<something>.up.railway.app
+railway variables --set PUBLIC_URL=https://<that host>
+railway up --detach               # second pass: PUBLIC_URL is the OAuth issuer and must match
+```
+
+Leave `EMET_SOURCE_TAG` unset on this server: several hosts share it, each host passes its own
+tag as `source` on its writes, and `EMET_SOURCE_TAGS` registers the tags. A default tag would
+make every host look the same; set one only on a server a single host uses.
+
+The repository's `Dockerfile` already starts the HTTP transport; no start command to set. The
+two-pass deploy is not optional. **Never run `railway variables` without `--kv` and never paste
+its output anywhere** — it prints secrets in plaintext.
+
+**Verify** (build takes about two minutes; poll):
+
+```
+curl https://<host>/health                                  → {"ok":true,"service":"emet","tools":N,...}
+curl https://<host>/.well-known/oauth-authorization-server  → OAuth metadata, not a 404
+```
+
+A 404 on the second means `PUBLIC_URL` is wrong. The connector URL is `https://<host>/mcp` —
+**the `/mcp` suffix is required**; the root path is 404 by design.
+
+**Human moment 3.** Tell the person, exactly: *"Open Claude → Settings → Connectors → Add custom
+connector. Name: EMET. URL: `https://<host>/mcp`. Click connect — you will be sent to a
+passphrase page. The passphrase is: `<passphrase>` — keep it; it is the only key to your memory.
+Then enable EMET in this conversation from the + menu and tell me."*
+
+**Verify from the remote route:** `emet_status` with `probe: true` through the connector. Then the real
+test — `remember` something on one route and `recall` it on the other. If both see it, the
+deployment is real.
+
+### Stage 4 — the interview
+
+Say nothing about setup. Call `emet_initialize`. On a new store it returns `setup_required` and
+the interview questions. Ask them **conversationally, one at a time** — what the assistant should
+be called and how it should carry itself, the person's name in the form they want used, what the
+memory is for, and optionally how they want to be worked with and this host's tag. Then
+`emet_setup_complete`. It refuses partial answers rather than inventing an identity; that is
+correct behaviour.
+
+Then hand the person the short instruction block from [BOOTSTRAP.md](BOOTSTRAP.md) to paste
+into their project instructions, so future sessions consult the memory without being told.
+
+### Stage 5 — close out
+
+Tell the person, in plain words:
+
+- what was set up (local server, remote server, or both) and where the code lives on disk;
+- the connector URL and that the passphrase is the whole perimeter — rotate it by changing
+  `EMET_OAUTH_PASSPHRASE` on Railway and redeploying, which invalidates every device;
+- that every host has its own source tag (a local entry's `EMET_SOURCE_TAG`; on the shared
+  remote server, the `source` each host passes, registered in `EMET_SOURCE_TAGS`), and what
+  this one's is;
+- that `emet_status` (and `emet_status` with `probe: true`) is the thing to call when
+  something seems wrong, and [SETUP.md](SETUP.md) has the symptom table;
+- that after any future deploy which changes the tool list, each device must reconnect the
+  connector to see the new tools — nothing breaks, the new ones just stay invisible until then.
+- that if they later run other agents (bots) against the same memory, each needs its own tag,
+  its own handoff and a roster row before its first write — [BOTS.md](BOTS.md) is the procedure,
+  and their own assistant's tag (the hub) is never listed as a bot.
+
+Do not summarise what the person told you in the interview back at them. It is stored; they
+know what they said.

package/docs/PERMISSIONS.md

@@ -0,0 +1,118 @@
+# Permissions and approvals
+
+How to decide what EMET may do without being asked each time, and how to set it.
+
+---
+
+## Where the boundary can live
+
+There are three places, and it is worth being clear about which is which:
+
+- **The host** decides *what gets called* and *what data goes into the call*. Approval prompts,
+  allow-lists and "always allow" settings all live here.
+- **The server** decides *what it will do when asked*. Refusing an operation, versioning a write,
+  archiving before replacing, checking the order of a session's writes (the monorail) - all here.
+- **The database** decides *what the server's own login may do*. EMET's login runs under the
+  least-privilege role `emetRecordKeeper` ([SETUP.md](SETUP.md), `src/atlas-role.js`): it can
+  insert and update, and it has no permission to remove anything from the record. So "nothing is
+  deleted" holds even against a bug in the server, not only against a model's choice.
+
+No layer can widen another. In particular, **a server cannot grant itself permission**. Nothing in
+this repository can stop your host from asking you to approve every call, and nothing in it should
+be able to.
+
+What a server *can* do is describe itself accurately enough that a host has something to reason
+with. That is what tool annotations are.
+
+---
+
+## What EMET declares
+
+Every tool carries MCP annotations, declared in one table in `src/annotations.js`:
+
+| Hint | Meaning |
+|---|---|
+| `readOnlyHint` | The tool does not modify anything. |
+| `destructiveHint` | It may replace or remove existing data. |
+| `idempotentHint` | Calling it again with the same arguments changes nothing further. |
+| `openWorldHint` | It reaches systems outside this server's own store. |
+
+Of the 29 tools:
+
+- **11 are read-only.** `emet_gaps`, `emet_floor`, `recall`, `semantic_recall`,
+  `corpus_recall`, `query_layer`, `query_transcripts`, `read_doc`, `read_doc_history`, `list_docs`,
+  `validate_doc`. These cannot change the store under any arguments.
+- **10 are additive writes.** `emet_initialize` (it provisions a missing board), `save_to_layer`, `revise_memory`, `save_transcript`,
+  `revise_transcript`, `emet_session_open`, `emet_transcript_append`, `emet_session_close` (it
+  records blocked attempts), `rename_doc`, `accept_nonconformance`. They add; they do not remove or replace.
+  `emet_session_open` still needs the `emet.write` scope, because it stamps the drop list a board edit trusts.
+  `emet_initialize` stays a read.
+- **6 can replace what is already there, or hand out access.** `write_doc`, `patch_doc`, `restore_doc`, `emet_setup_complete`,
+  `emet_invite_create`, `emet_member_access_create`. Prior versions of a document are archived to the history
+  collection first, but the visible content a person may be relying on is replaced. A code that grants access
+  is marked the same way: it is not a harmless add.
+- **1 marks a document obsolete.** `retire_doc`. Neither a removal nor a replacement: the
+  document keeps its id and its full content, `read_doc` still returns it, and `list_docs`
+  keeps it after the current documents, marked with the date it was retired and what replaced
+  it. Idempotent — retiring an already-retired document reports
+  the existing mark rather than making a second one.
+- **1 reads, and on request writes a probe and removes it.** `emet_status`. Deliberately not
+  declared read-only: with `probe: true` it writes, and a health check that only reads cannot
+  detect a broken write path. A read-scoped token may call it without `probe`. With `probe: true` it needs
+  `emet.write`. The probe deletes only that document. It does not drop the collection.
+
+**`openWorldHint` is false on every tool.** The tools talk to this server's configured database
+and nothing else: no filesystem and no shell. The sign-in server fetches a client's metadata
+document, and only from a public address it has already checked. That is the main reason a memory
+server can reasonably be given standing permission when other servers should not.
+
+`src/annotations.js` is the complete statement of what EMET does to a store. It is short on
+purpose: anyone deciding how much to approve should be able to read it in one screen and check it
+against the code.
+
+---
+
+## Choosing a posture
+
+The question worth asking is not "how much do I trust this server" but **"what does a wrong call
+actually cost, and can I get back what it took?"**
+
+- **Reads cost nothing and cannot be wrong destructively.** Approving them individually spends
+  attention on the calls that carry no risk, and a session is mostly reads. Standing approval for
+  the read-only group is the change that removes most of the friction.
+- **Additive writes are recoverable by construction.** Layer entries are superseded rather than
+  edited, so a bad entry is visible and correctable but never overwrites what it corrects.
+- **Replacing writes are recoverable but not free.** The prior version is archived, so nothing is
+  destroyed; you may still want to see these, particularly early on, because a wrong `write_doc`
+  is silently a *different document* rather than an error.
+
+A reasonable default for most users: **standing approval for reads, per-call or standing for
+additive writes according to taste, and eyes on the replacing writes, including setup and the two access doors.**
+
+**Do not carry this posture across to other servers.** It rests on `openWorldHint` being false and
+on every write being versioned. A filesystem or shell server has neither property: there, a single
+wrong call can do something no archive brings back, and per-call approval is the actual safety
+mechanism rather than an inconvenience.
+
+---
+
+## Setting it
+
+Approval settings are host-side. The exact wording differs between hosts and changes over time,
+so look for the per-tool or per-connector permission settings in whichever host you have connected
+EMET to, and grant standing approval to the tools you have decided on.
+
+---
+
+## When the prompting suddenly increases
+
+**A host's remembered approvals are tied to the tool list it has cached.** When a server adds or
+renames tools, the host is looking at a list it has not seen before, and previously granted
+approvals may no longer match. Reconnecting the server to refresh its tool list is normal after an
+upgrade; being asked to approve things you had already approved is the usual symptom, and it
+settles once the new list is approved.
+
+If prompting stays heavy after that, the thing to check is whether the annotations are actually
+reaching the host: `emet_initialize` and any tool listing should show them. A host that receives no
+annotations has no way to distinguish `read_doc` from `write_doc`, and the correct behaviour for
+such a host is to ask about both.

package/docs/ROADMAP.md

@@ -0,0 +1,59 @@
+# EMET — Next Steps and Proposed Features
+
+Status as of 2026-10-07. This is a working roadmap, not a commitment: items move when the owner rules on them. Nothing here is built unless it says so.
+
+## Where things stand
+
+- **Live:** 29 tools (11 read-only); layer writes and reads native to MongoDB; server-side checks on session start and close (machine line on the first transcript append, blocked-close cap with scope, pending lessons at startup); receipts required at close; the handoff is a record, superseded and never amended.
+- **The aleph** verifies every write by reading it back before any receipt, and every later read by its digests, signature and place in its layer's hash chain. `emet_gaps` walks the whole chain for any host.
+- **Guardrails & Monorails** ([docs/GUARDRAILS-AND-MONORAILS.md](GUARDRAILS-AND-MONORAILS.md)): the server checks the order of a session's writes. Enforce only since 0.2.1 (deployed 2026-10-03; report mode 2026-09-29 to 2026-10-03): every skipped step is refused with the way to pass, and every check is stored as a timestamped lab result.
+- **The database** login runs under the least-privilege role `emetRecordKeeper`: it can insert and update, never remove the record.
+- **Startup load:** since 0.2.1, `emet_initialize` is served in pages of at most 18,000 bytes as received (on a live-sized store, five pages totalling about 68 KB as received, or about 64 KB whole), so a host that cuts long results short still reads all of it; `page: "all"` returns it whole on a host with no size limit.
+
+## Next steps, in order
+
+1. **Monorail: enforce only** (decided and deployed 2026-10-03, release 0.2.1). Every skipped step is refused and the refusal says how to pass; there is no report mode or off switch. Every host and scheduled routine must now read its startup, open a session with its `load_id`, and pass the `session_id` on its writes.
+2. **Admission test on the proposed items.** Every proposed feature below answers the four questions of charter commitment 6 before it is built (2026-09-30 read: the compiled-pages pilot passes; the lint pass needs a named measure; hybrid search, graph links and confidence scores do not pass yet).
+3. **Initialize payload trim.** Character document trim; measure the payload again.
+4. ~~**Register or retire the `cloud-scheduled-intake` source tag.**~~ Retired 2026-10-02 (the owner, a decision record, item 7): it is a legacy tag; the weekly intake now runs under `intake-bot`, with no `session_id` on its writes; under enforce-only those writes are refused (`no_session`) until it opens a session with its startup's `load_id` (item 1). The existing rows keep counting as ambiguous in `emet_gaps` rather than being re-attributed, and the count stops growing as long as nothing new is written under the old tag. The prefix `cloud-scheduled-<task>` does not count as registered. Only an exact tag in `EMET_SOURCE_TAGS` is accepted, and a refusal does not publish the list.
+5. **Monorail switches.** Small logic at each junction where a session's flow must fork, routing it to the right guardrail space: tripped only by its condition, like a transistor; no hosted model, no API; each designed from the function it serves and the flow of information and tasking through it ([GUARDRAILS-AND-MONORAILS.md](GUARDRAILS-AND-MONORAILS.md), decided 2026-09-29). First candidate junctions come with the socket, where a switch picks the GEM.
+6. **The socket** — see below.
+
+## Done since the last revision (2026-09-28)
+
+- SQL translator stage 2: read path native to MongoDB; the translator and the `event` mirror column removed.
+- Test-tree pass: one shared harness; dated suites named by subject.
+- Open questions answered 2026-09-29: the lessons `shadow` block dropped, the lesson key checked at the door; a coverage number published as an input to review; the character document consolidated quarterly (first pass done, SOUL.md v7).
+- Chain verification: one MongoDB connection path with a DNS fallback, then the chain walk moved into `emet_gaps` so no host needs the repo or a shell.
+- Security audit, first pass: two findings fixed; nothing open.
+- Least-privilege Atlas role, scripted and documented for new users.
+- Provenance stamped from the transcript; semantic and procedural writes with no source refused.
+- Guardrails & Monorails and lab results.
+- Charter revised 2026-09-29 (the aleph, the monorail, the database boundary, the per-exchange transcript) and again 2026-09-30 (the admission test in commitment 6).
+
+## Proposed features and functions
+
+- **GEM socket (plug-in standard).** A GEM is a nested module inside EMET that modifies engagement; a RUNED GEM also carries tools (RUNEs). The socket must mount several GEMs, switch each on or off, and prioritise the active ones in a running schema that prevents conflicts — with a cap on sockets, a cap on active GEMs, and a priority order, because every active GEM costs the model context. Includes a developer guide for building one.
+- **Claim-status grading.** Extend provenance so every recorded claim carries a status: established, deduced, proposed, still owed, or rejected — and rejected routes stay on the record with the reason they failed. (Idea taken from a physics research corpus that grades its own claims this way.)
+- **Index-first retrieval.** Score candidates against a one-line-per-item index before opening anything, open only the best match, follow one link at most — finding is logic, not a model call. EMET already has the shape (handoff and board as router, document list as index); the work is keeping the startup router small.
+- **Composite retrieval scoring.** Live as of this revision: recall ranks by how many query words match, then by importance. Current entries come first in every order, including time order. Time order is `order: 'latest'`, or a standalone latest, newest, or most recent together with other words. That phrase only reorders rows that already match. Nothing fades or is down-weighted for age. A superseded or expired entry stays in the result, marked with its end date and what replaced it. `history: true` reads the ended entries when current ones fill the limit. A recall or layer query ranks matching rows in the store (current before ended, then keyword hits and importance, or time when you asked for the latest) and then keeps a bounded window (at least 200 rows, or 20 times the page), not the whole layer. A blank sort value comes first when ascending and last when descending.
+- **Export, import, restore-and-compare.** Not built; listed in the README's known gaps.
+- **Organizational use.** Many private EMETs and a document gateway between them. Nothing built before a named customer.
+- **Shared hive memory for AI bots (proposed 2026-09-30).** One EMET as a common memory that several agent bots read and write as users, each keeping its own memories — candidates are Grok Bot, OpenAI dots and Meta Muse, all of which can reach a remote MCP server. A GEM per bot, seated in the socket, if needed. Taken up with the socket; the first design question is each bot's source tag and scope.
+- **Compiled topic pages, pilot (proposed 2026-09-30).** After the LLM-wiki pattern: a document prefix of topic pages compiled from semantic entries. Every claim cites its entry or transcript span; a compiled page never cites another compiled page as evidence; pages are derived, never the source of truth; one compiler role builds pages, others write entries only. No database change — the document store already versions, hashes, signs and checks form. Pilot page: the hive-memory idea. Nothing added beyond what the pilot needs.
+- **Lint pass over the semantic layer (proposed 2026-09-30).** A scheduled sweep for contradictions between entries, outdated claims a newer entry supersedes, entries that should link and don't, and subjects mentioned often with no compiled page. Findings are reported, never applied automatically; corrections go through supersession. Built after the pilot page, and only once it names its measure. Design inputs from the LLM Wiki v2 review (typed links, multi-agent sync rules, drift invariants, confidence only on top of provenance) are each weighed against commitment 6 before adoption. Its idea of letting entries fade from what surfaces is not taken: nothing in EMET fades.
+- **Advisory judge for team traffic (parked).** A fast external decision model (TypeSafe's Jev was evaluated) could sort traffic and interactions when many people and hosts share one EMET. Never in the write path — no model decides what EMET stores. Not for single-user installs.
+- **Local open-weight model as a host.** A read-only trial of EMET under a locally run model, once the host machine's GPU and RAM are on record.
+- **Stranger install.** A clean-machine install by someone who has never seen EMET, to find first-run friction.
+- **Remove Dynamic Client Registration** by 2027-06-01, as MCP moves to client ID metadata documents.
+- **Public landing page (parked)** until a public publish path exists.
+
+## Design commitments these must keep
+
+- No model in the write path: EMET stores only what the assistant deliberately chose to write.
+- Controls, not reminders: a rule that matters is checked by the server.
+- Over-engineering is a defect, and the check comes before the build. Nothing is built until it
+  names the failure it fixes, what it replaces, how we will know it worked, and what keeps it
+  working (charter commitment 6). While EMET is in design it follows DMADV (define, measure,
+  analyze, design, verify); once stable, DMAIC (define, measure, analyze, improve, control).
+- Correct the record by superseding, never by editing.