ketoy-dev 0.1.0

package/skills/ketoy/guides/migrate.md

@@ -0,0 +1,190 @@
+# Migration Playbook — Compose → KBC
+
+Migration is **always per-file, one-shot**. Never offer "migrate the whole project." Refuse if asked.
+
+## The audit pass (before writing any code)
+
+For the file the user wants migrated, produce a written audit covering:
+
+### 1. Composables called
+
+List every `Foo(...)` call. For each, check `reference/supported-composables.md`. Categorize:
+- ✅ supported — fine
+- ⚠️ supported via different overload — note the param list to use
+- ❌ unsupported — propose alternative or recommend keeping native
+
+### 2. State holders
+
+Find:
+- `var x by remember { mutableStateOf(...) }` → migrate to `vmGetState` / `vmSetState`
+- `collectAsState()` → migrate to `vmObserveState(...).collectAsState()` (collectAsState is supported via FLOW capability)
+- `viewModel()` injection → migrate state slots to `vmGetState` + dispatch events via `VM_DISPATCH`
+- `rememberSaveable` → migrate to `vmGetState` (KetoyVirtualViewModel persists to SavedStateHandle automatically)
+
+### 3. Side effects
+
+Find every:
+- `LaunchedEffect(...) { ... }` — keep as-is, but only call capability functions inside
+- `DisposableEffect` — NOT supported. Rewrite using state observation or move to host.
+- `SideEffect` — partial support (see KNOWN_ISSUES.md). Avoid in migrations.
+- `coroutineScope { ... }` / `withContext(...)` — supported, but every suspend call must be a capability
+
+### 4. Forbidden API references
+
+`grep` the file for:
+- `android.*`, `androidx.*` outside Compose
+- `kotlin.reflect`
+- `java.io`, `java.nio`
+- `GlobalScope`, `runBlocking`
+
+For each, propose a capability replacement.
+
+### 5. Custom components
+
+Any non-Compose-stdlib type construction. If it's a data holder, see if it can be passed via state (`Map<String, Any?>`). If it's a custom drawing primitive, recommend wrapping it as a custom composable adapter (out of migration scope) or keep native.
+
+## The migration step
+
+1. **Show the audit** to the user as a checklist. Get explicit acknowledgment of the migration scope.
+2. **Add or update capability stubs** in `Capabilities.kt` for every side effect / state observation.
+3. **Update `ketoy-capabilities.json`** with the new capabilities.
+4. **Update the host-side `CapabilityRegistry`** (either `AppCapabilityProvider.buildRegistry()` for Hilt or inline in `App.onCreate()` for non-Hilt). Each new capability needs its `register*(id) { args -> ... }` line.
+5. **Rewrite the composable**:
+   - Add `@KetoyEntryPoint @KetoyComposable` to the screen root.
+   - Replace state holders with `vmGetState` / `vmSetState`.
+   - Replace effects with capability calls.
+   - Replace forbidden API calls with capability calls.
+   - Hoist captured `val`s to the top of the function body for clarity.
+6. **Run `./gradlew :app:ketoyBundle --rerun-tasks`** — fix any compile errors via `guides/diagnose-errors.md`.
+7. **Run `./gradlew :app:assembleDebug`** — verify the bundle assembles into the APK.
+8. **Show user a diff** of every modified file before committing.
+
+## Migration patterns
+
+### State migration
+
+**Before**:
+```kotlin
+@Composable
+fun Counter() {
+    var count by remember { mutableStateOf(0) }
+    Button(onClick = { count++ }) {
+        Text("Count: $count")
+    }
+}
+```
+
+**After**:
+```kotlin
+@KetoyComposable
+@Composable
+fun Counter() {
+    val count = vmGetState("count") as Int? ?: 0
+    Button(onClick = { vmSetState("count", count + 1) }) {
+        Text("Count: $count")
+    }
+}
+```
+
+### Flow observation migration
+
+**Before**:
+```kotlin
+@Composable
+fun TodoScreen(vm: TodoViewModel = viewModel()) {
+    val todos by vm.todos.collectAsState()
+    Column { todos.forEach { Text(it.title) } }
+}
+```
+
+**After (new stub)**:
+```kotlin
+@KetoyCapabilityStub(id = 0x4000, name = "OBSERVE_TODOS")
+public fun observeTodos(): Flow<List<Any?>> = error(STUB_MSG)
+```
+
+**After (KBC code)**:
+```kotlin
+@KetoyEntryPoint @KetoyComposable @Composable
+fun TodoScreen() {
+    val todos = observeTodos().collectAsState(initial = emptyList()).value
+    Column {
+        todos.forEach { todo ->
+            val title = (todo as Map<String, Any?>)["title"] as String
+            Text(title)
+        }
+    }
+}
+```
+
+**Host (Hilt module)**:
+```kotlin
+KBCRoomBridge(registry).observeList(0x4000) { _ ->
+    todoRepository.observeAll()  // Flow<List<TodoEntity>>
+        .map { list -> list.map { it.toMap() } }  // Flow<List<Map<String, Any?>>>
+}
+```
+
+### Network call migration
+
+**Before**:
+```kotlin
+val response = httpClient.get("https://api.example.com/users/$id")
+```
+
+**After**:
+```kotlin
+// In Capabilities.kt:
+@KetoyCapabilityStub(id = 0x4010, name = "FETCH_USER")
+public suspend fun fetchUser(id: Long): Map<String, Any?> = error(STUB_MSG)
+
+// In screen:
+LaunchedEffect(userId) {
+    val user = fetchUser(userId)
+    vmSetState("user", user)
+}
+```
+
+**Host**:
+```kotlin
+registry.registerSuspend(0x4010) { args ->
+    val id = args[0] as Long
+    httpClient.get("https://api.example.com/users/$id").body
+}
+```
+
+### Navigation migration
+
+**Before**:
+```kotlin
+val navController = LocalNavController.current
+Button(onClick = { navController.navigate("detail/$id") }) { ... }
+```
+
+**After**:
+```kotlin
+Button(onClick = { navPush("detail/$id") }) { ... }
+```
+
+(Host registers `NAV_PUSH` via `registerNavigationCapabilities(...)` already.)
+
+### Lazy lists — fallback strategy
+
+LazyColumn / LazyRow are not yet supported. Options:
+
+- **Small lists**: Use `Column` with explicit `forEach`. Performance acceptable up to ~50 items.
+- **Large lists**: Keep the screen native and have the KBC screen navigate to it via `navPush("nativeList/<args>")`. Native screens read the same Hilt-injected repository as the host-registered capabilities.
+- **Pagination**: Implement server-side and pass current page items via state.
+
+## When NOT to migrate
+
+Recommend keeping a screen native if it:
+
+- Uses `LazyColumn` or `LazyVerticalGrid` for >50 items.
+- Has gesture handling (`pointerInput`, swipe-to-dismiss, custom drag).
+- Uses Canvas / Path drawing.
+- Embeds AndroidViews via `AndroidView { ... }`.
+- Implements custom `Layout` or `SubcomposeLayout`.
+- Has performance-critical animations (`Animatable`, `Transition`).
+
+Migration adds compile complexity and runtime indirection. If the screen isn't part of a server-driven update strategy (A/B tests, hot patches, feature rollouts), there's no benefit to shipping it as KBC.

package/skills/ketoy/guides/publish-deferred.md

@@ -0,0 +1,46 @@
+# Publishing Bundles (DEFERRED)
+
+> **Status**: The Ketoy publishing backend is not GA. Don't write publishing code yet. This document captures the intended flow so the agent can describe it on request without inventing details.
+
+## Why this is deferred
+
+Server-side bundle delivery requires:
+- A trusted CDN with per-app namespace isolation.
+- Signed-bundle validation pipeline (verify on upload, reject mismatched keys).
+- Version manifests so clients know "is there a newer bundle?".
+- A/B test routing and rollout controls.
+- Audit logs for which bundle each user received.
+
+None of that is shipping yet. Until it does, the answer to "how do I publish?" is: **build, sign, upload to your own CDN, point `KetoyBundleSource.Remote(url)` at it.**
+
+## Future CLI shape (do NOT implement)
+
+```
+ketoy publish --package com.example.app
+# Prompts:
+#   "You are about to publish to 'com.example.app'. Confirm by typing the package name: "
+#   <user types it exactly>
+# Then:
+#   - reads `app/src/main/assets/ketoy/main.ktx`
+#   - re-verifies signature against the registered public key
+#   - uploads to ketoy.dev/api/bundles/com.example.app/{version}
+#   - returns a deployment ID + signed URL
+```
+
+The written-package-name confirmation is a safety gate — copy-pasting accidentally is the easiest way to push the wrong bundle to production.
+
+## Until then
+
+If a user asks "how do I publish?":
+
+1. Confirm they want CDN delivery (vs. APK-bundled).
+2. Point them at `KetoyBundleSource.Remote(url, headers)` in `reference/`.
+3. Explain the ETag-based caching: their CDN's `ETag` response header drives `If-None-Match` revalidation on the host.
+4. Recommend a CI step:
+   ```bash
+   ./gradlew :app:ketoyBundle --rerun-tasks
+   aws s3 cp app/src/main/assets/ketoy/main.ktx s3://your-cdn/bundles/com.example.app/$(git rev-parse HEAD).ktx
+   ```
+5. Recommend signature verification ON in production (`enableSignatureVerification = true` + matching public key shipped in APK).
+
+Do **not** offer to write the upload pipeline. That's the user's CI / CDN choice.

package/skills/ketoy/guides/safe-edits.md

@@ -0,0 +1,141 @@
+# Safe Edits Policy — Never Rewrite Existing Files
+
+**Hard rule**: when modifying existing files (`build.gradle.kts`, `AndroidManifest.xml`, `MainActivity.kt`, `Application` class, `settings.gradle.kts`, etc.) the agent MUST make **surgical, additive edits** at specific locations. Never write/overwrite the whole file.
+
+A full rewrite of a user's `app/build.gradle.kts` will destroy their existing dependencies, signing config, build types, flavors, ProGuard rules, Crashlytics integration, custom tasks, and anything else. Treat every existing file as sacred. Templates in `templates/` are reference scaffolds — they describe the final shape, NOT the bytes to write.
+
+## How to make a safe edit
+
+For every file the user already has:
+
+1. **Read** the file in full.
+2. **Locate the insertion point** by pattern matching on stable anchors (e.g. `plugins {`, `dependencies {`, `android {`, `<application`, `class MainActivity`, `override fun onCreate`).
+3. **Check for prior Ketoy entries** — if `id("dev.ketoy.compiler")` already exists in `plugins { }`, don't add it again. Same for every dependency, every annotation, every import.
+4. **Make the minimal Edit** — single-line additions, or single-block appends. Never delete user content.
+5. **Show a diff** before confirming the change. Get explicit acknowledgment when:
+   - Modifying a file the user is likely to have hand-tuned (MainActivity, Application, build.gradle.kts).
+   - Touching anything that affects packaging (Manifest, ProGuard, signing).
+
+## File-by-file insertion strategy
+
+### `app/build.gradle.kts`
+
+Three surgical edits:
+
+**a. Add plugin** — find the `plugins { ... }` block, insert `id("dev.ketoy.compiler")` at the end of its body. Verify it's not already present.
+
+```kotlin
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+    // ... user's existing plugins ...
+    id("dev.ketoy.compiler")     // ← single line added
+}
+```
+
+**b. Add dependencies** — find the `dependencies { ... }` block, append a `// Ketoy` section at the end of the body:
+
+```kotlin
+dependencies {
+    // ... user's existing dependencies, untouched ...
+
+    // Ketoy
+    implementation(platform("dev.ketoy.vm:ketoy-bom:0.2.1-alpha"))
+    implementation("dev.ketoy.vm:ketoy-runtime")
+    implementation("dev.ketoy.vm:ketoy-capabilities-core")
+    implementation("dev.ketoy.vm:ketoy-capabilities-navigation")
+    implementation("dev.ketoy.vm:ketoy-adapters-material3")
+    implementation("dev.ketoy.vm:ketoy-annotations")
+    // implementation("dev.ketoy.vm:ketoy-hilt")  // add only if user uses Hilt
+}
+```
+
+**c. Append the `ketoy { }` block** at file bottom (after the last `}`). Don't insert mid-file.
+
+```kotlin
+// existing file ends here.
+// Then append:
+ketoy {
+    exportFromAppModule.set(true)
+    bundleId.set("main")
+    bundleVariant.set("release")
+    capabilityRegistryFile.set(file("ketoy-capabilities.json"))
+    debugMode.set(true)
+    val signingKey = file("keys/sample-private.key")
+    if (signingKey.exists()) {
+        signingKeyFile.set(signingKey)
+    }
+}
+```
+
+**Never touch**: `android { }`, `defaultConfig { }`, `buildTypes { }`, `compileOptions { }`, `kotlinOptions { }`, `buildFeatures { }`, `packagingOptions`, signing configs, or any custom block the user wrote. If `minSdk < 26`, **stop and ask** — don't silently bump it.
+
+### `AndroidManifest.xml`
+
+Single surgical edit: add `android:name` attribute to the existing `<application>` tag. Do NOT replace the whole `<application>` block — the user has `android:icon`, `android:theme`, `android:label`, `android:allowBackup`, possibly `tools:replace`, network security config, etc.
+
+If `android:name` already exists pointing at a non-Ketoy Application class → tell the user and ask whether to make their existing Application class extend our setup, or whether to point at a new class.
+
+### `MainActivity.kt`
+
+Three scenarios:
+
+**a. File doesn't exist** — safe to write from `examples/hilt-config.kt` or `examples/no-hilt-config.kt`.
+
+**b. File exists and is the boilerplate Android Studio template** (typically just sets up a `setContent { GreetingTheme { Greeting("Android") } }`) — show a diff, ask, then replace with the Ketoy-aware version.
+
+**c. File exists and contains user code** — **do NOT replace**. Instead:
+   - Add the necessary imports (single Edit).
+   - Add the `@AndroidEntryPoint` annotation if Hilt and missing (single Edit).
+   - Add `@Inject lateinit var ...` field declarations (single Edit block inside the class).
+   - **Don't touch `onCreate`** — the user might be doing complex setup. Instead, point them at the example and say: "Here's how to integrate `KetoyScreen` inside your existing `setContent { }`. Make the edit yourself, or paste this block:" and show the snippet.
+
+### `Application` class
+
+**a. File doesn't exist** — safe to create new (`App.kt` or `MyApplication.kt`).
+
+**b. User already has an `Application` subclass** — **don't replace**. Edit it surgically:
+   - Add `@HiltAndroidApp` if Hilt and missing.
+   - For non-Hilt: add the `ketoyRuntime` / `ketoyBundleLoader` field declarations and initialization inside `onCreate()` — as an Edit that inserts the new lines AFTER `super.onCreate()` without disturbing the user's existing init code.
+
+### `settings.gradle.kts`
+
+Only edit if `mavenCentral()` is missing from `pluginManagement.repositories` or `dependencyResolutionManagement.repositories`. Single-line Edit appending `mavenCentral()` to whichever block lacks it.
+
+### `.gitignore`
+
+Single-line append: `**/keys/*-private.key`. Check it's not already there.
+
+## New files — always fair game
+
+Files that the user does NOT have an existing version of can be created in full:
+
+- `app/ketoy-capabilities.json` (new)
+- `app/src/main/.../ketoyscreens/Capabilities.kt` (new file in new directory)
+- `app/src/main/.../ketoyscreens/HelloKetoyScreen.kt` or migrated screens (new files)
+- `app/src/main/.../di/AppCapabilityProvider.kt` (new, Hilt only)
+- `app/src/main/.../di/AppHiltModule.kt` (new, Hilt only — UNLESS user already has an `AppHiltModule` / `AppModule`, in which case insert into theirs)
+
+For Hilt module insertion when the user has their own: append `@Binds` for `KetoyCapabilityProvider` and `@Provides` for the three resolvers + the config customizer — as additive entries in the existing module. Don't introduce a parallel module unless the user's existing one is `internal` / not in scope.
+
+## The diff-and-confirm checkpoint
+
+Before any edit that touches `build.gradle.kts`, `AndroidManifest.xml`, `MainActivity.kt`, or an existing `Application` class:
+
+1. Show the user the proposed diff (using `Edit`'s natural diff output).
+2. Wait for confirmation. Don't batch multiple file edits without checking in.
+3. If the user denies, ask what they'd prefer and adjust.
+
+For the easy stuff (new files in `ketoyscreens/`, capability registry JSON, fresh Hilt provider) you can proceed without the diff-and-confirm dance — but always print what was created.
+
+## If the project is unusual
+
+If grepping turns up things like:
+
+- A custom `Application` that extends `MultiDexApplication` or a third-party class
+- An existing `KetoyScreen` integration (someone already started)
+- Build scripts in Groovy (`build.gradle`, not `.kts`)
+- KMP project structure with `androidApp` instead of `app`
+
+Stop. Describe what you found, and ask the user how they want to proceed. Don't guess.

package/skills/ketoy/reference/architecture-cheatsheet.md

@@ -0,0 +1,122 @@
+# Architecture cheatsheet — for AI grounding
+
+When reasoning about Ketoy code, keep this layered model in mind:
+
+```
+┌───────────────────────────────────────────────────────┐
+│ 1. Kotlin source (.kt)                                │
+│    @KetoyComposable + @KetoyEntryPoint + @KetoyViewModel
+│    @KetoyCapabilityStub (compile-time only)           │
+├───────────────────────────────────────────────────────┤
+│ 2. Compiler plugin (K2 IR → KBC bytecode)             │
+│    KetoyIRGenerationExtension + KBCEmitter            │
+│    CapabilityValidator does transitive closure walk    │
+├───────────────────────────────────────────────────────┤
+│ 3. .ktx bundle                                        │
+│    Brotli-compressed, Ed25519-signed                  │
+│    Sections: string pool, manifests, function table,  │
+│    code, modifier table, bundle metadata, entries     │
+├───────────────────────────────────────────────────────┤
+│ 4. VM interpreter (register-based)                    │
+│    KBCInterpreter + KBCCoroutineEngine                │
+│    Tier-1 DexMaker JIT (API 26+)                      │
+├───────────────────────────────────────────────────────┤
+│ 5. Compose renderer                                   │
+│    KBCComposeEngine + adapter / constructor registries│
+│    Native Compose slot table via registered adapters  │
+└───────────────────────────────────────────────────────┘
+```
+
+## Module dependency order (small → large)
+
+```
+ketoy-annotations  (KMP — pure annotations, zero deps)
+   ↓
+ketoy-bytecode     (KMP — KBC opcodes + KBCValue + bundle data types)
+   ↓
+ketoy-bundle-format (KMP — KtxReader/Writer, signing, compression)
+   ↓
+ketoy-runtime      (Android AAR — interpreter, ViewModels, Compose engine)
+   ↓
+ketoy-capabilities-core (Android AAR — HTTP, KV, dispatchers, navigation registration)
+ketoy-capabilities-navigation (Android AAR — navigator integration)
+ketoy-adapters-material3 (Android AAR — Material3 adapters + constructors)
+ketoy-hilt         (Android AAR — Hilt modules + factory builder)
+ketoy-test         (Android AAR — fakes + KBCBuilder DSL)
+
+ketoy-compiler-plugin (JVM jar — K2 compiler plugin)
+ketoy-gradle-plugin   (JVM jar — wires compiler plugin + ketoyBundle task)
+```
+
+## Key data types to recognize
+
+| Type | What it is | Where it lives |
+|---|---|---|
+| `@KetoyComposable` | Marks a function for KBC compilation | `ketoy-annotations` |
+| `@KetoyEntryPoint` | Marks a function as an entry-point (host can name-lookup) | `ketoy-annotations` |
+| `@KetoyCapabilityStub` | Compile-time bridge to a host capability | `ketoy-annotations` |
+| `KetoyConfig` | Runtime config (sig verification, JIT, resolvers) | `ketoy-runtime` |
+| `KetoyRuntime` | Top-level runtime entry — `parseBundle` + `createVM` | `ketoy-runtime` |
+| `KetoyBundleLoader` | Loads `.ktx` from Asset/Raw/Remote/Preloaded | `ketoy-runtime` |
+| `KetoyBundleSource` | Sealed source variants (Asset, Remote, Raw, Preloaded) | `ketoy-runtime` |
+| `KetoyScreen` | `@Composable` entry point for host code | `ketoy-runtime` |
+| `KetoyVirtualViewModel` | Per-bundle ViewModel hosting the VM | `ketoy-runtime` |
+| `CapabilityRegistry` | Host-side registry of capability IDs → callbacks | `ketoy-runtime` |
+| `KetoyCapabilityProvider` | Hilt interface for building the registry | `ketoy-hilt` |
+| `KetoyHiltProvider` | `@Composable` Hilt-context publisher | `ketoy-hilt` |
+| `KetoyConfigCustomizer` | Hilt `fun interface` to customize default config | `ketoy-hilt` |
+| `MaterialIconsResolver` | Host registry for `Icons.<Style>.<Name>` | `ketoy-adapters-material3` |
+| `MaterialFontFamilyResolver` | Host registry for `R.font.X` | `ketoy-adapters-material3` |
+| `MaterialDrawableResolver` | Host registry for `R.drawable.X` | `ketoy-adapters-material3` |
+| `KBCRoomBridge` | Helper for Room DAO → capability registration | `ketoy-capabilities-core` |
+
+## Bundle lifecycle (load path)
+
+```
+KetoyScreen
+  └─> KetoyBundleLoader.load(KetoyBundleSource.Asset("ketoy/main.ktx"))
+        ↓ reads bytes from APK assets
+  └─> KetoyRuntime.parseBundle(bytes)
+        ↓ optional: Ed25519Verifier.verify(bytes, publicKey)
+        ↓ KtxReader.read(bytes) → KetoyBundle
+        ↓ BundleValidator.validate(bundle, adapter/constructor/capability registries)
+        ↓ (STRICT — every manifest entry must be registered)
+        ↓ cache by SHA-256(bytes) for future loads
+  └─> KetoyVirtualViewModel.Factory(bundle, extras, registries, config)
+        ↓ creates per-bundle VM with viewModelScope
+  └─> KetoyVM.executeComposable(entryPointFnIdx)
+        ↓ interpreter walks bytecode, dispatches:
+        ↓   COMPOSABLE_CALL → adapterRegistry.invoke(id, params)
+        ↓   CONSTRUCT_JVM   → constructorRegistry.construct(id, params)
+        ↓   INVOKE_CAPABILITY[_SUSPEND] → registry.invoke(id, args)
+```
+
+## Compile lifecycle
+
+```
+.kt source with @KetoyComposable
+  └─> Kotlin K2 frontend (normal)
+  └─> KetoyIRGenerationExtension (compiler plugin)
+        ↓ KetoyDeclarationCollector — scans for @Ketoy* annotations
+        ↓ CapabilityValidator.validate(root, allTopLevelFns)
+        ↓   - transitive closure walk over @KetoyComposable roots
+        ↓   - native sibling top-level fns untouched (compile to DEX)
+        ↓   - errors carry `Reached via:` breadcrumbs
+        ↓ KBCEmitter.emit(root, captures)
+        ↓   - IR nodes → KBC instructions
+        ↓   - ClosureAnalyzer finds outer-scope captures → KBCValue.ClosureRef
+        ↓   - Compose token reads → ComposeTokenRegistry → KBCValue.*Id literals
+        ↓   - Modifier chains → KBCModifierIRWalker → modifier table
+        ↓   - Atomic-collapse encoder shortcuts (Color.X, R.font.X, etc.)
+  └─> KtxBundleBuilder accumulates functions + manifests
+  └─> KtxWriter.write(bundle, optional signer) → bytes
+  └─> KetoyBundleTask writes to app/src/main/assets/ketoy/main.ktx
+```
+
+## What's at each ID range
+
+- `0x0000 – 0x0FFF`: Reserved / standard Compose adapters + constructors (Material3 + Foundation + Coil)
+- `0x4000+`: App-specific (your custom composables, capabilities, constructors)
+- `0xFFFF`: Sentinel / never used
+
+Stable forever; never re-assign.

package/skills/ketoy/reference/capabilities.md

@@ -0,0 +1,122 @@
+# Capabilities Catalog
+
+Capabilities are how KBC source calls back into the Android host. Each capability has a stable `Short` ID and is registered into a `CapabilityRegistry` once per host (via Hilt module or `Application.onCreate`).
+
+Inside KBC source, capabilities are referenced through `@KetoyCapabilityStub`-annotated functions whose bodies throw — the compiler plugin replaces each call with `INVOKE_CAPABILITY` / `INVOKE_CAPABILITY_SUSPEND` / `INVOKE_CAPABILITY_FLOW`.
+
+## Standard library capability IDs
+
+Ranges:
+
+| Range | Domain | Examples |
+|---|---|---|
+| `0x0001 – 0x08FF` | UI / modifier infrastructure (reserved, internal) | |
+| `0x0500 – 0x05FF` | Network | `HTTP_GET`, `HTTP_POST`, `SSE_SUBSCRIBE` |
+| `0x0600 – 0x06FF` | Storage | `KV_GET/SET/OBSERVE`, `DB_QUERY/OBSERVE` |
+| `0x0700 – 0x07FF` | Navigation | `NAV_PUSH`, `NAV_POP`, `NAV_REPLACE`, `NAV_DEEP_LINK` |
+| `0x0900 – 0x09FF` | Platform | `TOAST`, `VIBRATE`, `CLIPBOARD_SET/GET`, `OPEN_URL`, `LOG`, `ANALYTICS_TRACK` |
+| `0x0A00 – 0x0AFF` | ViewModel state | `VM_GET_STATE`, `VM_SET_STATE`, `VM_OBSERVE_STATE`, `VM_DISPATCH` |
+| `0x0B00 – 0x0BFF` | Dispatchers | `DISPATCHER_IO`, `DISPATCHER_DEFAULT`, `DISPATCHER_MAIN` |
+| `0x0C00 – 0x0CFF` | Flow operators | `FLOW_MAP`, `FLOW_FILTER`, `FLOW_COMBINE`, `FLOW_DEBOUNCE`, `STATE_FLOW_CREATE` |
+| `0x4000+` | App-specific | Anything your host registers |
+
+Full list lives in `ketoy-capabilities-core/.../CapabilityIds.kt`. Read that file when in doubt.
+
+## Common stubs (paste into your KBC source)
+
+The stubs below are conventional — the IDs and names match the standard library. Place in `app/src/main/.../ketoyscreens/Capabilities.kt`.
+
+```kotlin
+@file:Suppress("UnusedParameter") // Stub bodies discard params; compiler reads the signature.
+package com.example.app.ketoyscreens
+
+import dev.ketoy.annotations.KetoyCapabilityStub
+import kotlinx.coroutines.flow.Flow
+
+private const val STUB_MSG = "Ketoy capability stub — replaced by INVOKE_CAPABILITY at compile time"
+
+// Navigation
+@KetoyCapabilityStub(id = 0x0700, name = "NAV_PUSH")
+public fun navPush(route: String): Unit = error(STUB_MSG)
+
+@KetoyCapabilityStub(id = 0x0701, name = "NAV_POP")
+public fun navPop(): Unit = error(STUB_MSG)
+
+@KetoyCapabilityStub(id = 0x0702, name = "NAV_REPLACE")
+public fun navReplace(route: String): Unit = error(STUB_MSG)
+
+// ViewModel state bridge
+@KetoyCapabilityStub(id = 0x0A00, name = "VM_GET_STATE")
+public fun vmGetState(key: String): Any? = error(STUB_MSG)
+
+@KetoyCapabilityStub(id = 0x0A01, name = "VM_SET_STATE")
+public fun vmSetState(key: String, value: Any?): Unit = error(STUB_MSG)
+
+@KetoyCapabilityStub(id = 0x0A02, name = "VM_OBSERVE_STATE")
+public fun vmObserveState(key: String): Flow<Any?> = error(STUB_MSG)
+
+// Platform
+@KetoyCapabilityStub(id = 0x0900, name = "ANALYTICS_TRACK")
+public fun analyticsTrack(event: String, props: Map<String, Any?>): Unit = error(STUB_MSG)
+
+@KetoyCapabilityStub(id = 0x0901, name = "TOAST")
+public fun toast(message: String, duration: Int = 0): Unit = error(STUB_MSG)
+```
+
+## Defining an app-specific capability
+
+Step 1 — declare the stub:
+
+```kotlin
+@KetoyCapabilityStub(id = 0x4001, name = "FETCH_USER_PROFILE")
+public suspend fun fetchUserProfile(userId: Long): Map<String, Any?> = error(STUB_MSG)
+```
+
+Step 2 — register host-side (inside your `KetoyCapabilityProvider.buildRegistry()`):
+
+```kotlin
+override fun buildRegistry(): CapabilityRegistry {
+    val registry = CapabilityRegistry()
+    registry.registerCoreCapabilities(context, httpClient = httpClient)
+    registry.registerSuspend(0x4001) { args ->
+        val userId = args[0] as Long
+        userProfileRepository.fetch(userId)  // returns Map<String, Any?>
+    }
+    return registry
+}
+```
+
+Step 3 — declare it in the capability registry JSON for compile-time validation (`app/ketoy-capabilities.json`):
+
+```json
+{
+  "version": 1,
+  "allowedStdlibFqNames": [],
+  "capabilities": [
+    { "id": 16385, "name": "FETCH_USER_PROFILE",
+      "fqName": "com.example.app.ketoyscreens.fetchUserProfile",
+      "kind": "SUSPEND", "required": true }
+  ]
+}
+```
+
+(`0x4001` = `16385` decimal.)
+
+## Registration flavors
+
+| Flavor | When to use | Wire op |
+|---|---|---|
+| `register(id) { args -> Any? }` | Pure sync, fire-and-forget or returns immediately | `INVOKE_CAPABILITY` |
+| `registerSuspend(id) { args -> Any? }` | Network calls, DB writes, anything that suspends | `INVOKE_CAPABILITY_SUSPEND` |
+| `registerFlow(id) { args -> Flow<Any?> }` | DB observes, SSE streams, state subscriptions | `INVOKE_CAPABILITY_FLOW` |
+| `KBCRoomBridge.observeList(id) { args -> Flow<List<...>> }` | Room DAO `Flow<List<X>>` queries | flow wrapper |
+
+## Validation timing
+
+| When | What's checked |
+|---|---|
+| Compile (compiler plugin) | Stub FQ name → capability ID lookup, signature shape |
+| Bundle load (`BundleValidator`) | Every manifest entry in the `.ktx` exists in the host's `CapabilityRegistry` (STRICT — even `required = false` entries are checked) |
+| Runtime (`INVOKE_CAPABILITY`) | Args match the registered callback's expectations (you write the cast) |
+
+So a missing host registration explodes at bundle load, not at the call site — diagnostics point at the bundle, not the screen.