feat: add user-focused Loro skill (#961)

* feat: add Loro skill repository guide

* refactor: focus Loro skill on user onboarding

* docs: index Loro language bindings in skill

---------

Co-authored-by: Zixuan Chen <zx@loro.dev>

Author: lodyai[bot]

skills/loro/SKILL.md

@@ -1,41 +1,44 @@
 ---
 name: loro
-description: "Comprehensive guide for using Loro across document modeling, synchronization, versioning, rich text editors, app-state mirroring, performance tradeoffs, and wasm bindings. Use when Codex needs to work with `loro-crdt`, `loro`, `loro-prosemirror`, `loro-mirror`, or `crates/loro-wasm` for: (1) Choosing CRDT container types and document structure, (2) Designing sync, persistence, checkout, or history workflows, (3) Integrating rich-text editors and stable selections, (4) Mirroring app state with schemas and React, (5) Reasoning about versions, events, import status, or Inspector output, or (6) Maintaining the WASM binding layer."
+description: "Practical guide for helping app developers evaluate, adopt, and use Loro for local-first collaboration. Use when Codex needs to answer questions or write examples for `loro-crdt`, `loro`, `loro-prosemirror`, `loro-codemirror`, `loro-mirror`, language bindings such as Swift/Python/C#/Go/React Native, or Loro-powered apps about: (1) Deciding whether Loro fits a product, (2) Getting started in JavaScript/TypeScript, Rust, or another supported binding, (3) Choosing CRDT containers and document structure, (4) Designing sync, persistence, snapshots, versioning, undo, presence, or time travel, (5) Integrating rich-text editors and stable selections, (6) Mirroring app state with React, or (7) Understanding performance and tradeoffs."
 ---
 
 # Loro
 
-Use this skill as the single entry point for all Loro work. Load one primary chapter first. Load a second chapter only when the task clearly crosses domains.
+Use this skill to help users build applications with Loro. Start from the user's product goal, then choose the narrowest chapter that answers it. Load a second chapter only when the task crosses domains.
 
 ## Select A Chapter
 
 - Read [references/topic-map.md](references/topic-map.md) if the task is broad and you need to route it.
-- Read [references/fit-and-architecture.md](references/fit-and-architecture.md) for CRDT fit, local-first framing, setup, and high-level architecture.
-- Read [references/containers-and-encoding.md](references/containers-and-encoding.md) for container choice, composition, encoding, persistence, shallow snapshots, and redaction.
-- Read [references/sync-versioning-and-events.md](references/sync-versioning-and-events.md) for sync flows, frontiers, version vectors, checkout, import status, timestamps, event timing, and Inspector.
+- Read [references/fit-and-architecture.md](references/fit-and-architecture.md) for product fit, installation, language/package choices, first examples, and core mental models.
+- Read [references/containers-and-encoding.md](references/containers-and-encoding.md) for choosing containers, shaping documents, exporting updates, snapshots, persistence, shallow snapshots, and redaction.
+- Read [references/sync-versioning-and-events.md](references/sync-versioning-and-events.md) for realtime/offline sync, version vectors, frontiers, checkout, undo, presence, timestamps, events, and Inspector.
 - Read [references/richtext-and-editors.md](references/richtext-and-editors.md) for `LoroText`, cursors, `applyDelta`, `updateByLine`, `loro-prosemirror`, Tiptap, and CodeMirror.
 - Read [references/mirror-and-react.md](references/mirror-and-react.md) for `loro-mirror`, `$cid`, `idSelector`, validation, selectors, and React integration.
-- Read [references/wasm-maintenance.md](references/wasm-maintenance.md) for `crates/loro-wasm`, `#[wasm_bindgen]`, pending-event flushing, wrapper decoration, and tests.
-- Read [references/performance-and-research.md](references/performance-and-research.md) for benchmarks, Eg-Walker tradeoffs, movable-tree context, rich-text design context, and project history.
+- Read [references/performance-and-tradeoffs.md](references/performance-and-tradeoffs.md) for scaling, document/update size, loading speed, and workload tradeoffs.
 
 ## Route Common Tasks
 
+- “I am new to Loro / should I use it / show me a first example”
+  - Start with `fit-and-architecture.md`
+- “Which language package or binding should I use?”
+  - Start with `fit-and-architecture.md`
 - “Build a collaborative document model / choose data types / persist history”
   - Start with `containers-and-encoding.md`
   - Add `sync-versioning-and-events.md` if version/history behavior matters
-- “Debug checkout / detached mode / missing imports / event timing”
+- “Sync devices, store data, use snapshots, time travel, undo, or presence”
   - Start with `sync-versioning-and-events.md`
 - “Integrate ProseMirror, Tiptap, CodeMirror, or custom rich text”
   - Start with `richtext-and-editors.md`
   - Add `sync-versioning-and-events.md` if undo/version/event behavior matters
 - “Model app state with loro-mirror or loro-mirror-react”
   - Start with `mirror-and-react.md`
   - Add `containers-and-encoding.md` if schema semantics depend on container choice
-- “Change wasm bindings or debug pending event flushing”
-  - Start with `wasm-maintenance.md`
-- “Decide whether Loro is even the right tool / explain tradeoffs”
+- “Explain performance, large documents, loading, update size, or tradeoffs”
+  - Start with `performance-and-tradeoffs.md`
+- “Decide whether Loro is the right tool”
   - Start with `fit-and-architecture.md`
-  - Add `performance-and-research.md` if benchmark or research context matters
+  - Add `performance-and-tradeoffs.md` if workload scale matters
 
 ## Execute The Task
 
@@ -46,12 +49,13 @@ Use this skill as the single entry point for all Loro work. Load one primary cha
    - choose data types by merge behavior,
    - distinguish state version from history version,
    - keep ephemeral state out of persisted CRDT data,
-   - respect the binding/runtime invariants in `crates/loro-wasm`.
+   - use stable cursors for collaborative selections,
+   - design sync around updates and snapshots rather than a central locking protocol.
 
 ## Keep Guardrails
 
 - Do not assume CRDTs are the right fit for hard invariants, exclusivity, or authorization-at-write-time problems.
 - Do not model editable text as plain strings when user intent requires merged edits.
 - Do not reuse peer IDs across concurrent sessions.
 - Do not confuse detached documents with detached containers.
-- Do not change wasm-exposed mutators without checking pending-event flushing behavior.
+- Do not persist cursor presence, hover state, or connection state inside the main document; use ephemeral state.

skills/loro/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Loro"
-  short_description: "Complete Loro guide for modeling, sync, editors, and wasm"
-  default_prompt: "Use $loro to solve a Loro modeling, sync, editor, mirror, versioning, or wasm-maintenance task."
+  short_description: "Guide for adopting and using Loro in apps"
+  default_prompt: "Use $loro to design or explain a Loro-powered app, from choosing a language binding through modeling, sync, editors, React state, and performance."

skills/loro/references/fit-and-architecture.md

@@ -1,4 +1,4 @@
-# Fit And Architecture
+# Getting Started And Fit
 
 ## When Loro Fits
 
@@ -14,11 +14,59 @@
 - Authorization decisions that must be enforced at write time.
 - Arbitrary graph-shaped or non-JSON-like data without an adaptation layer.
 
+## Install
+
+- JavaScript/TypeScript: install `loro-crdt`.
+- Rust: install the `loro` crate.
+- Use editor integrations when available instead of writing editor sync from scratch:
+  - `loro-prosemirror` for ProseMirror and Tiptap-style editors.
+  - `loro-codemirror` for CodeMirror 6.
+- Use `loro-mirror` and `loro-mirror-react` when the app already thinks in immutable state and actions.
+
+## Language And Package Index
+
+- JavaScript/TypeScript: [`loro-crdt`](https://www.npmjs.com/package/loro-crdt). Start here for web apps and most examples in the Loro docs.
+- Rust: [`loro`](https://crates.io/crates/loro) and [`docs.rs/loro`](https://docs.rs/loro). Use for native Rust apps, services, CLIs, and custom infrastructure.
+- Swift: [`loro-swift`](https://github.com/loro-dev/loro-swift). Use for Swift/iOS/macOS experiments and native apps.
+- Python: [`loro-py`](https://github.com/loro-dev/loro-py). Use for Python apps, scripts, and server-side tooling.
+- React Native: [`loro-react-native`](https://github.com/loro-dev/loro-react-native). Use for mobile apps that need native React Native bindings.
+- C#: [`loro-cs`](https://github.com/sensslen/loro-cs). Community-maintained .NET/C# binding; check its README and release state before adopting.
+- Go: [`loro-go`](https://github.com/aholstenson/loro-go). Community-maintained Go binding; check platform support and API completeness before adopting.
+- Cross-language FFI base: [`loro-ffi`](https://github.com/loro-dev/loro-ffi). Use this as the reference for generated/native bindings and as a starting point for new language bindings.
+
+Prefer the official JS/TS or Rust package when there is no product reason to choose another language. For community bindings, verify platform binaries, Loro core version, and API coverage before making product commitments.
+
+## First JavaScript Example
+
+```ts
+import { LoroDoc } from "loro-crdt";
+
+const docA = new LoroDoc();
+const listA = docA.getList("items");
+listA.insert(0, "A");
+listA.insert(1, "B");
+
+const update = docA.export({ mode: "update" });
+
+const docB = new LoroDoc();
+docB.import(update);
+
+console.log(docB.toJSON()); // { items: ["A", "B"] }
+```
+
+## First Design Questions
+
+1. What parts of the state should merge when edited concurrently?
+2. Which data needs durable history, and which data is only presence or UI state?
+3. Do users need text/rich-text intent preservation, ordered moves, tree moves, or simple last-write-wins fields?
+4. How will peers exchange updates, and where will snapshots or updates be persisted?
+
 ## Conceptual Model
 
 - Loro is a CRDT framework for local-first apps.
 - It trades strict coordination for strong eventual consistency.
-- Under the hood it mixes Fugue-style correctness with Eg-Walker-inspired replay and simple local indexing.
+- Each peer edits locally, exports updates, imports updates from other peers, and converges after seeing the same operations.
+- Loro records history, so versioning and time travel are core concepts rather than an afterthought.
 
 ## Document Shape Constraints
 
@@ -28,21 +76,12 @@
 
 ## Entry Points
 
-- JS/TS: `loro-crdt`
-- Rust: `loro`
-- Swift: `loro-swift`
-- Python: `loro-py`
-- Ecosystem integrations include editor bindings, state-mirroring layers, and Inspector.
-
-## Setup Notes
-
-- In JS frontends, install `loro-crdt`.
-- In Vite-based apps, WASM support and top-level-await handling must be configured correctly.
-- Inspector is the quickest interactive tool for browsing state and history during development.
+- Core packages and language bindings are listed in `Language And Package Index`.
+- Ecosystem integrations include editor bindings, state-mirroring layers, React Native, and Inspector.
 
-## Read Order Inside This Skill
+## Practical Start Path
 
-1. Start here for fit and high-level tradeoffs.
-2. Switch to `containers-and-encoding.md` for concrete data types and storage choices.
-3. Switch to `sync-versioning-and-events.md` for history, events, and sync state.
-4. Switch to `richtext-and-editors.md` or `mirror-and-react.md` for integrations.
+1. Pick container types in `containers-and-encoding.md`.
+2. Decide sync and persistence shape in `sync-versioning-and-events.md`.
+3. Add editor or React integration only after the document model is clear.
+4. Use Inspector during development to inspect state and history.

skills/loro/references/performance-and-research.md

@@ -0,0 +1,43 @@
+# Performance And Tradeoffs
+
+Use this chapter when users ask whether Loro can handle a workload, how to store data efficiently, or why one sync/storage design is preferable to another.
+
+## What To Compare
+
+- Encoded document size and update size.
+- Snapshot export/import time.
+- Update import time.
+- Memory footprint while editing and loading.
+- Conflict-heavy collaboration versus mostly independent edits.
+- Initial load path versus steady-state sync path.
+
+## Practical Defaults
+
+- Use update exchange for live collaboration.
+- Use snapshots for fast startup checkpoints.
+- Store frequent small updates between snapshots when durable replay is needed.
+- Recompact by exporting a fresh snapshot after enough updates accumulate.
+- Consider shallow snapshots when old history can be archived or discarded.
+
+## Workload-Specific Advice
+
+- Collaborative text: use `LoroText`; do not model text as a plain string just to reduce apparent complexity.
+- Reorder-heavy collections: use `LoroMovableList` instead of delete+insert if move identity matters.
+- Hierarchies: use `LoroTree`; avoid forcing tree-shaped data into ad hoc map/list structures.
+- High-frequency presence or cursor movement: use `EphemeralStore`, not the persisted document.
+- Hard invariants such as balances, bookings, or permissions still need application/server-side validation outside the CRDT merge.
+
+## Benchmark Interpretation
+
+- Treat benchmarks as workload indicators, not universal rankings.
+- A smaller full snapshot does not automatically mean smaller incremental updates.
+- A fast import path matters most for startup and bulk sync.
+- A compact update path matters most for live collaboration and bandwidth-constrained clients.
+- Shallow snapshots reduce retained history, but peers with only older history may need a fresh snapshot or archived history to sync.
+
+## Explain Tradeoffs
+
+- Loro optimizes for local editing, automatic merging, history, and version control.
+- Strong eventual consistency means peers converge after receiving the same operations.
+- Loro does not provide central locking, serializable transactions, or write-time authorization by itself.
+- Pick containers by merge semantics first, then tune storage and sync format for performance.

skills/loro/references/performance-and-tradeoffs.md

@@ -30,7 +30,7 @@
 - Use two cursors for selections: anchor and head.
 - Resolve live offsets with `doc.getCursorPos(...)`.
 - Persist updated cursors returned from resolution to reduce replay cost.
-- WASM text offsets are UTF-16 indices.
+- JavaScript text offsets are UTF-16 indices.
 
 ## ProseMirror And Tiptap
 
@@ -55,4 +55,4 @@
 
 - Do not model editable prose as `string` in a `LoroMap`.
 - Do not store collaborative selections as plain indices.
-- Do not mix old and new ProseMirror cursor APIs accidentally; inspect the package version and current codebase first.
+- Do not mix old and new ProseMirror cursor APIs accidentally; check the installed package version and current API docs first.

skills/loro/references/richtext-and-editors.md

@@ -65,7 +65,7 @@
 
 - Some older examples describe JS events as microtask-delayed.
 - Modern `loro-crdt` dispatches events synchronously at the JS boundary.
-- Always check the package version and current codebase before assuming old timing semantics.
+- Check the installed package version and current API docs before relying on old timing examples.
 
 ## Event Sources
 
@@ -93,7 +93,7 @@
 
 - If imports arrive out of order, inspect `ImportStatus.pending`.
 - If checkout seems stale, compare DocState version to OpLog version.
-- If a hook missed an implicit commit, audit `subscribePreCommit(...)` rather than adding ad hoc commit calls.
+- If commit metadata hooks miss implicit commits, use `subscribePreCommit(...)` rather than adding ad hoc commit calls.
 
 ## Undo, Cursor, And Ephemeral Presence
 

skills/loro/references/sync-versioning-and-events.md

@@ -1,34 +1,36 @@
 # Topic Map
 
-Use this file to choose the right chapter inside the unified `loro` skill.
+Use this file to choose the right user-facing chapter inside the unified `loro` skill.
 
 ## Route By User Ask
 
+- “I am new to Loro. How do I start?”
+  - Read `fit-and-architecture.md`
+- “Which package, language binding, or platform should I use?”
+  - Read `fit-and-architecture.md`
 - “Should I use Loro here?”
   - Read `fit-and-architecture.md`
 - “Which container should I choose?”
   - Read `containers-and-encoding.md`
-- “How should I sync, persist, time-travel, or debug imports?”
+- “How should I sync, persist, time-travel, use undo, or debug imports?”
   - Read `sync-versioning-and-events.md`
 - “How do I integrate rich text editors?”
   - Read `richtext-and-editors.md`
 - “How do I use loro-mirror with React?”
   - Read `mirror-and-react.md`
-- “How do I change crates/loro-wasm safely?”
-  - Read `wasm-maintenance.md`
-- “Why does Loro behave this way, and what are the performance tradeoffs?”
-  - Read `performance-and-research.md`
+- “How will Loro behave at scale?”
+  - Read `performance-and-tradeoffs.md`
 
-## Product Fit And High-Level Architecture
+## Getting Started And Product Fit
 
-- CRDT basics, CAP tradeoffs, local-first framing, OT comparison
+- Install choices, language bindings, first example, local-first framing
   - Read `fit-and-architecture.md`
 - When CRDTs are the wrong fit
   - Read `fit-and-architecture.md`
-- Package entry points, setup notes, ecosystem overview
+- Package entry points and ecosystem overview
   - Read `fit-and-architecture.md`
 
-## Containers, Composition, Encoding, Persistence
+## Containers, Composition, Storage
 
 - Choosing between `LoroMap`, `LoroList`, `LoroMovableList`, `LoroTree`, `LoroCounter`, `LoroText`
   - Read `containers-and-encoding.md`
@@ -51,6 +53,8 @@ Use this file to choose the right chapter inside the unified `loro` skill.
   - Read `sync-versioning-and-events.md`
 - Event timing, `subscribePreCommit`, Inspector
   - Read `sync-versioning-and-events.md`
+- Undo, cursors, and ephemeral presence
+  - Read `sync-versioning-and-events.md`
 
 ## Text, Rich Text, And Editors
 
@@ -68,20 +72,11 @@ Use this file to choose the right chapter inside the unified `loro` skill.
 - `loro-mirror-react`, selectors, provider/hooks patterns
   - Read `mirror-and-react.md`
 
-## WASM Binding Maintenance
-
-- `crates/loro-wasm` API changes
-  - Read `wasm-maintenance.md`
-- Pending-event flushing and JS decorator allowlists
-  - Read `wasm-maintenance.md`
-- Binding aliases, generated TS docs, wasm tests
-  - Read `wasm-maintenance.md`
-
-## Performance And Research Context
+## Performance And Tradeoffs
 
-- Benchmark interpretation
-  - Read `performance-and-research.md`
-- Event-graph replay and efficiency tradeoffs
-  - Read `performance-and-research.md`
-- Movable-tree algorithm context, rich-text algorithm context, project history
-  - Read `performance-and-research.md`
+- Loading speed, encoded size, memory, update size
+  - Read `performance-and-tradeoffs.md`
+- Conflict-heavy vs low-conflict workloads
+  - Read `performance-and-tradeoffs.md`
+- When to use snapshots, shallow snapshots, or update streams
+  - Read `performance-and-tradeoffs.md`