android-sdd 1.0.0

package/skills/System Integration/Notification/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: notification
+description: >
+  Android notification system implementation.
+  Load this skill when creating notification channels, building
+  notifications, handling notification permissions, showing progress
+  notifications, or adding actions and deep links to notifications.
+---
+
+# Notification
+
+## Overview
+Android notifications require a notification channel (API 26+), a POST_NOTIFICATIONS permission request (API 33+), and a properly built `Notification` object. Notifications can contain actions, deep link intents, progress indicators, and custom layouts.
+
+---
+
+## Core Principles
+
+- Create notification channels **once** at app startup — not on every notification
+- Request `POST_NOTIFICATIONS` permission on Android 13+ before showing notifications
+- Use `NotificationCompat` — not the platform `Notification` directly
+- Always provide a `contentIntent` — tapping the notification should open the relevant screen
+- Group related notifications with a summary notification
+
+---
+
+## Permissions
+
+```xml
+<!-- AndroidManifest.xml -->
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+```
+
+```kotlin
+// ✅ Request permission on Android 13+
+class MainActivity : ComponentActivity() {
+    private val requestPermissionLauncher = registerForActivityResult(
+        ActivityResultContracts.RequestPermission()
+    ) { isGranted ->
+        if (!isGranted) {
+            // Show rationale or disable notification features
+        }
+    }
+
+    fun requestNotificationPermission() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            if (ContextCompat.checkSelfPermission(
+                    this, Manifest.permission.POST_NOTIFICATIONS
+                ) != PackageManager.PERMISSION_GRANTED
+            ) {
+                requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Notification Channels
+
+```kotlin
+// ✅ Create channels once at app startup
+class NotificationChannelSetup @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    fun createChannels() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+
+        val manager = context.getSystemService(NotificationManager::class.java)
+
+        manager.createNotificationChannel(
+            NotificationChannel(
+                CHANNEL_MESSAGES,
+                "Messages",
+                NotificationManager.IMPORTANCE_HIGH
+            ).apply {
+                description = "New message notifications"
+                enableVibration(true)
+            }
+        )
+
+        manager.createNotificationChannel(
+            NotificationChannel(
+                CHANNEL_SYNC,
+                "Sync",
+                NotificationManager.IMPORTANCE_LOW
+            ).apply {
+                description = "Background sync status"
+            }
+        )
+    }
+
+    companion object {
+        const val CHANNEL_MESSAGES = "channel_messages"
+        const val CHANNEL_SYNC = "channel_sync"
+    }
+}
+```
+
+---
+
+## Basic Notification
+
+```kotlin
+// ✅ Simple notification with deep link intent
+fun showMessageNotification(context: Context, message: Message) {
+    val deepLinkIntent = Intent(
+        Intent.ACTION_VIEW,
+        Uri.parse("https://example.com/messages/${message.id}")
+    ).apply {
+        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    }
+
+    val pendingIntent = TaskStackBuilder.create(context).run {
+        addNextIntentWithParentStack(deepLinkIntent)
+        getPendingIntent(
+            message.id.hashCode(),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )
+    }
+
+    val notification = NotificationCompat.Builder(context, CHANNEL_MESSAGES)
+        .setSmallIcon(R.drawable.ic_message)
+        .setContentTitle(message.senderName)
+        .setContentText(message.preview)
+        .setStyle(NotificationCompat.BigTextStyle().bigText(message.body))
+        .setContentIntent(pendingIntent)
+        .setAutoCancel(true)
+        .setPriority(NotificationCompat.PRIORITY_HIGH)
+        .build()
+
+    NotificationManagerCompat.from(context)
+        .notify(message.id.hashCode(), notification)
+}
+```
+
+---
+
+## Notification with Actions
+
+```kotlin
+// ✅ Action buttons on notification
+val replyIntent = PendingIntent.getBroadcast(
+    context,
+    0,
+    Intent(context, ReplyReceiver::class.java).putExtra("message_id", messageId),
+    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+)
+
+val markReadIntent = PendingIntent.getBroadcast(
+    context,
+    1,
+    Intent(context, MarkReadReceiver::class.java).putExtra("message_id", messageId),
+    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+)
+
+NotificationCompat.Builder(context, CHANNEL_MESSAGES)
+    .addAction(R.drawable.ic_reply, "Reply", replyIntent)
+    .addAction(R.drawable.ic_check, "Mark Read", markReadIntent)
+    .build()
+```
+
+---
+
+## Progress Notification
+
+```kotlin
+// ✅ Update progress notification
+fun showProgressNotification(context: Context, progress: Int, done: Boolean) {
+    val notification = NotificationCompat.Builder(context, CHANNEL_SYNC)
+        .setSmallIcon(R.drawable.ic_sync)
+        .setContentTitle("Uploading file")
+        .setContentText(if (done) "Upload complete" else "$progress%")
+        .setProgress(100, progress, false)
+        .setOngoing(!done)
+        .setOnlyAlertOnce(true)   // ✅ don't re-alert on every update
+        .build()
+
+    NotificationManagerCompat.from(context).notify(NOTIFICATION_ID_UPLOAD, notification)
+
+    if (done) {
+        // Remove progress after delay
+        Handler(Looper.getMainLooper()).postDelayed({
+            NotificationManagerCompat.from(context).cancel(NOTIFICATION_ID_UPLOAD)
+        }, 3_000)
+    }
+}
+```
+
+---
+
+## Grouped Notifications
+
+```kotlin
+// ✅ Group multiple notifications with a summary
+val GROUP_KEY = "com.example.MESSAGES"
+
+// Individual notifications
+messages.forEach { message ->
+    val notification = NotificationCompat.Builder(context, CHANNEL_MESSAGES)
+        .setSmallIcon(R.drawable.ic_message)
+        .setContentTitle(message.sender)
+        .setContentText(message.preview)
+        .setGroup(GROUP_KEY)
+        .build()
+    manager.notify(message.id.hashCode(), notification)
+}
+
+// Summary notification
+val summary = NotificationCompat.Builder(context, CHANNEL_MESSAGES)
+    .setSmallIcon(R.drawable.ic_message)
+    .setStyle(NotificationCompat.InboxStyle()
+        .setSummaryText("${messages.size} new messages"))
+    .setGroup(GROUP_KEY)
+    .setGroupSummary(true)
+    .build()
+manager.notify(SUMMARY_ID, summary)
+```
+
+---
+
+## Anti-Patterns
+
+- Creating notification channels on every `notify()` call — create once at startup
+- Not providing a `contentIntent` — tapping the notification does nothing
+- Using `IMPORTANCE_HIGH` for background sync notifications — disrupts the user
+- Not setting `FLAG_IMMUTABLE` on `PendingIntent` — crashes on Android 12+
+- Showing notifications without requesting `POST_NOTIFICATIONS` on Android 13+
+
+---
+
+## Related Skills
+- `deep-navigation` — building deep link intents for notifications
+- `foreground-service` — persistent service notification
+- `alarmmanager` — triggering notifications at a specific time
+- `firebase-messaging` — push notifications via FCM

package/skills/System Integration/WorkManager/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: workmanager
+description: >
+  WorkManager for guaranteed background task execution in Android.
+  Load this skill when scheduling deferrable work, running periodic tasks,
+  chaining workers, handling constraints, observing work state,
+  or running tasks that must survive app and device restarts.
+---
+
+# WorkManager
+
+## Overview
+WorkManager is the recommended solution for deferrable, guaranteed background work in Android. It handles Doze mode, app death, and device restarts transparently. It supports one-time and periodic work, constraints, chaining, and progress reporting.
+
+---
+
+## Core Principles
+
+- Use WorkManager for work that **must complete** even if the app is killed
+- Use `CoroutineWorker` — not `Worker` — for suspend-friendly work
+- Set **constraints** to avoid running on metered networks or low battery
+- Use **unique work** to prevent duplicate tasks
+- Observe work state via `WorkInfo` — never poll manually
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+workmanager = "2.9.0"
+
+[libraries]
+workmanager = { module = "androidx.work:work-runtime-ktx", version.ref = "workmanager" }
+```
+
+---
+
+## CoroutineWorker
+
+```kotlin
+// ✅ Standard worker
+class SyncWorker(
+    context: Context,
+    params: WorkerParameters
+) : CoroutineWorker(context, params) {
+
+    override suspend fun doWork(): Result {
+        return try {
+            val userId = inputData.getString(KEY_USER_ID)
+                ?: return Result.failure()
+
+            syncRepository.syncUser(userId)
+            Result.success()
+        } catch (e: Exception) {
+            if (runAttemptCount < 3) Result.retry()
+            else Result.failure(
+                workDataOf("error" to (e.message ?: "Unknown"))
+            )
+        }
+    }
+
+    companion object {
+        const val KEY_USER_ID = "user_id"
+    }
+}
+```
+
+---
+
+## One-Time Work
+
+```kotlin
+// ✅ Enqueue one-time work
+fun scheduleSyncUser(userId: String) {
+    val request = OneTimeWorkRequestBuilder<SyncWorker>()
+        .setInputData(workDataOf(SyncWorker.KEY_USER_ID to userId))
+        .setConstraints(
+            Constraints.Builder()
+                .setRequiredNetworkType(NetworkType.CONNECTED)
+                .build()
+        )
+        .setBackoffCriteria(
+            BackoffPolicy.EXPONENTIAL,
+            WorkRequest.MIN_BACKOFF_MILLIS,
+            TimeUnit.MILLISECONDS
+        )
+        .addTag("sync")
+        .build()
+
+    WorkManager.getInstance(context).enqueueUniqueWork(
+        "sync_user_$userId",
+        ExistingWorkPolicy.KEEP,   // don't replace if already queued
+        request
+    )
+}
+```
+
+---
+
+## Periodic Work
+
+```kotlin
+// ✅ Periodic sync — minimum interval is 15 minutes
+fun schedulePeriodicSync() {
+    val request = PeriodicWorkRequestBuilder<SyncWorker>(
+        repeatInterval = 1,
+        repeatIntervalTimeUnit = TimeUnit.HOURS
+    )
+        .setConstraints(
+            Constraints.Builder()
+                .setRequiredNetworkType(NetworkType.CONNECTED)
+                .setRequiresBatteryNotLow(true)
+                .build()
+        )
+        .build()
+
+    WorkManager.getInstance(context).enqueueUniquePeriodicWork(
+        "periodic_sync",
+        ExistingPeriodicWorkPolicy.KEEP,
+        request
+    )
+}
+```
+
+---
+
+## Chaining Workers
+
+```kotlin
+// ✅ Sequential chain
+WorkManager.getInstance(context)
+    .beginUniqueWork(
+        "upload_pipeline",
+        ExistingWorkPolicy.REPLACE,
+        OneTimeWorkRequestBuilder<CompressWorker>().build()
+    )
+    .then(OneTimeWorkRequestBuilder<UploadWorker>().build())
+    .then(OneTimeWorkRequestBuilder<NotifyWorker>().build())
+    .enqueue()
+
+// ✅ Parallel then merge
+val syncA = OneTimeWorkRequestBuilder<SyncAWorker>().build()
+val syncB = OneTimeWorkRequestBuilder<SyncBWorker>().build()
+val merge = OneTimeWorkRequestBuilder<MergeWorker>().build()
+
+WorkManager.getInstance(context)
+    .beginWith(listOf(syncA, syncB))
+    .then(merge)
+    .enqueue()
+```
+
+---
+
+## Progress Reporting
+
+```kotlin
+// ✅ Report progress from worker
+class UploadWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
+    override suspend fun doWork(): Result {
+        val files = getFilesToUpload()
+        files.forEachIndexed { index, file ->
+            uploadFile(file)
+            val progress = ((index + 1) * 100) / files.size
+            setProgress(workDataOf("progress" to progress))
+        }
+        return Result.success()
+    }
+}
+
+// ✅ Observe progress in ViewModel
+val workInfo: Flow<WorkInfo?> = workManager
+    .getWorkInfosForUniqueWorkFlow("upload_pipeline")
+    .map { it.firstOrNull() }
+
+// In composable
+val progress = workInfo?.progress?.getInt("progress", 0) ?: 0
+```
+
+---
+
+## Observing Work State
+
+```kotlin
+// ✅ Observe in ViewModel
+class SyncViewModel @Inject constructor(
+    private val workManager: WorkManager
+) : ViewModel() {
+
+    val syncState: StateFlow<SyncUiState> = workManager
+        .getWorkInfosForUniqueWorkFlow("periodic_sync")
+        .map { workInfos ->
+            when (workInfos.firstOrNull()?.state) {
+                WorkInfo.State.RUNNING   -> SyncUiState.Syncing
+                WorkInfo.State.SUCCEEDED -> SyncUiState.Success
+                WorkInfo.State.FAILED    -> SyncUiState.Failed
+                else                     -> SyncUiState.Idle
+            }
+        }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), SyncUiState.Idle)
+}
+```
+
+---
+
+## Hilt Integration
+
+```kotlin
+// ✅ Inject dependencies into Worker with Hilt
+@HiltWorker
+class SyncWorker @AssistedInject constructor(
+    @Assisted context: Context,
+    @Assisted params: WorkerParameters,
+    private val syncRepository: SyncRepository
+) : CoroutineWorker(context, params) {
+
+    override suspend fun doWork(): Result {
+        return try {
+            syncRepository.sync()
+            Result.success()
+        } catch (e: Exception) {
+            if (runAttemptCount < 3) Result.retry() else Result.failure()
+        }
+    }
+}
+
+// In Application class
+@HiltAndroidApp
+class App : Application(), Configuration.Provider {
+    @Inject lateinit var workerFactory: HiltWorkerFactory
+
+    override val workManagerConfiguration
+        get() = Configuration.Builder()
+            .setWorkerFactory(workerFactory)
+            .build()
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `Worker` instead of `CoroutineWorker` — blocks the thread
+- Not using unique work — creates duplicate background tasks
+- Not setting network constraints for network-dependent workers
+- Doing UI updates directly inside a Worker — use WorkInfo observation
+- Using WorkManager for immediate short tasks — use coroutines instead
+
+---
+
+## Related Skills
+- `background-processing` — choosing the right background tool
+- `foreground-service` — long-running user-visible work
+- `hilt` — injecting dependencies into workers
+- `coroutine` — coroutine fundamentals used inside CoroutineWorker

package/skills/System Integration/clipboard/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: clipboard
+description: >
+  Clipboard read and write operations in Android.
+  Load this skill when copying text or URIs to the clipboard,
+  reading clipboard content, showing copy confirmation feedback,
+  handling clipboard access restrictions on Android 10+,
+  or implementing paste functionality.
+---
+
+# Clipboard
+
+## Overview
+The Android clipboard allows apps to copy and paste text, URIs, and other data. Since Android 10, apps can only read the clipboard when they are in the foreground. Android 13 shows a visual confirmation when an app reads clipboard content. Best practice is to write to clipboard and show immediate in-app feedback rather than reading silently.
+
+---
+
+## Core Principles
+
+- Always show **visual feedback** after copying — toast or snackbar
+- Never read clipboard silently in background — it's restricted on Android 10+
+- Use `ClipData.newPlainText` for text — `ClipData.newUri` for URIs
+- On Android 13+, the system shows a clipboard toast automatically — avoid double-toasting
+- Sensitive content (passwords, tokens) should set `ClipDescription.EXTRA_IS_SENSITIVE`
+
+---
+
+## Writing to Clipboard
+
+```kotlin
+// ✅ Copy text to clipboard
+fun copyToClipboard(context: Context, text: String, label: String = "Copied text") {
+    val clipboard = context.getSystemService(ClipboardManager::class.java)
+    val clip = ClipData.newPlainText(label, text)
+    clipboard.setPrimaryClip(clip)
+
+    // ✅ Show feedback only on Android 12 and below
+    // Android 13+ shows system toast automatically
+    if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.S_V2) {
+        Toast.makeText(context, "Copied", Toast.LENGTH_SHORT).show()
+    }
+}
+
+// ✅ Copy sensitive content (password, token)
+fun copySensitiveToClipboard(context: Context, text: String) {
+    val clipboard = context.getSystemService(ClipboardManager::class.java)
+    val clip = ClipData.newPlainText("sensitive", text).apply {
+        description.extras = PersistableBundle().apply {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                putBoolean(ClipDescription.EXTRA_IS_SENSITIVE, true)
+            }
+        }
+    }
+    clipboard.setPrimaryClip(clip)
+}
+```
+
+---
+
+## Reading from Clipboard
+
+```kotlin
+// ✅ Read clipboard — only when app is in foreground
+fun readFromClipboard(context: Context): String? {
+    val clipboard = context.getSystemService(ClipboardManager::class.java)
+    val clip = clipboard.primaryClip ?: return null
+    if (clip.itemCount == 0) return null
+    return clip.getItemAt(0).coerceToText(context).toString()
+}
+
+// ✅ Check if clipboard has text before reading
+fun hasTextInClipboard(context: Context): Boolean {
+    val clipboard = context.getSystemService(ClipboardManager::class.java)
+    return clipboard.hasPrimaryClip() &&
+        clipboard.primaryClipDescription?.hasMimeType("text/*") == true
+}
+```
+
+---
+
+## Clipboard in Compose
+
+```kotlin
+// ✅ Copy on long press or button tap
+@Composable
+fun CopyableText(text: String) {
+    val context = LocalContext.current
+    val clipboardManager = LocalClipboardManager.current
+
+    Text(
+        text = text,
+        modifier = Modifier.clickable {
+            clipboardManager.setText(AnnotatedString(text))
+            // Show feedback on Android 12 and below
+            if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.S_V2) {
+                Toast.makeText(context, "Copied", Toast.LENGTH_SHORT).show()
+            }
+        }
+    )
+}
+
+// ✅ Paste button in Compose
+@Composable
+fun PasteButton(onPaste: (String) -> Unit) {
+    val clipboardManager = LocalClipboardManager.current
+
+    Button(onClick = {
+        val text = clipboardManager.getText()?.text ?: return@Button
+        onPaste(text)
+    }) {
+        Text("Paste")
+    }
+}
+```
+
+---
+
+## Clipboard Change Listener
+
+```kotlin
+// ✅ Listen for clipboard changes (e.g. autofill OTP)
+class OtpViewModel : ViewModel() {
+
+    private val clipboardListener = ClipboardManager.OnPrimaryClipChangedListener {
+        val text = readFromClipboard(context) ?: return@OnPrimaryClipChangedListener
+        if (text.matches(Regex("\\d{6}"))) {
+            _otpInput.value = text
+        }
+    }
+
+    fun registerClipboardListener(clipboard: ClipboardManager) {
+        clipboard.addPrimaryClipChangedListener(clipboardListener)
+    }
+
+    fun unregisterClipboardListener(clipboard: ClipboardManager) {
+        clipboard.removePrimaryClipChangedListener(clipboardListener)
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Reading clipboard in the background — restricted on Android 10+, throws SecurityException
+- Not showing feedback after copy — user doesn't know the action succeeded
+- Showing a toast on Android 13+ — the system already shows one, causing double notification
+- Storing passwords in clipboard without `EXTRA_IS_SENSITIVE` — shown in clipboard history
+- Reading clipboard on every resume — intrusive, user sees system clipboard access notification
+
+---
+
+## Related Skills
+- `compose` — `LocalClipboardManager` in Compose
+- `share-intent` — sharing content with other apps instead of clipboard