docs: refresh for local-first, sync, DID, tables, CMS, and presence

docs/README.md

@@ -5,7 +5,7 @@
 _Atomic Data is a specification for sharing, modifying and modeling graph data._
 
 View it on [docs.atomicdata.dev](https://docs.atomicdata.dev).
-If you're looking for **implementations of Atomic Data**, check out [atomic-server](https://github.com/atomicdata-dev/atomic-server) (server + cli + lib written in Rust) and [atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser) (react / typescript).
+If you're looking for **implementations of Atomic Data**, check out [atomic-server](https://github.com/atomicdata-dev/atomic-server) (server + cli + lib + web app, written in Rust / TypeScript).
 
 ## About this repo
 

docs/src/SUMMARY.md

@@ -11,10 +11,14 @@
 
 - [AtomicServer](atomic-server.md)
   - [When (not) to use it](atomicserver/when-to-use.md)
+  - [Local-first](atomicserver/local-first.md)
   - [Installation](atomicserver/installation.md)
   - [Using the GUI](atomicserver/gui.md)
     - [Tables](atomicserver/gui/tables.md)
+    - [Sync & pairing](atomicserver/gui/sync-and-pairing.md)
+    - [Presence & collaboration](atomicserver/gui/presence.md)
     - [AI and Atomic Assistant](atomicserver/gui/ai-and-atomic-assistant.md)
+  - [Headless CMS, drafts & forks](atomicserver/cms.md)
   - [Plugins](plugins.md)
     - [Creating Plugins](plugins/creating-plugins.md)
     - [Custom Views](plugins/custom-views.md)
@@ -83,6 +87,7 @@
   - [Commits (writing data)](commits/intro.md)
     - [Concepts](commits/concepts.md)
     - [Compared to](commits/compare.md)
+    - [Forks (proposed edits)](commits/suggestions.md)
   - [WebSockets](websockets.md)
   - [Endpoints](endpoints.md)
   - [Collections, filtering, sorting](schema/collections.md)

docs/src/atomic-data-overview.md

@@ -6,6 +6,7 @@
 ![Venn diagram showing Atomic Data is the combination of JSON, RDF and Type-Safety](assets/venn.svg)
 
 Atomic Data uses links to connect pieces of data, and therefore makes it easier to connect datasets to each other - even when these datasets exist on separate machines.
+Resources are addressed with portable [`did:ad` identifiers](did.md), edited with signed [CRDT commits](commits/intro.md), and can live [entirely local-first](atomicserver/local-first.md) before syncing to peers.
 
 ## AtomicServer
 
@@ -37,11 +38,11 @@ Atomic Data Extended is a set of extra modules (on top of Atomic Data Core) that
 
 ## Tools & libraries
 
-- Browser app [atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser) ([demo on atomicdata.dev](https://atomicdata.dev))
-- Build a react app using [typescript & react libraries](https://github.com/atomicdata-dev/atomic-data-browser). Start with the [react template on codesandbox](https://codesandbox.io/s/atomic-data-react-template-4y9qu?file=/src/MyResource.tsx)
+- Web app (data-browser) in the [`atomic-server` monorepo](https://github.com/atomicdata-dev/atomic-server/tree/master/browser) ([demo on atomicdata.dev](https://atomicdata.dev))
+- Typescript libraries: [`@tomic/lib`](js.md), [`@tomic/react`](usecases/react.md), [`@tomic/svelte`](svelte.md)
 - Host your own [atomic-server](https://github.com/atomicdata-dev/atomic-server) (powers [atomicdata.dev](https://atomicdata.dev), run with `docker run -p 80:80 -v atomic-storage:/atomic-storage joepmeneer/atomic-server`)
-- Discover the command line tool: [atomic-cli](https://github.com/atomicdata-dev/atomic-server) (`cargo install atomic-cli`)
-- Use the Rust library: [atomic-lib](https://github.com/atomicdata-dev/atomic-server)
+- Command line tool: [atomic-cli](https://github.com/atomicdata-dev/atomic-server) (`cargo install atomic-cli`)
+- Rust library: [atomic-lib](https://github.com/atomicdata-dev/atomic-server)
 
 ## Get involved
 
@@ -50,12 +51,13 @@ Make sure to [join our Discord](https://discord.gg/a72Rv2P) if you'd like to dis
 ## Status
 
 Keep in mind that none of the Atomic Data projects has reached a v1, which means that breaking changes can happen.
+The 0.41 line is the local-first / `did:ad` release — see the [roadmap](roadmap.md) and [changelog](https://github.com/atomicdata-dev/atomic-server/blob/develop/CHANGELOG.md).
 
 ## Reading these docs
 
 This is written mostly as a book, so reading it in the order of the Table of Contents will probably give you the best experience.
 That being said, feel free to jump around - links are often used to refer to earlier discussed concepts.
-If you encounter any issues while reading, please leave an [issue on Github](https://github.com/ontola/atomic-data/issues).
+If you encounter any issues while reading, please leave an [issue on Github](https://github.com/atomicdata-dev/atomic-server/issues).
 Use the arrows on the side / bottom to go to the next page.
 
 {{#include SUMMARY.md}}

docs/src/atomic-server.md

@@ -8,7 +8,7 @@ AtomicServer is a real-time headless CMS, graph database server for storing and
 It's free, open source (MIT license), and has a ton of features:
 
 <!-- Copied from root README -->
-- 🏠  **Local-first**: create and edit data with no server at all. Resources are addressed by [`did:ad` identifiers](https://docs.atomicdata.dev/did) and resolve peer-to-peer over the Mainline DHT, so an identity is a keypair you hold rather than an account on someone else's machine. Edits are signed CRDT commits that merge when you reconnect.
+- 🏠  **Local-first**: create and edit data with no server at all. Resources are addressed by [`did:ad` identifiers](https://docs.atomicdata.dev/did) — an identity is a keypair you hold rather than an account on someone else's machine. Peer discovery uses pkarr; devices sync over [WebSocket and Iroh](https://docs.atomicdata.dev/websockets). Edits are signed CRDT commits that merge when you reconnect. See [Local-first](atomicserver/local-first.md).
 - 🔒  **Encrypted at rest, per agent**: each agent's in-browser database is encrypted with XChaCha20-Poly1305, under a key wrapped by that agent's own private key. Signing out leaves the cache in place but unreadable to the next session — no wipe required.
 - 🔑  **Passkey-backed recovery**: a WebAuthn passkey wraps the backup of your agent secret (Argon2id + AES-GCM), so onboarding hands you nothing to write down, and a lost device doesn't have to mean a lost account.
 - 🚀  **Fast** (less than 1ms median response time on my laptop), powered by [actix-web](https://github.com/actix/actix-web) and [redb](https://github.com/cberner/redb)
@@ -18,12 +18,14 @@ It's free, open source (MIT license), and has a ton of features:
 - ⚙️  **Restful API**, with [JSON-AD](https://docs.atomicdata.dev/core/json-ad.html) responses.
 - 🔎  **Full-text search** with fuzzy search and various operators, often <3ms responses. Powered by [tantivy](https://github.com/quickwit-inc/tantivy).
 - ✨  **AI** with [MCP](https://modelcontextprotocol.io/) support, use any model via OpenRouter or host your own with Ollama.
-- 🗄️  **Tables**, with strict schema validation, keyboard support, copy / paste support. Similar to Airtable.
+- 🗄️  **Tables**, with strict schema validation, kanban / calendar / timer views, filters, templates, computed columns, aggregates, keyboard and copy/paste support. Similar to Airtable. See [Tables](atomicserver/gui/tables.md).
 - 📄  **Documents**, collaborative, rich text, similar to Google Docs / Notion.
 - 💬  **Group chat**, performant and flexible message channels with attachments, search and replies.
+- 👁️  **Presence**: see who is viewing a resource, follow someone through the app, live cursors while co-editing. See [Presence](atomicserver/gui/presence.md).
+- 📰  **Headless CMS**: drafts by folder location, forks for proposed edits, website templates, and [i18n](schema/translations.md). See [CMS](atomicserver/cms.md).
 - 📂  **File management**: Upload, download and preview attachments.
 - 💾  **Event-sourced versioning** / history powered by [Atomic Commits](https://docs.atomicdata.dev/commits/intro.html)
-- 🔄  **Real-time synchronization**: instantly communicates state changes with a client. Build dynamic, collaborative apps using [websockets](https://docs.atomicdata.dev/websockets) (using a [single one-liner in react](https://docs.atomicdata.dev/usecases/react) or [svelte](https://docs.atomicdata.dev/svelte)).
+- 🔄  **Real-time synchronization**: instantly communicates state changes with a client. Build dynamic, collaborative apps using [websockets](https://docs.atomicdata.dev/websockets) (using a [single one-liner in react](https://docs.atomicdata.dev/usecases/react) or [svelte](https://docs.atomicdata.dev/svelte)). Pair devices with a QR code — see [Sync & pairing](atomicserver/gui/sync-and-pairing.md).
 - 🧰  **Many serialization options**: to JSON, [JSON-AD](https://docs.atomicdata.dev/core/json-ad.html), and various Linked Data / RDF formats (RDF/XML, N-Triples / Turtle / JSON-LD).
 - 📖  **Pagination, sorting and filtering** queries using [Atomic Collections](https://docs.atomicdata.dev/schema/collections.html).
 - 🔐  **Authorization** (read / write permissions) and Hierarchical structures powered by [Atomic Hierarchy](https://docs.atomicdata.dev/hierarchy.html)

docs/src/atomicserver/cms.md

@@ -0,0 +1,86 @@
+# Headless CMS, drafts, and forks
+
+AtomicServer is a local-first headless CMS: model content with ontologies, edit
+it in the GUI, and render it from any front-end that can read Atomic Data
+([Astro guide](../astro-guide/1-index.md), Next.js / SvelteKit website templates,
+or your own `@tomic/react` / `@tomic/svelte` app).
+
+Two generic capabilities make publishing work. Neither is Website-specific.
+
+## Visibility is location
+
+A resource is public because it lives somewhere public — not because of a
+`status` field that can drift from reality.
+
+On a drive that is not blanket-public you typically have:
+
+- a **public folder** with `read` granted to the public agent; children inherit
+  public read through the [hierarchy](../hierarchy.md);
+- a private **Drafts** folder (no public grant) for unpublished new content.
+
+**Publishing** a draft is moving it to a public parent. **Archiving** is moving
+it somewhere non-public. No extra class or workflow engine required.
+
+The drive keeps a well-known Drafts folder (created on first use). New content
+you are not ready to show the world goes there.
+
+## Forks: propose a change
+
+A **Fork** is a proposed edit to an *existing* resource.
+
+| Property | Meaning |
+| --- | --- |
+| `Fork` (class) | Marker: this resource proposes a change to another |
+| `originalSubject` | The resource being changed |
+| `forkBase` / `forkVersion` | Snapshot of the original at fork time (for merge) |
+
+Creating a fork copies the resource into a private Forks folder, sets
+`originalSubject`, and lets you edit freely. The original is untouched until you
+**merge**. Merge squashes the fork onto the original (properties + Loro body
+where applicable). While a fork is open, the original can show that pending
+forks exist.
+
+Forks are ordinary resources: they have their own subject, history, and rights.
+They carry the content class alongside `Fork` (`isA: [BlogPost, Fork]`), so the
+normal editors and site previews render them.
+
+This replaces the older "Suggestions / Inbox HTTP POST" idea. Cross-agent
+"suggest an edit to someone else's drive" can reuse the same Fork mechanism once
+authorization for that path is fully productized; today the GUI flow is
+optimized for staging your own edits and merging them.
+
+## Websites and front-ends
+
+- **Website templates** in the app scaffold a site (pages, nav, locales) as
+  Atomic resources you can edit in the GUI.
+- **Headless front-ends** fetch JSON-AD over HTTP or sync a drive locally, then
+  render with your stack. See [Build a portfolio with Astro](../astro-guide/1-index.md)
+  and [`@tomic/template`](../create-template/atomic-template.md).
+- **Edit from the webpage** — guest edit / local clone flows let a visitor
+  propose changes without write access to the live drive (forks / local-only
+  drives); merge happens when an editor accepts them.
+
+## Internationalization
+
+Multilingual sites use the two mechanisms in
+[Translations & Localization](../schema/translations.md):
+
+- **Document-level** — one resource per language (`language` + `translationOf`),
+  so each locale has its own path, history, and publish state (a translation in
+  Drafts is simply unpublished).
+- **Field-level** — [`LocalizedText`](../schema/datatypes.md#localizedtext) for
+  short strings inside shared structure (nav labels, feature cards).
+
+Declare `defaultLanguage` (and optionally `languages`) on the website or drive.
+
+## Local-first CMS
+
+Editors can work offline: drafts and forks live in the local database until
+sync. See [Local-first](local-first.md) and [Sync & pairing](gui/sync-and-pairing.md).
+
+## Related
+
+- [Use case: Headless CMS](../usecases/headless-cms.md) (why / comparison)
+- [Tables](gui/tables.md) for structured content collections
+- [Hierarchy and authorization](../hierarchy.md)
+- [Commits](../commits/intro.md)

docs/src/atomicserver/gui.md

@@ -20,12 +20,12 @@ At the start these will be:
 ## Creating an agent
 To create data in AtomicServer you'll need an agent.
 An agent is like a user account, it signs the changes (commits) you make to data so that others can verify that you made them.
-Agents are identified by a DID derived from their public key (`did:ad:{publicKey}`), so they can be used on any AtomicServer without needing to be registered first.
+Agents are identified by a DID derived from their public key (`did:ad:agent:{publicKey}`), so they can be used on any AtomicServer without needing to be registered first.
 
 To get started, you can use the [demo invite](https://atomicdata.dev/invites/1) on atomicdata.dev, or the `/setup` invite on your own server.
 
 Click the "Accept as new user" button. The app will generate a key pair and your Agent will be created.
-Navigate to the User Settings page to find your agent secret. This secret is what you use to login, so keep it somewhere safe, like in a password manager. If you lose it you won't be able to recover your account.
+Navigate to the User Settings page to find your agent secret. You can also set up **passkey-backed recovery** so a lost device does not mean a lost account. Keep a backup of the secret or passkey enrollment somewhere safe.
 
 ### Setting up the root Agent
 Next, we'll set up the root Agent that has write access to the Drive.
@@ -49,3 +49,12 @@ Now that everything is up and running you can start creating some resources.
 To create a new resource, click the + button in the sidebar.
 You will be presented with a list of resource types to choose from like Tables, Folders, Documents etc.
 You can also create your own types by using ontologies.
+
+## Next in the GUI
+
+- [Tables](gui/tables.md) — views, filters, templates, aggregates
+- [Sync & pairing](gui/sync-and-pairing.md) — connect devices and always-on peers
+- [Presence & collaboration](gui/presence.md) — who is here, follow-me, meetings
+- [Headless CMS, drafts & forks](cms.md) — publishing and proposed edits
+- [Local-first](local-first.md) — how offline storage works
+- [AI and Atomic Assistant](gui/ai-and-atomic-assistant.md)

docs/src/atomicserver/gui/presence.md

@@ -0,0 +1,55 @@
+# Presence & collaboration
+
+AtomicServer shows who else is in a workspace with you — without writing that
+information into your data. Presence is ephemeral: it rides a drive-scoped relay
+with a short TTL and disappears when someone leaves.
+
+## What you see
+
+- **Avatars / facepile** in the navbar for people viewing the current resource
+- **Sidebar dots** on resources others have open
+- **Document cursors** while co-editing rich text (colored per agent)
+- **Canvas pointers** on collaborative canvases
+- **Table cell rings** on the cell another person has selected
+- **"Typing…"** in chat rooms and comments
+- **Follow-me** — follow someone as they navigate; they can lead a tour through
+  the app
+- **Meetings** — a meeting resource with agenda, notes, and live presence for
+  participants (optional peer-to-peer audio/video in the meeting panel)
+
+## How it works
+
+Each drive has a presence channel. Every session announces a small entry:
+
+- which agent you are
+- which resource you are viewing
+- optional follow target
+- optional view-specific data (selected table cell, canvas coordinates, …)
+
+Entries expire if the heartbeat stops (~30s TTL). The browser and other clients
+subscribe over the [WebSocket protocol](../../websockets.md) (`EPHEMERAL` /
+presence frames). Document text cursors use a dedicated Loro ephemeral channel
+because cursor positions must track the CRDT oplog; canvas and tables attach
+lightweight payloads to the drive presence entry instead.
+
+Presence is **not** a Commit. It is never stored in the database and does not
+appear in history.
+
+## Follow-me and meetings
+
+From the presence UI you can follow another session: your view tracks theirs as
+they open resources. Meetings are first-class resources with agenda/notes and a
+prepare-then-start flow; participants show up through the same presence layer.
+
+## Multi-device and P2P
+
+Same-agent presence across your own devices works through the always-on device
+(or hub) that relays the drive channel. Direct multi-user presence over Iroh
+without a hub is on the roadmap; today collaboration between people typically
+shares a workspace on a server or desktop that both can reach.
+
+## Related
+
+- [Sync & pairing](sync-and-pairing.md)
+- [WebSocket protocol](../../websockets.md) (`EPHEMERAL` tag)
+- [Documents and real-time editing](../gui.md)