openuispec 0.2.3 → 0.2.5

package/README.md

@@ -123,10 +123,40 @@ Or run directly: `openuispec mcp`
 | `openuispec_get_contract` | Incremental edits | Get a single contract spec, optionally filtered to one variant |
 | `openuispec_get_tokens` | Incremental edits | Get tokens for a specific category (color, typography, spacing, etc.) |
 | `openuispec_get_locale` | Incremental edits | Get a single locale file, optionally filtered to specific keys |
-| `openuispec_screenshot` | Visual verification | Take a screenshot of the generated web app at a specific route (requires `puppeteer`) |
+| `openuispec_screenshot` | Visual verification | Screenshot the web app at a route via headless browser (requires `puppeteer`) |
+| `openuispec_screenshot_android` | Visual verification | Screenshot Android app on emulator — builds APK, installs, captures via adb. Works with any Android project via `project_dir` param |
+| `openuispec_screenshot_ios` | Visual verification | Screenshot iOS app on Simulator — builds with xcodebuild, captures via XCUITest. Works with any iOS project via `project_dir` param |
 
 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.
 
+### Visual verification
+
+The screenshot tools work with **any** Android/iOS/web project — they don't require an OpenUISpec manifest. Use `project_dir` to point directly at a project root:
+
+```
+# With OpenUISpec manifest (auto-discovers generated app)
+openuispec_screenshot_android(screen: "home")
+
+# Standalone — any Android project
+openuispec_screenshot_android(project_dir: "/path/to/android/project", screen: "home")
+
+# Standalone — any iOS project
+openuispec_screenshot_ios(project_dir: "/path/to/ios/project", scheme: "MyApp")
+```
+
+Additional override params:
+
+| Param | Android | iOS | Purpose |
+|-------|---------|-----|---------|
+| `project_dir` | yes | yes | Skip manifest, point directly at project root |
+| `module` | yes | — | Override app module name (default: auto-detect from `settings.gradle`) |
+| `scheme` | — | yes | Override Xcode scheme (default: auto-detect) |
+| `bundle_id` | — | yes | Override bundle ID (default: auto-detect from `project.pbxproj`) |
+
+Auto-detection features:
+- **Android**: Scans `settings.gradle.kts`/`.gradle` to find the module with `com.android.application` plugin. Supports both Kotlin DSL and Groovy DSL.
+- **iOS**: Reads deployment target from `project.pbxproj`. For navigation screenshots, generates an XCUITest project via xcodegen — works with both xcodegen-managed and standalone Xcode projects.
+
 ## Using without MCP
 
 You can also use OpenUISpec with any AI by providing context manually:
@@ -191,8 +221,17 @@ openuispec/
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
 ├── mcp-server/                          # MCP server (openuispec-mcp)
-│   ├── index.ts                        # Stdio transport, 13 tools
-│   └── screenshot.ts                  # Dev server + headless browser screenshot
+│   ├── index.ts                        # Stdio transport, 15 tools
+│   ├── screenshot.ts                  # Dev server + headless browser screenshot (web)
+│   ├── screenshot-shared.ts           # Shared utilities for platform screenshot tools
+│   ├── screenshot-android.ts          # Android screenshot via emulator (adb screencap)
+│   └── screenshot-ios.ts             # iOS screenshot via Simulator (xcodebuild + XCUITest)
+├── scripts/
+│   └── take-all-screenshots.ts        # Batch screenshot capture for all example projects
+├── artifacts/                           # Screenshot artifacts from generated apps
+│   ├── social-app/screenshots/        # Web + Android screenshots
+│   ├── todo-orbit/screenshots/        # Web + Android + iOS screenshots
+│   └── taskflow/screenshots/          # Web + Android + iOS screenshots
 ├── check/                               # Composite validation command
 │   └── index.ts                        # Schema + semantic + readiness
 ├── drift/                               # Drift detection (spec change tracking)
@@ -293,6 +332,20 @@ Use the commands like this:
 - `openuispec prepare --target <t>` builds the target work bundle for either first-time generation or drift-based updates
 - `openuispec status` shows every target's snapshot state, baseline commit, and whether that target is behind the current spec, still needs a baseline, or has not been generated yet
 
+Spec access commands (also available as MCP tools):
+- `openuispec read-specs [paths...]` reads spec file contents as JSON
+- `openuispec get-screen <name>` gets a single screen spec
+- `openuispec get-contract <name> [--variant v]` gets a contract spec, optionally one variant
+- `openuispec get-tokens <category>` gets tokens for a category (color, typography, spacing, etc.)
+- `openuispec get-locale <locale> [--keys k1,k2]` gets a locale file, optionally filtered keys
+- `openuispec spec-types` lists all available spec types with descriptions
+- `openuispec spec-schema <type>` gets the full JSON schema for a spec type
+
+Screenshot commands (also available as MCP tools):
+- `openuispec screenshot --route /path [--theme dark] [--output-dir dir]` screenshots the web app
+- `openuispec screenshot-android [--project-dir path] [--screen name] [--module name]` screenshots the Android app on an emulator
+- `openuispec screenshot-ios [--project-dir path] [--screen name] [--scheme name]` screenshots the iOS app on a Simulator
+
 In first-time generation mode, `prepare` also carries target-specific generation constraints such as native localization requirements, multi-file output rules, target folder layout expectations, and a requirement to refresh current platform/framework setup knowledge before code generation.
 
 If stack choices were auto-applied via `configure-target --defaults` or `init --defaults`, they remain unconfirmed. `prepare` will block implementation readiness until the user explicitly confirms the target stack, and AI agents should ask the user to confirm or change those choices instead of silently proceeding to code generation.

package/cli/index.ts

@@ -15,11 +15,39 @@
  *   openuispec status                         Show cross-target baseline/drift status
  *   openuispec check --target <t> [--json]    Composite validation + prepare readiness
  *   openuispec validate [group...]            Validate spec files against schemas
+ *   openuispec read-specs [paths...]          Read spec file contents
+ *   openuispec get-screen <name>              Get a single screen spec
+ *   openuispec get-contract <name> [--variant v] Get a contract spec
+ *   openuispec get-tokens <category>          Get tokens for a category
+ *   openuispec get-locale <locale> [--keys k1,k2] Get a locale file
+ *   openuispec spec-types                     List available spec types
+ *   openuispec spec-schema <type>             Get JSON schema for a spec type
+ *   openuispec screenshot [--route /path]     Screenshot the web app
+ *   openuispec screenshot-android [opts]      Screenshot Android app on emulator
+ *   openuispec screenshot-ios [opts]          Screenshot iOS app on simulator
  */
 
 import { init, updateRules, extractRulesVersion, getPackageVersion } from "./init.js";
-import { join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { join, dirname, relative, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// ── arg parsing helpers ──────────────────────────────────────────────
+
+function getFlag(argv: string[], name: string): boolean {
+  return argv.includes(name);
+}
+
+function getOption(argv: string[], name: string): string | null {
+  const idx = argv.indexOf(name);
+  return idx !== -1 && argv[idx + 1] ? argv[idx + 1] : null;
+}
+
+function getPositional(argv: string[], startIdx = 0): string[] {
+  return argv.slice(startIdx).filter((a) => !a.startsWith("--"));
+}
+
+// ── rules version check ─────────────────────────────────────────────
 
 function checkRulesVersion(): void {
   const cwd = process.cwd();
@@ -45,8 +73,35 @@ function checkRulesVersion(): void {
   }
 }
 
+// ── spec helpers (shared with MCP server) ────────────────────────────
+
+function resolveSpecDir(projectDir: string, manifest: any, key: string): string {
+  return resolve(projectDir, manifest.includes?.[key] ?? `./${key}/`);
+}
+
+const SCHEMA_CATALOG: Record<string, { file: string; title: string; description: string }> = {
+  manifest:         { file: "openuispec.schema.json",            title: "Root Manifest",    description: "Root manifest (openuispec.yaml)" },
+  screen:           { file: "screen.schema.json",                title: "Screen",           description: "Screen composition: layout, sections, navigation" },
+  flow:             { file: "flow.schema.json",                  title: "Flow",             description: "Navigation flow definitions" },
+  platform:         { file: "platform.schema.json",              title: "Platform",         description: "Platform-specific generation config" },
+  contract:         { file: "contract.schema.json",              title: "Contract",         description: "Built-in UI contract definitions" },
+  "custom-contract":{ file: "custom-contract.schema.json",       title: "Custom Contract",  description: "User-defined UI contract definitions (x_ prefixed)" },
+  locale:           { file: "locale.schema.json",                title: "Locale",           description: "Locale translation files" },
+  "tokens/color":       { file: "tokens/color.schema.json",       title: "Color Tokens",       description: "Color tokens" },
+  "tokens/typography":  { file: "tokens/typography.schema.json",   title: "Typography Tokens",  description: "Typography tokens" },
+  "tokens/spacing":     { file: "tokens/spacing.schema.json",     title: "Spacing Tokens",     description: "Spacing tokens" },
+  "tokens/elevation":   { file: "tokens/elevation.schema.json",   title: "Elevation Tokens",   description: "Elevation tokens" },
+  "tokens/motion":      { file: "tokens/motion.schema.json",      title: "Motion Tokens",      description: "Motion tokens" },
+  "tokens/layout":      { file: "tokens/layout.schema.json",      title: "Layout Tokens",      description: "Layout tokens" },
+  "tokens/themes":      { file: "tokens/themes.schema.json",      title: "Theme Tokens",       description: "Theme definitions" },
+  "tokens/icons":       { file: "tokens/icons.schema.json",       title: "Icon Tokens",        description: "Icon tokens" },
+};
+
+// ── main ─────────────────────────────────────────────────────────────
+
 async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
+  const cwd = process.cwd();
 
   switch (command) {
     case "init":
@@ -100,35 +155,252 @@ async function main(): Promise<void> {
       break;
     }
 
+    // ── spec getters ───────────────────────────────────────────────
+
+    case "read-specs": {
+      const { findProjectDir, discoverSpecFiles } = await import("../drift/index.js");
+      const projectDir = findProjectDir(cwd);
+      const allFiles = discoverSpecFiles(projectDir);
+      const paths = getPositional(rest);
+
+      const filesToRead = paths.length > 0
+        ? allFiles.filter((f) => {
+            const rel = relative(projectDir, f);
+            return paths.some((p) => rel === p || rel.endsWith(p));
+          })
+        : allFiles;
+
+      const contents = filesToRead.map((f) => ({
+        path: relative(projectDir, f),
+        content: readFileSync(f, "utf-8"),
+      }));
+      console.log(JSON.stringify(contents, null, 2));
+      break;
+    }
+
+    case "get-screen": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: openuispec get-screen <name>"); process.exit(1); }
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const screensDir = resolveSpecDir(projectDir, manifest, "screens");
+      const filePath = join(screensDir, `${name}.yaml`);
+      if (!existsSync(filePath)) { console.error(`Screen "${name}" not found at ${filePath}`); process.exit(1); }
+      console.log(readFileSync(filePath, "utf-8"));
+      break;
+    }
+
+    case "get-contract": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: openuispec get-contract <name> [--variant v]"); process.exit(1); }
+      const variant = getOption(rest, "--variant");
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const contractsDir = resolveSpecDir(projectDir, manifest, "contracts");
+
+      if (!existsSync(contractsDir)) { console.error(`Contracts directory not found: ${contractsDir}`); process.exit(1); }
+
+      let found = false;
+      for (const file of readdirSync(contractsDir).filter(f => f.endsWith(".yaml")).sort()) {
+        const filePath = join(contractsDir, file);
+        const raw = readFileSync(filePath, "utf-8");
+        const content = YAML.parse(raw);
+        const contractName = Object.keys(content)[0];
+        if (contractName !== name) continue;
+        found = true;
+
+        if (variant) {
+          const variantDef = content[contractName]?.variants?.[variant];
+          if (!variantDef) {
+            const available = Object.keys(content[contractName]?.variants ?? {}).join(", ");
+            console.error(`Variant "${variant}" not found. Available: ${available}`);
+            process.exit(1);
+          }
+          console.log(JSON.stringify({ name, variant, definition: variantDef }, null, 2));
+        } else {
+          console.log(raw);
+        }
+        break;
+      }
+      if (!found) { console.error(`Contract "${name}" not found in ${contractsDir}`); process.exit(1); }
+      break;
+    }
+
+    case "get-tokens": {
+      const category = rest[0];
+      if (!category) { console.error("Usage: openuispec get-tokens <category>"); process.exit(1); }
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const tokensDir = resolveSpecDir(projectDir, manifest, "tokens");
+
+      for (const ext of [".yaml", ".yml"]) {
+        const filePath = join(tokensDir, `${category}${ext}`);
+        if (existsSync(filePath)) { console.log(readFileSync(filePath, "utf-8")); process.exit(0); }
+      }
+
+      const available = readdirSync(tokensDir).filter(f => f.endsWith(".yaml") || f.endsWith(".yml")).map(f => f.replace(/\.ya?ml$/, ""));
+      console.error(`Token category "${category}" not found. Available: ${available.join(", ")}`);
+      process.exit(1);
+      break;
+    }
+
+    case "get-locale": {
+      const locale = rest[0];
+      if (!locale) { console.error("Usage: openuispec get-locale <locale> [--keys k1,k2,k3]"); process.exit(1); }
+      const keysStr = getOption(rest, "--keys");
+      const keys = keysStr ? keysStr.split(",").map(k => k.trim()) : null;
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const localesDir = resolveSpecDir(projectDir, manifest, "locales");
+      const filePath = join(localesDir, `${locale}.json`);
+
+      if (!existsSync(filePath)) {
+        const available = existsSync(localesDir)
+          ? readdirSync(localesDir).filter(f => f.endsWith(".json")).map(f => f.replace(".json", ""))
+          : [];
+        console.error(`Locale "${locale}" not found. Available: ${available.join(", ")}`);
+        process.exit(1);
+      }
+
+      const content = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (keys) {
+        const filtered: Record<string, unknown> = {};
+        for (const key of keys) { if (key in content) filtered[key] = content[key]; }
+        console.log(JSON.stringify(filtered, null, 2));
+      } else {
+        console.log(JSON.stringify(content, null, 2));
+      }
+      break;
+    }
+
+    // ── schema reference ───────────────────────────────────────────
+
+    case "spec-types": {
+      const types = Object.entries(SCHEMA_CATALOG).map(([type, info]) => ({
+        type, title: info.title, description: info.description,
+      }));
+      console.log(JSON.stringify(types, null, 2));
+      break;
+    }
+
+    case "spec-schema": {
+      const type = rest[0];
+      if (!type) { console.error("Usage: openuispec spec-schema <type>\nRun `openuispec spec-types` to list types."); process.exit(1); }
+      const entry = SCHEMA_CATALOG[type];
+      if (!entry) { console.error(`Unknown spec type "${type}". Run \`openuispec spec-types\` to list types.`); process.exit(1); }
+      const __dirname = dirname(fileURLToPath(import.meta.url));
+      const schemaPath = join(__dirname, "..", "schema", entry.file);
+      console.log(readFileSync(schemaPath, "utf-8"));
+      break;
+    }
+
+    // ── screenshot tools ───────────────────────────────────────────
+
+    case "screenshot": {
+      const { takeScreenshot } = await import("../mcp-server/screenshot.js");
+      const result = await takeScreenshot(cwd, {
+        route: getOption(rest, "--route") ?? "/",
+        viewport: {
+          width: parseInt(getOption(rest, "--width") ?? "1280"),
+          height: parseInt(getOption(rest, "--height") ?? "800"),
+        },
+        theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
+        wait_for: parseInt(getOption(rest, "--wait-for") ?? "1000"),
+        full_page: getFlag(rest, "--full-page"),
+        selector: getOption(rest, "--selector") ?? undefined,
+        output_dir: getOption(rest, "--output-dir") ?? undefined,
+      });
+      printScreenshotResult(result);
+      break;
+    }
+
+    case "screenshot-android": {
+      const { takeAndroidScreenshot } = await import("../mcp-server/screenshot-android.js");
+      const result = await takeAndroidScreenshot(cwd, {
+        screen: getOption(rest, "--screen") ?? undefined,
+        route: getOption(rest, "--route") ?? undefined,
+        nav: getOption(rest, "--nav")?.split(",") ?? undefined,
+        theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
+        wait_for: parseInt(getOption(rest, "--wait-for") ?? "3000"),
+        output_dir: getOption(rest, "--output-dir") ?? undefined,
+        project_dir: getOption(rest, "--project-dir") ?? undefined,
+        module: getOption(rest, "--module") ?? undefined,
+      });
+      printScreenshotResult(result);
+      break;
+    }
+
+    case "screenshot-ios": {
+      const { takeIOSScreenshot } = await import("../mcp-server/screenshot-ios.js");
+      const result = await takeIOSScreenshot(cwd, {
+        screen: getOption(rest, "--screen") ?? undefined,
+        device: getOption(rest, "--device") ?? undefined,
+        nav: getOption(rest, "--nav")?.split(",") ?? undefined,
+        theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
+        wait_for: parseInt(getOption(rest, "--wait-for") ?? "3000"),
+        output_dir: getOption(rest, "--output-dir") ?? undefined,
+        project_dir: getOption(rest, "--project-dir") ?? undefined,
+        scheme: getOption(rest, "--scheme") ?? undefined,
+        bundle_id: getOption(rest, "--bundle-id") ?? undefined,
+      });
+      printScreenshotResult(result);
+      break;
+    }
+
+    // ── help ────────────────────────────────────────────────────────
+
     case undefined:
     case "--help":
     case "-h":
       console.log(`
-OpenUISpec CLI v0.1
+OpenUISpec CLI v${getPackageVersion()}
 
 Usage:
   openuispec init                           Create a new spec project
   openuispec init --defaults                Scaffold non-interactively with unconfirmed defaults
-  openuispec init --list-options            Print init prompt options as JSON
   openuispec init --no-configure-targets    Skip target stack setup during init
   openuispec update-rules                   Update AI rules to match installed version
-  openuispec configure-target <t> [--defaults] Configure target stack; --defaults stays unconfirmed
-  openuispec configure-target <t> --set k=v    Set specific stack values (confirmed)
-  openuispec configure-target <t> --list-options Print target stack prompt options as JSON
+  openuispec configure-target <t> [--defaults]  Configure target stack
+  openuispec configure-target <t> --set k=v     Set specific stack values (confirmed)
+
+Workflow:
+  openuispec status                         Show cross-target baseline/drift status
   openuispec drift [--target <t>]           Check for spec drift
   openuispec drift --snapshot --target <t>  Snapshot current state + git baseline
   openuispec drift --target <t> --explain   Explain semantic changes since baseline
   openuispec prepare --target <t>           Build the target work bundle
-  openuispec status                         Show cross-target baseline/drift status
   openuispec check --target <t> [--json]    Composite validation + prepare readiness
   openuispec validate [group...] [--json]   Validate spec files
-  openuispec validate semantic --json       Semantic validation as JSON
-  openuispec mcp                           Start MCP server (stdio transport)
 
-Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
+Spec access:
+  openuispec read-specs [paths...]          Read spec file contents as JSON
+  openuispec get-screen <name>              Get a single screen spec (YAML)
+  openuispec get-contract <name> [--variant v]  Get a contract spec
+  openuispec get-tokens <category>          Get tokens for a category (YAML)
+  openuispec get-locale <locale> [--keys k1,k2] Get a locale file (JSON)
+  openuispec spec-types                     List available spec types
+  openuispec spec-schema <type>             Get full JSON schema for a spec type
 
-Exit codes: 0 = success, 1 = missing config/usage error, 2 = validation failure
+Screenshots:
+  openuispec screenshot [--route /path] [--theme light|dark] [--output-dir dir]
+  openuispec screenshot-android [--screen name] [--project-dir path] [--module name]
+      [--route deeplink] [--nav Step1,Step2] [--theme light|dark] [--output-dir dir]
+  openuispec screenshot-ios [--screen name] [--project-dir path] [--scheme name]
+      [--bundle-id id] [--device name] [--nav Step1,Step2] [--theme light|dark]
+
+Server:
+  openuispec mcp                            Start MCP server (stdio transport)
 
+Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
+Exit codes: 0 = success, 1 = missing config/usage error, 2 = validation failure
 Docs: https://openuispec.rsteam.uz
 `);
       break;
@@ -140,6 +412,25 @@ Docs: https://openuispec.rsteam.uz
   }
 }
 
+// ── screenshot result printer ────────────────────────────────────────
+
+function printScreenshotResult(result: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; isError?: boolean }): void {
+  if (result.isError) {
+    for (const item of result.content) {
+      if (item.type === "text") console.error(item.text);
+    }
+    process.exit(1);
+  }
+  for (const item of result.content) {
+    if (item.type === "text") console.log(item.text);
+    if (item.type === "image" && item.data) {
+      const outFile = `screenshot-${Date.now()}.png`;
+      writeFileSync(outFile, Buffer.from(item.data, "base64"));
+      console.log(`Screenshot saved: ${outFile}`);
+    }
+  }
+}
+
 main().catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);

package/cli/init.ts

@@ -282,11 +282,14 @@ When the openuispec MCP server is configured, AI assistants should use these too
 | \`openuispec_get_contract\` | Get a single contract spec, optionally filtered to one variant. |
 | \`openuispec_get_tokens\` | Get tokens for a specific category (color, typography, spacing, etc.). |
 | \`openuispec_get_locale\` | Get a single locale file, optionally filtered to specific keys. |
-| \`openuispec_screenshot\` | Take a screenshot of the generated web app at a route (requires \`puppeteer\`). |
+| \`openuispec_screenshot\` | Screenshot the web app at a route via headless browser (requires \`puppeteer\`). |
+| \`openuispec_screenshot_android\` | Screenshot Android app on emulator — works with any project via \`project_dir\`. |
+| \`openuispec_screenshot_ios\` | Screenshot iOS app on Simulator via XCUITest — works with any project via \`project_dir\`. |
 
 ## CLI commands
 
 \`\`\`bash
+# Workflow
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Run semantic cross-reference linting
 openuispec configure-target ${targets[0]} [--defaults] # Configure target stack; --defaults stays unconfirmed
@@ -294,6 +297,20 @@ openuispec status               # Show cross-target baseline/drift status
 openuispec drift --target ${targets[0]} --explain   # Explain semantic spec drift
 openuispec prepare --target ${targets[0]}          # Build the target work bundle
 openuispec drift --snapshot --target ${targets[0]} # Snapshot current state + git baseline after target output exists
+
+# Spec access
+openuispec read-specs [paths...]          # Read spec file contents as JSON
+openuispec get-screen <name>              # Get a single screen spec
+openuispec get-contract <name> [--variant v] # Get a contract spec
+openuispec get-tokens <category>          # Get tokens for a category
+openuispec get-locale <locale> [--keys k1,k2] # Get a locale file
+openuispec spec-types                     # List available spec types
+openuispec spec-schema <type>             # Get JSON schema for a spec type
+
+# Screenshots
+openuispec screenshot --route /home --theme dark --output-dir screenshots
+openuispec screenshot-android --screen home --project-dir /path/to/android
+openuispec screenshot-ios --screen home --project-dir /path/to/ios --scheme MyApp
 \`\`\`
 
 The target work bundle has two modes:
@@ -374,6 +391,16 @@ If MCP tools are not available, use these CLI commands with \`--json\` flag:
 - \`openuispec status --json\` — cross-target status
 - \`openuispec drift --target <t> --explain --json\` — semantic drift
 - \`openuispec validate [group...] --json\` — schema validation
+- \`openuispec read-specs [paths...]\` — read spec file contents
+- \`openuispec get-screen <name>\` — get a single screen spec
+- \`openuispec get-contract <name> [--variant v]\` — get a contract spec
+- \`openuispec get-tokens <category>\` — get tokens for a category
+- \`openuispec get-locale <locale> [--keys k1,k2]\` — get a locale file
+- \`openuispec spec-types\` — list available spec types
+- \`openuispec spec-schema <type>\` — get JSON schema for a spec type
+- \`openuispec screenshot --route /path\` — screenshot the web app
+- \`openuispec screenshot-android [--project-dir path]\` — screenshot Android app
+- \`openuispec screenshot-ios [--project-dir path]\` — screenshot iOS app
 
 ### Other CLI commands
 - \`openuispec init\` — scaffold a new spec project

package/examples/social-app/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.2.2 -->
+<!-- openuispec-rules-version: 0.2.4 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -60,6 +60,16 @@ If MCP tools are not available, use these CLI commands with `--json` flag:
 - `openuispec status --json` — cross-target status
 - `openuispec drift --target <t> --explain --json` — semantic drift
 - `openuispec validate [group...] --json` — schema validation
+- `openuispec read-specs [paths...]` — read spec file contents
+- `openuispec get-screen <name>` — get a single screen spec
+- `openuispec get-contract <name> [--variant v]` — get a contract spec
+- `openuispec get-tokens <category>` — get tokens for a category
+- `openuispec get-locale <locale> [--keys k1,k2]` — get a locale file
+- `openuispec spec-types` — list available spec types
+- `openuispec spec-schema <type>` — get JSON schema for a spec type
+- `openuispec screenshot --route /path` — screenshot the web app
+- `openuispec screenshot-android [--project-dir path]` — screenshot Android app
+- `openuispec screenshot-ios [--project-dir path]` — screenshot iOS app
 
 ### Other CLI commands
 - `openuispec init` — scaffold a new spec project

package/examples/social-app/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.2.2 -->
+<!-- openuispec-rules-version: 0.2.4 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -60,6 +60,16 @@ If MCP tools are not available, use these CLI commands with `--json` flag:
 - `openuispec status --json` — cross-target status
 - `openuispec drift --target <t> --explain --json` — semantic drift
 - `openuispec validate [group...] --json` — schema validation
+- `openuispec read-specs [paths...]` — read spec file contents
+- `openuispec get-screen <name>` — get a single screen spec
+- `openuispec get-contract <name> [--variant v]` — get a contract spec
+- `openuispec get-tokens <category>` — get tokens for a category
+- `openuispec get-locale <locale> [--keys k1,k2]` — get a locale file
+- `openuispec spec-types` — list available spec types
+- `openuispec spec-schema <type>` — get JSON schema for a spec type
+- `openuispec screenshot --route /path` — screenshot the web app
+- `openuispec screenshot-android [--project-dir path]` — screenshot Android app
+- `openuispec screenshot-ios [--project-dir path]` — screenshot iOS app
 
 ### Other CLI commands
 - `openuispec init` — scaffold a new spec project

package/examples/social-app/generated/android/social-app/app/.paparazzi-hashes.json

@@ -0,0 +1,3 @@
+{
+  "/Users/rustam/Projects/openuispec/examples/social-app/generated/android/social-app/app/src/main/java/com/social/app/ui/screens/HomeFeedScreen.kt": "5917db1b3b8c8633cd315829f8d2ecaf"
+}

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

@@ -1,4 +1,5 @@
 plugins {
+    id("app.cash.paparazzi")
     alias(libs.plugins.android.application)
     alias(libs.plugins.compose.compiler)
     kotlin("plugin.serialization")
@@ -89,4 +90,5 @@ dependencies {
     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/java/com/social/app/ui/screens/HomeFeedScreen.kt

@@ -28,6 +28,7 @@ import androidx.compose.runtime.setValue
 import androidx.compose.runtime.snapshotFlow
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.tooling.preview.Preview
 import com.social.app.R
 import com.social.app.data.MockData
 import com.social.app.ui.components.ChipOption
@@ -155,3 +156,14 @@ fun HomeFeedScreen(
         }
     }
 }
+
+@Preview(showBackground = true)
+@Composable
+fun HomeFeedScreenPreview() {
+    MaterialTheme {
+        HomeFeedScreen(
+            onPostClick = {},
+            onUserClick = {},
+        )
+    }
+}

package/examples/social-app/generated/android/social-app/app/src/test/kotlin/com/social/app/screenshots/HomeFeedScreenshotTest.kt

@@ -0,0 +1,34 @@
+package com.social.app.screenshots
+
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import com.social.app.ui.screens.*
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.test.setMain
+import kotlinx.coroutines.test.resetMain
+import org.junit.After
+import org.junit.Before
+
+class HomeFeedScreenshotTest {
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_5)
+
+    @Before
+    fun setUp() {
+        Dispatchers.setMain(Dispatchers.Unconfined)
+    }
+
+    @After
+    fun tearDown() {
+        Dispatchers.resetMain()
+    }
+
+    @Test
+    fun homeFeedScreenPreview() {
+        paparazzi.snapshot {
+            HomeFeedScreenPreview()
+        }
+    }
+}

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

@@ -3,4 +3,5 @@ plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.compose.compiler) apply false
     kotlin("plugin.serialization") version "2.3.0" apply false
+    id("app.cash.paparazzi") version "2.0.0-alpha04" apply false
 }

package/examples/social-app/generated/android/social-app/gradle/libs.versions.toml

@@ -1,4 +1,5 @@
 [versions]
+paparazzi = "2.0.0-alpha04"
 agp = "9.1.0"
 kotlin = "2.3.0"
 coreKtx = "1.18.0"
@@ -43,6 +44,7 @@ androidx-datastore-preferences = { group = "androidx.datastore", name = "datasto
 androidx-datastore-core = { group = "androidx.datastore", name = "datastore-core", version.ref = "datastore" }
 
 [plugins]
+paparazzi = { id = "app.cash.paparazzi", version.ref = "paparazzi" }
 android-application = { id = "com.android.application", version.ref = "agp" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }