@nocobase/plugin-ai 2.1.0-alpha.40 → 2.1.0-alpha.46

package/dist/ai/docs/nocobase/ai-dev/capabilities.md

@@ -18,7 +18,7 @@ Here is a list of everything AI can currently help you do. Each capability comes
 
 :::warning Note
 
-- NocoBase is migrating from `client` (v1) to `client-v2`, and `client-v2` is still under development. The client code generated by AI development is based on `client-v2` and can only be used under the `/v2/` path. It is available for early access and experimentation, but is not recommended for production use.
+- NocoBase is migrating from `client` (v1) to `client-v2`, and `client-v2` is still under development. The client code generated by AI development is based on `client-v2` and can only be used under the `/v/` path. It is available for early access and experimentation, but is not recommended for production use.
 - AI-generated code may not be 100% correct. We recommend reviewing it before enabling. If you encounter issues at runtime, send the error message to AI and let it investigate and fix -- it usually takes just a few rounds of conversation to resolve.
 - We recommend using GPT or Claude series models for development, as they produce the best results. Other models can also work, but generation quality may vary.
 

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

@@ -33,7 +33,7 @@ Your browser will automatically open the visual configuration page, guiding you
 
 :::warning Note
 
-- NocoBase is migrating from `client` (v1) to `client-v2`, and `client-v2` is still under development. The client code generated by AI development is based on `client-v2` and can only be used under the `/v2/` path. It is available for early access and experimentation, but is not recommended for production use.
+- NocoBase is migrating from `client` (v1) to `client-v2`, and `client-v2` is still under development. The client code generated by AI development is based on `client-v2` and can only be used under the `/v/` path. It is available for early access and experimentation, but is not recommended for production use.
 - AI-generated code may not be 100% correct. We recommend reviewing it before enabling. If you encounter issues at runtime, send the error message to AI and let it investigate and fix -- it usually takes just a few rounds of conversation to resolve.
 - We recommend using GPT or Claude series models for development, as they produce the best results. Other models can also work, but generation quality may vary.
 

package/dist/ai/docs/nocobase/ai-dev/watermark-plugin.md

@@ -34,7 +34,7 @@ Make sure you have:
 
 :::warning Note
 
-- NocoBase is migrating from `client` (v1) to `client-v2`, and `client-v2` is still under development. The client code generated by AI development is based on `client-v2` and can only be used under the `/v2/` path. It is available for early access and experimentation, but is not recommended for production use.
+- NocoBase is migrating from `client` (v1) to `client-v2`, and `client-v2` is still under development. The client code generated by AI development is based on `client-v2` and can only be used under the `/v/` path. It is available for early access and experimentation, but is not recommended for production use.
 - AI-generated code may not be 100% correct. We recommend reviewing it before enabling. If you encounter issues at runtime, send the error message to AI and let it investigate and fix -- it usually takes just a few rounds of conversation to resolve.
 
 :::

package/dist/ai/docs/nocobase/api/cli/app/index.md

@@ -6,7 +6,7 @@ keywords: "nb app,NocoBase CLI,app runtime,start,stop,logs,upgrade"
 
 # nb app
 
-Manage the runtime of a selected NocoBase env. npm/Git envs run local app commands; Docker envs manage saved app containers.
+Manage the runtime of a selected NocoBase env. npm/Git envs run local app commands; Docker envs manage app containers from the saved env config.
 
 ## Usage
 
@@ -18,12 +18,12 @@ nb app <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb app start`](./start.md) | Start the app or Docker container |
-| [`nb app stop`](./stop.md) | Stop the app or Docker container |
+| [`nb app start`](./start.md) | Start the app or recreate the Docker container |
+| [`nb app stop`](./stop.md) | Stop the app or remove the Docker container |
 | [`nb app restart`](./restart.md) | Stop and then start the app |
 | [`nb app logs`](./logs.md) | View app logs |
 | [`nb app down`](./down.md) | Stop and clean up local runtime resources |
-| [`nb app upgrade`](./upgrade.md) | Update source or image and restart the app |
+| [`nb app upgrade`](./upgrade.md) | Stop the app, replace the source or image, then start it again |
 
 ## Examples
 

package/dist/ai/docs/nocobase/api/cli/app/restart.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app restart"
-description: "nb app restart command reference: restart the NocoBase app or Docker container for a selected env."
+description: "nb app restart command reference: restart the NocoBase app for a selected env and recreate the Docker app container from saved env config when needed."
 keywords: "nb app restart,NocoBase CLI,restart app,Docker"
 ---
 
 # nb app restart
 
-Stop and then start the NocoBase app for a selected env.
+Stop and then start the NocoBase app for a selected env. Local envs reuse the `nb app stop` and `nb app start` flow; Docker envs remove the current container first, then recreate the app container from saved env config.
 
 ## Usage
 
@@ -43,6 +43,8 @@ nb app restart --env local-docker
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
+Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out. If you pass `--no-daemon` for a local env, the app runs in the foreground, so the CLI does not keep waiting for the readiness check after startup.
+
 ## Related Commands
 
 - [`nb app start`](./start.md)

package/dist/ai/docs/nocobase/api/cli/app/start.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app start"
-description: "nb app start command reference: start the NocoBase app or Docker container for a selected env."
+description: "nb app start command reference: start the NocoBase app for a selected env and recreate the Docker app container from saved env config when needed."
 keywords: "nb app start,NocoBase CLI,start app,Docker,pm2"
 ---
 
 # nb app start
 
-Start the NocoBase app for a selected env. npm/Git installations run local app commands; Docker installations start the saved app container.
+Start the NocoBase app for a selected env. npm/Git installations run local app commands; Docker installations recreate the saved app container from the saved env config.
 
 ## Usage
 
@@ -44,6 +44,10 @@ nb app start --env local-docker
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
+By default, local envs start in daemon mode and Docker envs recreate the app container from saved env config. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
+
+If you pass `--no-daemon` for a local env, the app runs in the foreground. In that case, the CLI does not keep waiting for the readiness check after startup.
+
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

package/dist/ai/docs/nocobase/api/cli/app/stop.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app stop"
-description: "nb app stop command reference: stop the NocoBase app or Docker container for a selected env."
+description: "nb app stop command reference: stop the NocoBase app and remove the Docker app container for a selected env."
 keywords: "nb app stop,NocoBase CLI,stop app,Docker"
 ---
 
 # nb app stop
 
-Stop the NocoBase app for a selected env. npm/Git installations stop local app processes; Docker installations stop the saved app container.
+Stop the NocoBase app for a selected env. npm/Git installations stop local app processes; Docker installations remove the saved app container.
 
 ## Usage
 

package/dist/ai/docs/nocobase/api/cli/app/upgrade.md

@@ -1,12 +1,12 @@
 ---
 title: "nb app upgrade"
-description: "nb app upgrade command reference: update source or image and restart a selected NocoBase app."
+description: "nb app upgrade command reference: stop the app, replace the saved source or image, then start the selected NocoBase app again."
 keywords: "nb app upgrade,NocoBase CLI,upgrade,update,Docker image"
 ---
 
 # nb app upgrade
 
-Upgrade a selected NocoBase app. npm/Git installations refresh the saved source and restart with quickstart; Docker installations refresh the saved image and recreate the app container.
+Upgrade a selected NocoBase app. The CLI stops the current app, replaces the saved source or image by default, synchronizes commercial plugins, quickstarts the app again, and refreshes the env runtime at the end. Docker envs recreate the app container from the saved env config during startup.
 
 ## Usage
 
@@ -20,23 +20,44 @@ nb app upgrade [flags]
 | --- | --- | --- |
 | `--env`, `-e` | string | CLI env name to upgrade; uses the current env if omitted |
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
-| `--skip-code-update`, `-s` | boolean | Restart from the saved local source or Docker image without downloading updates |
-| `--version` | string | Override the saved `downloadVersion`; when the upgrade succeeds, the new version is written back to the env config |
+| `--force`, `-f` | boolean | Skip the upgrade confirmation prompt. Required in non-interactive terminals and AI agent sessions |
+| `--skip-download`, `-s` | boolean | Restart from the currently saved local source or Docker image without downloading updates first; also skips `nb license plugins sync` |
+| `--version` | string | Override the target version for this upgrade; when the upgrade succeeds, the new version is written back to `downloadVersion` in the env config |
 | `--verbose` | boolean | Show underlying update and restart command output |
 
 ## Examples
 
 ```bash
 nb app upgrade
+nb app upgrade --force
 nb app upgrade --env local
-nb app upgrade --env local -s
+nb app upgrade --env local --force
+nb app upgrade --env local --skip-download
+nb app upgrade --env local --skip-download --version beta
 nb app upgrade --env local --version beta
 nb app upgrade --env local --verbose
-nb app upgrade --env local-docker -s
+nb app upgrade --env local-docker --skip-download
 ```
 
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
+Before the upgrade starts, interactive terminals also ask for upgrade confirmation unless you pass `--force`. In non-interactive terminals and AI agent sessions, `nb app upgrade` refuses to proceed without `--force` and prints a copyable re-run command. If the command is also cross-env, you need both `--yes` and `--force`.
+
+By default, `nb app upgrade` runs these steps:
+
+1. `nb app stop`
+2. `nb source download --replace`
+3. `nb license plugins sync --skip-if-no-license`
+4. `nb app start --quickstart`
+5. Save the new `downloadVersion` when needed
+6. `nb env update`
+
+When `--skip-download` is passed, the CLI skips steps 2 and 3 and restarts the currently saved source or image directly. If `--version` is also passed, the CLI does not download that version during this run; instead it only saves it as the new `downloadVersion` after a successful restart so later upgrades can use it.
+
+Step 4 waits for the app to pass `__health_check`. During this wait, the CLI prints one waiting line first, then one progress line every 10 seconds until the app is ready or the health check times out.
+
+If the final `nb env update` step fails, the upgrade still counts as successful. The CLI prints a warning and tells you to run `nb env update <envName>` manually afterward.
+
 ## Related Commands
 
 - [`nb source download`](../source/download.md)

package/dist/ai/docs/nocobase/api/cli/config/delete.md

@@ -18,14 +18,17 @@ nb config delete <key>
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `<key>` | string | Configuration key: `license.pkg-url`, `docker.network`, or `docker.container-prefix` |
+| `<key>` | string | Configuration key: `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, or `bin.yarn` |
 
 ## Examples
 
 ```bash
+nb config delete locale
+nb config delete update.policy
 nb config delete license.pkg-url
 nb config delete docker.network
 nb config delete docker.container-prefix
+nb config delete bin.git
 ```
 
 ## Related Commands

package/dist/ai/docs/nocobase/api/cli/config/get.md

@@ -18,14 +18,17 @@ nb config get <key>
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `<key>` | string | Configuration key: `license.pkg-url`, `docker.network`, or `docker.container-prefix` |
+| `<key>` | string | Configuration key: `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, or `bin.yarn` |
 
 ## Examples
 
 ```bash
+nb config get locale
+nb config get update.policy
 nb config get license.pkg-url
 nb config get docker.network
 nb config get docker.container-prefix
+nb config get bin.git
 ```
 
 ## Related Commands

package/dist/ai/docs/nocobase/api/cli/config/index.md

@@ -8,9 +8,27 @@ keywords: "nb config,NocoBase CLI,configuration,defaults"
 
 Manage CLI configuration defaults. Supported keys:
 
+- `locale`
+- `update.policy`
 - `license.pkg-url`
 - `docker.network`
 - `docker.container-prefix`
+- `bin.docker`
+- `bin.git`
+- `bin.yarn`
+
+## Common Keys
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `locale` | current CLI locale resolution | Override the CLI locale |
+| `update.policy` | `prompt` | Startup update behavior: `prompt`, `auto`, or `off` |
+| `license.pkg-url` | `https://pkg.nocobase.com/` | Package registry for commercial packages |
+| `docker.network` | `nocobase` | Default Docker network used by CLI-managed Docker apps |
+| `docker.container-prefix` | `nb` | Default container prefix used by CLI-managed Docker apps |
+| `bin.docker` | `docker` | Override the Docker executable path |
+| `bin.git` | `git` | Override the Git executable path |
+| `bin.yarn` | `yarn` | Override the Yarn executable path |
 
 ## Usage
 
@@ -31,8 +49,11 @@ nb config <command>
 
 ```bash
 nb config list
+nb config get update.policy
+nb config set update.policy auto
 nb config get docker.network
 nb config set docker.network nocobase
+nb config set bin.git /usr/bin/git
 nb config delete docker.container-prefix
 ```
 

package/dist/ai/docs/nocobase/api/cli/config/set.md

@@ -6,7 +6,7 @@ keywords: "nb config set,NocoBase CLI,configuration"
 
 # nb config set
 
-Set a CLI configuration value. Supported keys are `license.pkg-url`, `docker.network`, and `docker.container-prefix`.
+Set a CLI configuration value. Supported keys are `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, and `bin.yarn`.
 
 ## Usage
 
@@ -18,21 +18,28 @@ nb config set <key> <value>
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `<key>` | string | Configuration key: `license.pkg-url`, `docker.network`, or `docker.container-prefix` |
+| `<key>` | string | Configuration key: `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, or `bin.yarn` |
 | `<value>` | string | Configuration value; must not be empty |
 
 ## Examples
 
 ```bash
+nb config set locale zh-CN
+nb config set update.policy auto
 nb config set license.pkg-url https://pkg.nocobase.com/
 nb config set docker.network nocobase
 nb config set docker.container-prefix nb
+nb config set bin.docker /usr/local/bin/docker
+nb config set bin.git /usr/bin/git
+nb config set bin.yarn yarn
 ```
 
 ## Notes
 
 When setting `license.pkg-url`, the CLI normalizes the URL so it ends with `/`.
 
+`update.policy` supports `prompt`, `auto`, and `off`. The default is `prompt`.
+
 ## Related Commands
 
 - [`nb config get`](./get.md)

package/dist/ai/docs/nocobase/api/cli/init.md

@@ -63,7 +63,7 @@ nb init --env app1 --resume
 | `--db-database` | string | Database name |
 | `--db-user` | string | Database user |
 | `--db-password` | string | Database password |
-| `--fetch-source` | boolean | Download app files or pull the Docker image before installation |
+| `--skip-download` | boolean | Skip downloading app files or pulling the Docker image before installation, and reuse existing local resources |
 | `--source`, `-s` | string | How to obtain NocoBase: `docker`, `npm`, or `git` |
 | `--version`, `-v` | string | Version parameter: npm version, Docker image tag, or Git ref |
 | `--replace`, `-r` | boolean | Replace the target directory if it already exists |

package/dist/ai/docs/nocobase/api/cli/license/plugins/sync.md

@@ -22,6 +22,7 @@ nb license plugins sync [flags]
 | `--yes`, `-y` | boolean | When an explicitly passed `--env` targets a different env than the current env, skip the interactive confirmation prompt |
 | `--dry-run` | boolean | Preview changes without installing, upgrading, or removing plugins |
 | `--version` | string | Registry version or dist-tag to synchronize; defaults to the current workspace version |
+| `--skip-if-no-license` | boolean | Skip without error when the current env does not have a saved license key |
 | `--verbose` | boolean | Show detailed per-plugin sync logs |
 | `--json` | boolean | Output JSON |
 
@@ -32,6 +33,7 @@ nb license plugins sync
 nb license plugins sync --env app1
 nb license plugins sync --env app1 --yes
 nb license plugins sync --env app1 --dry-run
+nb license plugins sync --env app1 --skip-if-no-license
 nb license plugins sync --env app1 --json
 ```
 
@@ -39,6 +41,8 @@ nb license plugins sync --env app1 --json
 
 When `--version` is omitted, the CLI detects the current app version automatically and uses that to decide which registry version of commercial plugins should be downloaded.
 
+`--skip-if-no-license` only ignores one case: the current env does not have a saved license key yet. Other errors, such as missing registry credentials in the key, registry login failures, or plugin download failures, still surface normally.
+
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
 ## Related Commands

package/dist/ai/docs/nocobase/api/cli/self/update.md

@@ -21,6 +21,7 @@ nb self update [flags]
 | `--channel` | string | Release channel to update to, default `auto`; options: `auto`, `latest`, `beta`, `alpha` |
 | `--yes`, `-y` | boolean | Skip update confirmation |
 | `--json` | boolean | Output JSON |
+| `--skills` | boolean | Also refresh the globally installed NocoBase AI coding skills |
 | `--verbose` | boolean | Show detailed update output |
 
 ## Examples
@@ -28,6 +29,7 @@ nb self update [flags]
 ```bash
 nb self update
 nb self update --yes
+nb self update --skills
 nb self update --channel alpha --json
 ```
 

package/dist/ai/docs/nocobase/auth-verification/api-keys/index.md

@@ -8,7 +8,7 @@ pkg: '@nocobase/plugin-api-keys'
 
 ## Usage Instructions
 
-http://localhost:13000/admin/settings/api-keys/configuration
+https://example.com/admin/settings/api-keys
 
 
 ![](https://static-docs.nocobase.com/d64ccbdc8a512a0224e9f81dfe14a0a8.png)

package/dist/ai/docs/nocobase/file-manager/file-preview/index.md

@@ -9,3 +9,20 @@ For file types that do not support native preview, you can enable preview functi
 Currently, NocoBase provides the following file preview plugins:
 
 * [Office File Preview Plugin](../file-preview/ms-office.md)
+
+## PDF preview with external storage
+
+PDF preview uses PDF.js to render files in the browser. The browser must first read the PDF file content and then pass it to PDF.js for rendering. Therefore, when files are stored in external storage such as OSS, S3, COS, or a CDN, and the file access domain is different from the NocoBase site domain, the external storage must allow the NocoBase site to read files across origins.
+
+If CORS is not configured, PDF downloads can still work normally, but preview may fail with a file loading error.
+
+The CORS configuration for external storage or CDN should include:
+
+```http
+Access-Control-Allow-Origin: https://your-nocobase-domain
+Access-Control-Allow-Methods: GET, HEAD
+Access-Control-Allow-Headers: *
+Access-Control-Expose-Headers: Content-Length, Content-Range, Accept-Ranges, Content-Disposition, Content-Type
+```
+
+`Access-Control-Allow-Origin` should be set to the actual domain used to access NocoBase. Avoid using `*` for non-public files over the long term, because it expands the range of sites that can read the files.

package/dist/ai/docs/nocobase/get-started/installation/env.md

@@ -294,7 +294,7 @@ Log print format. Default is `console` in development and `json` in production.
 LOGGER_FORMAT=json
 ```
 
-Reference: [Log Format](/log-and-monitor/logger/index.md#log-format)
+Reference: [Log Format](/log-and-monitor/logger/index.md#log-formats)
 
 ### CACHE_DEFAULT_STORE
 
@@ -375,8 +375,10 @@ Supported formats:
 Used to append preset local plugins. The value is the package name (the `name` parameter in `package.json`), with multiple plugins separated by commas.
 
 :::info
+
 1. Ensure the plugin is downloaded locally and can be found in the `node_modules` directory. For more details, see [Plugin Organization](/plugin-development/project-structure).
 2. After adding the environment variable, the plugin will appear on the plugin manager page only after an initial installation (`nocobase install`) or upgrade (`nocobase upgrade`).
+
 :::
 
 ```bash
@@ -388,8 +390,10 @@ APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-foo,@my-project/plugin-bar
 Used to append built-in plugins that are installed by default. The value is the package name (the `name` parameter in `package.json`), with multiple plugins separated by commas.
 
 :::info
+
 1. Ensure the plugin is downloaded locally and can be found in the `node_modules` directory. For more details, see [Plugin Organization](/plugin-development/project-structure).
 2. After adding the environment variable, the plugin will be automatically installed or upgraded during the initial installation (`nocobase install`) or upgrade (`nocobase upgrade`).
+
 :::
 
 ```bash
@@ -472,7 +476,7 @@ yarn cross-env \
 
 ### WORKFLOW_SCRIPT_MODULES
 
-Workflow JavaScript node available modules list. For details, see "[JavaScript Node: Using External Modules](/workflow/nodes/javascript#using-external-modules)".
+Workflow JavaScript node available modules list. For details, see "[JavaScript Node: Using External Modules](/workflow/nodes/javascript#unsafe-mode-module-support)".
 
 ### WORKFLOW_LOOP_LIMIT
 

package/dist/ai/docs/nocobase/integration/api-keys/index.md

@@ -6,7 +6,7 @@
 
 ## Usage Instructions
 
-http://localhost:13000/admin/settings/api-keys/configuration
+https://example.com/admin/settings/api-keys
 
 
 ![](https://static-docs.nocobase.com/d64ccbdc8a512a0224e9f81dfe14a0a8.png)

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

@@ -10,12 +10,12 @@ This plugin is used to embed NocoBase pages into other websites or applications.
 
 ## Installation
 
-This is a commercial plugin. For detailed activation instructions, please refer to: [Commercial Plugin Activation Guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide)
+Enable the "Embed NocoBase" plugin in the plugin manager to use it.
 
 
 ## User Guide
 
-After activating the interface configuration, click "Copy embedded link" in the page's configuration menu (top right corner).
+After enabling the plugin, click "Copy embedded link" in the page's configuration menu (top right corner).
 
 
 ![](https://static-docs.nocobase.com/f11bd6d5e88d38731d7cd3cb149022c8.png)
@@ -27,4 +27,4 @@ After clicking, you will get a link that can be opened separately, for example,
 ![](https://static-docs.nocobase.com/9d847805a00fd07372a474665ec0e968.png)
 
 
-If you want to embed NocoBase pages into other websites or applications, user authentication is required, and the `token` needs to be appended to the link, for example, `https://example.com/embed/qs087rz4o2b?token=xxx`.
+If you want to embed NocoBase pages into other websites or applications, user authentication is required, and the `token` needs to be appended to the link, for example, `https://example.com/embed/qs087rz4o2b?token=xxx`.

package/dist/ai/docs/nocobase/multi-app/multi-app/app-block-and-switcher.md

@@ -0,0 +1,68 @@
+---
+pkg: '@nocobase/plugin-app-supervisor'
+title: 'Applications block and app switcher'
+description: 'Applications block and app switcher in multi-app: show sub-app entries on the frontend, configure app icons, visibility, and the app switcher in the upper-left corner.'
+keywords: 'multi-app,Applications block,app switcher,sub-app entry,NocoBase'
+---
+
+# Applications block and app switcher
+
+Besides managing sub-apps in the admin panel, multi-app can also provide app entries on the frontend. Common ways include:
+
+- Adding an "Applications" block to a page to display accessible sub-apps
+- Enabling the app switcher in the upper-left corner so users can switch between the main app and sub-apps
+
+## Applications block
+
+![](https://static-docs.nocobase.com/202605271350840.png)
+
+The "Applications" block displays a list of sub-apps on a frontend page. It is suitable for building a simple app portal, where end users can enter different business apps from one page.
+
+Each app in the block displays:
+
+- App icon
+- App name
+- Access entry
+
+Clicking an app opens the corresponding sub-app.
+
+### Configure app icons
+
+When creating or editing an app in App Supervisor, you can upload an app icon in "Display configuration".
+
+If no icon is uploaded, the system generates a default icon from the first letter of the app name, making apps easier to distinguish in the list.
+
+![](https://static-docs.nocobase.com/202605271402603.png)
+
+### Hide apps
+
+If an app should not appear in the frontend "Applications" block, select "Hide in Applications block" in the app configuration.
+
+After it is hidden:
+
+- The app can still be managed in the admin panel
+- The app can still be opened through its direct URL
+- It simply no longer appears in the frontend "Applications" block
+
+![](https://static-docs.nocobase.com/202605271403980.png)
+
+## App switcher
+
+![](https://static-docs.nocobase.com/202605271403304.png)
+
+The app switcher appears in the upper-left corner and is used to quickly switch to other apps.
+
+To show an app in the app switcher, enable "Show in app switcher" in the app configuration.
+
+After it is enabled, users can see the app switcher in the upper-left corner of the main app or sub-apps and enter other apps from the list.
+
+![](https://static-docs.nocobase.com/202605271404322.png)
+
+### Opening behavior
+
+The app switcher opens apps as follows:
+
+- From the main app to a sub-app: opens in a new tab
+- From one sub-app to another: opens in the current tab
+
+This avoids interrupting work in the main app while keeping switching between sub-apps natural.

package/dist/ai/docs/nocobase/multi-app/multi-app/app-sso.md

@@ -0,0 +1,71 @@
+---
+pkg: '@nocobase/plugin-app-supervisor'
+title: 'App SSO'
+description: 'App SSO in multi-app: automatically sign in to sub-apps from the main app or app switcher, with username mapping and automatic user signup.'
+keywords: 'multi-app,App SSO,automatic sign-in,app switcher,sub-app,NocoBase'
+---
+
+# App SSO
+
+App SSO simplifies the sign-in flow when users enter sub-apps in a multi-app setup.
+
+After it is enabled, when a user enters a sub-app from the main app entry or switches between sub-apps, the system attempts to automatically sign in to the target sub-app as the current user. Users do not need to enter their username and password repeatedly in each sub-app.
+
+## Use cases
+
+App SSO is suitable for the following scenarios:
+
+- The main app acts as a unified entry, and users enter different business sub-apps from it
+- A system is split into multiple business sub-apps, but the user sign-in experience should remain continuous
+- Users need to switch frequently between multiple sub-apps
+- User accounts are mapped between sub-apps by the same username
+
+## Enable App SSO
+
+Go to "App Supervisor", create or edit a sub-app, and enable "App SSO" in "Authentication configuration".
+
+After it is enabled, the sub-app can trigger automatic sign-in through the main app entry or the app switcher.
+
+> After changing authentication configuration, the sub-app usually needs to be restarted for the change to take effect.
+
+![](https://static-docs.nocobase.com/202605271406542.png)
+
+## Automatic user signup
+
+If the corresponding user does not exist in the target sub-app, you can enable "Automatically sign up when user does not exist".
+
+After it is enabled, when a user enters a sub-app through App SSO for the first time, the system creates a basic user in the sub-app from the user information in the main app.
+
+User mapping is mainly based on username. This means:
+
+- If the username is the same in the main app and sub-app, the user signs in as the corresponding sub-app user
+- If the username does not exist in the sub-app, the user is created only when automatic signup is enabled
+- If automatic signup is not enabled, the administrator needs to create the user in the sub-app in advance
+
+Roles and permissions after user creation are determined by the sub-app's own user and permission configuration.
+
+## Entries that trigger automatic sign-in
+
+App SSO is mainly triggered from:
+
+- Entering a sub-app from the main app's app entry
+- Entering a sub-app from the upper-left app switcher
+- Switching from one sub-app to another
+
+Directly visiting the sub-app sign-in page or the sub-app's own URL does not force the main app sign-in state. This preserves the sub-app's own sign-in methods and makes it possible to manage sub-app accounts separately when needed.
+
+## FAQ
+
+### Still not signed in automatically after enabling it?
+
+Check the following:
+
+- Whether App SSO is enabled for the sub-app
+- Whether the sub-app has been restarted so the authentication configuration takes effect
+- Whether the user entered from the main app entry or app switcher
+- Whether a user with the same username exists in the sub-app
+- If the user does not exist, whether automatic signup is enabled
+
+### Why does direct access to a sub-app not automatically sign in?
+
+This is expected. When directly visiting a sub-app, the sub-app may need to use its own sign-in method, so the main app sign-in state is not forced.

package/dist/ai/docs/nocobase/multi-app/multi-app/index.md

@@ -8,6 +8,14 @@ pkg: '@nocobase/plugin-app-supervisor'
 
 Multi-app management is a unified application management solution provided by NocoBase for creating and managing multiple physically isolated NocoBase application instances in one or more runtime environments. Through the AppSupervisor, users can create and maintain multiple applications from a unified entry point to meet the needs of different businesses and scale stages.
 
+Multi-app is suitable for the following scenarios:
+
+- Splitting a large system into multiple applications by business module, such as CRM, after-sales service, operations, and analytics
+- Letting teams develop by business line or module in parallel, reducing configuration and release impact between modules
+- Creating isolated applications for different customers, tenants, or organizations
+- Creating independent demo, test, or sandbox applications in batches
+- Assigning applications to different runtime environments as application count or load increases
+
 ## Single App
 
 In the early stages of a project, most users start with a single app.
@@ -63,4 +71,4 @@ For users, multiple applications can still be created and managed through a sing
 
 ![](https://static-docs.nocobase.com/202512231215186.png)
 
-This approach is suitable for SaaS platforms, large numbers of demo environments, or multi-tenant scenarios, improving system stability and maintainability while ensuring flexibility.
+This approach is suitable for SaaS platforms, large numbers of demo environments, or multi-tenant scenarios, improving system stability and maintainability while ensuring flexibility.