Add FAQ and quick start (#125)

Author: 0xLeif

README.md

@@ -40,6 +40,34 @@ To integrate **AppState** into your Swift project, you’ll need to use the Swif
 
 After installation, refer to the [Usage Overview](documentation/usage-overview.md) for a quick introduction on how to manage state and inject dependencies into your project.
 
+## Quick Example
+
+Below is a minimal example showing how to define a piece of state and access it from a SwiftUI view:
+
+```swift
+import AppState
+import SwiftUI
+
+private extension Application {
+    var counter: State<Int> {
+        state(initial: 0)
+    }
+}
+
+struct ContentView: View {
+    @AppState(\.counter) var counter: Int
+
+    var body: some View {
+        VStack {
+            Text("Count: \(counter)")
+            Button("Increment") { counter += 1 }
+        }
+    }
+}
+```
+
+This snippet demonstrates defining a state value in an `Application` extension and using the `@AppState` property wrapper to bind it inside a view.
+
 ## Documentation
 
 Here’s a detailed breakdown of **AppState**'s documentation:
@@ -55,6 +83,7 @@ Here’s a detailed breakdown of **AppState**'s documentation:
 - [FileState Usage Guide](documentation/usage-filestate.md): Learn how to persist larger amounts of data securely on disk.
 - [Keychain SecureState Usage](documentation/usage-securestate.md): Store sensitive data securely using the Keychain.
 - [iCloud Syncing with SyncState](documentation/usage-syncstate.md): Keep state synchronized across devices using iCloud.
+- [FAQ](documentation/faq.md): Answers to common questions when using **AppState**.
 
 ## Contributing
 

documentation/faq.md

@@ -0,0 +1,28 @@
+# Frequently Asked Questions
+
+This short FAQ addresses common questions developers may have when using **AppState**.
+
+## How do I reset a state value?
+
+Each `State` provides a `reset()` function that restores the value to the `initial` one defined in your `Application` extension. Call `reset()` when you need to clear user data or return to a default configuration.
+
+```swift
+@AppState(\.counter) var counter: Int
+
+func clearCounter() {
+    counter.reset() // Resets to the initial value
+}
+```
+
+## Can I use AppState with asynchronous tasks?
+
+Yes. `State` and dependency values are thread-safe and work seamlessly with Swift Concurrency. You can access and modify them inside `async` functions without additional locking.
+
+## Where should I define states and dependencies?
+
+Keep all your states and dependencies in `Application` extensions. This ensures a single source of truth and makes it easier to discover all available values.
+
+## Is AppState compatible with Combine?
+
+You can use AppState alongside Combine by bridging `State` changes to publishers. Observe a `State` value and send updates through a `PassthroughSubject` or other Combine publisher if needed.
+