@nocobase/plugin-ai 2.2.0-alpha.1 → 2.2.0-beta.2

package/dist/ai/docs/nocobase/ai/ai-quick-start.md

@@ -27,7 +27,7 @@ If the prerequisites are not met, tell the user they need to install the missing
 If the user already has NocoBase CLI installed (run `nb --version` to check), proceed to the next step. If not, run the following command to install:
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 ```
 
 Run `nb --version` to confirm successful installation.

package/dist/ai/docs/nocobase/ai/claude-code/index.md

@@ -63,7 +63,7 @@ Before starting, make sure you have the following environment ready:
 
 - Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
 - Node.js >= 22 (for running NocoBase CLI and Skills)
-- If you already have a NocoBase instance, **AI capabilities are evolving rapidly and only the latest beta version provides the full experience. Minimum version >= 2.1.0-beta.20, latest version strongly recommended.**
+- If you already have a NocoBase instance, **AI capabilities are evolving rapidly. The minimum required version is NocoBase 2.1.0, and we recommend updating to the latest version.**
 
 ## Quick Start
 
@@ -78,7 +78,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb init --ui
 ```
 

package/dist/ai/docs/nocobase/ai/codex/index.md

@@ -61,7 +61,7 @@ Before starting, make sure you have the following environment ready:
 
 - Codex installed (`npm install -g @openai/codex`)
 - Node.js >= 22 (for running NocoBase CLI and Skills)
-- If you already have a NocoBase instance, **AI capabilities are evolving rapidly and only the latest beta version provides the full experience. Minimum version >= 2.1.0-beta.20, latest version strongly recommended.**
+- If you already have a NocoBase instance, **AI capabilities are evolving rapidly. The minimum required version is NocoBase 2.1.0, and we recommend updating to the latest version.**
 
 ## Quick Start
 
@@ -76,7 +76,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb init --ui
 ```
 

package/dist/ai/docs/nocobase/ai/hermes-agent/index.md

@@ -69,7 +69,7 @@ Before starting, make sure you have the following environment ready:
 
 - A server running Hermes Agent (Linux / macOS, Python 3.10+)
 - Node.js >= 22 (for running NocoBase CLI and Skills)
-- If you already have a NocoBase instance, **AI capabilities are evolving rapidly and only the latest beta version provides the full experience. Minimum version >= 2.1.0-beta.20, latest version strongly recommended.**
+- If you already have a NocoBase instance, **AI capabilities are evolving rapidly. The minimum required version is NocoBase 2.1.0, and we recommend updating to the latest version.**
 
 Installing Hermes requires just one command:
 
@@ -96,7 +96,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb init --ui
 ```
 

package/dist/ai/docs/nocobase/ai/index.md

@@ -92,7 +92,7 @@ features:
     items:
       - title: NocoBase CLI
         details: The command-line tool for NocoBase — install and you're ready to go, with built-in AI Skills that let your AI assistant directly operate NocoBase.
-        link: /api/cli/
+        link: /nocobase-cli/
       - title: NocoBase Skills
         details: Domain knowledge packages installable into AI Agents, enabling AI to understand NocoBase's capabilities and conventions.
         link: /ai-builder#nocobase-skills

package/dist/ai/docs/nocobase/ai/install-nocobase-app.md

@@ -0,0 +1,104 @@
+---
+title: Install NocoBase App
+description: Install NocoBase CLI and quickly create a new NocoBase application with `nb init --ui`, so your AI Agent can start working right away.
+---
+
+# Install NocoBase App
+
+## Prerequisites
+
+- Node.js >= 22
+- Yarn 1.x
+- If you plan to install with Docker, make sure Docker is already running
+
+## Step 1: Install CLI
+
+Install NocoBase CLI globally first:
+
+```bash
+npm install -g @nocobase/cli
+nb --version
+```
+
+If you often work with multiple terminals or want to operate in parallel with AI Agents, we also recommend running `nb session setup` once. This lets each session keep its own `current env`, so they are less likely to affect one another.
+
+## Step 2: Initialize the app
+
+We recommend opening the visual wizard directly:
+
+```bash
+nb init --ui
+```
+
+![2026-06-11-20-14-32](https://static-docs.nocobase.com/2026-06-11-20-14-32.png)
+
+Different setup paths show slightly different steps. If you follow the default `Install a new app` path, you will usually see these six steps:
+
+1. `Getting started` - set the `--env` identifier and choose `Install a new app`
+2. `App environment` - set the app basics, storage location, and runtime port
+3. `App source and version` - choose how to get the app and which source and version to use
+4. `Configure the database` - choose the built-in database or a custom database
+5. `Create an admin account` - set up the first admin account
+6. `Connection & authentication` - enter the app access URL and choose an authentication method
+
+If you prefer terminal interaction, you can also run:
+
+```bash
+nb init
+```
+
+If you need to initialize in scripts or CI, use non-interactive mode:
+
+```bash
+nb init --yes --env app1
+```
+
+:::tip Install on a remote server
+
+If you run `nb init --ui` on a server, we recommend changing the default host to that server's IP first. That way, you can open the wizard from your local browser.
+
+```bash
+nb config set default-ui-host <server-ip>
+nb config set default-api-host <server-ip>
+```
+
+:::
+
+## Step 3: Confirm the app is ready
+
+After installation, it is usually worth confirming these three things first:
+
+- The env has been saved successfully
+- The app has started normally
+- You can sign in with the administrator account
+
+Common commands:
+
+```bash
+nb env list
+nb env info
+nb app logs
+```
+
+For a local default installation, you can usually open `http://localhost:13000` in your browser directly. After signing in, start a new AI Agent session or restart the current one, and the AI can begin working with this NocoBase app.
+
+CLI configuration is stored in `~/.nocobase/` by default, so AI Agents can usually access it from any working directory.
+
+If this app will be exposed to real users later, we do not recommend using `IP + port` for the long term. The next step is usually to put it behind a reverse proxy and enable HTTPS.
+
+## Next Steps
+
+- If you already have a running NocoBase app, see [AI Agent Integration Guide](./quick-start.mdx)
+- If you want to manage app startup, shutdown, logs, and upgrades, see [Manage apps](../nocobase-cli/operations/manage-app.md)
+- If you want to continue with production deployment, see [Install apps with CLI](../nocobase-cli/installation/cli.md) and [Production deployment overview](../nocobase-cli/production/index.md)
+- If you want AI to start building apps, see [AI Builder](../ai-builder/index.md)
+
+## Related Links
+
+- [Installation and Version Comparison](../get-started/quickstart.md) — Compare installation methods and version channels first, then decide how to install
+- [AI Agent Integration Guide](./quick-start.mdx) — Connect an existing NocoBase app and let your AI Agent start working
+- [`nb init` command reference](../api/cli/init.md) — Initialize a new app, take over an existing local app, or connect a remote app
+- [`nb env info` command reference](../api/cli/env/info.md) — View the connection details and runtime configuration of the current env
+- [NocoBase CLI](../api/cli/index.md) — Full reference for all `nb` commands
+- [Manage apps](../nocobase-cli/operations/manage-app.md) — Start, stop, restart, view logs, and upgrade apps
+- [Multiple environment management](../nocobase-cli/operations/multi-environment.md) — Common operations when you maintain multiple envs at the same time

package/dist/ai/docs/nocobase/ai/local-development-setup.md

@@ -0,0 +1,94 @@
+---
+title: Local Development Setup
+description: Prepare the local operating system environment for NocoBase CLI and NocoBase apps, covering Windows WSL, macOS, Linux, Node.js, Yarn, and Docker.
+---
+
+# Local Development Setup
+
+This page helps you prepare a local environment for NocoBase CLI and NocoBase apps. It is intended for local development, feature evaluation, and AI Agents installing or managing NocoBase on your computer.
+
+For real user-facing deployment, see [Production system requirements](../get-started/system-requirements.md).
+
+## Windows: Use WSL
+
+For local setup on Windows, we recommend keeping the main development environment inside WSL 2: install Node.js, Yarn, and NocoBase CLI in the Linux distribution in WSL, and run related commands from the WSL terminal.
+
+WSL is closer to the Linux environments where NocoBase is commonly deployed. This gives you several benefits:
+
+- Dependency installation, build, startup, and log troubleshooting are closer to the actual server workflow
+- After Docker Desktop WSL integration is enabled, you can run `docker` commands directly inside WSL
+- You can avoid extra issues from native Windows path formats, file permissions, symlinks, and native dependency builds
+- It is better for AI Agent workflows. When an agent runs commands such as `nb`, `yarn`, or `docker`, it uses one consistent Linux file path, shell syntax, and runtime environment, which makes troubleshooting more direct
+
+If the WSL-based local development environment is not ready yet, see [Set Up a Local Development Environment on Windows with WSL](./windows-wsl.md).
+
+Recommended setup:
+
+- Windows 10 / 11
+- WSL 2
+- Ubuntu LTS
+- Node.js >= 22
+- Yarn 1.x
+- Docker Desktop, if you plan to install NocoBase with Docker
+
+Usually, Node.js, Yarn, and NocoBase CLI should all be installed inside WSL. If you use Docker Desktop, enable WSL integration in Docker Desktop so WSL can access Docker.
+
+Check the environment:
+
+```bash
+node -v
+yarn -v
+docker version
+```
+
+:::tip Note
+
+NocoBase can also be installed on Windows Server. WSL is recommended here for local development and AI Agent setup on personal computers. It does not mean Windows Server cannot be used for deployment.
+
+:::
+
+## macOS
+
+On macOS, you can use the local terminal directly.
+
+Prepare:
+
+- Node.js >= 22
+- Yarn 1.x
+- Docker Desktop, OrbStack, or Colima, if you plan to install NocoBase with Docker
+
+Check the environment:
+
+```bash
+node -v
+yarn -v
+docker version
+```
+
+If you do not use Docker, you can skip `docker version`.
+
+## Linux
+
+Linux can be used directly as a local development environment. Ubuntu, Debian, or other common distributions are recommended.
+
+Prepare:
+
+- Node.js >= 22
+- Yarn 1.x
+- Docker Engine, if you plan to install NocoBase with Docker
+
+Check the environment:
+
+```bash
+node -v
+yarn -v
+docker version
+```
+
+If you do not use Docker, you can skip `docker version`.
+
+## Next Steps
+
+- [Installation and Version Comparison](../get-started/quickstart.md) — Compare installation methods and version channels first
+- [Install NocoBase App](./install-nocobase-app.md) — Initialize a local app with NocoBase CLI
+- [AI Agent Integration Guide](./quick-start.mdx) — Let an AI Agent connect to and operate NocoBase

package/dist/ai/docs/nocobase/ai/openclaw/index.md

@@ -63,7 +63,7 @@ Before starting, make sure you have the following environment ready:
 
 - A deployed OpenClaw Agent ([one-click Lark deployment](https://openclaw.feishu.cn) or local deployment)
 - Node.js >= 22 (for running NocoBase CLI and Skills)
-- If you already have a NocoBase instance, **AI capabilities are evolving rapidly and only the latest beta version provides the full experience. Minimum version >= 2.1.0-beta.20, latest version strongly recommended.**
+- If you already have a NocoBase instance, **AI capabilities are evolving rapidly. The minimum required version is NocoBase 2.1.0, and we recommend updating to the latest version.**
 
 :::warning Note
 
@@ -84,7 +84,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb init --ui
 ```
 

package/dist/ai/docs/nocobase/ai/opencode/index.md

@@ -63,7 +63,7 @@ Before starting, make sure you have the following environment ready:
 
 - OpenCode installed ([installation guide](https://opencode.ai/docs/))
 - Node.js >= 22 (for running NocoBase CLI and Skills)
-- If you already have a NocoBase instance, **AI capabilities are evolving rapidly and only the latest beta version provides the full experience. Minimum version >= 2.1.0-beta.20, latest version strongly recommended.**
+- If you already have a NocoBase instance, **AI capabilities are evolving rapidly. The minimum required version is NocoBase 2.1.0, and we recommend updating to the latest version.**
 
 ## Quick Start
 
@@ -78,7 +78,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb init --ui
 ```
 

package/dist/ai/docs/nocobase/ai/quick-start.mdx

@@ -2,7 +2,6 @@
 title: "AI Agent Integration Guide"
 description: "Install NocoBase CLI, connect to or install a NocoBase application, and let AI Agents start operating your business system."
 keywords: "NocoBase CLI,AI Agent,integration,connect,installation,Skills,quick start"
-sidebar: false
 ---
 
 # AI Agent Integration Guide
@@ -42,7 +41,7 @@ If you don't have a NocoBase application yet, you can use CLI to install and ini
 #### Step 1: Install CLI
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb --version // Confirm successful installation
 ```
 
@@ -58,15 +57,16 @@ Configuration files and application data are stored in your home directory by de
 
 :::
 
-The browser will automatically open a visual configuration page, guiding you through 5 steps:
+The browser will automatically open a visual configuration page, guiding you through 6 steps:
 
-1. **Start Configuration** — Set the application name (also used as the CLI environment name), select "Fresh Installation"
-2. **Create Application** — Choose the installation method (Docker / npm / Git), set port and other basic configurations
-3. **Download Application Files** — Select source and version, download NocoBase source code or image
-4. **Configure Database** — Use the built-in database or configure an external database (PostgreSQL, MySQL, MariaDB)
-5. **Create Admin Account** — Set the admin email and password
+1. "Getting started" — Choose whether to install a new app, manage a local app, or connect a remote app.
+2. "App environment" — Set the app basics, storage location, and runtime port.
+3. "App source and version" — Choose how to get the app and which source and version to use.
+4. "Configure the database" — Use built-in or custom.
+5. "Create an admin account" — Set up the first admin.
+6. "Connection & authentication" — Enter the app access URL and choose an authentication method.
 
-![nocobase cli visual wizard](https://static-docs.nocobase.com/2026-04-29-15-55-19.png)
+![nocobase cli visual wizard](https://static-docs.nocobase.com/2026-06-11-20-14-32.png)
 
 After installation is complete, open your browser and visit `http://localhost:13000` (default port), then log in with the admin account you just set up.
 
@@ -92,7 +92,7 @@ After configuration is complete, restart your AI Agent session and you can start
 
 ## Connect AI Agent to an Existing NocoBase
 
-If you already have a running NocoBase instance, you can connect AI Agent to it directly. **Since AI capabilities are evolving rapidly, only the latest beta version provides the full experience. The minimum required version is 2.1.0-beta.20 — we strongly recommend updating to the latest.**
+If you already have a running NocoBase instance, you can connect AI Agent to it directly. **Since AI capabilities are evolving rapidly, the minimum required version is NocoBase 2.1.0, and we recommend updating to the latest version.**
 
 <Tabs>
 <Tab label="Manual Connection" value="manual-connect">
@@ -100,7 +100,7 @@ If you already have a running NocoBase instance, you can connect AI Agent to it
 #### Step 1: Install CLI
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb --version // Confirm successful installation
 ```
 
@@ -116,12 +116,12 @@ Configuration files are stored in your home directory by default. See [NB_CLI_RO
 
 :::
 
-The browser will automatically open a visual configuration page. In the first step "Start Configuration", select "Connect to Existing Application", then:
+The browser will automatically open a visual configuration page. In the first step "Start Configuration", select "Remote Connection", then:
 
 1. **Enter API Address** — Input the API address of your existing NocoBase instance (e.g., `http://localhost:13000/api`)
 2. **Select Authentication Method** — Choose an [authentication method](../ai-builder/security) (OAuth is recommended for quick setup)
 
-![nocobase cli visual wizard](https://static-docs.nocobase.com/2026-04-29-15-55-55.png)
+![nocobase cli visual wizard](https://static-docs.nocobase.com/2026-06-11-21-18-31.png)
 
 No need to configure installation method, database, or admin account — the wizard will skip those steps.
 
@@ -132,7 +132,7 @@ Start a new or restart the AI Agent session, and you can let the AI Agent start
 </Tab>
 <Tab label="Connect with AI Agent" value="ai-connect">
 
-Copy the prompt below to your AI assistant. It will complete CLI installation and guide you through connecting to your existing NocoBase instance. Select "Connect to Existing Application" in the first step of the visual wizard:
+Copy the prompt below to your AI assistant. It will complete CLI installation and guide you through connecting to your existing NocoBase instance. Select "Remote Connection" in the first step of the visual wizard:
 
 ```
 Help me install NocoBase CLI and complete initialization: https://docs.nocobase.com/ai/ai-quick-start.md (please read the linked content directly)
@@ -145,6 +145,13 @@ After configuration is complete, restart your AI Agent session and you can start
 
 ## What's Next
 
+### Production Installation and Deployment
+
+If you're preparing to deploy NocoBase to production, this order usually works best:
+
+1. [Install using CLI](../nocobase-cli/installation/cli.md) - the complete installation flow. This is the right place when you want to install CLI from scratch, initialize env, and confirm the app is already running on your server
+2. [Production deployment overview](../nocobase-cli/production/index.md) - the next step after the app is running. This mainly covers autostart, reverse proxy, domain setup, and HTTPS
+
 ### Manage Application Environments
 
 If you need to manage existing NocoBase instances (such as test or production environments), or switch between multiple environments, see [Environment Management](../ai-builder/env-bootstrap) — covering environment checks, adding environments, upgrades, and troubleshooting.
@@ -172,4 +179,4 @@ If you already have a NocoBase application running, or have successfully complet
 - [AI Employees](../ai-employees/index.md) — Collaborate with AI in the business interface
 - [Environment Management](../ai-builder/env-bootstrap) — Environment checks, adding environments, upgrades, and troubleshooting
 - [NocoBase CLI Command Reference](../api/cli/index.md) — Full parameter documentation for all commands
-- [Installation Methods and Version Comparison](../get-started/quickstart) — Different installation methods and version channels for NocoBase
+- [Installation Methods and Version Comparison](../ai/quickstart) — Different installation methods and version channels for NocoBase

package/dist/ai/docs/nocobase/ai/upgrade-nocobase-app.md

@@ -0,0 +1,105 @@
+---
+title: Upgrade NocoBase App
+description: Upgrade a NocoBase app saved as a CLI env with nb app upgrade, including env confirmation, upgrade commands, target versions, and verification.
+---
+
+# Upgrade NocoBase App
+
+## Step 1: Confirm the Current Env
+
+```bash
+nb env current
+```
+
+If you are not sure which envs are available, list them first:
+
+```bash
+nb env list
+```
+
+If the current env is not the app you want to upgrade, switch to the target env:
+
+```bash
+nb env use <env-name>
+```
+
+## Step 2: Run the Upgrade
+
+:::warning Note
+
+By default, upgrade downloads the app source code or Docker image again.
+
+For npm / Git envs, the `source/` directory is deleted and downloaded again. Do not put files you need to keep in `source/`.
+
+If you have already prepared the source code or Docker image manually and do not want CLI to download it again, add `--skip-download` after the command.
+
+:::
+
+The default upgrade command is:
+
+```bash
+nb app upgrade
+```
+
+This command usually completes these steps:
+
+1. Stop the current app
+2. Download and replace the saved source or image
+3. Sync commercial plugins
+4. Upgrade and start the app
+5. Refresh env runtime information
+
+In scripts, CI, or AI Agent sessions, pass `--force` explicitly:
+
+```bash
+nb app upgrade --force
+```
+
+If the app to upgrade is not the current env, specify the env:
+
+```bash
+nb app upgrade --env app1 --yes --force
+```
+
+### Upgrade to a Specific Version
+
+Use `--version` to upgrade to a specific version channel:
+
+```bash
+nb app upgrade --version beta
+```
+
+You can also pass an exact version:
+
+```bash
+nb app upgrade --version 2.1.0-beta.24
+```
+
+After a successful upgrade, CLI writes the target version back to the env configuration, so later upgrades or recovery flows can reuse it.
+
+### Skip Download
+
+If you have already updated the source code or Docker image, and only want to run upgrade and start based on the current content, add `--skip-download`:
+
+```bash
+nb app upgrade --skip-download
+```
+
+This skips source or image download and also skips commercial plugin sync. Use it only when the target version has already been prepared manually.
+
+## Step 3: Verify the Result
+
+After the upgrade, check env runtime and app logs:
+
+```bash
+nb env info
+nb app logs
+```
+
+Then open the app and confirm that the administrator account can sign in. If you want an AI Agent to continue working with this app, start a new AI Agent session or restart the current one so it can read the latest env information.
+
+## Related Links
+
+- [Manage apps](../nocobase-cli/operations/manage-app.md) — Start, stop, restart, view logs, and upgrade apps
+- [`nb app upgrade` command reference](../api/cli/app/upgrade.md) — View all upgrade command options
+- [Multiple environment management](../nocobase-cli/operations/multi-environment.md) — Confirm, switch, and maintain multiple CLI envs