docs: a sync & onboarding guideline, and make the clients point at it

Three clients grew their own vocabulary for one concept — server, sync hub,
connection, node — and their own idea of what can reach what. That second
part is not a matter of taste: I shipped a pairing code for a server because
I assumed a server could be paired with, and it took a round trip through a
real phone to find out it cannot.

So write down what is true, once: the rules of reach (a server signs in as
its own agent and is never a pairing target; a browser tab is not a node and
holds nothing; connecting fetches but never offers), the words we use for
each thing, every account/device path someone can get into and whether it
works today, which file in each client twins which, and what is actually
tested versus verified by hand.

Both codebases' agent docs now open with a pointer to it, because the failure
mode is an agent changing one client's sync screen without knowing the other
exists.

Claude-Session: https://claude.ai/code/session_01VddwtxveM8Zqsf765aQSHY

browser/data-browser/CLAUDE.md

@@ -1,3 +1,15 @@
+## Sync & onboarding — read first
+
+The Flutter canvas app (`flutter/lib/atomic/`) is a client of the same system,
+used by the same person. Before changing anything about signing in, servers,
+pairing or sync, read
+[`../../planning/sync-onboarding-ux.md`](../../planning/sync-onboarding-ux.md):
+it holds the shared vocabulary, the rules of what can actually reach what (a
+server is **not** a device you can pair with), every account/device path, and
+the map of which file here twins which file in the Flutter app.
+
+Change a sync screen here → change its twin there, and update that doc.
+
 ## Editing UI
 
 When working on the data-browser, determine if you need to change or add UI, if so, read `./UI_COMPONENTS.md` for a list of existing reusable components.

flutter/AGENTS.md

@@ -1,5 +1,17 @@
 # Atomic Canvas Flutter — Agent Context
 
+## Sync & onboarding — read first
+
+The Dart in `lib/atomic/` is a client of the same system the data-browser
+talks to, and the same person uses both. Before changing anything about
+signing in, servers, pairing or sync, read
+[`../planning/sync-onboarding-ux.md`](../planning/sync-onboarding-ux.md): it
+holds the shared vocabulary, the rules of what can actually reach what (a
+server is **not** a device you can pair with), every account/device path, and
+the map of which file here twins which file in `browser/data-browser`.
+
+Change a sync screen here → change its twin there, and update that doc.
+
 ## What This Is
 
 A cross-platform infinite drawing canvas app, migrated from a Kotlin/Android + Jetpack Compose app at `../atomiccanvas`. The Flutter version targets Android, iOS, and Web from a single codebase.

planning/README.md

@@ -37,13 +37,16 @@ scratch document. When a plan becomes obsolete, delete it.
 | [`structural-problems-index.md`](./structural-problems-index.md)                                 | 2026-05-28 audit: ranked open structural issues with per-item plan files. Covers React Compiler / Resource proxy mismatch, subscription unification, save-state signals, Loro-as-authority, subject typing, and remaining actor-message Arc-wrap. |
 | [`nextgraph-interop.md`](./nextgraph-interop.md)                                                 | **Proposal:** read/edit `did:ng:` (NextGraph) resources via a pluggable, scheme-routed Store backend; use Atomic components chrome-free in NextGraph apps. Builds on the elfa-tables proof.                                                       |
 | [`drive-reconciliation.md`](./drive-reconciliation.md)                                           | **Proposal (2026-07-08):** replace the flat whole-drive VV hash with range-based set reconciliation (RBSR) so sync cost tracks the delta, not the drive; optional signed drive state root (reusing genesis `stateHash`) closes F1 + enables offline verification. Records the RBSR-over-hierarchy-Merkle and VV-leaves-first decisions before any build. |
+| [`sync-onboarding-ux.md`](./sync-onboarding-ux.md)                                              | **Guideline:** the language, the rules of what can reach what, every account/device path, where each client's logic lives, and what is tested. Read before changing a sync or onboarding screen in any client.                                     |
 | [`device-pairing.md`](./device-pairing.md)                                                       | **Proposal (2026-07-08):** one-scan pairing between a server and a phone/tablet — `atomic://pair` QR/deep-link envelope (`onboard` with secret now, channel-provisioned secret later), mDNS/pkarr as routing-only discovery, and a SaaS per-account device directory for zero-scan "sign in and it syncs". Resolves serverless-p2p OQ3, narrows OQ1/OQ4. |
 | [`importers.md`](./importers.md)                                                                 | **Analysis (2026-07-14):** importers for existing data — the LLM writes only a pure, sandboxed mapping function; the host owns acquire/parse/validate/preview/commit; schema validation is the feedback-loop oracle. Ontola-authored trusted importer skills (hash-pinned transform + verifiable fixtures, Notion export first) precede client publishing; promotion path to server-side connectors. |
 | [`habits-app.md`](./habits-app.md)                                                               | **Proposal (2026-07-13):** habit tracker built strictly as an external app (`@tomic/lib`, plugin iframe view, code-first schema, assistant skill, Wear OS Flutter watch client) — append-only Completion event log for conflict-free counter taps; doubles as a dogfooding exercise whose gaps feed the SDK, plugin, and query plans.                        |
 | [`atomic-assistant-browser-extension.md`](./atomic-assistant-browser-extension.md)               | **Proposal (2026-07-14):** local-first Chromium extension using Atomic WASM/OPFS to read approved webpage context, preview and fill forms from scoped personal data, and persist existing `AiChat` resources; Free local pairing first, Vault/Server optional.                                                     |
 | [`p2p-presence.md`](./p2p-presence.md)                                                           | **Proposal (2026-07-10):** carry ephemeral presence (cursors, viewing/following/typing) device-to-device over the Iroh live channel via the reserved `EPHEMERAL 0x40` frame and a server-side WS⇄peer bridge — never persisted. Same-agent (own devices) only; multi-user P2P presence deferred to `authorization-sync.md`. |
 | [`meetings.md`](./meetings.md)                                                                   | **Built (2026-07-14):** one Meeting-only resource with rich-text Agenda/Notes/Minutes, child chat, persisted lifecycle, a dedicated page, and an explicit prepare-then-start flow. Clean cutover; no backwards compatibility. |
 | [`dashboards.md`](./dashboards.md)                                                               | **Proposal (2026-07-15):** user- and LLM-composable dashboards — `Dashboard` resource + standalone `Block` resources (embedded View, stat, constrained-Vega-Lite chart, text) with JSON grid layout; `create_dashboard` tool mirroring `create_table`; blocks reusable later as DocumentV2 embeds.                                                        |
+| [`social-apps.md`](./social-apps.md)                                                             | **Requirements (2026-07-17):** platform gaps for social-network-shaped apps (recipes app as driver): generic `atomic_flutter` SDK extraction, mobile blobs, push notifications, feed primitives (client fan-out now, hub feed endpoint later), invite-link onboarding, web share views, groups, moderation-by-display-filtering. Companion to `zones.md`.                                  |
+| [`zones.md`](./zones.md)                                                                         | **Proposal (2026-07-17):** any ACL-bearing resource is a "zone" — the single unit of access, sync, quota, keys, and (opt-in) announce; rights live only on zone roots, `subject → zone` is a derived index (drive stamp leaves signed state), authority is evaluated at commit time via `AuthImpact` replay, discovery is one pkarr record per agent. "Share a doc" = promote it to a zone.                                  |
 | [`drafts-and-suggestions.md`](./drafts-and-suggestions.md)                                       | **Active (2026-07-15):** two generic capabilities, no Website-specific path. A **Fork** (`Fork` class + `originalSubject`) proposes a change to an existing resource and merges onto it; a **Draft** is unpublished new content defined by location (a resource in a private Drafts folder) and publishes by moving. Visibility is location; needs no deny rule. Milestone 11 (headless CMS): #467, mechanism half of #1000. |
 
 Protocol reference lives in the public docs: [`docs/src/websockets.md`](../docs/src/websockets.md).

planning/sync-onboarding-ux.md

@@ -0,0 +1,128 @@
+# Sync & Onboarding UX
+
+How we talk about sync, what can actually reach what, and which paths exist.
+Read this before changing any sync/onboarding screen in **any** client — the
+same person meets several of them, and should not have to learn each one.
+
+Applies to: the data-browser (browser tab), the data-browser in Tauri
+(desktop/mobile), the Flutter canvas app, and atomic-server.
+
+---
+
+## 1. What can reach what
+
+Most UX mistakes here come from getting this wrong. It is not symmetric.
+
+| From → to | How | Hard constraint |
+| --- | --- | --- |
+| your device ↔ your other device | Iroh peer sync, started by scanning a pairing code | **Same account only.** `is_same_agent_as_ours` (`lib/src/sync/peer.rs`) fails closed and says so |
+| your device → an always-on machine | push (replication) | needs write rights there, signed as *your* agent |
+| an always-on machine → your device | WS subscribe + fetch | the device must know its address |
+| browser tab ↔ anything | only through an always-on machine | a browser tab **is not a node**: it cannot pair, and holds nothing |
+
+Three consequences that keep being forgotten:
+
+- **An always-on machine is not one of your devices.** It signs in as its own
+  agent. It can never be a pairing target — a code for it is refused by every
+  device that scans it. (Learned by shipping one. Don't.)
+- **A secret restores who you are, not what you have.** Signing in on a new
+  device gets you an identity and an empty workspace. Something still has to
+  carry the data.
+- **Connecting is not pushing.** Connecting to a machine fetches a workspace
+  you lack; it never offers the one you have. A workspace made before you
+  connected anywhere exists in exactly one place until someone pushes it.
+
+## 2. Language
+
+The same concept has been called a server, a sync hub, a connection and a node
+— in three clients. Pick one word and keep it.
+
+| Say | Not | Why |
+| --- | --- | --- |
+| workspace | drive, store | "drive" is our schema's word, not a person's |
+| your devices | peers, nodes | a node is an implementation detail |
+| always-on machine, or its address (`atomicserver.eu`) | server, hub, sync hub | name the thing, not the category — "server" makes it plumbing to learn |
+| pairing code | envelope, node DID, `atomic://pair` URI | it is a code you scan |
+| sync | replicate, reconcile, promote | one verb, whatever the transport |
+
+Rules of thumb:
+
+- **Name what the person wants, not the mechanism.** "Where your data is",
+  not "Sync hub URL". The address is the answer, not the concept.
+- **Ask for plumbing only when there is plumbing to do.** Nothing that has no
+  data yet should be asked where to sync it.
+- **A dead end is not a question.** Do not offer a box to type into if no
+  answer exists — the workspace made on a phone has never been on a machine,
+  so "connect the machine it lives on" cannot be answered.
+- **Say where things are, plainly.** "This code reaches `localhost:9883`, not
+  this browser." Mechanism belongs in a footnote, never in the headline.
+- **A state is not an error.** No machine connected, unreachable, data
+  elsewhere — these are normal, and read as normal.
+
+## 3. The paths
+
+Every combination someone can actually get into. "Crosses by" is the only step
+that moves data.
+
+| Start | Then | Crosses by | Works today |
+| --- | --- | --- | --- |
+| new account in browser | mobile / desktop later | device connects the same address, fetches | ✅ |
+| new account on Tauri desktop | browser later | desktop pushes workspace up, browser reads it | ✅ `promoteLocalDrive` |
+| new account on Tauri desktop | Tauri mobile later | pairing code, either direction | ✅ |
+| new account on Flutter mobile | Tauri desktop later | pairing code | ⚠️ untested across the two apps |
+| new account on Flutter mobile | another Flutter mobile | pairing code | ✅ |
+| new account on Flutter mobile | browser later | mobile pushes workspace up, browser reads it | ✅ `syncDriveToServer` |
+| new account anywhere | atomicserver.eu later | device pushes up, then everything reads from there | ⚠️ untested |
+| new account in browser A | browser B, no machine in common | **nothing crosses** | ❌ by design — say so |
+
+The last row is the one to get right in copy: two browser tabs with no machine
+between them cannot reach each other, ever. Neither is a node.
+
+## 4. Where the logic lives
+
+Keep these in step. A change to one is usually a change to its twin.
+
+| Concern | Browser | Flutter |
+| --- | --- | --- |
+| sync screen | `data-browser/src/routes/SyncRoute.tsx` | `flutter/lib/atomic/widgets/server_settings_section.dart` |
+| settings shell | (same route) | `flutter/lib/atomic/widgets/agent_settings_dialog.dart` |
+| onboarding, data elsewhere | `data-browser/src/views/getting-started/ConnectDeviceStep.tsx` | `flutter/lib/screens/login_screen.dart` |
+| pairing code, show / scan | `components/PairingCode.tsx`, `ConnectToDeviceForm.tsx` | `flutter/lib/screens/pair_screen.dart` |
+| pairing code, format | `browser/lib/src/pairing.ts` | `pair_screen.dart` (`_parsePairingUri`) |
+| URL rules (scheme, local address) | `data-browser/src/helpers/serverUrl.ts` | `flutter/lib/atomic/server_url.dart` |
+| what a machine says about itself | `data-browser/src/helpers/managedServer.ts` | `flutter/lib/atomic/server_info.dart` |
+| push a workspace up | `browser/lib/src/store.ts` (`promoteLocalDrive`) | `AtomicClient.syncDriveToServer` |
+
+Shared, and authoritative over all of the above:
+
+- `lib/src/sync/peer.rs` — pairing, AUTH, the same-account rule
+- `lib/src/sync/replicate.rs` — `replicate_drive_to_remote`, the push
+- `server/src/plugins/server_info.rs` — `/server`, what a machine says it is
+- [`device-pairing.md`](./device-pairing.md) — the code's wire format
+- [`unified-sync.md`](./unified-sync.md) — where the transports are heading
+
+## 5. What is tested
+
+| Level | Covers | Where |
+| --- | --- | --- |
+| Rust unit | pairing AUTH, same-account refusal | `lib/src/sync/` |
+| Rust integration | replication, a fresh client reading a replicated workspace | `server/tests/replicate.rs` |
+| Rust integration | `/server`, `/drive-usage` | `server/src/tests.rs` |
+| Dart unit | URL rules, pairing code parsing, signing parity with Rust | `flutter/test/atomic/` |
+| Browser e2e | two servers, sync between them | `browser/e2e/` |
+
+Gaps worth knowing, rather than rediscovering:
+
+- **No test crosses two clients.** Every path in §3 is verified by hand. The
+  Flutter↔Tauri pairing row has never been run at all.
+- **Dart signing is checked against Rust by golden vectors**
+  (`lib/src/genesis_test_vectors.json`), not by a live handshake. That caught a
+  real bug (base64 alphabet); it would not catch a header the server ignores.
+- **The push path has no Dart-side test.** `syncDriveToServer` is covered by
+  Rust replication tests underneath, and nothing above.
+
+---
+
+*If you change vocabulary or a flow here, change it in both clients and update
+this table. A person moving from the phone to the laptop should not notice
+they moved.*