Doc updates

Author: marcprux

src/content/docs/docs/app-development.md

@@ -5,7 +5,7 @@ permalink: /docs/app-development/
 
 Skip allows you to share as much or as little code as you want between the iOS and Android versions of your app. The  [Cross-Platform Topics](/docs/platformcustomization/) chapter details how to integrate Android-specific or iOS-specific code. This chapter focuses on shared dual-platform development.
 
-The following sections do not attempt to teach you iOS development. There are other available resources for that. Rather, we focus on where dual-platform Skip development differs from standard iOS development, including how to use Skip’s tools and what to do when things go wrong.
+The following sections assume you are already familiar with iOS development. We focus on where dual-platform Skip development differs from standard iOS development, including how to use Skip’s tools and what to do when things go wrong.
 
 ## Philosophy
 
@@ -99,9 +99,9 @@ You must run your tests against a macOS destination in order to perform an Andro
 
 ## Coding {#coding}
 
-Writing dual-platform code with Skip resembles coding a standard iOS app, and it can feel magical to see your Swift and SwiftUI run on Android. But in the end Skip is a tool that you work with, and writing for two platforms does introduce complications not found in pure iOS development:
+Writing dual-platform code with Skip resembles coding a standard iOS app, and seeing your Swift and SwiftUI run on Android is a great experience. But writing for two platforms does introduce complications not found in pure iOS development:
 
-1. At some point, you will likely find yourself wanting to use an iOS API, framework, or feature that is not yet supported on Android. Don't give up! [This section](#unsupported-ios-features) discusses your options when you encounter a limitation in dual-platform coverage.
+1. At some point, you will likely want to use an iOS API, framework, or feature that is not yet supported on Android. [This section](#unsupported-ios-features) discusses your options when you encounter a limitation in dual-platform coverage.
 1. Our [porting](/docs/porting/) guide covers some of the common issues you'll run into when compiling cross-platform Swift. Additionally, compiled Swift must use [bridging](/docs/modes/#bridging) to interact with Android's Kotlin and Java APIs.
 1. Writing a dual-platform apps means using dual-platform libraries. Our documentation on [dependencies](/docs/dependencies/) discusses how to use other dual-platform libraries as well as iOS and Android-specific libraries.
 
@@ -174,7 +174,7 @@ This section only applies to [Skip Fuse](/docs/modes/#fuse). A [Skip Lite](/docs
 
 ### SwiftUI
 
-Writing cross-platform SwiftUI and watching it appear on both the iOS simulator and Android emulator can feel magical. It is a wonderful way to share all or parts of your user interface. And because Skip translates your SwiftUI calls to Jetpack Compose on Android, the result is a fully native user interface on both platforms, not an uncanny-valley replica.
+Skip lets you share all or parts of your user interface across both platforms. Because Skip translates your SwiftUI views to Jetpack Compose on Android, the result is a fully native user interface on both platforms, not a cross-platform approximation.
 
 On Android, `import SwiftUI` vends an implementation of the SwiftUI API called `SkipFuseUI` that is bridged to Jetpack Compose. Make sure you also **use default or public visibility for Views and their SwiftUI properties**. Skip cannot access private SwiftUI components on Android. Here is an example of a valid cross-platform SwiftUI view:
 

src/content/docs/docs/bridging.md

@@ -3,7 +3,7 @@ title: Bridging Reference
 permalink: /docs/bridging/
 ---
 
-Skip's [documentation](/docs/modes/#bridging) describes Skip's technology for bridging between compiled Swift and transpiled Swift or Kotlin and Java. This reference details the Swift language features and types that can be bridged. Bridging capabilities are symmetrical unless otherwise noted. That is, if something is marked as bridgeable, then you can use it whether you are bridging from native Swift to Kotlin/Java, or from transpiled Kotlin/Java to native Swift.
+Skip's [documentation](/docs/modes/#bridging) describes the technology for bridging between compiled Swift and transpiled Swift or Kotlin and Java. This reference details which Swift language features and types can be bridged. Bridging works in both directions (Swift to Kotlin/Java and Kotlin/Java to Swift) with equal capability, except where noted below.
 
 ## Language Features
 

src/content/docs/docs/c-development.md

@@ -3,4 +3,24 @@ title: C Development Reference
 permalink: /docs/c-development/
 ---
 
-One of the advantages of Skip's [native mode](/docs/modes/#fuse) is the ability to take full advantage of Swift's excellent interoperability with C libraries. But thanks to the magic of Skip's [`skip-ffi`](/docs/modules/skip-ffi/) module, you can interoperate with C in [transpiled mode](/docs/modes/#lite) as well! See the [Sharing C code between Swift and Kotlin for iPhone and Android apps](/blog/sharing-c-between-swift-and-kotlin/) blog entry to learn more about using C from transpiled Swift.
+Skip supports calling C and C++ code from your cross-platform Swift, with different mechanisms depending on which mode you are using.
+
+## Skip Fuse (Native Mode)
+
+In [Fuse mode](/docs/modes/#fuse), your Swift compiles natively for Android, so Swift's built-in C and C++ interoperability works exactly as it does on iOS. You can use Swift's `import` of C modules, call C functions directly, and work with C pointers and structs without any bridging layer.
+
+This means you can use C libraries (like SQLite, libxml2, or your own native code) on both platforms with no additional effort beyond what you would do on iOS. The [Swift Android SDK](https://www.swift.org/blog/swift-6.3-released/#android) includes the Android NDK, so common system libraries are available.
+
+For examples of C interop in a Fuse project, see the [skipapp-travelposters-native](https://github.com/skiptools/skipapp-travelposters-native) sample.
+
+## Skip Lite (Transpiled Mode)
+
+In [Lite mode](/docs/modes/#lite), your Swift is transpiled to Kotlin, so Swift's native C interop is not available. Instead, Skip provides the [`skip-ffi`](/docs/modules/skip-ffi/) module, which uses [JNA (Java Native Access)](https://github.com/java-native-access/jna) to call C functions from the transpiled Kotlin code.
+
+With `skip-ffi`, you write your C function declarations in Swift, and Skip transpiles them into JNA calls on Android. This lets you share C library code across both platforms from a single Swift codebase.
+
+For a detailed walkthrough, see the blog post [Sharing C code between Swift and Kotlin for iPhone and Android apps](/blog/sharing-c-between-swift-and-kotlin/).
+
+## Which approach to choose
+
+If your project relies heavily on C or C++ libraries, Fuse mode is the simpler path because Swift's native interop works identically on both platforms. If you are using Lite mode for other reasons (such as maximizing Kotlin interoperability), `skip-ffi` provides a solid bridge to C libraries through JNA.

src/content/docs/docs/dependencies.md

@@ -45,7 +45,7 @@ let package = Package(
 ```
 
 :::caution
-[Skip Lite](/docs/modes/#fuse) modules cannot use pure SwiftPM packages for Android. A Skip Lite module will see that the dependency does not have a `Skip/skip.yml` file and exclude it from the Android build. 
+[Skip Lite](/docs/modes/#lite) modules cannot use pure SwiftPM packages for Android. A Skip Lite module will see that the dependency does not have a `Skip/skip.yml` file and exclude it from the Android build. 
 :::
 
 ---

src/content/docs/docs/development-topics.md

@@ -178,9 +178,9 @@ Token | Meaning
 --- | ---
 $@ | String or stringified instance
 %ld or %lld | integer number
-%lf or %llf | floating point number
+%lf or %f | floating point number
 %.3f | formatted floating point number
-%1$@ | maually-specified positional argument
+%1$@ | manually-specified positional argument
 %% | literal escaped percent sign
 
 More information on the Xcode editor for the `xcstrings` format can be found at [https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog).

src/content/docs/docs/faq.md

@@ -60,11 +60,11 @@ We generally recommend the LGPL, which provides a good balance of flexibility an
 
 ### Can Skip Apps be distributed on the Apple App Store and the Google Play Store? {#appstore}
 
-Yes. Applications built with Skip utilize the user interface toolkits recommended by the platform vendors themselves, and thereby follow the guidelines and principles that are unique to each of these two individual platforms. On the iOS side, the [Skip Core Framrwork](#skipstack) modules can be eliminated from the build (with [SkipZero](#skipzero)), resulting in an app submission that contains no trace of any Skip libraries whatsoever.
+Yes. Applications built with Skip utilize the user interface toolkits recommended by the platform vendors themselves, and thereby follow the guidelines and principles that are unique to each of these two individual platforms. On the iOS side, the [Skip Core Framework](#skipstack) modules can be eliminated from the build (with [SkipZero](#skipzero)), resulting in an app submission that contains no trace of any Skip libraries whatsoever.
 
 One example of an app that is distributed on the Apple App Store and the Google Play Store is the [Skip Showcase](/docs/samples/skipapp-showcase/) app.
 
-### What does it mean it be Genuinely Native? {#genuinely_native}
+### What does it mean to be Genuinely Native? {#genuinely_native}
 
 Skip apps are genuinely native, in that they use the vendor-recommended UI toolkits directly, thereby guaranteeing maximum compatibility, accessibility, and performance. They use SwiftUI directly on the iPhone (“<i>SwiftUI is the preferred app-builder technology, because it offers a modern, platform-agnostic approach to building your UI and app infrastructure.</i>” – [developer.apple.com](https://developer.apple.com/ios/planning/#build-the-data-structures-youll-use-in-your-app)) and Compose on Android (“<i>We recommend using Jetpack Compose if you’re looking to build a new app</i>” – [android-developers.googleblog.com](https://android-developers.googleblog.com/2023/02/hundreds-of-thousands-of-developers-are-learning-jetpack-compose.html)).
 
@@ -100,11 +100,11 @@ However, AI tools can be very useful for generating Swift and SwiftUI code, espe
 
 ### What is the minimum iOS version for Skip apps? {#ios_version}
 
-iOS 16+. It is estimated at [developer.apple.com](https://developer.apple.com/support/app-store/) that 96% of all devices introduced in the last four years use iOS 16 or higher, as measured by devices that transacted on the App Store as of February 4, 2024.
+iOS 16+. According to [developer.apple.com](https://developer.apple.com/support/app-store/), the vast majority of active devices run iOS 16 or higher.
 
 ### What is the minimum Android version for Skip apps? {#android_version}
 
-Skip targets Android API level 34 (which is the minimum allowed level for submitting new apps to the Play Store, according to [https://developer.android.com/google/play/requirements/target-sdk](https://developer.android.com/google/play/requirements/target-sdk)) with a minimum supported version of API level 28. Android API 28 ("P"; Android 9) will run on over 95% of active Android devices as of January, 2026, according to the device reach estimate by Android Studio.
+Skip targets Android API level 34, which is the minimum level required for submitting new apps to the [Play Store](https://developer.android.com/google/play/requirements/target-sdk). The minimum supported version is API level 28 (Android 9 "Pie"), which covers over 95% of active Android devices according to Android Studio's device reach estimates.
 
 ### How large are apps that are built using Skip? {#app_size}
 
@@ -301,7 +301,7 @@ Some libraries have Skip-specific bridging implementations, like [SkipAV](/docs/
 
 ### What third-party dependencies will work with Skip Fuse? {#skip_fuse_third_party_deps}
 
-Some packages that rely solely on built-in frameworks like Foundation and the Swift standard library will work "out of the box" with Skip Fuse. For other packages, it is up to the maintainer to add support for Android to their Swift package. In some cases, this can be a trivial matter, and in other cases — especially when the package interacts with low-level operating-system specific nuances — it can be more challenging.
+Some packages that rely solely on built-in frameworks like Foundation and the Swift standard library will work "out of the box" with Skip Fuse. For other packages, it is up to the maintainer to add support for Android to their Swift package. In some cases this can be straightforward, but packages that interact with low-level OS-specific APIs can be more challenging to port.
 
 The [Bringing Swift Packages to Android](/blog/android-native-swift-packages/) post provides more information and some helpful suggestions for package authors who want to ensure their code can be used on Android.
 

src/content/docs/docs/gettingstarted.mdx

@@ -61,9 +61,9 @@ Skip requires a macOS 15+ development machine.
     skip create
     ```
 
-    You will be guided through a series of questions about the app you want to create. The first two are especially important:
+    You will be guided through a series of questions about the app you want to create. The two key choices are:
 
-    1. **App or Library?** The App option creates a single Swift and SwiftUI app that uses Skip's Xcode plugin to automatically build for Android. The Library option creates a Swift library that you can use in a unified Skip app, or use as shared business logic in [separate iOS and Android apps](/docs/project-types/#separate-apps). Neither option prevents you from using a combination of Swift and Kotlin, SwiftUI and Compose in your final application.
+    1. **App or Library?** The App option creates a single Swift and SwiftUI app that uses Skip's Xcode plugin to automatically build for Android. The Library option creates a Swift library that you can use in a unified Skip app, or use as shared business logic in [separate iOS and Android apps](/docs/project-types/#separate-apps). Both options allow you to use a combination of Swift and Kotlin, SwiftUI and Compose in your final application.
     2. **Skip Fuse or Skip Lite?** Information about the different modes can be found in the [Native and Transpiled Modes](/docs/modes/) documentation. In this example, we create a Skip Fuse app, which uses the official [Swift SDK for Android](https://www.swift.org/documentation/articles/swift-sdk-for-android-getting-started.html).
 
     If you're new to Skip, we recommend starting your exploration with an App project. An example session for creating a `hello-skip/HelloSkip` project (which generates a project identical to the minimal [Skip Fuse sample app](https://github.com/skiptools/skipapp-howdy) or [Skip Lite sample app](https://github.com/skiptools/skipapp-hello)) might look like:

src/content/docs/docs/glossary.md

@@ -37,7 +37,7 @@ Skip's modern app development mode that uses native Swift built with the [Swift
 - [Fully Native Cross-Platform Swift Apps (Skip Blog)](/blog/fully-native-android-swift-apps/)
 
 ### Skip Plugin {#skipstone}
-An [Xcode](#xcode) and [SwiftPM](#swiftpm) plugin — also known as _skipstone_ — that handles the conversion of an iOS project into an Android project. The plugin handles resource conversion and packaging, localization processing, building bridges between Swift and Kotlin in [Skip Fuse](#skip-fuse) mode, and performing Swift to Kotlin [transpilation](#transpiler) in [Skip Lite](#skip-lite) mode. In both modes, the plugin automatically translates [SwiftUI](#swiftui) into [Jetpack Compose](#jetpack-compose) as you develop.
+An [Xcode](#xcode) and [SwiftPM](#swiftpm) plugin (also known as _skipstone_) that handles the conversion of an iOS project into an Android project. The plugin handles resource conversion and packaging, localization processing, building bridges between Swift and Kotlin in [Skip Fuse](#skip-fuse) mode, and performing Swift to Kotlin [transpilation](#transpiler) in [Skip Lite](#skip-lite) mode. In both modes, the plugin automatically translates [SwiftUI](#swiftui) into [Jetpack Compose](#jetpack-compose) as you develop.
 
 **Related Terms:** [Xcode](#xcode), [Transpiler](#transpiler), [SwiftPM](#swiftpm), [Skip Lite](#skip-lite), [Skip Fuse](#skip-fuse), [Skip Bridge](#skip-bridge)
 

src/content/docs/docs/help.md

@@ -9,7 +9,27 @@ Please include the output of the `skip checkup` command in any communication rel
 
 ## Troubleshooting Common Issues {#troubleshooting}
 
-Skip's architecture relies on the Swift Package Manager build plugin system. When unexpected issues arise, often the best first step is to clean your Xcode build (`Product` -> `Clean Build Folder`) and reset packages (`File` -> `Packages` -> `Reset Package Caches`). Restarting Xcode is sometimes warranted, and trashing the local `DerivedData` folder as well as your app directory's `.build` folder might even be needed. 
+Skip's architecture relies on the Swift Package Manager build plugin system. When unexpected issues arise, often the best first step is to clean your Xcode build (`Product` -> `Clean Build Folder`) and reset packages (`File` -> `Packages` -> `Reset Package Caches`). Restarting Xcode is sometimes warranted, and trashing the local `DerivedData` folder as well as your app directory's `.build` folder might even be needed.
 
-Specific known error conditions are listed below. Search the [documentation](/docs), [issues](https://source.skip.dev/skip/issues), and [discussions](http://forums.skip.dev) for more information and to report problems.
+### First build is very slow or appears to hang
+
+The first build of a Skip project downloads all required Gradle dependencies and builds the Compose libraries. This can take several minutes and download over 1 GB of files. Subsequent builds are much faster because the dependencies are cached. Run with `--verbose` or check the Xcode build log to see progress.
+
+### "No such module" errors after updating Skip
+
+After upgrading Skip versions, you may need to reset your package caches. In Xcode, use `File` -> `Packages` -> `Reset Package Caches`, then clean and rebuild. If the error persists, delete the `.build` folder in your project directory.
+
+### Android emulator not found
+
+If Skip reports that no Android emulator is running, verify with `adb devices` that a device is listed. You can create and launch an emulator with `skip android emulator create` followed by `skip android emulator launch`. See the [CLI reference](/docs/skip-cli/#android-emulator) for details.
+
+### Gradle build failures
+
+Gradle errors are surfaced through the Xcode build log. Common causes include network issues (Gradle needs internet to resolve dependencies on the first build), Java version mismatches, and stale caches. Run `skip doctor` to verify your environment, and try deleting the `.build` folder in your project directory to clear the Gradle caches.
+
+### Plugin trust dialog in Xcode
+
+The first time you build a Skip project in Xcode, you may see a dialog asking you to trust the Skip build plugin. Select "Trust & Enable" to proceed. This is a standard Xcode security prompt for all SwiftPM build plugins.
+
+Search the [documentation](/docs), [issues](https://source.skip.dev/skip/issues), and [discussions](http://forums.skip.dev) for more information and to report problems.