openuispec 0.1.44 → 0.1.46

package/README.md

@@ -52,25 +52,92 @@ cd your-project
 openuispec init
 ```
 
-This scaffolds a spec directory, starter tokens, adds rules to `CLAUDE.md` / `AGENTS.md`, and configures the MCP server so AI assistants track spec changes automatically.
-Use `openuispec init --no-configure-targets` if you want to scaffold first and choose target stacks later.
+This scaffolds a spec directory, starter tokens, and **configures the MCP server** for your AI coding agent (Claude Code, VS Code/Copilot, Codex). Use `openuispec init --no-configure-targets` to scaffold first and choose target stacks later.
 
-Then hand your spec to any AI code generator:
+## AI integration (MCP)
 
-> Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined. Use `platform/ios.yaml` for SwiftUI-specific overrides.
+OpenUISpec is designed to be used by AI coding agents. The package includes an **MCP server** that exposes tools AI assistants call automatically during UI work — no manual prompting needed.
+
+### How it works
+
+```
+openuispec init → configures MCP for your agent → AI calls tools automatically
+```
+
+When you ask your AI to "add a settings page" or "update the home feed," the MCP server:
+
+1. **Schema reference** — `openuispec_spec_types` and `openuispec_spec_schema` give the AI the exact format for any spec file it needs to create or edit
+2. **Before generation** — `openuispec_prepare` gives the AI your spec context, platform config, and constraints
+3. **During generation** — `openuispec_read_specs` feeds the AI the actual spec file contents as the authoritative source
+4. **After generation** — `openuispec_check` returns a concrete audit checklist derived from your spec (every contract `must_handle` item, every screen section, every locale key) and the AI verifies its code matches
+
+This replaces the old approach of writing instructions in CLAUDE.md and hoping the AI follows them. MCP tools are called reliably because they're part of the AI's tool-calling loop, not a text instruction it can skip.
+
+### Setup
+
+`openuispec init` and `openuispec update-rules` automatically configure MCP for all supported agents:
+
+| Agent | Config file | Created automatically |
+|-------|------------|----------------------|
+| **Claude Code** | `.mcp.json` | Always |
+| **Codex** | `.codex/config.toml` | Always |
+| **VS Code / Copilot** | `.vscode/mcp.json` | If `.vscode/` exists |
+| **Gemini CLI** | `.gemini/settings.json` | If `.gemini/` exists |
+
+Manual setup (if needed):
+
+**Claude Code** (`.mcp.json`), **VS Code / Copilot** (`.vscode/mcp.json`), **Gemini CLI** (`.gemini/settings.json`):
+```json
+{
+  "mcpServers": {
+    "openuispec": {
+      "command": "openuispec",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Codex** (`.codex/config.toml`):
+```toml
+[mcp_servers.openuispec]
+command = "openuispec"
+args = ["mcp"]
+```
+
+Or run directly: `openuispec mcp`
+
+### Tools
 
-Before platform code generation, the AI should refresh its understanding of the current target toolchain and platform conventions instead of relying on stale memory. This matters most for project formats, resource wiring, navigation APIs, packaging rules, and other implementation details that change across toolchain versions.
+| Tool | When | What it does |
+|------|------|-------------|
+| `openuispec_spec_types` | Before creating spec files | Lists all available spec types with descriptions — discover what kinds of spec files exist |
+| `openuispec_spec_schema` | Before creating/editing spec files | Returns the full JSON schema for a specific spec type — exact structure, required fields, allowed values |
+| `openuispec_prepare` | Before UI code generation | Returns spec context, platform config, generation constraints |
+| `openuispec_read_specs` | Before and after generation | Loads spec file contents — the authoritative source for tokens, screens, contracts |
+| `openuispec_check` | After generation | Schema validation + concrete audit checklist from your spec |
+| `openuispec_validate` | After spec edits | Schema-only validation, optionally filtered by group |
+| `openuispec_drift` | Before updates | Detect spec drift since last snapshot, with semantic explanation |
+| `openuispec_status` | Anytime | Cross-target summary: baselines, drift, next steps |
+
+The server includes **protocol-level instructions** that trigger on UI-related requests independently of CLAUDE.md rules — so even if CLAUDE.md is buried under other project rules, the MCP enforcement still works.
+
+## Using without MCP
+
+You can also use OpenUISpec with any AI by providing context manually:
+
+> Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined. Use `platform/ios.yaml` for SwiftUI-specific overrides.
 
 For platform generation, treat these as hard output constraints:
 
-- Generate a valid native project or target that actually bundles every required runtime resource. Converting spec inputs into platform-native resource files is insufficient unless those files are attached to the final app target and resolve at runtime.
-- Do not ship unresolved resource identifiers in the UI. Raw localization keys, token references, asset names, or placeholder paths mean the generated output is incomplete.
-- Do not use a container or navigation primitive without defining its behavior for every supported size class and form factor. Master-detail patterns must provide a non-empty compact fallback instead of assuming large-screen behavior.
+- Generate a valid native project that bundles every required runtime resource
+- Do not ship unresolved resource identifiers (raw locale keys, token refs, placeholder paths)
+- Define behavior for every supported size class and form factor
 
-See the examples for concrete reference projects:
+See the examples for reference:
 
-- [TaskFlow](./examples/taskflow/openuispec/) for a compact reference spec covering all 7 contract families, with generated iOS, Android, and web targets under `examples/taskflow/generated/`
-- [Todo Orbit](./examples/todo-orbit/openuispec/) for a bilingual task app with generated iOS, Android, and web targets under `examples/todo-orbit/generated/`
+- [TaskFlow](./examples/taskflow/openuispec/) — compact reference spec covering all 7 contract families
+- [Todo Orbit](./examples/todo-orbit/openuispec/) — bilingual task app with localization, custom contracts, and generated native/web targets
 
 ## Repository structure
 
@@ -117,7 +184,7 @@ openuispec/
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
 ├── mcp-server/                          # MCP server (openuispec-mcp)
-│   └── index.ts                        # Stdio transport, 5 tools
+│   └── index.ts                        # Stdio transport, 8 tools
 ├── check/                               # Composite validation command
 │   └── index.ts                        # Schema + semantic + readiness
 ├── drift/                               # Drift detection (spec change tracking)
@@ -245,49 +312,6 @@ to see which targets are already up to date and which ones still need to catch u
 
 `drift --snapshot` is bookkeeping. It does not prove that the target code matches the spec, and it will not create a missing target output directory for you.
 
-## MCP server
-
-OpenUISpec includes an MCP (Model Context Protocol) server that exposes CLI commands as tools for AI assistants. This is the recommended way to integrate with Claude Code and other MCP-compatible clients — tools are called more reliably than CLAUDE.md instructions.
-
-### Setup
-
-`openuispec init` automatically configures the MCP server for your coding agent. For existing projects, run `openuispec update-rules` or add the config manually:
-
-**Claude Code** (`.mcp.json`), **VS Code / Copilot** (`.vscode/mcp.json`):
-```json
-{
-  "mcpServers": {
-    "openuispec": {
-      "command": "openuispec",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-**Codex** (`.codex/config.toml`):
-```toml
-[mcp_servers.openuispec]
-command = "openuispec"
-args = ["mcp"]
-```
-
-Or run directly: `openuispec mcp`
-
-Set `OPENUISPEC_PROJECT_DIR` to override the working directory.
-
-### Tools
-
-| Tool | Description |
-|------|-------------|
-| `openuispec_prepare` | Build AI-ready work bundle for a target. **Call before any UI code generation.** |
-| `openuispec_check` | Schema validation + semantic lint + prepare readiness. Call after spec edits. |
-| `openuispec_status` | Cross-target summary: baselines, drift, next steps. |
-| `openuispec_validate` | Schema-only validation, optionally filtered by group. |
-| `openuispec_drift` | Detect spec drift since last snapshot, with optional semantic explanation. |
-
-All tools return structured JSON. The server includes protocol-level instructions that tell AI assistants to call `openuispec_prepare` before any UI work — this works independently of CLAUDE.md rules.
-
 ## Spec at a glance
 
 | Section | What it defines |

package/cli/init.ts

@@ -268,11 +268,14 @@ When the openuispec MCP server is configured, AI assistants should use these too
 
 | Tool | When to use |
 |------|-------------|
+| \`openuispec_spec_types\` | Discover available spec types and their descriptions. |
+| \`openuispec_spec_schema\` | Get the full JSON schema for a specific spec type — exact structure, required fields, allowed values. |
 | \`openuispec_prepare\` | **Before any UI code generation.** Returns spec context, platform config, and constraints. |
+| \`openuispec_read_specs\` | Load spec file contents — the authoritative source for tokens, screens, contracts. |
 | \`openuispec_check\` | After editing spec files. Validates schema + semantics + readiness. |
-| \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
 | \`openuispec_validate\` | Schema-only validation, optionally by group. |
 | \`openuispec_drift\` | Detect spec changes since last snapshot. |
+| \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
 
 ## CLI commands
 
@@ -337,6 +340,11 @@ Call these MCP tools directly. They return structured JSON with everything you n
    - Navigation targets match flow definitions
 8. Report any real gaps found and fix them before finishing.
 
+**Creating new spec files:**
+- Call \`openuispec_spec_types\` to discover available spec types.
+- Call \`openuispec_spec_schema\` with the specific type to get the full JSON schema.
+- Write the spec file following the schema exactly.
+
 **Other tools:**
 - \`openuispec_status\` — cross-target summary, good starting point
 - \`openuispec_drift\` with \`explain: true\` — property-level spec changes
@@ -493,12 +501,14 @@ const EXPECTED_MCP_CONFIG = {
  * MCP config files by agent:
  *   .mcp.json              — Claude Code (project scope)
  *   .vscode/mcp.json       — VS Code / Copilot Chat
+ *   .gemini/settings.json  — Gemini CLI (if .gemini/ exists)
  *
  * All use the same { mcpServers: { openuispec: { command, args } } } shape.
  */
 const JSON_MCP_PATHS = [
   ".mcp.json",
   join(".vscode", "mcp.json"),
+  join(".gemini", "settings.json"),
 ];
 
 /** Codex uses TOML: .codex/config.toml */
@@ -534,8 +544,9 @@ function configureMcp(cwd: string, showRestart: boolean, quiet: boolean = false)
   for (const relPath of JSON_MCP_PATHS) {
     const configPath = join(cwd, relPath);
 
-    // .vscode/mcp.json: only write if .vscode/ already exists
-    if (relPath.startsWith(".vscode") && !existsSync(join(cwd, ".vscode"))) continue;
+    // Optional dirs: only write config if the parent directory already exists
+    const optionalParent = [".vscode", ".gemini"].find((d) => relPath.startsWith(d));
+    if (optionalParent && !existsSync(join(cwd, optionalParent))) continue;
 
     try {
       let config: Record<string, any> = {};

package/examples/social-app/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "openuispec": {
+      "command": "openuispec",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}

package/examples/social-app/AGENTS.md

@@ -0,0 +1,105 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.45 -->
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## MANDATORY — UI work requires OpenUISpec tools
+
+When the user's request involves UI — screens, navigation, layout, tokens, flows, localization,
+or any visual/structural change — you MUST use the OpenUISpec tools before writing any code.
+
+### MCP Tools (use these when available)
+
+Call these MCP tools directly. They return structured JSON with everything you need.
+
+**Pre-generation:**
+1. Call `openuispec_prepare` with the target platform — returns spec context, platform config, constraints.
+2. Call `openuispec_read_specs` to load spec file contents. Use these as the AUTHORITATIVE source.
+3. If spec changes are needed, update spec files FIRST, then call `openuispec_check`.
+4. Generate or update the platform UI code based on the spec contents.
+
+**Post-generation (EVERY TIME after writing UI code):**
+5. Call `openuispec_check` to validate spec integrity.
+6. Call `openuispec_read_specs` for the screens/contracts you just generated code for.
+7. Audit your generated code against the spec. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match exactly — no approximations
+   - Contract `must_handle` states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the spec's `size_classes`
+   - Locale keys match `$t:` references
+   - Navigation targets match flow definitions
+8. Report any real gaps found and fix them before finishing.
+
+**Creating new spec files:**
+- Call `openuispec_spec_types` to discover available spec types.
+- Call `openuispec_spec_schema` with the specific type to get the full JSON schema.
+- Write the spec file following the schema exactly.
+
+**Other tools:**
+- `openuispec_status` — cross-target summary, good starting point
+- `openuispec_drift` with `explain: true` — property-level spec changes
+- `openuispec_validate` — schema-only validation by group
+
+### CLI fallback (when MCP is not available)
+
+If MCP tools are not available, use these CLI commands with `--json` flag:
+- `openuispec prepare --target <t> --json` — build AI-ready work bundle
+- `openuispec check --target <t> --json` — composite validation
+- `openuispec status --json` — cross-target status
+- `openuispec drift --target <t> --explain --json` — semantic drift
+- `openuispec validate [group...] --json` — schema validation
+
+### Other CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec drift --snapshot --target <t>` — snapshot current state (only after UI code is updated)
+- `openuispec configure-target <t>` — configure target platform stack
+- `openuispec update-rules` — update AI rules to match installed package version
+
+## Spec format reference
+
+The spec format, schemas, and generation rules are in the installed `openuispec` package.
+You MUST read the reference files before creating or editing spec files — do NOT guess the format.
+
+**Find the package:** `node_modules/openuispec/` or run `npm root -g` → `<prefix>/openuispec/`.
+**Online fallback:** `https://openuispec.rsteam.uz/llms-full.txt`
+
+**Reference files (read in order):**
+1. `README.md` — schema tables, file format, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification
+3. `examples/taskflow/openuispec/` — complete working example
+4. `schema/` — JSON Schemas for every file type
+
+## Spec location
+- Spec root: `openuispec/` — read `openuispec/openuispec.yaml` first for actual paths.
+- Default dirs: tokens/, screens/, flows/, contracts/, platform/, locales/
+
+## When to start from spec vs platform code
+
+**Spec-first** (use `openuispec_prepare` or `openuispec prepare`):
+- Screen structure, navigation, fields, actions, validation, data binding changes
+- Token, variant, contract, flow, or localization changes
+- Changes affecting multiple platforms
+- Requests in product/UI terms
+
+**Platform-first** (skip spec tools):
+- Platform-specific polish (iOS-only, Android-only, web-only)
+- Local bug fixes that don't alter shared semantic behavior
+
+## If spec directories are empty (first-time setup)
+
+Read `spec/openuispec-v0.1.md` from the package first, then:
+1. Scan codebase for UI screens → create `openuispec/screens/<name>.yaml` as `status: stub`
+2. Extract tokens (colors, fonts, spacing) → `openuispec/tokens/`
+3. Create contract extensions → `openuispec/contracts/`
+4. Create locale files → `openuispec/locales/<locale>.json`
+5. Fill in `data_model`, `api.endpoints` in `openuispec/openuispec.yaml`
+
+## Rules
+- Do not snapshot drift unless the UI code has also been updated.
+- Do not modify generated UI without checking whether the spec must change first.
+- Do not use `configure-target --defaults` as silent approval — ask the user to confirm.
+- Always read spec format from the installed package, not from cached/memorized content.
+<!-- openuispec-rules-end -->

package/examples/social-app/CLAUDE.md

@@ -0,0 +1,105 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.45 -->
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## MANDATORY — UI work requires OpenUISpec tools
+
+When the user's request involves UI — screens, navigation, layout, tokens, flows, localization,
+or any visual/structural change — you MUST use the OpenUISpec tools before writing any code.
+
+### MCP Tools (use these when available)
+
+Call these MCP tools directly. They return structured JSON with everything you need.
+
+**Pre-generation:**
+1. Call `openuispec_prepare` with the target platform — returns spec context, platform config, constraints.
+2. Call `openuispec_read_specs` to load spec file contents. Use these as the AUTHORITATIVE source.
+3. If spec changes are needed, update spec files FIRST, then call `openuispec_check`.
+4. Generate or update the platform UI code based on the spec contents.
+
+**Post-generation (EVERY TIME after writing UI code):**
+5. Call `openuispec_check` to validate spec integrity.
+6. Call `openuispec_read_specs` for the screens/contracts you just generated code for.
+7. Audit your generated code against the spec. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match exactly — no approximations
+   - Contract `must_handle` states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the spec's `size_classes`
+   - Locale keys match `$t:` references
+   - Navigation targets match flow definitions
+8. Report any real gaps found and fix them before finishing.
+
+**Creating new spec files:**
+- Call `openuispec_spec_types` to discover available spec types.
+- Call `openuispec_spec_schema` with the specific type to get the full JSON schema.
+- Write the spec file following the schema exactly.
+
+**Other tools:**
+- `openuispec_status` — cross-target summary, good starting point
+- `openuispec_drift` with `explain: true` — property-level spec changes
+- `openuispec_validate` — schema-only validation by group
+
+### CLI fallback (when MCP is not available)
+
+If MCP tools are not available, use these CLI commands with `--json` flag:
+- `openuispec prepare --target <t> --json` — build AI-ready work bundle
+- `openuispec check --target <t> --json` — composite validation
+- `openuispec status --json` — cross-target status
+- `openuispec drift --target <t> --explain --json` — semantic drift
+- `openuispec validate [group...] --json` — schema validation
+
+### Other CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec drift --snapshot --target <t>` — snapshot current state (only after UI code is updated)
+- `openuispec configure-target <t>` — configure target platform stack
+- `openuispec update-rules` — update AI rules to match installed package version
+
+## Spec format reference
+
+The spec format, schemas, and generation rules are in the installed `openuispec` package.
+You MUST read the reference files before creating or editing spec files — do NOT guess the format.
+
+**Find the package:** `node_modules/openuispec/` or run `npm root -g` → `<prefix>/openuispec/`.
+**Online fallback:** `https://openuispec.rsteam.uz/llms-full.txt`
+
+**Reference files (read in order):**
+1. `README.md` — schema tables, file format, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification
+3. `examples/taskflow/openuispec/` — complete working example
+4. `schema/` — JSON Schemas for every file type
+
+## Spec location
+- Spec root: `openuispec/` — read `openuispec/openuispec.yaml` first for actual paths.
+- Default dirs: tokens/, screens/, flows/, contracts/, platform/, locales/
+
+## When to start from spec vs platform code
+
+**Spec-first** (use `openuispec_prepare` or `openuispec prepare`):
+- Screen structure, navigation, fields, actions, validation, data binding changes
+- Token, variant, contract, flow, or localization changes
+- Changes affecting multiple platforms
+- Requests in product/UI terms
+
+**Platform-first** (skip spec tools):
+- Platform-specific polish (iOS-only, Android-only, web-only)
+- Local bug fixes that don't alter shared semantic behavior
+
+## If spec directories are empty (first-time setup)
+
+Read `spec/openuispec-v0.1.md` from the package first, then:
+1. Scan codebase for UI screens → create `openuispec/screens/<name>.yaml` as `status: stub`
+2. Extract tokens (colors, fonts, spacing) → `openuispec/tokens/`
+3. Create contract extensions → `openuispec/contracts/`
+4. Create locale files → `openuispec/locales/<locale>.json`
+5. Fill in `data_model`, `api.endpoints` in `openuispec/openuispec.yaml`
+
+## Rules
+- Do not snapshot drift unless the UI code has also been updated.
+- Do not modify generated UI without checking whether the spec must change first.
+- Do not use `configure-target --defaults` as silent approval — ask the user to confirm.
+- Always read spec format from the installed package, not from cached/memorized content.
+<!-- openuispec-rules-end -->

package/examples/social-app/README.md

@@ -0,0 +1,19 @@
+# social-app
+
+Test project for exercising the local [`openuispec`](../openuispec) checkout.
+
+## Structure
+
+- `openuispec/` contains the spec scaffold.
+- `AGENTS.md` and `CLAUDE.md` include the OpenUISpec assistant rules generated by the local CLI.
+
+## Commands
+
+```bash
+npm run validate
+npm run validate:semantic
+npm run status
+npm run openuispec -- init
+```
+
+The scripts call the local `../openuispec` repo directly, so this project can be used without installing `openuispec` globally.

package/examples/social-app/backend/.gitkeep

@@ -0,0 +1 @@
+

package/examples/social-app/generated/android/social-app/app/build.gradle.kts

@@ -0,0 +1,92 @@
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.compose.compiler)
+    kotlin("plugin.serialization")
+}
+
+android {
+    namespace = "com.social.app"
+    compileSdk = 36
+
+    defaultConfig {
+        applicationId = "com.social.app"
+        minSdk = 26
+        targetSdk = 36
+        versionCode = 1
+        versionName = "1.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables {
+            useSupportLibrary = true
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+    kotlin {
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+        }
+    }
+    buildFeatures {
+        compose = true
+    }
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+dependencies {
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.activity.compose)
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.ui)
+    implementation(libs.androidx.ui.graphics)
+    implementation(libs.androidx.ui.tooling.preview)
+    implementation(libs.androidx.material3)
+    implementation(libs.androidx.material.icons.extended)
+    implementation(libs.google.material)
+    implementation(libs.coil.compose)
+    implementation(libs.coil.network)
+
+    // Decompose
+    implementation(libs.decompose)
+    implementation(libs.decompose.extensions.compose)
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
+
+    // MVIKotlin
+    implementation(libs.mvikotlin)
+    implementation(libs.mvikotlin.main)
+    implementation(libs.mvikotlin.logging)
+    implementation("com.arkivanov.mvikotlin:mvikotlin-extensions-coroutines:4.3.0")
+
+    // Essenty
+    implementation(libs.essenty.lifecycle)
+    implementation(libs.essenty.instancekeeper)
+
+    // DataStore
+    implementation(libs.androidx.datastore.preferences)
+    implementation(libs.androidx.datastore.core)
+
+    testImplementation("junit:junit:4.13.2")
+    androidTestImplementation("androidx.test.ext:junit:1.2.1")
+    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
+    androidTestImplementation(platform(libs.androidx.compose.bom))
+    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
+    debugImplementation(libs.androidx.ui.tooling)
+    debugImplementation("androidx.compose.ui:ui-test-manifest")
+}

package/examples/social-app/generated/android/social-app/app/src/main/AndroidManifest.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:name=".SocialAppApplication"
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/nav_home"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.SocialApp">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:label="@string/nav_home"
+            android:theme="@style/Theme.SocialApp">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

package/examples/social-app/generated/android/social-app/app/src/main/java/com/social/app/AppContainer.kt

@@ -0,0 +1,20 @@
+package com.social.app
+
+import android.content.Context
+import com.arkivanov.decompose.ComponentContext
+import com.arkivanov.mvikotlin.core.store.StoreFactory
+import com.social.app.data.preferences.DataStorePreferencesRepository
+import com.social.app.data.preferences.PreferencesRepository
+import com.social.app.ui.navigation.DefaultRootComponent
+import com.social.app.ui.navigation.RootComponent
+import com.arkivanov.mvikotlin.main.store.DefaultStoreFactory
+import com.arkivanov.mvikotlin.logging.store.LoggingStoreFactory
+
+class AppContainer(
+    context: Context,
+) {
+    val preferencesRepository: PreferencesRepository = DataStorePreferencesRepository(context.applicationContext)
+    val storeFactory: StoreFactory = LoggingStoreFactory(DefaultStoreFactory())
+
+    fun createRootComponent(componentContext: ComponentContext): RootComponent = DefaultRootComponent(componentContext)
+}

package/examples/social-app/generated/android/social-app/app/src/main/java/com/social/app/MainActivity.kt

@@ -0,0 +1,35 @@
+package com.social.app
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import com.arkivanov.decompose.defaultComponentContext
+import com.social.app.data.preferences.AppPreferences
+import com.social.app.ui.MainShell
+import com.social.app.ui.theme.SocialAppTheme
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val appContainer = (application as SocialAppApplication).appContainer
+        val root = appContainer.createRootComponent(defaultComponentContext())
+
+        enableEdgeToEdge()
+        setContent {
+            val preferences by appContainer.preferencesRepository.preferences.collectAsState(initial = AppPreferences())
+
+            SocialAppTheme(
+                themeMode = preferences.themeMode,
+            ) {
+                MainShell(
+                    root = root,
+                    preferencesRepository = appContainer.preferencesRepository,
+                    storeFactory = appContainer.storeFactory,
+                )
+            }
+        }
+    }
+}

package/examples/social-app/generated/android/social-app/app/src/main/java/com/social/app/SocialAppApplication.kt

@@ -0,0 +1,13 @@
+package com.social.app
+
+import android.app.Application
+
+class SocialAppApplication : Application() {
+    lateinit var appContainer: AppContainer
+        private set
+
+    override fun onCreate() {
+        super.onCreate()
+        appContainer = AppContainer(this)
+    }
+}