reorg documentation

SCHEMA.md

@@ -354,6 +354,48 @@ When a near-duplicate is detected:
 
 ---
 
+## Instance manifest (`index.json` — multi-user mode)
+
+In multi-user mode, the root `index.json` is a **shard manifest** rather than a user feed. It lists pointers to per-user BAS feeds. The browser fetches all shards concurrently and merges them.
+
+```json
+{
+  "bas_version": "1.0",
+  "instance": {
+    "name": "Our Rides",
+    "private": true
+  },
+  "generated_at": "2026-04-07T10:00:00Z",
+  "shards": [
+    { "handle": "dave",  "url": "dave/_merged/index.json" },
+    { "handle": "alice", "url": "alice/_merged/index.json" },
+    { "handle": "bob",   "url": "https://bob.example.com/index.json" }
+  ],
+  "activities": []
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `instance.name` | string | Human-readable instance name. |
+| `instance.private` | boolean | If `true`, the site redirects unauthenticated visitors to `/login/`. |
+| `shards` | array | Per-user shard entries. |
+
+### Shard object (multi-user)
+
+| Field | Type | Description |
+|---|---|---|
+| `handle` | string | User handle. Used for attribution (activities show `@handle`). |
+| `url` | string | Relative or absolute URL to the user's `index.json`. |
+
+The `url` field is relative to the location of the root manifest. Absolute URLs (starting with `http`) are fetched cross-origin — this is the federation mechanism.
+
+Each user's `{handle}/index.json` is a valid standalone BAS feed. It can be used independently or included in another instance's shard manifest (federation).
+
+---
+
 ## Versioning
 
 The `bas_version` field allows consumers to handle schema evolution. Consumers