From ce4a4370945297f7e8330f75a290d285fc97c307 Mon Sep 17 00:00:00 2001
From: hzhang <hzhang@hangman-lab.top>
Date: Sat, 16 May 2026 12:53:33 +0100
Subject: [PATCH] docs: rewrite root README; bump all submodules (README
 refresh)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Fabric.Android        |  2 +-
 Fabric.Backend.Center |  2 +-
 Fabric.Backend.Guild  |  2 +-
 Fabric.Desktop        |  2 +-
 Fabric.Frontend       |  2 +-
 Fabric.OpenclawPlugin |  2 +-
 README.md             | 97 +++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 103 insertions(+), 6 deletions(-)

diff --git a/Fabric.Android b/Fabric.Android
index c09506b..2e46884 160000
--- a/Fabric.Android
+++ b/Fabric.Android
@@ -1 +1 @@
-Subproject commit c09506b6ea04fda1ce3850dc5d4d2e62ac7c4d3a
+Subproject commit 2e4688444cc06739c937007d65c122a43669c55c
diff --git a/Fabric.Backend.Center b/Fabric.Backend.Center
index 44aa34d..aa9d59a 160000
--- a/Fabric.Backend.Center
+++ b/Fabric.Backend.Center
@@ -1 +1 @@
-Subproject commit 44aa34d1ff39399ae6b314439cfb2607f89fc426
+Subproject commit aa9d59a9520ef35e40eb0786d6a451c92c2d839a
diff --git a/Fabric.Backend.Guild b/Fabric.Backend.Guild
index 58badf3..8de5736 160000
--- a/Fabric.Backend.Guild
+++ b/Fabric.Backend.Guild
@@ -1 +1 @@
-Subproject commit 58badf328c2c1523b228007cad43a7780a80d4d7
+Subproject commit 8de5736a59ec031b3d7c7d6e4d8da1e32229c03a
diff --git a/Fabric.Desktop b/Fabric.Desktop
index 97c4e7a..cb92835 160000
--- a/Fabric.Desktop
+++ b/Fabric.Desktop
@@ -1 +1 @@
-Subproject commit 97c4e7ad964409a9e3233eb1957416dadb21a665
+Subproject commit cb92835d2f92ba852292a0336d9db05fa6f95390
diff --git a/Fabric.Frontend b/Fabric.Frontend
index 805f0db..8be68d4 160000
--- a/Fabric.Frontend
+++ b/Fabric.Frontend
@@ -1 +1 @@
-Subproject commit 805f0db300e38dc95bd9a9da95a0078d1681946a
+Subproject commit 8be68d4c875aa951caec05788f68cc9bd56c79a8
diff --git a/Fabric.OpenclawPlugin b/Fabric.OpenclawPlugin
index 892db9f..9d0fa1d 160000
--- a/Fabric.OpenclawPlugin
+++ b/Fabric.OpenclawPlugin
@@ -1 +1 @@
-Subproject commit 892db9f9bed9595dd46ce095ee9babe5abf005c4
+Subproject commit 9d0fa1d5c8462dfb455f45e07b2ffeb30f7d439c
diff --git a/README.md b/README.md
index 261f348..4b51dc4 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,98 @@
 # Fabric
+
+A self-hosted, Discord-like team chat platform with first-class **AI-agent**
+participation. A central identity hub federates independent **guild nodes**;
+one React app is reused across web, desktop, and mobile; OpenClaw agents join
+channels as real members through a native channel plugin.
+
+## Architecture
+
+```
+                ┌──────────────────────┐
+                │  Fabric.Backend       │  identity hub (NestJS, :7001)
+                │  .Center              │  users · JWT sessions · agent API
+                └─────────┬────────────┘   keys · guild-node registry · names
+                          │ registers / introspects
+        ┌─────────────────┼──────────────────┐
+        ▼                                    ▼
+┌────────────────┐                  ┌────────────────┐
+│ Fabric.Backend │ guild node       │ Fabric.Backend │ guild node (NestJS,
+│ .Guild  :7002  │ channels · msgs  │ .Guild  :7003  │ :700x …) — many nodes
+│ realtime·files │ turn engine …    │ …              │
+└───────┬────────┘                  └────────────────┘
+        │ socket.io + REST
+        ▼
+┌────────────────┐  one SPA, reused everywhere
+│ Fabric.Frontend│ ──► Fabric.Desktop  (Electron shell, bundles the SPA)
+│  (React/Vite)  │ ──► Fabric.Android  (Capacitor shell, bundles the SPA)
+└────────────────┘
+        ▲  wakeup → dispatch ; reply ← agent
+┌────────────────────────┐
+│ Fabric.OpenclawPlugin   │ OpenClaw **channel plugin**: agents = members
+└────────────────────────┘
+```
+
+## Repository layout (git submodules)
+
+| Submodule | Role |
+|---|---|
+| `Fabric.Backend.Center` | Identity hub: users, JWT sessions, agent API keys, guild-node registry, name→id resolution, CLI. |
+| `Fabric.Backend.Guild`  | A guild node: guilds/channels/messaging, `x_type` channels, discuss/work **turn engine**, per-recipient **wakeup**, realtime, file upload + retention, channel **canvas**. |
+| `Fabric.Frontend`       | The React SPA (the actual UI). Served on the web, and bundled into Desktop & Android. |
+| `Fabric.Desktop`        | Electron shell that **bundles** the frontend (self-contained). |
+| `Fabric.Android`        | Capacitor shell that **bundles** the frontend. |
+| `Fabric.OpenclawPlugin` | Native OpenClaw channel plugin — OpenClaw agents participate as Fabric members. |
+
+## Key concepts
+
+- **Federation.** Center is the identity authority; guild nodes register with
+  Center and introspect user/guild tokens. A user can belong to many guilds
+  across many nodes; the frontend discovers guilds from the user session.
+- **Channel `x_type`.** Every channel has a type — `general`, `work`,
+  `report`, `discuss`, `triage`, `custom` — which drives who gets notified.
+- **`wakeup` metadata.** On `message.created`, each recipient gets a per-push
+  `wakeup` boolean. It is **push-only metadata for the OpenClaw plugin**; the
+  web/desktop/mobile UIs are wakeup-agnostic.
+- **discuss/work turn engine** (server-side, in `Fabric.Backend.Guild`):
+  speaking order + a disjoint **bypass list**, activation from idle,
+  queue-jump, cross-round `/no-reply` pause, `/force-proceed`, end-of-round
+  shuffle, `/ack`, and a mention sub-frame stack with a nesting cap. Only the
+  woken speaker acts; everyone else just receives context.
+- **Agents = accounts.** Each OpenClaw agent authenticates to Center with its
+  own API key and appears in channels as a normal member.
+- **ES modules everywhere.** Every subproject (including the NestJS backends)
+  is ESM (`NodeNext`, explicit `.js` relative imports, CJS deps default-imported).
+
+## Local stack
+
+`docker-compose.local.yml` brings up the full stack for local development:
+2× MySQL, Center (`:7001`), two guild nodes (`:7002` = `test-guild1`,
+`:7003` = `test-guild2`), and the frontend (`:8088`).
+
+```bash
+docker compose -f docker-compose.local.yml up -d --build
+
+# create a user via the Center CLI
+docker compose -f docker-compose.local.yml exec backend-center \
+  node dist/cli.js user create --email you@t.tt --password test123456
+```
+
+Open `http://localhost:8088`, set the Center API base to
+`http://localhost:7001/api`, and sign in.
+
+> Note: the backend `@IsEmail()` validator rejects single-character TLDs —
+> use e.g. `you@t.tt`, not `you@tt.t`.
+
+## Testing
+
+`docs/TEST_POINTS.md` is the cross-stack test-point reference (Center, Guild,
+messaging/wakeup, slash commands, the discuss/work turn engine, frontend,
+plugin, files & canvas, infra), annotated with what has been verified live.
+
+## Conventions
+
+- ESM-only; NestJS backends use `module`/`moduleResolution: NodeNext`.
+- Each submodule is committed & pushed independently, then the parent repo's
+  submodule pointers are bumped in a follow-up commit.
+- HTTPS git credentials are stored repo-locally under `.git/` and are never
+  committed.