docs: own the current-NextGraph-state knowledge + boundary (lib side)

This library presents a mature-NextGraph SDK face to consumers while
compensating for the current SDK's gaps via a shared-wallet simulation. It
therefore OWNS all current-state + simulation knowledge — moved here out of the
Festipod app repo, which must treat this library as a finished SDK.

New docs/:
- nextgraph-current-state.md — what the current SDK/broker do and don't expose
  (5 store types, document=repo, per-document ReadCap, inbox not exposed, iframe
  RPC proxy, mono-user/no-global-data, wallet import constraint). Keeps the
  nextgraph-rs source pointers.
- simulation.md — how the lib emulates the mature behaviour on one shared wallet
  (shim, store!=document two axes, docCreate→private store, RepoNotFound scope
  rule, @ng-org double-proxy DataCloneError, emulated ReadCap/inbox/curator).
- decisions/ — the current-SDK ADRs (private-store-nuri-scope, sparql-delete,
  shared-wallet-login, discovery mechanism).
- fork-inbox-fallback.md — the Rust-patch/self-host route not taken.
- migration-guide.md — the checklist for when real NextGraph matures.

README: boundary framing from the lib's side + docs/ index; replaced the stale
"scaffold/stubbed" status with the actually-implemented mechanisms per source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/decisions/shared-wallet-login-flow.md

@@ -0,0 +1,64 @@
+# ADR — Shared-wallet login/logout flow
+
+**Date:** 2026-06-15 · **Status:** Accepted (frozen). The rationale behind this
+lib's **faux login** (`accounts.ts`) and why it must never touch NextGraph.
+
+## Starting constraint
+
+NextGraph login **is not programmable**: it is a **web redirect** to the broker
+page (`nextgraph.net`). The shared wallet cannot be opened silently — at least one
+broker-redirect pass is required per device. The question is therefore not "how to
+avoid the redirect" but "how to order and present it" so the UX stays coherent.
+
+## Decision — technical gate first, application "Connexion" second
+
+Two distinct auth layers, presented in this order:
+
+1. **Real layer (technical, NOT perceived as login).** The broker redirect appears
+   **immediately, before any app render**. Because it precedes the app, the user
+   reads it as a **technical access barrier to the test environment** (a beta
+   wall), **not** an application login. Same shared credentials for everyone
+   (given in the invitation, "access code" style). Once per device, then
+   persistent. **Never labelled "login."**
+2. **Application layer (perceived as THE login).** A **"Connexion"** screen =
+   **username only** (→ `localStorage`, the current principal). This is the login
+   *in the user's perception*. **No password** → declarative connection (anyone
+   takes any username — coherent with zero-security / friends). **"Déconnexion"**
+   clears **only** the username and returns to "Connexion"; it **calls no NG
+   function**.
+
+The **real logout** (`ng.session_stop` / `user_disconnect` / `wallet_close`) stays
+**hidden** (settings/debug), because it forces a new redirect.
+
+## Why (vs the rejected option)
+
+**Rejected** — faux login first, then a warning page "enter this username/password",
+then a *Continue* button triggering the redirect. Rejected: strange workflow,
+dissonant double-login, a warning page that **looks like a scam**, and the
+redirect **resurfacing mid-use** on every session expiry.
+
+**Chosen** because: the mental model stays coherent (the technical barrier not
+being perceived as login, the app-level Connexion/Déconnexion pair is complete and
+self-consistent); graceful degradation (a re-gate after a browser restart reads as
+"reconnecting to the environment", not a bug); and **similarity to the target
+infra** — the "broker redirect → app" shape is exactly the real multi-wallet flow.
+At migration you **remove the username "Connexion" screen** and the **technical
+barrier becomes the real per-user login** — the flow shape does not change.
+
+## Verified technical facts (`nextgraph-rs`, 2026-06-15)
+
+- **Session persistence: YES.** Wallet remembered iframe-side (`localStorage`
+  long-term + `sessionStorage` for the active session); on reload `init()`
+  recovers the session **without** re-triggering the redirect while the broker
+  session exists (`sdk/js/web/src/index.ts`, `sdk/js/api-web/main.ts`). A full
+  browser restart (losing `sessionStorage`) can re-trigger the gate.
+- **Real logout exposed: YES.** `ng.session_stop()`, `ng.user_disconnect()`,
+  `ng.wallet_close()` (`sdk/js/lib-wasm/src/lib.rs`); they stop the session /
+  clear the wallet and **force a new redirect** afterwards — hence: do NOT call
+  them in the app-level "Déconnexion," and hide the real logout.
+
+## How this lib realizes it
+
+`accounts.ts` `AccountStore.login()`/`logout()` only read/write the username in an
+injected `AccountStorage`; they **never** call NG. See the faux login in
+[`../simulation.md`](../simulation.md).