From 9bbaeb7b07c699b60fec5239c3af8a3c03925397 Mon Sep 17 00:00:00 2001 From: Rasmus Widing Date: Tue, 28 Jul 2026 20:09:14 +0300 Subject: [PATCH] docs: the drain is a POST, and the model doc said GET MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/model.html` — the current-model document, not a historical one — listed the inbox drain as `GET /api/kilds/:id/inbox?as=`. The engine serves `POST /api/kilds/:id/inbox/drain`. Wrong method and wrong path. The method is wrong in the exact way the route deliberately guards against. Its own comment: "POST, never GET: this MUTATES, so a caching proxy or a retry on a GET would silently eat somebody's messages." So the doc pointed a client at the thing the engine refuses to offer, for a reason the engine had already written down. Found by checking every route the doc names against every route the server registers. That was the only mismatch — the rest are accurate, and the dead verbs elsewhere in the file (`kild room open`, `room join`) are all in a "Was" column, which is what that column is for. Sixth instance of a pattern helm's agent named today and hit again an hour ago with a stale `--room` in their AGENTS.md: THE THING THAT VERIFIES IS THE THING NOBODY VERIFIES. Instructions are verification too — they tell the next reader what to check against — and nothing checks them. --- docs/model.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/model.html b/docs/model.html index 59ee772b..a3937ad6 100644 --- a/docs/model.html +++ b/docs/model.html @@ -609,7 +609,7 @@

REST — the command surface

POST /api/kilds/:id/agentsSpawn an owned agent into the kild (handle, persona, model).invite_agent / room_add POST /api/kilds/:id/agents/attachRegister an attached agent — the honryo. Idempotent; addressable at once.joinRoom (room join) POST /api/kilds/:id/messagesSend — { from, to[], text } into recipients' inboxes.postRoom / room_post - GET /api/kilds/:id/inbox?as=Drain an attached agent's inbox (the pull side).drainRoom (room drain) + POST /api/kilds/:id/inbox/drainDrain an attached agent's inbox (the pull side). POST, never GET — it MUTATES, so a cache or a retry on a GET would silently eat somebody's mail.drainRoom (room drain) GET /api/kildsList + observe: participants, git status, cost rollup, collisions.getLiveRooms / rooms_status GET /api/kilds/:idOne kild — detail + full message log.room show / room log POST /api/kilds/:id/landMerge toward base; return the collision/merge report.new — was implicit prune