@lingxia/skill 0.8.0

package/skill/cli/lxdev.md

@@ -0,0 +1,195 @@
+# `lxdev` — Drive a running dev session
+
+`lxdev` is the external automation client for a running LingXia `lingxia dev` session. It ships from the same crate as `lingxia` and is on `PATH` after a standard install. Use it to inspect / drive the host app's browser tabs, the lxapps inside it, and the dev log stream — without rebuilding or restarting the dev session.
+
+This is the **agent-facing** dev surface: every command takes plain flags, prints predictable JSON (with `--json`), and never owns a long-running process. Run it from anywhere inside the project tree.
+
+---
+
+## How it finds the session
+
+`lingxia dev` writes one file per active session under `.lingxia/sessions/<session_id>.json` and removes it on clean exit. `lxdev` scans that directory on every invocation. Each file records:
+
+| Field | Purpose |
+|---|---|
+| `session_id` | `<unix-ms>-<uuid>`; stable for the whole session |
+| `pid` | The `lingxia dev` process — diagnostics only |
+| `platform` | `android` / `ios` / `macos` / `harmony` / `lxapp` |
+| `started_at` | Unix milliseconds |
+| `ws_url` | `ws://host:port` the dev websocket is listening on |
+| `log_file` | Path to the session's JSONL log file |
+
+There is no daemon. The CLI process that started the session owns its file; nothing else writes there.
+
+---
+
+## Selecting a session
+
+When `lxdev` is invoked **without** `--session` or `--platform`:
+
+- **One live session in the project** → use it (no probe).
+- **Multiple live sessions** → refuse and list candidates. The user must add `--session <id-prefix>` or `--platform <name>`.
+
+Why refuse rather than pick a default? In a project where a human and an agent (Claude / Codex / CI) might both be running dev sessions concurrently, "default to the most recent" silently routes commands to the wrong target. Explicit selection beats a guess.
+
+Flags (both are global — they go before the subcommand):
+
+```bash
+lxdev --session 20260520-abc browser tabs
+lxdev --platform ios browser tabs
+```
+
+`--session` matches by prefix, so a short unique fragment is enough. `--platform` is exact (case-insensitive). Selectors error out if zero or multiple sessions match.
+
+---
+
+## `lxdev sessions`
+
+Inspect / clean up session state:
+
+```bash
+lxdev sessions              # human-readable table
+lxdev sessions --json       # JSON array — each entry has a `stale` boolean
+lxdev sessions prune        # remove session files whose WS server no longer responds
+```
+
+A session is considered **stale** when a 200ms TCP probe to its `ws_url` fails. Stale entries are normally cleaned up automatically — by the next `lingxia dev` startup (which prunes before checking same-platform conflicts), and by `lxdev` when ambiguity forces it to probe. `lxdev sessions prune` is the manual escape hatch after a hard crash (`kill -9`, IDE force-stop, etc.).
+
+---
+
+## Subcommand families
+
+`lxdev` exposes four families of commands, all of which target a single resolved session:
+
+### `lxdev browser …`
+
+Drive the host app's browser tabs. Roughly a subset of Playwright's automation surface, scoped to a single LingXia browser instance:
+
+`open`, `tabs`, `current`, `activate`, `close`, `reload`, `back`, `forward`, `eval`, `query`, `wait`, `wait-url`, `wait-navigation`, `click`, `type`, `fill`, `press`, `scroll`, `scroll-to`, `cookies list|set|delete|clear`, `screenshot`.
+
+Most subcommands accept `--tab current|<tab-id>` (default: `current`) and `--json`. Wait/navigation commands take `--timeout-ms`.
+
+**Screenshot** captures a PNG of the tab's visible content via the platform WebView's native snapshot API. By default writes to `.lingxia/screenshots/<tab>-<ts>.png`; pass `--output <path>` or `--output -` for stdout, or `--json` to get the base64-encoded payload inline.
+
+This is the **WebView-scope** screenshot — only web content, no host UI overlays. For the entire window (including native sidebars, surfaces, etc.) see `lxdev app screenshot` below.
+
+| Platform | WebView screenshot | App/window screenshot |
+|---|---|---|
+| macOS | ✅ WKWebView `takeSnapshotWithConfiguration:` → `NSImage` → `NSBitmapImageRep` PNG | ✅ `NSView.cacheDisplayInRect:toBitmapImageRep:` (no Screen Recording permission needed) |
+| iOS | ✅ WKWebView `takeSnapshotWithConfiguration:` → `UIImagePNGRepresentation` | ✅ `UIWindow.layer.renderInContext:` (key UIWindow via scene + fallback chain) |
+| Android | ✅ `WebView.draw(Canvas)` onto a `Bitmap` → `Bitmap.compress(PNG)` via JNI | ✅ `PixelCopy.request(window.decorView)` (API 26+) → `View.draw(Canvas)` fallback |
+| HarmonyOS | ✅ `WebviewController.webPageSnapshot` → `image.PixelMap` → `ImagePacker` PNG | ✅ `window.snapshot` → `ImagePacker` PNG |
+
+All platforms time out after 5 seconds. The PNG bytes are returned to the CLI base64-encoded in the JSON envelope; `lxdev` decodes and writes the binary file.
+
+### `lxdev app …`
+
+Operate at the host-app scope (not lxapp-scope): window enumeration and full window screenshot.
+
+```bash
+lxdev app windows                          # list all NSWindow / Activity / UIWindow
+lxdev app windows --json                   # same as JSON
+lxdev app screenshot                       # capture key/focused window
+lxdev app screenshot --scope screen        # full device display (default off iOS)
+lxdev app screenshot --scope window        # app's own window only (default on iOS)
+lxdev app screenshot --window <id>         # specific window (id from `app windows`); window scope only
+lxdev app screenshot --output ~/x.png      # custom path; default .lingxia/screenshots/app-<platform>-<ts>.png
+lxdev app screenshot --output -            # PNG bytes to stdout
+lxdev app screenshot --json                # JSON envelope (window-scope only — screen scope writes a file)
+```
+
+#### Scope: `screen` vs `window`
+
+These two scopes capture **different things**; the same command produces different output across platforms because Apple's iOS doesn't expose a host-side screen-capture CLI.
+
+- **`screen`** — full device display via host tools (`adb shell screencap` / `hdc shell snapshot_display` / `screencapture`). Includes IME, status bar, dialogs from other windows, system overlays. No in-app code, no consent prompt, no foreground service. Default on android / harmony / macos.
+- **`window`** — only the app's own window via the in-app `PixelCopy` / `webPageSnapshot` / `UIWindow.layer.render` path. Excludes IME and system bars. Required default on **iOS** (no public CLI screen capture) and the only way to target a specific `--window` on multi-window platforms (macOS).
+
+| Platform | Default | `--scope screen` | `--scope window` |
+|---|---|---|---|
+| android | screen | adb screencap (full incl. IME) | PixelCopy (app window) |
+| harmony | screen | hdc snapshot_display (full incl. IME) | webPageSnapshot (app window) |
+| macos | screen | screencapture (full display) | NSWindow capture |
+| **ios** | **window** | **errors — Apple platform limit** | UIWindow.layer.render |
+
+If you're using `lxdev` to verify a layout change against an IME / keyboard scenario, you need `--scope screen` (the default everywhere except iOS). On iOS that case can only be verified manually because there's no CLI screen-capture tool — Apple does not expose one through `xcrun devicectl` today.
+
+**Multi-window** matters mainly on desktop. On macOS, `lx.surface({kind:'window'})` creates a separate NSWindow. Use `lxdev app windows` to enumerate; `--window <id>` selects one in `window` scope (the `id` is the platform-native window number — NSWindow.windowNumber on macOS, HWND on future Windows). Mobile platforms have a single foreground window and `--window` is ignored.
+
+#### How `screen` finds the right device
+
+`lingxia dev` set up an `adb forward` / `hdc fport` mapping when it created the session — the port forward is the only persistent record of which physical device this session belongs to. `lxdev` discovers the device at screenshot time by reading `adb forward --list` (or `hdc fport ls`) and matching its `ws_url` port against the host side of every forward. No device id is duplicated into session metadata, so there's nothing to keep in sync — the forward table is the source of truth.
+
+### `lxdev lxapp …`
+
+Manage lxapps running inside the session:
+
+`list`, `current`, `info`, `pages`, `page`, `eval`, `open`, `close`, `restart`, `uninstall`.
+
+`lxdev lxapp eval` runs JavaScript inside the lxapp's Logic runtime (AppService); useful for inspecting state or invoking actions without a UI round-trip.
+
+### `lxdev logs`
+
+Tail and filter the session log stream:
+
+```bash
+lxdev logs                                    # last 200 lines
+lxdev logs -f                                 # follow
+lxdev logs -f --level error                   # filter by level
+lxdev logs --source webview --grep CSP        # filter by source + text
+lxdev logs --path pages/home --json           # JSONL output
+```
+
+Levels: `verbose`, `debug`, `info`, `warn`, `error`.
+Sources: `native`, `webview`, `logic`, `web_view_console`, `lx_app_service_console`.
+
+---
+
+## Concurrency rules
+
+The whole design is built around "a human and one or more agents may be doing dev in parallel." The rules are:
+
+1. **`lingxia dev` refuses to start a second same-platform session** unless `--parallel` is passed. This is the primary defense — if you never trip this, you'll never have an ambiguous `lxdev` call.
+2. **`lxdev` refuses to act when ambiguity exists.** It will not silently pick a session for you; it prints the candidates and asks for a `--session` / `--platform`.
+3. **Stale sessions don't count.** Pruning happens in three places (`lingxia dev` startup, `lxdev sessions prune`, and `lxdev` itself when ambiguity forces it), so a hard-crashed `lingxia dev` won't keep blocking future runs.
+4. **`--parallel` is per-launch.** It does not persist; each subsequent `lingxia dev` for that platform must opt in again.
+
+---
+
+## Typical agent flow
+
+```bash
+# Discover what's available
+lxdev sessions
+
+# Single session, no ambiguity → zero-arg invocation
+lxdev browser open https://example.com
+lxdev browser eval --js "document.title"
+lxdev logs -f --level warn
+
+# Visual regression / what-does-the-user-see
+lxdev app windows                  # see all host windows
+lxdev app screenshot               # current focused window
+lxdev browser screenshot           # just the web content of the current tab
+
+# Two sessions running (e.g. ios + harmony) → disambiguate by platform
+lxdev --platform ios browser tabs
+lxdev --platform harmony logs --grep BridgeError
+
+# After a crash leaves residue
+lxdev sessions prune
+```
+
+---
+
+## Symptom router
+
+| Symptom | Fix |
+|---|---|
+| `No active dev session found` | Run `lingxia dev` in this project. |
+| `Multiple active dev sessions match` | Add `--session <prefix>` or `--platform <name>`. |
+| `All matching dev sessions are unreachable` | Run `lxdev sessions prune`, then start a fresh `lingxia dev`. |
+| `Existing <platform> dev session is already running` (from `lingxia dev`) | Stop the other one, or pass `--parallel` if you genuinely want two. |
+| `lxdev` connects but commands hang | The host app likely lost its bridge — restart `lingxia dev`. |
+
+For the underlying design rationale (why no daemon, why this specific file layout), see the project draft `docs/draft/dev-session-multi.md` in the LingXia repo.

package/skill/cli/reference.md

@@ -0,0 +1,481 @@
+# CLI Command Reference
+
+Complete reference for the `lingxia` command-line interface. This skill assumes the CLI is already installed and you are working inside a LingXia project. For first-time install and onboarding, see `docs/quick-start.md`.
+
+---
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--version`, `-V` | Print version |
+| `--help`, `-h` | Print help |
+
+---
+
+## Commands
+
+### `lingxia new`
+
+Create a new LingXia project.
+
+```bash
+lingxia new [name] [options]
+```
+
+**Arguments:**
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `name` | Project name | No (prompted if omitted) |
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --project-type <type>` | Project type: `native-app` or `lxapp` | prompted |
+| `-p, --platform <platforms>` | Target platforms (comma-separated): android, ios, harmony, all | prompted |
+| `--package-id <id>` | Package identifier (e.g., com.example.app) | prompted |
+| `--icon <path>` | Path to app icon (PNG, recommended 1024x1024) | none |
+| `-y, --yes` | Skip confirmation prompts | false |
+
+**Examples:**
+
+```bash
+# Interactive mode
+lingxia new
+
+# With project name
+lingxia new my-app
+
+# Non-interactive with all options
+lingxia new my-app -t native-app -p android,ios --package-id com.example.myapp -y
+
+# Create LxApp only
+lingxia new my-lxapp -t lxapp -y
+```
+
+---
+
+### `lingxia build`
+
+Build the project.
+
+```bash
+lingxia build [options]
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--release` | Release build (optimized) | false (debug) |
+| `--env <env>` | Build environment: `developer` (or `dev`), `preview`, `release` | `developer` |
+| `-f, --features <features>` | Rust features to enable (comma-separated) | none |
+| `--abis <abis>` | Android ABIs (comma-separated): `arm64-v8a`, `armeabi-v7a` | auto (`arm64-v8a`) |
+| `--macos-arch <arch>` | macOS build architecture: `arm64`, `x86_64` | host arch |
+| `--platform <platforms>` | Platforms to build (comma-separated) | all detected |
+| `--skip-native` | Skip native Rust library compilation | false |
+
+> **`--env` vs `--release`** — independent. `--env` chooses an environment slot (which determines the suffixed package id, the backend URL, and whether the launcher icon is badged); `--release` toggles the compiler's release profile. `lingxia build --env release --release` is the shippable combination. The CLI prints `ℹ Build env: <env> (default|--env)` on every build. See [App Project → Env versions](../app/project.md#environment-versions) for what each env produces.
+
+**Examples:**
+
+```bash
+# Development build (default: --env developer)
+lingxia build
+
+# Optimized release build for shipping
+lingxia build --env release --release
+
+# Preview build (side-by-side installable next to release)
+lingxia build --env preview
+
+# Build for specific platform
+lingxia build --platform android
+
+# Skip native compilation (use existing binaries)
+lingxia build --skip-native
+```
+
+When a host project has `lingxia.yaml`, `lingxia build` also prepares configured host assets. LxApp builds generate the Native client automatically when `lxapp.config.ts` contains `native`.
+
+---
+
+### `lingxia clean`
+
+Remove generated artifacts for the current project context.
+
+```bash
+lingxia clean
+```
+
+Context rules:
+
+- In a host app project with `lingxia.yaml`, cleans host outputs, generated host assets, platform build directories, configured bundle `dist/` directories, and native `target/`.
+- In an lxapp or lxplugin project, cleans local `dist/` or `dist-plugin/`, `node_modules/`, and LingXia view build cache.
+- In a standalone Apple Swift Package, such as runner development packages without `lingxia.yaml`, cleans `.build/` and `.lingxia/`.
+
+---
+
+### `lingxia package`
+
+Package release artifacts for publishing or delivery.
+
+```bash
+lingxia package [options]
+```
+
+`lingxia package` always performs a release package build.
+
+For native host projects, publishable Android artifacts are staged under
+`dist/android/`; macOS update zips are written under `dist/macos/`.
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--env <env>` | Build environment: `developer` (or `dev`), `preview`, `release` | `release` |
+| `-f, --features <features>` | Rust features to enable (comma-separated) | none |
+| `--abis <abis>` | Android ABIs (comma-separated): `arm64-v8a`, `armeabi-v7a` | auto (`arm64-v8a`) |
+| `--macos-arch <arch>` | macOS package architecture: `arm64`, `x86_64` | host arch |
+| `--platform <platforms>` | Platforms to package (comma-separated) | all detected |
+| `--skip-native` | Skip native Rust library compilation | false |
+| `--framework <framework>` | Override lxapp view framework detection: `react`, `vue`, `html` | auto-detect |
+| `--progress <mode>` | LxApp progress output mode: `task`, `plain` | default CLI output |
+
+**Examples:**
+
+```bash
+# Package the current project for publishing
+lingxia package
+
+# Package only macOS output
+lingxia package --platform macos
+```
+
+---
+
+### `lingxia dev`
+
+Development mode for both app and lxapp projects.
+
+```bash
+lingxia dev [options]
+```
+
+Behavior depends on the current project:
+
+- In an app project, `lingxia dev` builds, installs, launches the host app, and starts a local dev websocket for `lxdev`.
+- Android and Harmony dev sessions set reverse port forwarding so the device app can reach the local dev server.
+- iOS dev sessions embed a LAN dev websocket URL into the dev build; the iOS device must be able to reach the host Mac on the local network.
+- In a standalone lxapp project, `lingxia dev` builds the lxapp and launches LingXia Runner on macOS.
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --platform <platform>` | Target platform: `android`, `ios`, `macos`, `harmony` | auto-detect for app projects |
+| `-d, --device <id>` | Target device ID (required if multiple connected) | auto-detect |
+| `--release` | Release build (optimized) | false (debug) |
+| `--env <env>` | Build environment: `developer` (or `dev`), `preview`, `release` | `developer` |
+| `-f, --features <features>` | Rust features to enable (comma-separated) | none |
+| `--skip-native` | Skip native Rust library compilation | false |
+| `--abis <abis>` | Android ABIs (comma-separated): `arm64-v8a`, `armeabi-v7a` | auto (`arm64-v8a`) |
+| `--macos-arch <arch>` | macOS build architecture: `arm64`, `x86_64` (must match host for local app dev) | host arch |
+| `--framework <framework>` | Override lxapp view framework detection: `react`, `vue`, `html` | auto-detect |
+| `--progress <mode>` | LxApp progress output mode: `task`, `plain` | default CLI output |
+| `--reinstall` | Reinstall app by uninstalling existing one first (best effort) | false |
+
+**Examples:**
+
+```bash
+# App project: build, install, and launch
+lingxia dev
+
+# App project: target a specific device
+lingxia dev -d deviceid
+
+# Standalone lxapp project: build and launch Runner
+lingxia dev
+
+# Use release build
+lingxia dev --release
+```
+
+> **Note:** For standalone lxapp projects, `--device`, `--abis`, and non-macOS `--platform` are not supported. Runner currently launches locally on macOS.
+
+---
+
+### `lingxia install`
+
+Install the built app to a device.
+
+```bash
+lingxia install [options]
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-a, --artifact <path>` | Path to artifact file (APK/HAP) | auto-detected |
+| `-d, --device <id>` | Target device ID | auto-detect |
+| `--reinstall` | Reinstall app by uninstalling existing one first (best effort) | false |
+
+**Examples:**
+
+```bash
+# Install to default device
+lingxia install
+
+# Install specific artifact
+lingxia install -a ./build/app-debug.apk
+
+# Install to specific device
+lingxia install -d emulator-5554
+
+# Reinstall cleanly before install
+lingxia install --reinstall
+```
+
+---
+
+### `lingxia launch`
+
+Launch the installed app on a device.
+
+```bash
+lingxia launch [bundle_id] [options]
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-d, --device <id>` | Target device ID | auto-detect |
+| `-p, --platform <platform>` | Target platform | auto-detect |
+| `--restart` | Restart app by terminating an existing instance before launch (best effort) | false |
+
+**Examples:**
+
+```bash
+# Launch inferred app on default device
+lingxia launch
+
+# Launch specific app on a specific device
+lingxia launch com.example.app -d emulator-5554 -p android
+
+# Restart the app before launching
+lingxia launch --restart
+```
+
+> **Note:** `--restart` is currently supported for Android and iOS. HarmonyOS currently supports plain `launch` only.
+
+---
+
+### `lingxia icon`
+
+Generate or update app icons from a source image.
+
+```bash
+lingxia icon <icon_path> [options]
+```
+
+**Arguments:**
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `icon_path` | Path to source icon (PNG, recommended 1024x1024) | Yes |
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --platform <platform>` | Target platform | all from config |
+| `-b, --background-color <color>` | Background color for adaptive icons (hex) | #FFFFFF |
+
+**Examples:**
+
+```bash
+# Generate icons for all platforms
+lingxia icon logo.png
+
+# With custom background color
+lingxia icon logo.png -b "#1E88E5"
+
+# For specific platform only
+lingxia icon logo.png -p android
+```
+
+---
+
+### `lingxia publish`
+
+Publish a package to the API server.
+
+```bash
+lingxia publish --token <token> [options]
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--token <token>` | Bearer token (`LINGXIA_AUTH_TOKEN` env var also accepted) | required |
+| `--lingxia-server <url>` | LingXia server URL (falls back to `app.lingxiaServer` when available) | from config |
+| `--package-path <path>` | Path to the package file (`app` only) | auto |
+| `--platform <platform>` | App platform to publish: `android`, `macos` | required for multi-platform app projects |
+| `--release-type <type>` | Release channel: `release`, `preview`, `developer` (required for lxapp) | none |
+| `--framework <framework>` | Override lxapp view framework detection: `react`, `vue`, `html` | auto-detect |
+| `--progress <mode>` | LxApp progress output mode: `task`, `plain` | default CLI output |
+
+**Auto-detection:**
+
+| Project file | Target | ID source | Version source |
+|---|---|---|---|
+| `lxapp.json` | `lxapp` | `appId` | `version` |
+| `lxplugin.json` | `lxplugin` | `lxPluginId` | `version` |
+| `lingxia.yaml` | `app` | `app.lingxiaId` | `app.productVersion` |
+
+**Examples:**
+
+```bash
+# Set token once via env var
+export LINGXIA_AUTH_TOKEN=lx_dev_your_token
+
+# Publish lxapp (auto-detected from lxapp.json; packages current project automatically)
+lingxia publish --release-type developer
+
+# Publish preview build
+lingxia publish --release-type preview
+
+# Publish lxplugin (auto-detected from lxplugin.json)
+lingxia publish --lingxia-server http://localhost:8080
+
+# Publish Android host app package
+lingxia publish --platform android --token <token>
+```
+
+> **Note:** `lxapp` and `lxplugin` publish always package the current project first. Only `app` publish supports `--package-path`.
+
+---
+
+### `lingxia doctor`
+
+Check development environment setup.
+
+```bash
+lingxia doctor
+```
+
+**No options.**
+
+Prints pass/warn/fail checks for common + target platforms.
+
+Use `--platform` to scope checks:
+
+```bash
+lingxia doctor --platform android
+lingxia doctor --platform harmony
+```
+
+---
+
+### `lingxia ds`
+
+Interact with developer services (Apple, Harmony, etc.).
+
+```bash
+lingxia ds <platform> <command>
+```
+
+**Platforms:**
+
+| Platform | Description |
+|----------|-------------|
+| `apple`  | Apple Developer Services |
+
+---
+
+### `lingxia ds apple`
+
+Interact with Apple Developer Services.
+
+```bash
+lingxia ds apple <command>
+```
+
+**Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `teams` | List development teams |
+| `certificates` | List certificates |
+| `identifiers` | List bundle identifiers (App IDs) |
+| `devices` | List registered devices |
+| `profiles` | List provisioning profiles |
+
+**Examples:**
+
+```bash
+# List development teams
+lingxia ds apple teams
+
+# List certificates
+lingxia ds apple certificates
+
+# List bundle identifiers
+lingxia ds apple identifiers
+
+# List registered devices
+lingxia ds apple devices
+
+# List provisioning profiles
+lingxia ds apple profiles
+```
+
+> **Note:** Requires authentication via `lingxia auth login` with password mode.
+
+---
+
+## Environment Variables
+
+Required during build/dev for the listed platforms. One-time SDK installation is covered in `docs/quick-start.md`; the variables below must be present in your shell every time you build.
+
+| Variable | Used by | Description |
+|----------|---------|-------------|
+| `ANDROID_SDK_ROOT` | android | Android SDK root path |
+| `ANDROID_NDK_ROOT` | android | Android NDK path (e.g. `$ANDROID_SDK_ROOT/ndk/28.2.13676358`) |
+| `OHOS_NDK_HOME` | harmony | Harmony command-line tools SDK path |
+| `JAVA_HOME` | android | Java JDK path |
+
+If a platform build complains about missing tools, run `lingxia doctor --platform <p>` to see exactly what's missing.
+
+---
+
+## Configuration Files
+
+This reference focuses on commands and flags. File schemas live in the dedicated guides:
+
+| File | Purpose | Canonical guide |
+|---|---|---|
+| `lingxia.yaml` | Host app metadata, platform config, runtime-facing build inputs | [App Project](../app/project.md) |
+| `lxapp.json` | LxApp runtime metadata such as `appId`, `version`, and `pages` | [LxApp Development Guide](../lxapp/guide.md) |
+| `lxapp.config.ts` | LxApp build config such as aliases, view tooling, and `staticDirs` | [LxApp Development Guide](../lxapp/guide.md) |
+
+Quick reminders:
+
+- `lingxia.yaml` is the source of truth for host app build metadata.
+- `homeAppVersion` is generated into runtime `app.json`; you do not set it manually.
+- Storage/cache limits live under `storage`; set `storage.cacheMaxSizeMB` to `0` to disable usercache size enforcement.
+- When `splash` is configured, CLI requires a PNG source image and writes `splashTimeout` into runtime `app.json`.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |