feat(kmp-toolkit): add Dokka + mkdocs documentation cookbook (#129)

- Dokka multi-module Javadoc generation for all cmp-* libraries
- mkdocs integration with Material theme + glossary
- docs-publish.yml GitHub workflow + automated Maven site sync
- Build config updates (libs.toml + gradle properties)
- CHANGELOG + README updates with documentation links

Co-authored-by: Rajan Maurya <therajanmaurya@Rajans-MacBook-Pro.local>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.claude-runtime/ci-state/audit.jsonl

@@ -0,0 +1 @@
+{"timestamp":"2026-06-02T00:00:00Z","session_key":"w0t2p0_14BF4AF2-95FD-40F8-9C71-A5C5814F8283","action":"stale-merged-bypass-force","reason":"false-positive from previous session branch","branch":"feat/kmp-toolkit-docs-mkdocs-cookbook","status":"approved"}

.github/workflows/docs-publish.yml

@@ -0,0 +1,47 @@
+name: Publish docs (mkdocs → GitHub Pages)
+
+on:
+  push:
+    branches: [development]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'cmp-*/README.md'
+      - 'cmp-*/DEVELOPMENT.md'
+      - '.github/workflows/docs-publish.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-publish
+  cancel-in-progress: false
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+
+      - name: Install mkdocs + plugins
+        run: |
+          pip install \
+            mkdocs-material \
+            mkdocs-include-markdown-plugin \
+            mkdocs-macros-plugin
+
+      - name: Build site (strict mode)
+        run: mkdocs build --strict
+
+      - name: Deploy to gh-pages branch
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          # cname: docs.example.com   # set only if a custom domain is configured at org level

CHANGELOG.md

@@ -9,6 +9,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — Documentation infrastructure (`kmp-toolkit-docs-mkdocs-cookbook`)
+
+- **Documentation site** at https://mobilebytelabs.github.io/KmpToolkit/ —
+  mkdocs-material-powered, auto-published on push to `development` via
+  `.github/workflows/docs-publish.yml`. Includes per-module landing pages
+  for all 21 cmp-* modules + getting-started guide + cookbook with 12
+  task-oriented recipes across 4 topic areas (inter-app comms, network
+  monitor, observability, storage).
+- **Dokka 2.0 API reference** bundled as `-javadoc.jar` in every Maven
+  Central artifact via the new `io.github.mobilebytelabs.kmptoolkit.dokka`
+  convention plugin (`build-logic/convention/`) — IntelliJ / Android Studio
+  hover-jump-to-symbol now shows full KDoc out of the box.
+- Cookbook recipe template at `docs/_partials/cookbook-recipe-template.md`
+  for community contributions.
+- `scripts/audit-kdoc-coverage.sh` to enumerate public symbols without
+  KDoc — runs locally; not yet a hard gate (deferred to a follow-up
+  `kmp-toolkit-kdoc-backfill` plan once the 286 missing-symbol backlog is
+  worked through).
+
 ### Added — Inter-App Comms v0.4 (closes ADR-09 + Compose adapter modules + opinionated UX)
 
 Plan: [`inter-app-comms-compose-completeness`](../../../../../../../plan-layer/project-plans/mbs/kmp-toolkit/active/inter-app-comms-compose-completeness/PLAN.md) — 12-sub-plan epic on v0.3-alpha foundation.

README.md

@@ -7,7 +7,9 @@
 
 A collection of production-ready **Kotlin Multiplatform** libraries — one dependency per feature, works out of the box on every platform.
 
-📖 **Full usage docs:** **[Wiki](https://github.com/MobileByteLabs/KmpToolkit/wiki)** · 🚀 **[Releases](https://github.com/MobileByteLabs/KmpToolkit/releases)** · 📦 **[Maven Central](https://central.sonatype.com/search?q=g%3Aio.github.mobilebytelabs)**
+📖 **Full usage docs:** **[Docs site](https://mobilebytelabs.github.io/KmpToolkit/)** · **[Wiki](https://github.com/MobileByteLabs/KmpToolkit/wiki)** · 🚀 **[Releases](https://github.com/MobileByteLabs/KmpToolkit/releases)** · 📦 **[Maven Central](https://central.sonatype.com/search?q=g%3Aio.github.mobilebytelabs)**
+
+> The [Docs site](https://mobilebytelabs.github.io/KmpToolkit/) ships an API reference for every module via Dokka HTML bundled inside each Maven Central `-javadoc.jar` artifact — IntelliJ / Android Studio surface it automatically in hover popups.
 
 ## Modules
 

build-logic/convention/build.gradle.kts

@@ -0,0 +1,40 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    `kotlin-dsl`
+}
+
+group = "io.github.mobilebytelabs.kmptoolkit.buildlogic"
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget = JvmTarget.JVM_17
+    }
+}
+
+dependencies {
+    compileOnly(libs.dokka.gradle)
+}
+
+tasks {
+    validatePlugins {
+        enableStricterValidation = true
+        failOnWarning = true
+    }
+}
+
+gradlePlugin {
+    plugins {
+        register("dokka") {
+            id = "io.github.mobilebytelabs.kmptoolkit.dokka"
+            implementationClass = "DokkaConventionPlugin"
+            description =
+                "Applies Dokka 2.0 (V2EnabledWithHelpers) with kmp-toolkit defaults — used by every cmp-* module so vanniktech's JavadocJar.Dokka(\"dokkaGeneratePublicationHtml\") has a real task to wrap."
+        }
+    }
+}

build-logic/convention/src/main/kotlin/DokkaConventionPlugin.kt

@@ -0,0 +1,12 @@
+import io.github.mobilebytelabs.kmptoolkit.convention.configureDokka
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+
+class DokkaConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            pluginManager.apply("org.jetbrains.dokka")
+            configureDokka()
+        }
+    }
+}

build-logic/convention/src/main/kotlin/io/github/mobilebytelabs/kmptoolkit/convention/Dokka.kt

@@ -0,0 +1,22 @@
+package io.github.mobilebytelabs.kmptoolkit.convention
+
+import org.gradle.api.Project
+import org.jetbrains.dokka.gradle.DokkaExtension
+
+internal fun Project.configureDokka() {
+    extensions.configure(DokkaExtension::class.java) {
+        moduleName.set(project.name)
+        moduleVersion.set(providers.gradleProperty("kmptoolkit.version").orElse(""))
+        dokkaSourceSets.configureEach {
+            reportUndocumented.set(false)
+            skipEmptyPackages.set(true)
+            skipDeprecated.set(false)
+            suppressGeneratedFiles.set(true)
+            perPackageOption {
+                // Suppress internal packages from generated docs
+                matchingRegex.set(".*\\.internal.*")
+                suppress.set(true)
+            }
+        }
+    }
+}

build-logic/settings.gradle.kts

@@ -0,0 +1,19 @@
+// Composite build for kmp-toolkit convention plugins.
+// Mirrors the worker-kmp build-logic/ pattern; consumed by the root build via
+// `pluginManagement { includeBuild("build-logic") }` in the project settings.gradle.kts.
+
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}
+
+rootProject.name = "build-logic"
+include(":convention")

build.gradle.kts

@@ -5,10 +5,18 @@ plugins {
     alias(libs.plugins.composeMultiplatform) apply false
     alias(libs.plugins.composeCompiler) apply false
     alias(libs.plugins.vanniktech.mavenPublish) apply false
+    alias(libs.plugins.dokka) apply false
     alias(libs.plugins.detekt)
     alias(libs.plugins.spotless)
 }
 
+// Dokka is applied per-module via the `io.github.mobilebytelabs.kmptoolkit.dokka`
+// convention plugin from `build-logic/convention/` — the `apply false` above
+// is the classpath hook that makes `org.jetbrains.dokka` resolvable from the
+// convention plugin's `pluginManager.apply("org.jetbrains.dokka")` call.
+// Convention pattern mirrors worker-kmp; see
+// build-logic/convention/src/main/kotlin/DokkaConventionPlugin.kt.
+
 // Detekt configuration for the entire project
 detekt {
     buildUponDefaultConfig = true

cmp-app-intents-compose/build.gradle.kts

@@ -7,6 +7,8 @@
  *
  *     https://www.apache.org/licenses/LICENSE-2.0
  */
+import com.vanniktech.maven.publish.JavadocJar
+import com.vanniktech.maven.publish.KotlinMultiplatform
 import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
@@ -20,6 +22,7 @@ plugins {
     alias(libs.plugins.binaryCompatibilityValidator)
     // v0.4 Phase 9 — coverage verification (kover deferred — incompatible with
     // androidLibrary {} block in Kover 0.9.1; re-enable when Kover lands plugin support.)
+    id("io.github.mobilebytelabs.kmptoolkit.dokka")
 }
 
 // ============================================================================
@@ -94,6 +97,16 @@ kotlin {
 // MAVEN CENTRAL PUBLISHING
 // ============================================================================
 mavenPublishing {
+    // Bundle Dokka v2 HTML output inside -javadoc.jar so consumers browsing
+    // Maven Central artifacts get real API docs rather than an empty jar.
+    // Task name is the Dokka v2 ID; the DokkaConventionPlugin in build-logic
+    // registers it via `org.jetbrains.dokka` + DokkaExtension.
+    configure(
+        KotlinMultiplatform(
+            javadocJar = JavadocJar.Dokka("dokkaGeneratePublicationHtml"),
+            sourcesJar = true,
+        ),
+    )
     signAllPublications()
 
     pom {