@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.68

package/README.en.md

@@ -1,311 +1,156 @@
 # @h-ai/cli
 
-[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md)
 
-[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+[Framework home](../../README.en.md)
 
-For creation, traditional/AI-first development, compilation, packaging, deployment, and upgrades, follow the [complete usage guide](../../docs/usage/README.en.md). This page provides detailed CLI and template references.
+## Introduction
 
-> hai Agent Framework CLI: interactive project scaffolding and code generation.
+Generated projects enable `zh-CN`, `en-US` and `ja-JP` by default. Interactive setup can select Japanese as the default; fullstack can restrict locales through `fullstack.i18n.locales`. CLI messages select Chinese, English or Japanese using `HAI_CORE_DEFAULTLOCALE` → `LC_ALL` → `LC_MESSAGES` → `LANG`.
 
-`pnpm build` / `hai build` compiles source by default. Use `pnpm build --target docker` to build/export app + optional Web images (Podman first, Docker fallback), or `pnpm build --target desktop --platform windows|linux|macos` for Tauri on the matching host. Build does not select deployment environments. `hai deploy` consumes existing artifacts and uploads one Compose tar; `--bundle-only --output release.tar` generates a manual-transfer bundle without SSH. Fullstack `pnpm run deploy --env test` publishes API/Web together. See [deploy usage and offline prerequisites](../deploy/README.en.md). Test artifacts are cleaned in finally/teardown, including failures.
+Use `hai` to create applications, add modules, generate starter code, build and deliver releases. It supports SvelteKit, independent APIs and separate frontend/backend workspaces. Follow the [usage guide](../../docs/usage/README.en.md) for the complete workflow.
 
-## Capabilities
+## Core features
 
-`hai deploy` exits nonzero on missing modules/configuration, credential loading, scanning, initialization, deployment, or closure failures. Scripts must check the exit code; only complete deployment success can unlock subsequent steps.
+- Create admin, website, H5, API, mobile or fullstack applications.
+- Add modules, configuration and AI guidance to existing projects.
+- Generate starter pages, components, endpoints, models and migrations.
+- Build selected images, deliver complete offline bundles or update selected services.
 
-- **Project creation**: guided creation of SvelteKit apps, Svelte 5 mobile/desktop frontends, and hai backends.
-- **Module addition**: incrementally enable modules in an existing project with dependency resolution.
-- **Configuration initialization**: validate completeness and create missing configuration files.
-- **Code generation**: pages, components, API endpoints, data models, and migrations.
-- **Templates**: minimal / default / full / custom project templates.
-- **Feature composition**: enable IAM, DB, AI, Storage, Crypto, and more as needed.
-- **API service scaffolding**: compose contracts/procedures with `@h-ai/api-contract` + `@h-ai/serv`, consumed through the `@h-ai/api-client` typed client.
-- **Dependency resolution**: selecting features automatically includes their dependencies (for example, IAM adds Crypto).
-
-## AI usage guidance
-
-Claude Code v2.1.277 and later can also read root `AGENTS.md` directly when no higher-priority project CLAUDE file overrides it and the built-in support is enabled. The single-line `@AGENTS.md` bridge supports older or disabled sessions without duplicating instructions or requiring a `.claude/` directory. See [AGENTS.md support](https://code.claude.com/docs/en/memory#agentsmd).
-
-The CLI copies complete selected skill directories from `templates/skills/` into the generated project's `.agents/skills/`. `SKILL.md` defines boundaries and task navigation; `reference.md`/`guide.md` hold on-demand examples. Do not copy only the entry file. AGENTS.md holds application constraints and Claude/Copilot bridge files reference it. Template changes must sync relevant repository skills. Generation tests verify delivery of reference files.
-
-Every application type includes `hai-spec-review` to review requirements and designs before generation: completeness, ambiguity, technical/framework correctness, and consistent naming. It reports located issues with concrete corrections and declares generation readiness only when issues are resolved and evidence is sufficient. `hai init` / `hai add` also backfill this workflow skill while preserving custom files.
-
-Business behavior follows the user's current explicit requirements and designated requirements/design documents. Template AGENTS, README, skills, generated code and tests provide adjustable defaults for roles, permissions, workflows, limits and architecture. Review lists differences as template adaptations rather than requirements defects; authorized implementation updates conflicting code, tests and outdated guidance. Installed public API contracts, server authorization, resource isolation, input validation and credential protection still apply. Existing projects must merge this guidance explicitly; `hai init` preserves existing files.
-
-After review, the separate `hai-spec-implement` skill handles implementation from documents. Every application includes it, and `hai init` / `hai add` backfill its complete resources. AI splits work by independently verifiable features and actual dependencies, using `docs/task-list.md` and `docs/tasks/<id>-<slug>.md` by default. Each task uses its own Git branch, TDD, quality gates and a local merge; records are marked complete after the actual merge commit and integration checks. Rework keeps the same task ID, file and branch, adding a new cycle linked to prior evidence. This uses Markdown, Git and existing development/test skills, with no new runtime dependency or workflow engine. Requests can plan only, implement a document, execute T003, or repair and merge T002. Planning does not start implementation; selected tasks require completed dependencies, and remote actions follow the user's authorization.
-
-After committing requirements/design changes, ask: “I updated docs/requirements.md and docs/design.md; please update the implementation.” The skill records the accepted document SHA, fixed target document SHA and accepted implementation SHA separately in the existing task list. It compares the complete document set, including additions, deletions, renames and related effects, then updates existing tasks or creates new ones for branch-based testing and merging. It advances the baseline only after all differences are handled and overall acceptance passes; interrupted or partial work retains the old baseline. Missing baselines require historical evidence or a coverage review. See [document changes and baselines](templates/skills/hai-spec-implement/changes.md). `hai init` / `hai add` backfill the new reference; existing entrypoints, workflows and task templates still need to be merged against the updated templates.
-
-For everyday feature additions, changes and fixes, `AGENTS.md` routes to `hai-app-create/SKILL.md` and `development.md`. Map requirements to existing framework features, configuration and extension points before implementing against the installed package's exports and types. Reuse applicable capabilities and explain concrete gaps; do not install unrelated dependencies to increase module coverage. Codex uses `.agents/skills/` and the project root's persistent `AGENTS.md` rules.
-
-Tool entry points share one set of rules and skills: Codex/Cursor use AGENTS and `.agents/skills/`; Copilot's `.github/copilot-instructions.md` only references the shared `AGENTS.md`, with application-specific rules maintained there; OpenCode's opencode.json references the shared rules directly through `instructions: ["AGENTS.md"]`. Claude Code's root CLAUDE.md contains only `@AGENTS.md`; task navigation in the shared rules leads to skill bodies and references in `.agents/skills/` as needed. The CLI does not create `.claude/`, duplicate skills or require symlinks. This setup does not register native Claude skills or `/skill` commands; existing Claude settings and skills are preserved. Sources: [Claude project instructions](https://code.claude.com/docs/en/memory), [Claude native skills](https://code.claude.com/docs/en/skills), [Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills), [OpenCode](https://docs.opencode.ai/docs/skills/), [Cursor](https://cursor.com/docs/skills).
-
-Codex discovers `.agents/skills/` natively and selects skills as needed. Invoke `$hai-app-create`, `$hai-app-review`, or another skill explicitly when useful; entry points and references remain on demand. No additional `.codex/skills` tree or Copilot settings are required. Sources: [Codex skills](https://learn.chatgpt.com/docs/build-skills), [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
-
-Generated projects share `eslint-rules.js`. Lint rejects explicit `any`, console calls, unexplained suppressions, double unknown assertions, internal framework source imports and writes to known sensitive localStorage keys. A necessary third-party workaround requires a documented local exception. Static rules do not prove authorization, input safety, transaction behavior or log redaction; verify those through tests and review.
-
-For existing projects, update the CLI and run `hai init` to fill missing workflow skills, resources and entry files. Existing files are preserved, including AI rules when using `--force`. Merge existing entry files, skills, ESLint configuration and scripts against a newly generated project, and restore missing .npmrc/.gitignore files; filling missing files does not upgrade old rules. Before release, use the CLI built from this repository to create the comparison project and keep unpublished capabilities separate from installed package capabilities.
-
-Before writing AI files, the CLI resolves existing file and directory links. Shared skills and project bridges must stay inside the project; external targets stop the write. Existing `.claude/` directories and links are outside generation; `hai init` / `hai add` do not modify or delete their contents.
-
-Delivery checks cover both the package archive and generated projects. Source `.npmrc` / `.gitignore` templates use a `.hbs` suffix to avoid packaging exclusions; generation restores their normal names and preserves dependency layout and sensitive-artifact ignore rules. An archive regression verifies every template is in the `.tgz`, beyond creation from the source checkout.
-
-## Quick start
-
-Requires Node.js 22.22.2+ / 24.15.0+ / 26+; generated root projects and workspace packages declare the same minimum.
+## Getting started
 
 ### Install the CLI
 
-First install `@h-ai/cli` globally. It provides the `hai` command; the quick-start examples below assume this installation is complete.
+Use Node.js matching `engines` (`^22.22.2 || ^24.15.0 || >=26.0.0`) and pnpm 12.11.2. In PowerShell use `pnpm.cmd`.
 
-```bash
+```sh
 pnpm add -g @h-ai/cli
 hai --version
+hai --help
 ```
 
-In PowerShell, use `pnpm.cmd add -g @h-ai/cli`. To update an installed CLI to the current published version, run the same installation command. Check available commands with `hai --help`. For unpublished templates, follow the local development section below to build and run the CLI from this repository.
-
-### Create a project
-
-Generated `@h-ai/*` dependencies are pinned to the CLI version; pnpm references that exact version through `catalog:`. Upgrade framework packages together and verify the versions resolved in the lockfile.
+Generated framework dependencies use the exact CLI version. Installation failures show the command, exit code and output, leaving files available for retry. To test unpublished source, use the local development commands below.
 
-In your application repository, ask the AI to "upgrade Hai-framework to the latest version". Project instructions route to [hai-framework-sync](templates/skills/hai-framework-sync/SKILL.md) to check published versions online, compare cumulative changes and application impact, request decisions or blocker resolution when needed, then migrate dependencies/code/configuration, merge skills and AI instructions, and validate. Comparison-only requests do not modify the application. `hai init` / `hai add` backfill the upgrade skill, adjacent resources and referenced CI/PR workflow skills even when the original template cannot be identified. Existing files are preserved; older skills and routing still need to be merged.
+### Create an application
 
-Creation messages are written directly to the terminal. Installation failures display the package manager command, exit code and stdout/stderr, and retain generated files for a retry from the project directory. The `prebuild-install@7.1.3` deprecation warning comes from the upstream `better-sqlite3` installer dependency. That warning alone does not fail installation; do not override or remove the native installer to hide it.
-
-```bash
-# 交互式创建（推荐）
-hai create my-admin-app
-
-# 指定模板与功能
-hai create my-app -t full
-hai create my-app -t custom -f iam,db,ai
+```sh
+hai create my-app --type fullstack --frontends web --yes
+cd my-app
+pnpm dev
 ```
 
-Interactive steps:
+Omit options for interactive choices, or use `--yes` for defaults. Installation and Git initialization are enabled; disable them with `--no-install` / `--no-git`. Deployment tools are development dependencies by default; use `--no-deploy` to omit them.
 
-1. Enter the project name.
-2. Choose a template (minimal / default / full / custom).
-3. Select feature modules (custom template).
-4. Choose whether to include example code.
-5. Choose a package manager (pnpm / npm / yarn).
-6. Choose whether to install dependencies.
-7. Choose whether to initialize Git.
+### Project templates
 
-### Add modules
+| Type                       | Generated project                                                               |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `admin` / `website` / `h5` | SvelteKit admin, website or mobile web application                              |
+| `api`                      | Shared contract and API service in a pnpm workspace                             |
+| `mobile-app`               | Svelte + Vite + Capacitor                                                       |
+| `fullstack`                | Contract, API, shared UI and selected Web/App/Desktop; miniapp is a placeholder |
 
-```bash
-# 交互式选择
-hai add
+Use `--template minimal|default|full|custom` for module presets and `--features iam,db,...` for application modules. Fullstack keeps IAM, database, cache, crypto, storage and audit for its default management UI. It does not install AI/ONNX/CUDA by default.
 
-# 指定模块
-hai add iam
-hai add storage
-```
+A standalone `mobile-app` with IAM or crypto installs frontend crypto and enables encrypted typed-client transport by default. Without crypto, a deliberate plaintext API remains supported. Use `PUBLIC_API_TRANSPORT=off` only with a matching plaintext service; `PUBLIC_API_KEY_EXCHANGE_PATH` overrides the public exchange subpath. A failed handshake never falls back to plaintext, and server private keys never enter the client. Cleanup closes client transport before crypto initialized by that client.
 
-Add modules incrementally to an existing project. The CLI updates `package.json`, creates configuration, and resolves dependencies.
+### Fullstack mini administration
 
-### Initialize/validate configuration
+Includes user management, roles, audit logs, avatars, personal settings, themes, languages, onboarding and help. Sign in as `admin` using the random `HAI_ADMIN_DEFAULT_PASSWORD` in root `.env.local`. Existing users are not reset. Adapt the sample business rules as needed; authorization remains on the server.
 
-```bash
-# 校验配置完整性，补全缺失配置
-hai init
+### Application configuration and display
 
-# 强制重新生成所有配置
-hai init --force
-```
-
-### Code generation
+See `.env.example` for settings. Commit shared `.env` and `.env.dev/.env.test/.env.prod`; keep private overrides in `.env.local`. Precedence is process environment > local private file > selected environment > shared base. API projects keep these files in the service directory; fullstack uses the root. See the [usage guide](../../docs/usage/README.en.md) for YAML, environment overrides and application metadata.
 
-Names must start with a letter and contain only letters, digits, hyphens, or underscores; paths are rejected. All outputs are preflighted and overwrites rejected by default; only explicit `--force` replaces files. Outputs and symlink targets must stay in the working directory.
+### Existing projects and code generation
 
-Page/API generators target SvelteKit; components use Svelte 5 children snippets. APIs use `kit.handler` and Zod validation. Migrations export explicit `up()` / `down()`; initialize `reldb` before calling and check HaiResult afterward. This is not an automatic migration runner. `down()` deletes tables and requires application confirmation before execution.
+Creating or adding AI also installs reldb and vecdb. Generated startup initializes database → vector store → AI and checks reverse cleanup failures. Production profiles select PostgreSQL (or the chosen MySQL), Redis, S3 and Qdrant for enabled modules, using Compose DNS names `db/cache/storage/vecdb`. Inject database/cache passwords, S3 credentials, model keys and protected Qdrant keys privately. Override internal addresses when running outside Compose. Production Reach intentionally rejects an empty provider array until a real `HAI_REACH_PROVIDERS` JSON secret is supplied. `hai add` preserves configured production values, adds missing fields, and requires integration into the existing application entry point.
 
-```bash
-# 交互式生成
+```sh
+hai add storage
+hai init
 hai generate
-
-# 指定类型
-hai generate page users
+hai generate page dashboard
 hai generate component UserCard
-hai generate api users
-hai generate model user
-hai generate migration add-users
-
-# 快捷命令
-hai g:page dashboard
-hai g:component StatusBadge
-hai g:api orders
-hai g:model order
-```
-
-## Project templates
-
-| Template  | Description | Included features                                         |
-| --------- | ----------- | --------------------------------------------------------- |
-| `minimal` | Minimal     | Basic SvelteKit/hai skeleton (Svelte 5 + Vite on mobile)  |
-| `default` | Default     | IAM + DB + Cache + Crypto                                 |
-| `full`    | Full        | All business modules + API Service / contract integration |
-| `custom`  | Custom      | Choose as needed                                          |
-
-## Fullstack mini administration
-
-The default workspace includes `@h-ai/ui/guide` onboarding and help: first-use invitations, element tours, searchable instructions, manual replay and profile setup tours. Web/App/Desktop share content and translations; Web uses Cookies and native WebViews use localStorage, isolated by user and tour version. Extend the shared guide-store and data-guide anchors; see the [guide skill](templates/skills/hai-ui/guide.md).
-
-`--type fullstack` generates an administration workspace with IAM, reldb, cache, audit, storage and crypto by default. The required management modules remain enabled even with the minimal preset. `--frontends` selects Web, Capacitor App and Tauri Desktop; miniapp remains a documentation placeholder excluded from runtime and builds.
-
-```powershell
-hai create mini-admin --type fullstack --frontends web,app,desktop
-cd mini-admin
-pnpm.cmd install
-pnpm.cmd dev
+hai generate api orders
+hai generate model order
+hai generate migration add-orders
 ```
 
-Add `--features deploy` to install a matching project-local `@h-ai/deploy` development dependency for automated deployment. Fullstack does not install AI/ONNX/CUDA by default. Image builds download the official SQLite prebuild matching the driver version, Node ABI, architecture and libc, retry and validate it, then reuse the cache. No compiler toolchain is preinstalled; missing binaries or network failures stop the build.
+`hai add` resolves module dependencies and fills configuration. `hai init` fills missing configuration and AI files while preserving custom content. `--force` regenerates module configuration; review the diff before using it.
 
-The CLI generates a root `.env.local` with a unique random strong `HAI_ADMIN_DEFAULT_PASSWORD`, so `dev` / `start` work directly. Sign in as `admin` using that password; an environment variable with the same name overrides it. Passwords follow `_iam.yml` policy, with a default minimum of 8 characters. Startup logs include the specific validation reason and error code when a password violates the policy. Once users exist, the variable does not reset accounts or passwords. Git and container builds ignore `.env.local`, while `.env.example` contains only a placeholder. Set a separate password in each deployment environment.
+Pages use SvelteKit file routes. APIs use either SvelteKit routes or the target serv application's shared contract/procedure structure. API/fullstack roots select a unique backend automatically; use `--workspace <package-name-or-relative-path>` when multiple applications apply, or enter the target workspace. Plain Vite page/API combinations are rejected. Serv does not accept `--output`; SvelteKit route output must stay inside `src/routes`; custom `kit.files` layouts are rejected rather than guessed. SvelteKit API targets must already install `@h-ai/kit` and `zod`. Serv updates only existing aggregation points with `@hai-generator` markers; unknown structures require manual integration. Names cannot contain paths. Existing files require `--force`, which never replaces registered business domains. Files are checked as one batch and rolled back on write failure. Migrations only generate up/down functions; inspect data effects before running them.
 
-- Administrators can search, paginate, create, edit, enable, disable and delete users and upload avatars. The server protects the current administrator and rechecks authorization inside a mutation lock so concurrent actions cannot remove every administrator's access.
-- Initial roles are `admin` / `user`. The role page shows member counts and edits descriptions; the user page assigns roles. By default, ordinary users only access personal settings, and the server rejects direct management API calls from them. Adapt these business rules to actual requirements.
-- The audit page filters by action, resource and date. Successful login, logout, password changes and management writes produce audit records without passwords, tokens or avatar contents.
-- Personal settings cover profile, avatar, language, theme and password changes. Preferences are stored in IAM user metadata. Avatars accept PNG/JPEG/WebP up to 512 KiB; the server validates image contents and generates the storage key.
+CLI messages support Chinese, English and Japanese. The first nonempty value from `HAI_CORE_DEFAULTLOCALE`, `LC_ALL`, `LC_MESSAGES` and `LANG` selects the initial language. Regional `en`/`zh`/`ja` variants use the existing dictionaries; `C`/`POSIX` use English. Unknown languages preserve the current core locale, which defaults to Chinese. In PowerShell, run `$env:HAI_CORE_DEFAULTLOCALE='en-US'` before `hai generate`. Internal commands also honor in-process locale changes via `core.i18n.setGlobalLocale('en-US')`. Omitting a type or name opens a prompt; cancellation writes no files. Generated Chinese code comments and user-supplied names remain unchanged.
 
-The typed api-client and serv crypto transport encrypt JSON business requests, login and refresh in both directions. Web uses an in-memory access token and an HttpOnly refresh Cookie. Native App uses Capacitor secure TokenStorage; native Desktop stores tokens only in memory and requires login after restart. The native refresh body channel verifies the client identifier, explicit transport header and trusted Origin; browser previews use Cookie mode. Public avatars are binary image resources restricted by a whitelist.
+Prompts, validation, module/template names, descriptions and completion messages in `create`, `add`, `init` and `generate` use the current CLI locale. Catalog labels are translated when read, including after an in-process locale change. The CLI locale is separate from the generated application’s `core.defaultLocale`; generated Chinese README text, configuration/code comments, user input and original external-tool diagnostics remain unchanged.
 
-Web/App/Desktop share one `AdminWorkspace`, management store and typed client. Current-user and refresh routes use the framework's default IAM procedures; theme caching and DOM updates use `@h-ai/ui/theme`. Application code composes initial roles, self-protection, avatars and auditing as example business rules that can change with actual requirements.
+### Build and deploy
 
-Default SQLite, local storage and memory cache suit a single-instance mini administration service. Management writes support one writer instance. Multiple read instances require shared database, storage, Redis cache and sticky transport sessions; all management writes must still reach the same writer. Redis alone does not provide atomic last-administrator protection across arbitrary writers. Generated root scripts provide typecheck, lint, build, test and test:e2e; Capacitor/Tauri delivery additionally requires the appropriate native build and packaging.
+Database connections are validated against the selected backend’s public schema before saving. MySQL `ssl` accepts only `false` or a strict TLS object; `{}` verifies the certificate chain and DNS identity by default. PostgreSQL keeps its modes. CLI bundles the pure schemas and Zod, so validation needs no database package or driver in the target application; running that application still requires its dependencies. Deployment still requires an installed, resolvable `@h-ai/deploy` (a development dependency in generated projects).
 
-## Application configuration and display
+`pnpm build` compiles sources. Each image has its own Dockerfile in `images/`, selected through `hai.build.json`. `--images` selects build outputs; `--services` selects deployed services. Automatic engine detection prefers reachable Podman, then Docker. Downloads, installation and production dependency packaging share package and SQLite driver caches to avoid downloading them again.
 
-Each project documents its variables, enums and bounds in `.env.example`. The [root catalog](../../.env.example) covers all modules; the [environment configuration](templates/skills/hai-app-create/development.md#环境配置) explains mode loading and common scripts.
+The default container supports CPU workloads or remote AI services without downloading extra GPU runtimes. To use the deployment host's GPU, customize the image and container runtime settings.
 
-Every generated `.gitignore` includes `**/data/`, covering runtime data and `.gitkeep` at every workspace depth. Runtime code creates the required directories.
-
-Fullstack always includes 13 `.yml` files in `packages/<project>-serv/config/`: `_core`, `_serv`, `_db`, `_cache`, `_iam`, `_storage`, `_audit`, `_reach`, `_ai`, `_vecdb`, `_payment`, `_scheduler`, and `_deploy`. Used modules retain working defaults; unused modules, optional fields, and alternative providers remain as comments. `.env.example` also includes commented credentials for unused modules. Module choices entered during creation are preserved.
-
-To extend the service, install the required package in its workspace, validate with the public schema, initialize it and close it in reverse order in `src/server/runtime.ts`, then uncomment the relevant configuration. For a fully commented file, remove one outer comment layer first and enable optional blocks as needed. A configuration file alone does not connect business features. Replace connection blocks when switching SQLite/Redis/S3 or Reach providers, keeping each provider name unique. `crypto.init()` takes no configuration and datapipe provides pure functions; neither gets an invented YAML file.
-
-Every template reads `name`, `version`, `env`, `defaultLocale` and `logging` from `_core.yml`, obtains metadata through `core.config` and uses `core.logger`. Single-app configuration lives in `config/`, API workspace configuration in `apps/<project>-service/config/`, and fullstack configuration in `packages/<project>-serv/config/`. YAML controls log level and format; initialization does not replace them with a fixed `logging` option.
-
-Core environment overrides include `HAI_CORE_NAME`, `HAI_CORE_VERSION`, `HAI_CORE_ENV` and `HAI_CORE_LOGGING_LEVEL`; a whole `HAI_CORE` override follows parent-node precedence. Restart services after server configuration changes. Containers explicitly set `HAI_CORE_ENV=production`, which enables production security policy.
-
-Leaf overrides apply only to existing YAML paths: uncomment the key first, or replace the whole object with `HAI_DB`, `HAI_CACHE`, etc. CamelCase remains one segment: `connectTimeout` maps to `HAI_CACHE_CONNECTTIMEOUT`. Locale lists belong in each frontend/shared `project.inlang/settings.json`; `_core.yml` specifies only the default locale.
-
-The automatically generated fullstack `.env.local` enables only the initial administrator password and `PUBLIC_API_BASE`. Module overrides remain commented so YAML supplies defaults. Explicitly uncomment environment overrides when needed, and check existing overrides when editing YAML.
-
-SvelteKit server layouts expose only whitelisted public metadata such as name, version, environment and default locale. Standalone mobile-app Vite configuration parses YAML through core in the Node build process and injects public values plus browser logging level/format; YAML or override changes require a rebuild. Fullstack frontends obtain public server metadata through encrypted `app.info`. No template exposes complete core/module configuration, secrets or log-redaction context to the browser.
-
-## Environment-specific deployment
-
-Run `hai deploy --env test` to check `.env.test` first, then choose defaults, custom connections or keep unchanged for each middleware. `--yes` keeps complete target settings and otherwise uses the current backend defaults; `--env-dir` selects the environment directory. Specify the service directory explicitly, for example `hai deploy packages/my-app-serv --env test`; workspace layouts are not guessed. Startup scripts carry the selected environment. Public connections go to the target file; credentials go to `.env.local` with redacted output.
-
-Choose “deploy directly” in the wizard, or run `hai deploy packages/my-app-serv --env prod --yes --skip-middleware`, to skip all middleware prompts, configuration writes and provisioning when your environment is complete. Missing deployment targets are guided through SSH/Vercel setup. Host, ports, key paths, remote directory and tokens are saved only in Git-ignored `.env.local` and reused on later runs. Edit `HAI_DEPLOY_PROVIDER` there to change the target; supply private key paths only.
-
-## Global options
-
-See the [usage guide](../../docs/usage/README.en.md) for build/deploy meanings, defaults, and examples. Deliverables use the application root package.json version, not the CLI version.
-
-| Option             | Description       | Default           | Example                       |
-| ------------------ | ----------------- | ----------------- | ----------------------------- |
-| `-v, --verbose`    | Verbose output    | false             | `hai create my-app --verbose` |
-| `-C, --cwd <path>` | Working directory | Current directory | `hai build --cwd ../my-app`   |
-| `-h, --help`       | Command help      | false             | `hai build --help`            |
-| `-V, --version`    | CLI version       | false             | `hai --version`               |
-
-## Local development usage
-
-> For local CLI development in the monorepo before publishing to npm.
-
-### 1. Build
-
-```bash
-# 构建 CLI（生成 dist/）
-pnpm --filter @h-ai/cli build
-
-# 或启动 watch 模式（修改源码后自动重建）
-pnpm --filter @h-ai/cli dev
+```sh
+pnpm build --target docker
+pnpm run deploy --env prod
+pnpm run deploy --env prod --build --services web
+pnpm run deploy --env prod --build --bundle-only
 ```
 
-### 2. Run directly (no installation)
+Complete bundles include application and self-hosted middleware images. Deployment caches, archives and operation directories default to `.hai/deploy/<environment>/` at the project root; `--output` can explicitly override the archive path relative to the command's working directory. Bundle-only mode skips SSH questions and creates a tar, `deploy-target.json` with per-field descriptions, Windows `deploy.ps1` and Linux/macOS `deploy.sh`. Edit and check `deploy-target.json` before running either upload script; both scripts read this file. On an isolated Linux server, extract and run `sh apply.sh`. First installations require a complete bundle; partial updates preserve other services and volumes. Each step reports its result; failure exits nonzero and attempts recovery. See [deployment](../deploy/README.en.md) for prerequisites, caching, versions and recovery.
 
-After building, invoke `dist/index.js` directly with `node`:
+Failures display local managed-process termination separately from remote unknown/finished-script state and the server result path. Local SSH exit does not prove remote termination. Inspect unknown server state first; CLI never reruns deployment or rollback automatically. Windows command execution uses an embedded system PowerShell/.NET Job and requires Add-Type; failure never starts an unmanaged command.
 
-```bash
-# 从仓库根目录运行
-node packages/cli/dist/index.js create my-app
-node packages/cli/dist/index.js create my-app --type admin --features iam,db
-```
+Normal foreground deployment and synchronous failure recovery explicitly unlock `.deploy.lock` after finalization and terminal-result publication, so background services do not block later deployments. On HUP/INT/TERM or a killed parent shell, active child commands retain the inherited lock until every holder exits or the server restarts. Keep the lock file permanently; never delete or replace it.
 
-Or invoke it by absolute path from any directory:
+Build desktop installers with `pnpm build --target desktop --platform windows|linux|macos --arch x64|arm64`, using the target system and toolchain. Test native installers separately from container-hosted web pages.
 
-```bash
-node /path/to/hai-framework/packages/cli/dist/index.js create my-app
-```
+### AI-assisted development
 
-### 3. Global linking (`pnpm link`)
+Root `AGENTS.md` points to `.agents/skills/`; Claude, Copilot and OpenCode entry files reference the same rules. Use [application development](templates/skills/hai-app-create/SKILL.md) for features, [review](templates/skills/hai-spec-review/SKILL.md) and [implementation](templates/skills/hai-spec-implement/SKILL.md) for larger specifications, and [framework sync](templates/skills/hai-framework-sync/SKILL.md) for upgrades.
 
-To use `hai` directly in a terminal, create a global link:
+Skill entries define task boundaries and load adjacent references as needed. `hai init` / `hai add` fill missing content; merge existing custom rules deliberately and copy complete skill directories when syncing.
 
-```bash
-# 在 packages/cli 目录下执行
-cd packages/cli
-pnpm link --global
+## Development and testing
 
-# 验证
-hai --version
-hai create my-app
-```
+### Local development usage
 
-> Remove the link afterward with `pnpm unlink --global @h-ai/cli`.
-
-### 4. Use in other monorepo apps
-
-Projects in `apps/*` reference local packages through `workspace:*` and can use them directly:
-
-```bash
-# 在仓库根目录执行，对任意 app 类型生成项目
-node packages/cli/dist/index.js create ../my-new-project
-```
+Run from the framework repository root to create projects from current source. Deployment gates additionally require reachable Podman/Docker.
 
-## 5. Configuration driven authentication
-
-Agreements support configuration-loaded userAgreementMarkdown/privacyPolicyMarkdown and URLs. Markdown takes priority for the same agreement and is safely rendered in a modal.
-
-Admin/H5/website templates with IAM include AuthPanel and standard routes; mobile and fullstack clients share API actions. Server config/_iam.yml controls methods, registration, recovery, agreement modals and branding. LDAP/Reach are optional: install ldapts only for the default LDAP client, then enable login.ldap and set connection settings. Email/SMS use Reach templates or custom callbacks. Forms expose header/extraFields/footer snippets and AuthPanel forwards login*/register* snippets. Multiple nodes share a database and Redis.
-
-[完整 IAM 配置 / IAM configuration](../iam/README.en.md)
-
-### 6. Run tests
-
-```bash
-# 单元测试 + E2E 模板生成测试
+```sh
+pnpm --filter @h-ai/cli build
+node packages/cli/dist/index.js create ../my-app
+pnpm --filter @h-ai/cli typecheck
+pnpm --filter @h-ai/cli lint
 pnpm --filter @h-ai/cli test
+pnpm check:skills
+pnpm --filter @h-ai/cli test:scaffold-gates
+pnpm --filter @h-ai/cli test:scaffold-gates --list --json
+pnpm --filter @h-ai/cli test:deploy-gates
+```
 
-# 真实脚手架 E2E 门禁（生成项目后执行 install/typecheck/lint/build/test/e2e）
-pnpm --filter @h-ai/cli test:e2e
+The eight scaffold scenarios retain real installation, compilation and HTTP/browser checks for every application type. The heavy scaffold and generated-route runtime files run in sequential batches because measured build and installation resource contention made concurrent runs slower. The three smaller locale, CLI process and environment-consumption files can share the runtime batch, with at most two file workers. Each scenario uses the complete build already provided by its E2E entry; existing production build isolation checks inspect nonempty generated outputs after E2E. Real container deployment selects API, SSR (admin represents the shared website/h5 Dockerfile and deployment branch), static mobile and fullstack shapes. Ownership, authentication/transport, incremental updates, damaged artifacts and rollback checks remain. Fixtures enable init and verify orphan reaping; a fast gate runs the production Nginx version against the public bundle with `nginx -t`. Unit tests do not probe engines. Workspace compilation builds contracts through the dependency graph; fullstack prepares shared i18n first without compiling contracts twice.
 
-# watch 模式
-pnpm --filter @h-ai/cli test:watch
+Scaffold gates generate real projects and run install, typecheck, lint, build, tests and browser workflows, including generated HTTP routes, CLI process locale selection and environment file consumption. Use `--generate` or `--i18n` for focused reruns. Deployment gates cover actual resource ownership and dynamic host port isolation, as well as offline bundles, SSH/manual deployment, incremental updates and rollback. Cleanup uses only container IDs and private image tags recorded by the current run. Safe metadata remains in ignored `tmp/validation/module-review/VERIFY-05/`. Produced browser screenshots, traces and reports remain under ignored `tmp/validation/module-review/scaffold-browser/` or `deploy-browser/` by default. Explicit evidence, HTML report and output paths are respected; temporary projects, keys, data and processes are still cleaned up. Native shells and real cloud providers need separate acceptance.
 
-# 覆盖率
-pnpm --filter @h-ai/cli test:coverage
-```
+Optional Windows installer acceptance requires the Rust `x86_64-pc-windows-msvc` target and MSVC build tools. Set `HAI_CLI_NATIVE_BUILD=1` and run `pnpm --filter @h-ai/cli test:scaffold-gates`; the existing fullstack scenario builds an NSIS installer and checks the application-root version against its filename. `CARGO_BUILD_JOBS=2` limits Rust compilation concurrency. Native UI interactions and device capabilities require separate acceptance.
 
-Admin and fullstack gates also verify public types and runtime behavior from installed local tarballs: streams/checksums/create-only writes, API Key scopes/revocation, current authorization, batch users/role pagination, Reach templates and Audit metadata. Fullstack also verifies trusted peer IPs.
+Deployment fixtures inspect pinned public base images and pull only confirmed missing images; HAI_DEPLOY_E2E_MIRROR remains available. Public image caches are never cleanup targets. A successful create records its container ID before asynchronous APT/pip/sshd preparation inside a private PID namespace. Preparation errors, deadlines and cooperative cancellation wait for the local client to close, then remove and verify that exact owned ID; only the nested Podman fixture is privileged. HAI_DEPLOY_E2E_APT_MIRROR accepts a mirror hostname and keeps HTTPS. Ownership tests use run-specific private tags of pinned public images while preserving foreign same-content tags, retag protection, dynamic ports and external sentinels. A lost create acknowledgment without a trusted ID, or a forcibly terminated test process, remains unknown and never authorizes adoption by name or label.
 
-Successful screenshots default to the CLI's `test-results/scaffold-evidence/`. Set `HAI_AUTH_EVIDENCE_DIR` to retain them in a chosen directory after generated projects are cleaned up. Fullstack E2E starts every selected Web/App/Desktop browser preview and checks login, tours, help and profile navigation. Miniapp and native shells require separate platform acceptance.
+`--generate` runs focused route gates: it reuses installed workspace dependencies, generates and builds real SvelteKit, serv API and fullstack backend projects, then accesses their new routes, including transport. It does not replace the full installation and browser matrix.
 
-Failures and degraded-state messages must also be localized: website APIs use the request locale for AI fallback and email delivery status; undelivered messages must not be described as received. CLI deployment status uses cliM, and Gallery encryption limitations use bilingual messages. Verify unconfigured, failed, and successful paths in Chinese and English without paid service calls.
+`test:e2e` gives each server explicit isolated backends and an absolute data directory. Server children do not inherit external `HAI_*` / `PUBLIC_*` / `VITE_*` settings or read the user's `.env.local`. Test-only `HAI_E2E=1` preserves ordinary development/production dotenv behavior and shared-backend requirements; transport cases use a fresh trusted SM2 ring and the actual registry. Scaffold browser runs also use an independent TCP counter to verify that external database settings are never contacted. Complete deployment acceptance retains real Redis/S3, incremental updates and rollback for fullstack.
 
-Provisioned configuration: Neon emits HAI_DB (PostgreSQL JSON), Upstash HAI_CACHE (Redis rediss URL JSON), and R2 HAI_STORAGE (flat S3 JSON). Email/SMS emit HAI_REACH_PROVIDERS; deployApp merges both channels while preserving YAML message templates, replacing the original providers array. Core supports whole-object/array overrides, with parents preceding leaves and schema validation retained. Provisioned values are runtime-only and are never passed to build subprocesses. R2 needs existing S3 accessKeyId/secretAccessKey, Resend a verified-domain from address, and Alibaba Cloud approved signName/templates. Applications need matching `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` loaded at startup; network clients require Node.
+`--i18n` builds the CLI and checks language precedence, help, successful generation and errors in separate processes, alongside Chinese/English/Japanese prompt, validation, cancellation and create/add/init cases.
 
-Deployment recovery: `ProvisionResult.resourceStatus` marks created/reused. `getDeployRecovery(result.error)` reads projectName, stage, platformProjectId, and resource lists; unknown means an uncertain request result that must first be checked in the provider console. Preserve returned IDs for failed resources. Recovery excludes envVars, raw exceptions, and credentials; the CLI shows resources and advice. Same-name retries reuse resources. Reused resources are never deleted automatically; clean up newly created resources only after manually confirming they are unused.
+## Skill workflows and frontend guidance
 
-## Generated form layouts
+The workflow uses hai-spec-review, hai-spec-implement, hai-app-create, hai-app-tests, hai-app-review and hai-pr-review. The [handoff contract](templates/skills/hai-spec-implement/handoff.md) connects requirements, acceptance, findings and evidence while retaining Git document baselines.
 
-Website contact forms and fullstack management screens reuse UI FormLayout/FormField: one or two columns, stacked or inline labels, automatic spans and narrow-container fallback. User, profile and password forms share the same options and built-in Chinese/English validation. The generated hai-ui skill documents the complete contract.
+UI delivery includes [hai-ui-design](templates/skills/hai-ui-design/SKILL.md), hai-ui and [hai-ui-review](templates/skills/hai-ui-review/SKILL.md). API templates exclude frontend skills. init/add preserve private entrypoints and backfill missing resources. Repository entrypoints use the same names for shared responsibilities.
 
 ## License