docs: finalize Full Developer Guidance Suite (Intro, FAQ, Architecture, Security)

Author: HassamSheikh

README.md

@@ -110,9 +110,11 @@ We subjected the engine to a "Thundering Herd" stress test (10,000 records).
 
 For deep-dives into the engine's internals and security protocols:
 
-*   **[🏟️ Architecture Specification](doc/architecture.md)**: Understanding the Sync Engine Protocol, Delta Pulls, and High-Scale Ingestion.
+*   **[🚀 Getting Started Tutorial](doc/getting_started.md)**: Build a high-scale sync engine in 5 minutes.
+*   **[🏟️ Architecture Specification](doc/architecture.md)**: Understanding Delta Pulling and the Ordered Ingestion Protocol.
 *   **[🛡️ Security Audit Report](doc/security_audit.md)**: Deep-dive into the 42 attack vectors and current hardening state.
-*   **[🤝 Contributing Guide](CONTRIBUTING.md)**: How to add new adapters or features while maintaining Diamond-Standard quality.
+*   **[❓ Common Questions & FAQ](doc/faq.md)**: Troubleshooting, performance, and best practices.
+*   **[🤝 Contributing Guide](CONTRIBUTING.md)**: How to add new adapters or features while maintaining Diamond quality.
 
 ---
 

doc/faq.md

@@ -0,0 +1,47 @@
+# ❓ dynos_sync FAQ
+
+Common questions and troubleshooting for the **dynos_sync** engine.
+
+---
+
+## 🛠️ General Questions
+
+### **Q: Does this replace my local database?**
+**A: No.** `dynos_sync` is a **headless** layer. It sits between your existing local database (Drift, Hive, Isar) and your remote API. You use your database normally; the engine simply mirrors those changes to the remote backend.
+
+### **Q: What is "Ordered Ingestion"?**
+**A: Data Reliability.** Unlike libraries that push data in parallel chunks, `dynos_sync` preserves the **causal ordering** of your writes. This prevents race conditions where a record is "deleted" before it's even "created" on the server.
+
+### **Q: How does it handle 100,000 records?**
+**A: Through Delta-Pulling.** Instead of fetching all data, the engine checks remote table timestamps. If `RemoteTS == LocalTS`, zero data is pulled. Only modified tables are fetched in memory-efficient batches.
+
+---
+
+## 🛡️ Security & Privacy
+
+### **Q: What happens if the user logs out while offline?**
+**A: The Session Purge protocol.** When `logout()` is called, we call `local.clearAll([tables])`. This ensures that if User B logs into the same shared device, they cannot see User A's un-synced local data.
+
+### **Q: Where is my data masked?**
+**A: On the edge.** Masking happens **locally on the device** before the JSON is even written to the sync queue. Your sensitive PII never leaves your device's boundary in plain text.
+
+---
+
+## 🚀 Performance & UI
+
+### **Q: Will syncing block my UI thread?**
+**A: Not if you use isolates.** Wrap your engine in `IsolateSyncEngine` to offload all JSON serialization, deep-cloning, and PII masking to a dedicated background worker.
+
+### **Q: My sync is stuck. How do I clear it?**
+**A: Check the Queue.** If a "poison pill" (a record that repeatedly fails) is blocking the queue, you can inspect it via `queue.getPending()` and either delete it or increase `maxRetries` in your `SyncConfig`.
+
+---
+
+## 🤝 Support & Licensing
+
+### **Q: Can I use this for free?**
+**A: Yes!** If you are a startup with <$5M ARR/Funding or a non-commercial dev, the **Community Tier** is 100% free under the Business Source License (BSL).
+
+---
+
+*Secured by [dynos.fit](https://dynos.fit)*

doc/getting_started.md

@@ -0,0 +1,90 @@
+# 🚀 Getting Started with dynos_sync
+
+This guide will walk you through building a high-reliability, production-hardened offline-first synchronization layer in under 5 minutes.
+
+---
+
+## 🏗️ 1. Define Your Implementation
+
+Every **dynos_sync** architecture requires 4 core adapters. You can use our built-in helpers or write your own:
+
+### A. The Local Store (e.g. SQLite via Drift)
+```dart
+class MyLocalStore implements LocalStore {
+  @override
+  Future<void> upsert(String t, String id, Map<String, dynamic> d) async => ...;
+  @override
+  Future<void> delete(String t, String id) async => ...;
+  @override
+  Future<void> clearAll(List<String> tables) async => ...; // Critical for secure logout
+}
+```
+
+### B. The Remote Store (e.g. Supabase or REST)
+```dart
+class MyRemoteStore implements RemoteStore {
+  @override
+  Future<void> pushBatch(List<SyncEntry> entries) async => ...;
+  @override
+  Future<List<Map<String, dynamic>>> pullSince(String t, DateTime ts) async => ...;
+}
+```
+
+---
+
+## ⚡ 2. Initialize the Engine
+
+Configure the `SyncEngine` with your schemas and security policies.
+
+```dart
+final sync = SyncEngine(
+  local: MyLocalStore(),
+  remote: MyRemoteStore(),
+  queue: MyQueueStore(),
+  timestamps: MyTimestampStore(),
+  tables: ['workouts', 'profiles'],
+  config: const SyncConfig(
+    sensitiveFields: ['password', 'ssn'], // 🛡️ Automasking for PII
+    useExponentialBackoff: true,          // 📶 Scalable retry logic
+    batchSize: 50,                        // 🧠 Memory-efficient processing
+  ),
+);
+```
+
+---
+
+## 🦾 3. Efficient Backgrounding
+
+To keep your UI at 120 FPS during massive data pulls (e.g., 100k rows), use the `IsolateSyncEngine`:
+
+```dart
+final manager = IsolateSyncEngine(sync);
+
+// Runs in a dedicated background worker
+await manager.syncAllInBackground(); 
+```
+
+---
+
+## 🛡️ 4. Security Practices
+
+### The "Session Void" Pattern
+Ensure you call logout explicitly to purge sensitive un-synced data on shared devices:
+
+```dart
+await sync.logout(); // Triggers table-scoped local wiping
+```
+
+### JSON Exfiltration Prevention
+Set `maxPayloadBytes` in the config to prevent oversized accidental writes from jamming your sync pipeline.
+
+---
+
+## 📚 What's Next?
+*   Read the **[🏟️ Architecture Guide](architecture.md)** for protocol deep-dives.
+*   Check the **[🛡️ Security Audit](security_audit.md)** for the 42 attack vectors.
+*   Explore **[example/example.dart](../example/example.dart)** for a complete Supabase integration sample.
+
+---
+
+*Battle-Tested by [dynos.fit](https://dynos.fit)*