docs: add host app development guide and update CLI help

Author: Hongwei-MB

README.md

@@ -115,6 +115,19 @@ Modulus provides a comprehensive command-line tool for module development and ma
 | `modulus uninstall <name>` | Uninstall a module |
 | `modulus list` | List installed modules |
 
+### Create Host App (plugin-based application)
+
+```bash
+# Avalonia desktop host app
+modulus new avaloniaapp -n MyApp
+
+# Blazor Hybrid (MAUI) host app
+modulus new blazorapp -n MyApp
+```
+
+**Notes:**
+- `blazorapp` is a **MAUI** host template and typically requires **Windows** to build.
+
 ### Create Module
 
 ```bash
@@ -236,6 +249,7 @@ modulus install ./output/MyExtension-1.0.0.modpkg
 - [Getting Started Guide](./docs/getting-started.md)
 - [CLI Reference](./docs/cli-reference.md)
 - [Module Development Guide](./docs/module-development.md)
+- [Host App Development Guide](./docs/host-app-development.md)
 - [OpenSpec Specifications](./openspec/specs/)
 - [Contributing Guide](./CONTRIBUTING.md)
 

README.zh-CN.md

@@ -115,6 +115,19 @@ Modulus 提供全面的命令行工具用于模块开发和管理。
 | `modulus uninstall <name>` | 卸载模块 |
 | `modulus list` | 列出已安装模块 |
 
+### 创建 Host App（插件式应用）
+
+```bash
+# Avalonia 桌面 Host App
+modulus new avaloniaapp -n MyApp
+
+# Blazor Hybrid（MAUI）Host App
+modulus new blazorapp -n MyApp
+```
+
+**注意：**
+- `blazorapp` 是 **MAUI** Host 模板，通常需要 **Windows** 才能稳定构建。
+
 ### 创建模块
 
 ```bash
@@ -236,6 +249,7 @@ modulus install ./output/MyExtension-1.0.0.modpkg
 - [快速入门指南](./docs/getting-started.zh-CN.md)
 - [CLI 参考](./docs/cli-reference.md)
 - [模块开发指南](./docs/module-development.md)
+- [Host App 开发指南](./docs/host-app-development.zh-CN.md)
 - [OpenSpec 规格说明](./openspec/specs/)
 - [贡献指南](./CONTRIBUTING.zh-CN.md)
 

docs/README.md

@@ -10,13 +10,14 @@ Welcome to the Modulus project documentation.
 
 ### Module Development
 - [Module Development Guide](./module-development.md) - In-depth module development guide
+- [Host App Development Guide](./host-app-development.md) - Create and customize plugin-based host apps
 - [CLI Reference](./cli-reference.md) - Complete CLI command reference
 
 ## 🔧 Reference
 
 ### OpenSpec Specifications
 - [Module Packaging](../openspec/specs/module-packaging/spec.md) - Module packaging format
-- [Manifest Format](../openspec/specs/vsixmanifest-format/spec.md) - extension.vsixmanifest format
+- [Module Template](../openspec/specs/module-template/spec.md) - includes extension.vsixmanifest conventions
 
 ### Architecture
 - [Project Context](../openspec/project.md) - Project overview and architecture
@@ -33,6 +34,7 @@ Common images and resources used across documentation are stored in the [Images]
 | Getting Started | [getting-started.md](./getting-started.md) | [getting-started.zh-CN.md](./getting-started.zh-CN.md) |
 | CLI Reference | [cli-reference.md](./cli-reference.md) | - |
 | Module Development | [module-development.md](./module-development.md) | - |
+| Host App Development | [host-app-development.md](./host-app-development.md) | [host-app-development.zh-CN.md](./host-app-development.zh-CN.md) |
 
 ## Contributing to Documentation
 

docs/cli-reference.md

@@ -1,6 +1,6 @@
 # Modulus CLI Reference
 
-The Modulus CLI (`modulus`) is a command-line tool for creating, building, packaging, and managing Modulus modules.
+The Modulus CLI (`modulus`) is a command-line tool for creating, building, packaging, and managing Modulus projects (modules and host apps).
 
 ## Installation
 
@@ -19,7 +19,7 @@ dotnet tool uninstall -g Agibuild.Modulus.Cli
 
 | Command | Description |
 |---------|-------------|
-| `modulus new` | Create a new module project |
+| `modulus new` | Create a new project (module or host app) |
 | `modulus build` | Build the module project |
 | `modulus pack` | Package the module for distribution |
 | `modulus install` | Install a module |
@@ -30,7 +30,7 @@ dotnet tool uninstall -g Agibuild.Modulus.Cli
 
 ## modulus new
 
-Create a new Modulus module project with all necessary files and structure.
+Create a new Modulus project with all necessary files and structure.
 
 ### Syntax
 
@@ -42,7 +42,7 @@ modulus new [<template>] -n <name> [options]
 
 | Argument | Required | Description |
 |----------|----------|-------------|
-| `<template>` | No | Template name: `module-avalonia` or `module-blazor` (default: `module-avalonia`) |
+| `<template>` | No | Template name: `avaloniaapp`, `blazorapp`, `module-avalonia`, `module-blazor` (default: `module-avalonia`) |
 
 ### Options
 
@@ -55,6 +55,8 @@ modulus new [<template>] -n <name> [options]
 
 ### Templates
 
+- `avaloniaapp`: Modulus host app (Avalonia)
+- `blazorapp`: Modulus host app (Blazor Hybrid / MAUI)
 - `module-avalonia`: Modulus module (Avalonia)
 - `module-blazor`: Modulus module (Blazor)
 
@@ -64,6 +66,12 @@ modulus new [<template>] -n <name> [options]
 # List templates
 modulus new --list
 
+# Create an Avalonia host app
+modulus new avaloniaapp -n MyApp
+
+# Create a Blazor Hybrid (MAUI) host app
+modulus new blazorapp -n MyApp
+
 # Create an Avalonia module (default template)
 modulus new -n MyModule
 
@@ -76,10 +84,13 @@ modulus new -n MyModule --force
 
 ### Generated Structure
 
+#### Module project (module-avalonia / module-blazor)
+
 ```
 MyModule/
 ├── MyModule.sln
 ├── .gitignore
+├── Directory.Build.props
 ├── extension.vsixmanifest
 ├── MyModule.Core/
 │   ├── MyModule.Core.csproj
@@ -93,6 +104,54 @@ MyModule/
     └── MainView.axaml.cs
 ```
 
+#### Host app project (avaloniaapp / blazorapp)
+
+```
+MyApp/
+├── MyApp.sln
+├── .gitignore
+├── Directory.Build.props
+└── MyApp.Host.Avalonia/ (or MyApp.Host.Blazor)
+    ├── appsettings.json
+    └── ... host entrypoint + UI files ...
+```
+
+**Notes:**
+- `blazorapp` is a **MAUI** host template and typically requires **Windows** to build.
+
+#### Host app details
+
+**Avalonia host app (`avaloniaapp`)**
+
+- **Project**: `MyApp.Host.Avalonia/`
+- **Typical entrypoint**: `Program.cs`
+- **Typical UI**: `App.axaml`, `MainWindow.axaml`
+- **Build & run**:
+
+```bash
+cd MyApp
+dotnet build -c Release
+dotnet run --project MyApp.Host.Avalonia -c Release
+```
+
+**Blazor Hybrid (MAUI) host app (`blazorapp`)**
+
+- **Project**: `MyApp.Host.Blazor/`
+- **Typical entrypoint**: `MauiProgram.cs` + platform entry under `Platforms/`
+- **Build prerequisites**:
+  - Windows machine
+  - .NET MAUI workload installed (for example: `dotnet workload install maui`)
+- **Build & run**:
+
+```bash
+cd MyApp
+dotnet build -c Release
+dotnet run --project MyApp.Host.Blazor -c Release
+```
+
+See also:
+- [`docs/host-app-development.md`](./host-app-development.md)
+
 ---
 
 ## modulus build
@@ -217,8 +276,7 @@ modulus install <source> [options]
 
 Modules are installed to:
 - **Windows**: `%APPDATA%\Modulus\Modules\{ModuleId}\`
-- **macOS**: `~/Library/Application Support/Modulus/Modules/{ModuleId}/`
-- **Linux**: `~/.local/share/Modulus/Modules/{ModuleId}/`
+- **macOS/Linux**: `~/.modulus/Modules/{ModuleId}/`
 
 ### Examples
 
@@ -306,7 +364,7 @@ modulus list --verbose
 # Installed Modules:
 #   MyModule v1.0.0
 #     ID: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
-#     Path: /Users/you/.local/share/Modulus/Modules/MyModule
+#     Path: ~/.modulus/Modules/MyModule
 #     Installed: 2025-12-14 10:30:00
 ```
 
@@ -324,11 +382,11 @@ modulus list --verbose
 
 | Variable | Description |
 |----------|-------------|
-| `MODULUS_HOME` | Override default Modulus data directory |
+| `MODULUS_CLI_DATABASE_PATH` | Override CLI database path (primarily for tests/automation) |
+| `MODULUS_CLI_MODULES_DIR` | Override CLI modules directory (primarily for tests/automation) |
 
 ## See Also
 
 - [Getting Started](./getting-started.md)
 - [Module Development Guide](./module-development.md)
-- [Manifest Format](./manifest-format.md)
 

docs/getting-started.md

@@ -4,7 +4,7 @@ This guide will walk you through setting up your development environment, creati
 
 ## Prerequisites
 
-- **.NET 9 SDK** or later
+- **.NET 10 SDK** or later
 - **IDE**: Visual Studio 2022, JetBrains Rider, or VS Code
 - **Git** (optional, for cloning the repository)
 
@@ -77,6 +77,8 @@ This creates a module with the following structure:
 MyFirstModule/
 ├── MyFirstModule.sln              # Solution file
 ├── .gitignore
+├── Directory.Build.props          # Generated to reference Modulus assemblies from the CLI installation
+├── extension.vsixmanifest         # Module manifest
 ├── MyFirstModule.Core/            # Core logic (host-agnostic)
 │   ├── MyFirstModule.Core.csproj
 │   ├── MyFirstModuleModule.cs     # Module entry point
@@ -191,27 +193,26 @@ The manifest file is automatically generated by the template and contains:
 
 | Command | Description |
 |---------|-------------|
-| `modulus new <name>` | Create a new module project |
+| `modulus new` | Create a new project (module or host app) |
 | `modulus build` | Build the module in current directory |
 | `modulus pack` | Build and package as .modpkg |
 | `modulus install <source>` | Install a module from .modpkg or directory |
 | `modulus uninstall <name>` | Uninstall a module |
 | `modulus list` | List installed modules |
 
-### modulus new
+### Create a Host App (plugin-based application)
 
 ```bash
-modulus new MyModule [options]
+# Avalonia desktop host app
+modulus new avaloniaapp -n MyApp
 
-Options:
-  -t, --target <avalonia|blazor>  Target host platform
-  -d, --display-name <name>       Display name in menus
-  -p, --publisher <name>          Publisher name
-  -i, --icon <icon>               Menu icon (e.g., Folder, Home, Settings)
-  --output <path>                 Output directory
-  --force                         Overwrite existing files
+# Blazor Hybrid (MAUI) host app
+modulus new blazorapp -n MyApp
 ```
 
+**Notes:**
+- `blazorapp` is a **MAUI** host template and typically requires **Windows** to build.
+
 ### modulus build
 
 ```bash
@@ -253,8 +254,7 @@ Options:
 
 - [Module Development Guide](./module-development.md) - Deep dive into module development
 - [CLI Reference](./cli-reference.md) - Complete CLI command reference
-- [Manifest Format](./manifest-format.md) - Understanding extension.vsixmanifest
-- [UI Components](./ui-components.md) - Available UI components and styling
+- [Host App Development Guide](./host-app-development.md) - Create and customize plugin-based host apps
 
 ## Troubleshooting
 

docs/getting-started.zh-CN.md

@@ -4,7 +4,7 @@
 
 ## 环境要求
 
-- **.NET 9 SDK** 或更高版本
+- **.NET 10 SDK** 或更高版本
 - **IDE**: Visual Studio 2022、JetBrains Rider 或 VS Code
 - **Git**（可选，用于克隆仓库）
 
@@ -77,6 +77,8 @@ cd MyFirstModule
 MyFirstModule/
 ├── MyFirstModule.sln              # 解决方案文件
 ├── .gitignore
+├── Directory.Build.props          # 由 CLI 生成，用于从 CLI 安装目录引用 Modulus 程序集
+├── extension.vsixmanifest         # 模块清单
 ├── MyFirstModule.Core/            # 核心逻辑（主机无关）
 │   ├── MyFirstModule.Core.csproj
 │   ├── MyFirstModuleModule.cs     # 模块入口点
@@ -191,27 +193,26 @@ dotnet run --project path/to/Modulus/src/Hosts/Modulus.Host.Avalonia
 
 | 命令 | 描述 |
 |------|------|
-| `modulus new <name>` | 创建新模块项目 |
+| `modulus new` | 创建新项目（模块或 Host App） |
 | `modulus build` | 在当前目录编译模块 |
 | `modulus pack` | 编译并打包为 .modpkg |
 | `modulus install <source>` | 从 .modpkg 或目录安装模块 |
 | `modulus uninstall <name>` | 卸载模块 |
 | `modulus list` | 列出已安装模块 |
 
-### modulus new
+### 创建 Host App（插件式应用）
 
 ```bash
-modulus new MyModule [options]
+# Avalonia 桌面 Host App
+modulus new avaloniaapp -n MyApp
 
-选项:
-  -t, --target <avalonia|blazor>  目标主机平台
-  -d, --display-name <name>       菜单中显示的名称
-  -p, --publisher <name>          发布者名称
-  -i, --icon <icon>               菜单图标（如 Folder, Home, Settings）
-  --output <path>                 输出目录
-  --force                         覆盖已有文件
+# Blazor Hybrid（MAUI）Host App
+modulus new blazorapp -n MyApp
 ```
 
+**注意：**
+- `blazorapp` 是 **MAUI** Host 模板，通常需要 **Windows** 才能稳定构建。
+
 ### modulus build
 
 ```bash
@@ -251,10 +252,9 @@ modulus install <source> [options]
 
 ## 下一步
 
-- [模块开发指南](./module-development.zh-CN.md) - 深入了解模块开发
-- [CLI 参考](./cli-reference.zh-CN.md) - 完整的 CLI 命令参考
-- [清单格式](./manifest-format.zh-CN.md) - 理解 extension.vsixmanifest
-- [UI 组件](./ui-components.zh-CN.md) - 可用的 UI 组件和样式
+- [模块开发指南](./module-development.md) - 深入了解模块开发（英文）
+- [CLI 参考](./cli-reference.md) - 完整的 CLI 命令参考（英文）
+- [Host App 开发指南](./host-app-development.zh-CN.md) - Host App 创建与定制（中文）
 
 ## 故障排除