From 8615a5c6da2ee331bfdb3b3d1b9a6e70b8b7fc91 Mon Sep 17 00:00:00 2001
From: Vernon Stinebaker <vernon.stinebaker@gmail.com>
Date: Mon, 28 Sep 2026 22:12:41 +0800
Subject: [PATCH 1/2] docs: add AGENTS.md engineering protocol and
 CONTRIBUTING.md

Captures the gateway wire-protocol compatibility contract (protocol/ and
session/ as the compatibility surface), the dual build targets (app +
NullHub module.js), and the validation gates.
---
 AGENTS.md       | 36 ++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md |  9 +++++++++
 2 files changed, 45 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CONTRIBUTING.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..801c0ba
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,36 @@
+# AGENTS.md — NullClaw Chat UI Engineering Protocol
+
+Default working protocol for coding agents in this repository. Scope: entire repository.
+
+## 1) Project Snapshot
+
+The chat surface for NullClaw: a SvelteKit app served two ways — as a web app
+(vite dev/build) and as a dynamically-mounted UI module (`npm run build:module`
+→ `module.js`, consumed by NullHub's module loader). TypeScript + Svelte 5.
+
+Transport contract: WebSocket to the NullClaw gateway's `channels.web` endpoint
+(default `ws://127.0.0.1:32123/ws`), end-to-end encryption (X25519 + ChaCha20),
+PIN/token pairing. The protocol lives in `src/lib/protocol/` and the session
+controller in `src/lib/session/` — treat these as the compatibility surface.
+
+## 2) Engineering Principles
+
+- The gateway wire protocol is a compatibility contract: changes must be
+  backward-compatible or explicitly versioned, and tested against a running
+  `nullclaw gateway`.
+- No secrets in the repo or logs; pairing tokens are ephemeral client-side state.
+- Deterministic tests: `npm test` (vitest) must pass; no network in unit tests.
+
+## 3) Validation
+
+```bash
+npm install          # node 20+, npm 10+
+npm test             # vitest — required before every commit
+npm run check        # svelte-check — required before every commit
+npm run build        # app build must succeed
+npm run build:module # module.js must build (NullHub consumption)
+```
+
+## 4) Contribution flow
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..61187bc
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,9 @@
+# Contributing to NullClaw Chat UI
+
+1. **Read [AGENTS.md](AGENTS.md)** first — the gateway wire protocol is a
+   compatibility contract and the validation gates live there.
+2. One concern per PR. No drive-by refactors.
+3. Before every commit: `npm test`, `npm run check`, `npm run build`,
+   `npm run build:module` — all must pass.
+4. Every PR runs CI. Keep it green.
+5. Bug fixes must include a regression test citing the issue number.

From 5934c521c259db8dada71bdb1d40a78176c78628 Mon Sep 17 00:00:00 2001
From: Vernon Stinebaker <vernonstinebaker@users.noreply.github.com>
Date: Sat, 3 Oct 2026 23:51:33 +0800
Subject: [PATCH 2/2] docs(agents): name ChaCha20-Poly1305; describe real auth
 storage contract (DonPrus review)

---
 AGENTS.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 801c0ba..b5978b0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,7 +9,7 @@ The chat surface for NullClaw: a SvelteKit app served two ways — as a web app
 → `module.js`, consumed by NullHub's module loader). TypeScript + Svelte 5.
 
 Transport contract: WebSocket to the NullClaw gateway's `channels.web` endpoint
-(default `ws://127.0.0.1:32123/ws`), end-to-end encryption (X25519 + ChaCha20),
+(default `ws://127.0.0.1:32123/ws`), end-to-end encryption (X25519 + ChaCha20-Poly1305),
 PIN/token pairing. The protocol lives in `src/lib/protocol/` and the session
 controller in `src/lib/session/` — treat these as the compatibility surface.
 
@@ -18,7 +18,8 @@ controller in `src/lib/session/` — treat these as the compatibility surface.
 - The gateway wire protocol is a compatibility contract: changes must be
   backward-compatible or explicitly versioned, and tested against a running
   `nullclaw gateway`.
-- No secrets in the repo or logs; pairing tokens are ephemeral client-side state.
+- No secrets in the repo. Keep tokens and keys out of logs; persisted browser
+  auth must respect its TTL and be cleared on rejection.
 - Deterministic tests: `npm test` (vitest) must pass; no network in unit tests.
 
 ## 3) Validation