android-sdd 1.0.0

package/skills/Android Platform/Filesystem/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: filesystem
+description: >
+  Android filesystem — internal storage, external storage, cache, and file sharing.
+  Load this skill when reading or writing files, sharing files between apps,
+  choosing the right storage location, or handling storage permissions.
+---
+
+# Filesystem
+
+## Overview
+
+Android provides several storage locations with different visibility, persistence, and permission requirements. Choosing the right location depends on whether files are private to the app, shareable with other apps, or user-visible. Scoped Storage (API 29+) significantly restricts direct filesystem access.
+
+---
+
+## Core Principles
+
+- Default to **internal storage** — private, no permissions needed
+- Use **external storage** only for files the user should access via file manager
+- Never use `Environment.getExternalStorageDirectory()` — deprecated, requires dangerous permission
+- Use `FileProvider` for sharing files with other apps — never expose raw file paths
+- Cache files can be deleted by the system at any time — don't rely on them for critical data
+
+---
+
+## Storage Locations
+
+| Location           | API                             | Permission               | Cleared on Uninstall | Visible to User |
+| ------------------ | ------------------------------- | ------------------------ | -------------------- | --------------- |
+| `filesDir`         | `context.filesDir`              | None                     | ✅ Yes                | ❌ No            |
+| `cacheDir`         | `context.cacheDir`              | None                     | ✅ Yes                | ❌ No            |
+| `externalFilesDir` | `context.getExternalFilesDir()` | None (API 19+)           | ✅ Yes                | ✅ Yes           |
+| `externalCacheDir` | `context.externalCacheDir`      | None                     | ✅ Yes                | ✅ Yes           |
+| MediaStore         | Via ContentResolver             | `READ_MEDIA_*` (API 33+) | ❌ No                 | ✅ Yes           |
+
+---
+
+## Internal Storage
+
+```kotlin
+// ✅ Write to internal storage
+fun writeFile(context: Context, fileName: String, content: String) {
+    val file = File(context.filesDir, fileName)
+    file.writeText(content)
+}
+
+// ✅ Read from internal storage
+fun readFile(context: Context, fileName: String): String? {
+    val file = File(context.filesDir, fileName)
+    return if (file.exists()) file.readText() else null
+}
+
+// ✅ Subdirectory in internal storage
+fun getAppDirectory(context: Context, dirName: String): File {
+    return File(context.filesDir, dirName).also { it.mkdirs() }
+}
+
+// ✅ Write binary data
+fun writeBinaryFile(context: Context, fileName: String, bytes: ByteArray) {
+    File(context.filesDir, fileName).writeBytes(bytes)
+}
+```
+
+---
+
+## Cache Storage
+
+```kotlin
+// ✅ Use cache for temporary/reproducible data
+fun cacheImage(context: Context, name: String, bitmap: Bitmap) {
+    val file = File(context.cacheDir, name)
+    file.outputStream().use { out ->
+        bitmap.compress(Bitmap.CompressFormat.JPEG, 90, out)
+    }
+}
+
+// ✅ Check cache before downloading
+fun getCachedFile(context: Context, name: String): File? {
+    val file = File(context.cacheDir, name)
+    return if (file.exists()) file else null
+}
+
+// ✅ Limit cache size manually if needed
+fun trimCache(context: Context, maxSizeBytes: Long) {
+    val cacheDir = context.cacheDir
+    val files = cacheDir.listFiles()?.sortedBy { it.lastModified() } ?: return
+    var totalSize = files.sumOf { it.length() }
+    for (file in files) {
+        if (totalSize <= maxSizeBytes) break
+        totalSize -= file.length()
+        file.delete()
+    }
+}
+```
+
+---
+
+## External App-Specific Storage
+
+```kotlin
+// ✅ Write to app-specific external directory (no permission needed)
+fun writeToExternalFiles(context: Context, fileName: String, content: String) {
+    val dir = context.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS)
+        ?: return // external storage may not be available
+    File(dir, fileName).writeText(content)
+}
+
+// ✅ Check external storage availability
+fun isExternalStorageWritable(): Boolean =
+    Environment.getExternalStorageState() == Environment.MEDIA_MOUNTED
+```
+
+---
+
+## File Sharing with FileProvider
+
+```xml
+<!-- AndroidManifest.xml -->
+<provider
+    android:name="androidx.core.content.FileProvider"
+    android:authorities="${applicationId}.fileprovider"
+    android:exported="false"
+    android:grantUriPermissions="true">
+    <meta-data
+        android:name="android.support.FILE_PROVIDER_PATHS"
+        android:resource="@xml/file_paths" />
+</provider>
+```
+
+```xml
+<!-- res/xml/file_paths.xml -->
+<paths>
+    <files-path name="internal_files" path="." />
+    <cache-path name="cache" path="." />
+    <external-files-path name="external_files" path="." />
+</paths>
+```
+
+```kotlin
+// ✅ Share a file via FileProvider
+fun shareFile(context: Context, file: File) {
+    val uri = FileProvider.getUriForFile(
+        context,
+        "${context.packageName}.fileprovider",
+        file
+    )
+
+    val intent = Intent(Intent.ACTION_SEND).apply {
+        type = "application/pdf"
+        putExtra(Intent.EXTRA_STREAM, uri)
+        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+    }
+
+    context.startActivity(Intent.createChooser(intent, "Share File"))
+}
+```
+
+---
+
+## Reading Files from Assets
+
+```kotlin
+// ✅ Read from assets/
+fun readAsset(context: Context, fileName: String): String {
+    return context.assets.open(fileName).bufferedReader().use { it.readText() }
+}
+
+// ✅ Read JSON config from assets
+fun readJsonAsset(context: Context, fileName: String): JsonObject {
+    val content = readAsset(context, fileName)
+    return Json.parseToJsonElement(content).jsonObject
+}
+```
+
+---
+
+## Coroutine-Safe File I/O
+
+```kotlin
+// ✅ Always perform file I/O on Dispatchers.IO
+suspend fun writeFileSafely(context: Context, fileName: String, content: String) {
+    withContext(Dispatchers.IO) {
+        File(context.filesDir, fileName).writeText(content)
+    }
+}
+
+suspend fun readFileSafely(context: Context, fileName: String): String? {
+    return withContext(Dispatchers.IO) {
+        val file = File(context.filesDir, fileName)
+        if (file.exists()) file.readText() else null
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `Environment.getExternalStorageDirectory()` — deprecated since API 29
+- File I/O on the main thread — causes ANR
+- Exposing raw `file://` URIs to other apps — crashes on API 24+, use FileProvider
+- Storing sensitive data in external storage — accessible by other apps
+- Relying on cache files for critical data — system can delete them anytime
+- Not checking external storage availability before writing
+- Hardcoding absolute paths — they differ across devices and API levels
+
+---
+
+## Related Skills
+
+- `file-storage` — higher-level file storage patterns
+- `binary-storage` — storing binary/media files
+- `encrypted-database` — encrypting sensitive stored data
+- `workmanager` — background file operations
+- `datastore` — structured key-value persistence

package/skills/Android Platform/Lifecycle/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: lifecycle
+description: >
+  Android Lifecycle management for Activities, Fragments, and Compose.
+  Load this skill when working with lifecycle-aware components, collecting
+  flows with lifecycle awareness, managing resources tied to lifecycle,
+  or avoiding memory leaks caused by lifecycle misuse.
+---
+
+# Lifecycle
+
+## Overview
+
+The Android Lifecycle represents the states an Activity, Fragment, or other component goes through from creation to destruction. Lifecycle-awareness ensures that operations start and stop at the right time, preventing memory leaks, crashes, and wasted resources.
+
+---
+
+## Core Principles
+
+- Never hold references to Activity or Fragment in long-lived objects
+- Always use lifecycle-aware collection for Flows — never raw `launch {}`
+- Release resources in the **symmetric opposite** of where they were acquired
+- Prefer `ViewModel` to survive configuration changes — never store UI state in Activity
+- Use `repeatOnLifecycle` over `launchWhenStarted` — it properly cancels on stop
+
+---
+
+## Lifecycle States
+
+```
+INITIALIZED → CREATED → STARTED → RESUMED
+                ↑           ↓
+             DESTROYED ← STOPPED
+```
+
+| State     | Activity callback | Fragment callback |
+| --------- | ----------------- | ----------------- |
+| CREATED   | `onCreate()`      | `onViewCreated()` |
+| STARTED   | `onStart()`       | `onStart()`       |
+| RESUMED   | `onResume()`      | `onResume()`      |
+| STOPPED   | `onStop()`        | `onStop()`        |
+| DESTROYED | `onDestroy()`     | `onDestroyView()` |
+
+---
+
+## Flow Collection — The Right Way
+
+```kotlin
+// ✅ repeatOnLifecycle — cancels collection when below target state
+viewLifecycleOwner.lifecycleScope.launch {
+    repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.state.collect { state ->
+            renderState(state)
+        }
+    }
+}
+
+// ✅ Multiple flows — launch inside repeatOnLifecycle
+viewLifecycleOwner.lifecycleScope.launch {
+    repeatOnLifecycle(Lifecycle.State.STARTED) {
+        launch { viewModel.state.collect { renderState(it) } }
+        launch { viewModel.events.collect { handleEvent(it) } }
+    }
+}
+
+// ✅ Compose — collectAsStateWithLifecycle (preferred over collectAsState)
+@Composable
+fun MyScreen(viewModel: MyViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+}
+
+// ❌ Wrong — doesn't cancel when app goes to background
+lifecycleScope.launch {
+    viewModel.state.collect { renderState(it) }
+}
+
+// ❌ Wrong — deprecated, doesn't resume collection after stop
+lifecycleScope.launchWhenStarted {
+    viewModel.state.collect { renderState(it) }
+}
+```
+
+---
+
+## ViewModel and Lifecycle
+
+```kotlin
+// ✅ ViewModel survives configuration changes
+class UserViewModel : ViewModel() {
+    // State here survives rotation
+    private val _state = MutableStateFlow(UserUiState())
+    val state: StateFlow<UserUiState> = _state.asStateFlow()
+
+    // ✅ viewModelScope is cancelled when ViewModel is cleared
+    fun loadUsers() {
+        viewModelScope.launch {
+            // safe — auto-cancelled on ViewModel destruction
+        }
+    }
+
+    // ✅ onCleared — clean up resources
+    override fun onCleared() {
+        super.onCleared()
+        // cancel non-coroutine resources if needed
+    }
+}
+
+// ✅ Get ViewModel in Fragment
+class UserFragment : Fragment() {
+    private val viewModel: UserViewModel by viewModels()
+    // shared ViewModel across fragments in same Activity
+    private val sharedViewModel: SharedViewModel by activityViewModels()
+}
+```
+
+---
+
+## Lifecycle-Aware Resource Management
+
+```kotlin
+// ✅ Register/unregister in symmetric callbacks
+class LocationFragment : Fragment() {
+
+    private lateinit var locationManager: LocationManager
+
+    override fun onStart() {
+        super.onStart()
+        locationManager.startUpdates()  // start in onStart
+    }
+
+    override fun onStop() {
+        locationManager.stopUpdates()   // stop in onStop
+        super.onStop()
+    }
+}
+
+// ✅ ViewBinding — avoid leaks
+class UserFragment : Fragment(R.layout.fragment_user) {
+
+    private var _binding: FragmentUserBinding? = null
+    private val binding get() = _binding!!
+
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        super.onViewCreated(view, savedInstanceState)
+        _binding = FragmentUserBinding.bind(view)
+    }
+
+    override fun onDestroyView() {
+        _binding = null  // ✅ clear binding reference
+        super.onDestroyView()
+    }
+}
+```
+
+---
+
+## DefaultLifecycleObserver
+
+```kotlin
+// ✅ Use DefaultLifecycleObserver for custom lifecycle-aware components
+class AnalyticsTracker(private val analytics: Analytics) : DefaultLifecycleObserver {
+
+    override fun onStart(owner: LifecycleOwner) {
+        analytics.startSession()
+    }
+
+    override fun onStop(owner: LifecycleOwner) {
+        analytics.endSession()
+    }
+}
+
+// Register in Activity or Fragment
+lifecycle.addObserver(AnalyticsTracker(analytics))
+```
+
+---
+
+## Compose Lifecycle
+
+```kotlin
+// ✅ LaunchedEffect — scoped to composition, cancelled on leave
+@Composable
+fun UserScreen(userId: String) {
+    LaunchedEffect(userId) {
+        // runs when userId changes, cancelled when composable leaves
+        viewModel.loadUser(userId)
+    }
+}
+
+// ✅ DisposableEffect — for non-coroutine cleanup
+@Composable
+fun MapScreen() {
+    DisposableEffect(Unit) {
+        val listener = registerMapListener()
+        onDispose {
+            listener.unregister()
+        }
+    }
+}
+
+// ✅ rememberUpdatedState — keep latest value in long-running effect
+@Composable
+fun Timer(onTick: () -> Unit) {
+    val currentOnTick by rememberUpdatedState(onTick)
+    LaunchedEffect(Unit) {
+        while (true) {
+            delay(1_000)
+            currentOnTick()
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Storing Activity/Fragment reference in ViewModel or Repository — causes memory leaks
+- Using `lifecycleScope.launch {}` without `repeatOnLifecycle` for Flow collection
+- Using `launchWhenStarted` — deprecated, doesn't cancel on stop
+- Starting work in `onCreate` that should be in `onStart` — runs even when not visible
+- Forgetting to clear ViewBinding in `onDestroyView` — memory leak
+- Using `GlobalScope` for any lifecycle-bound work
+
+---
+
+## Related Skills
+
+- `savedstatehandle` — persisting state across process death
+- `process-death-recovery` — surviving process kill
+- `viewmodel` — state management with ViewModel
+- `compose` — Compose-specific lifecycle patterns
+- `reactive-streams` — lifecycle-aware Flow collection

package/skills/Android Platform/Manifest/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: manifest
+description: >
+  Android Manifest configuration and best practices.
+  Load this skill when editing AndroidManifest.xml, declaring components,
+  configuring permissions, intent filters, or app-level attributes.
+---
+
+# Manifest
+
+## Overview
+
+The AndroidManifest.xml is the entry point configuration of every Android app. It declares all components, permissions, hardware requirements, and app-level behavior. Incorrect manifest configuration causes runtime crashes, security vulnerabilities, and Play Store rejections.
+
+---
+
+## Core Principles
+
+- Declare only what the app **actually needs** — minimal permissions
+- Never declare a component that isn't used — increases attack surface
+- Always declare `android:exported` explicitly on components with intent filters
+- Keep sensitive config (API keys, secrets) out of the manifest — use BuildConfig or encrypted storage
+- Use `tools:` namespace for merge directives — never duplicate entries
+
+---
+
+## Application Block
+
+```xml
+<application
+    android:name=".MyApplication"
+    android:icon="@mipmap/ic_launcher"
+    android:roundIcon="@mipmap/ic_launcher_round"
+    android:label="@string/app_name"
+    android:theme="@style/Theme.App"
+    android:supportsRtl="true"
+    android:allowBackup="false"
+    android:fullBackupContent="false"
+    android:dataExtractionRules="@xml/data_extraction_rules"
+    android:networkSecurityConfig="@xml/network_security_config">
+
+    <!-- components go here -->
+
+</application>
+```
+
+---
+
+## Activity Declaration
+
+```xml
+<!-- ✅ Main launcher activity -->
+<activity
+    android:name=".MainActivity"
+    android:exported="true"
+    android:windowSoftInputMode="adjustResize"
+    android:configChanges="orientation|screenSize|keyboardHidden">
+    <intent-filter>
+        <action android:name="android.intent.action.MAIN" />
+        <category android:name="android.intent.category.LAUNCHER" />
+    </intent-filter>
+</activity>
+
+<!-- ✅ Internal activity — not exported -->
+<activity
+    android:name=".feature.detail.DetailActivity"
+    android:exported="false" />
+
+<!-- ✅ Deep link support -->
+<activity
+    android:name=".MainActivity"
+    android:exported="true">
+    <intent-filter android:autoVerify="true">
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="https" android:host="example.com" />
+    </intent-filter>
+</activity>
+```
+
+---
+
+## Permissions
+
+```xml
+<!-- ✅ Declare only what's needed -->
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+<!-- ✅ Runtime permissions — still declare in manifest -->
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+
+<!-- ✅ Restrict to specific OS version if not needed on older -->
+<uses-permission
+    android:name="android.permission.POST_NOTIFICATIONS"
+    android:minSdkVersion="33" />
+
+<!-- ✅ Remove permission added by a library -->
+<uses-permission
+    android:name="android.permission.READ_PHONE_STATE"
+    tools:node="remove" />
+```
+
+### Permission Groups by Category
+
+| Category      | Permissions                                                                    |
+| ------------- | ------------------------------------------------------------------------------ |
+| Network       | `INTERNET`, `ACCESS_NETWORK_STATE`, `CHANGE_NETWORK_STATE`                     |
+| Location      | `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`, `ACCESS_BACKGROUND_LOCATION` |
+| Camera        | `CAMERA`                                                                       |
+| Storage       | `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`, `READ_MEDIA_AUDIO`                    |
+| Notifications | `POST_NOTIFICATIONS` (API 33+)                                                 |
+| Bluetooth     | `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT` (API 31+)                                |
+
+---
+
+## Services
+
+```xml
+<!-- ✅ Foreground service -->
+<service
+    android:name=".service.DownloadService"
+    android:exported="false"
+    android:foregroundServiceType="dataSync" />
+
+<!-- ✅ WorkManager worker — no declaration needed -->
+<!-- Workers are not components and don't need manifest entries -->
+```
+
+---
+
+## Receivers
+
+```xml
+<!-- ✅ Boot receiver -->
+<receiver
+    android:name=".receiver.BootReceiver"
+    android:exported="true">
+    <intent-filter>
+        <action android:name="android.intent.action.BOOT_COMPLETED" />
+    </intent-filter>
+</receiver>
+
+<!-- ✅ Internal receiver — not exported -->
+<receiver
+    android:name=".receiver.DownloadReceiver"
+    android:exported="false" />
+```
+
+---
+
+## Providers
+
+```xml
+<!-- ✅ FileProvider for sharing files -->
+<provider
+    android:name="androidx.core.content.FileProvider"
+    android:authorities="${applicationId}.fileprovider"
+    android:exported="false"
+    android:grantUriPermissions="true">
+    <meta-data
+        android:name="android.support.FILE_PROVIDER_PATHS"
+        android:resource="@xml/file_paths" />
+</provider>
+```
+
+---
+
+## Manifest Merge (Multi-Module)
+
+```xml
+<!-- ✅ Override a library's manifest entry -->
+<activity
+    android:name="com.library.SomeActivity"
+    android:exported="false"
+    tools:node="merge" />
+
+<!-- ✅ Remove a component added by a library -->
+<activity
+    android:name="com.library.UnwantedActivity"
+    tools:node="remove" />
+
+<!-- ✅ Replace an attribute from a library -->
+<application
+    android:allowBackup="false"
+    tools:replace="android:allowBackup" />
+```
+
+---
+
+## Hardware Features
+
+```xml
+<!-- ✅ Declare required hardware -->
+<uses-feature
+    android:name="android.hardware.camera"
+    android:required="true" />
+
+<!-- ✅ Declare optional hardware — don't block install -->
+<uses-feature
+    android:name="android.hardware.camera.autofocus"
+    android:required="false" />
+```
+
+---
+
+## Anti-Patterns
+
+- `android:exported` not set on components with intent-filters — security risk, required API 31+
+- Storing API keys or secrets in `<meta-data>` — visible in decompiled APK
+- Declaring `READ_EXTERNAL_STORAGE` on API 33+ — use `READ_MEDIA_*` instead
+- Requesting `ACCESS_BACKGROUND_LOCATION` without foreground location first
+- Declaring unused permissions — increases permissions dialog burden and audit surface
+- Missing `android:supportsRtl="true"` — breaks RTL layouts
+- `android:allowBackup="true"` without configuring backup rules — leaks sensitive data
+
+---
+
+## Related Skills
+
+- `deep-link` — intent filter setup for deep links
+- `foreground-service` — foreground service declaration
+- `network-security-config` — network security configuration
+- `resources` — resource references in manifest