@nocobase/plugin-ai 3.0.0-alpha.5 → 3.0.0-alpha.7

package/dist/ai/docs/nocobase/ai-builder/ai-portal/index.md

@@ -0,0 +1,144 @@
+---
+title: "AI Portal Quick Start"
+description: "AI Portal building lets an AI Agent write your business system code, with NocoBase providing authentication, database, API, and permissions as the foundation. The code lives in an application entry called AI Portal."
+keywords: "AI Portal building,AI Builder,AI Portal,NocoBase AI,NocoBase foundation,frontend development,React,shadcn/ui,AI Agent,quick start"
+---
+
+# AI Portal Quick Start
+
+We found that AI vibe coding can produce a good-looking page, but it has a hard time connecting to a real business system — or it ends up reimplementing authentication, permissions, and collection design from scratch.
+
+NocoBase, as a low-code/no-code platform, already provides all of that. You can treat it as the foundation of your system kernel, letting the AI Agent focus on business logic while NocoBase supplies reliable authentication, database, API, and permission infrastructure.
+
+For this we provide an application entry called **AI Portal**. Its source code lives locally and is reserved for the AI Agent to write. Code written in this entry can access NocoBase's built-in capabilities directly, and the built pages are ready to visit.
+
+![AI Portal Settings](https://static-docs.nocobase.com/20260803154352.png)
+
+## What NocoBase provides
+
+When you build a business system, the time usually goes not into the pages but into everything behind them — user login, permission checks, collection design, CRUD APIs, file upload and download. Every system needs these, and building them from scratch each time doesn't pay off.
+
+NocoBase already provides all of them:
+
+- **Authentication** — Username and password login works out of the box. OIDC, SAML, CAS, LDAP, SMS, DingTalk, WeCom and others work once enabled on the server, and the frontend just needs to hook into them
+- **Database and multiple data sources** — Built-in collection management, plus connections to external data sources such as MySQL and PostgreSQL
+- **REST API** — Once a collection exists, its CRUD endpoints come with it, supporting filtering, sorting, pagination, and association fields
+- **Access control** — Role-based ACL down to the field and record level. The frontend can read the current user's permissions and decide what to show
+- **Workflow** — Business process automation, triggered from the frontend or by data changes
+- **File storage** — Upload and download
+
+![AI Portal Template](https://static-docs.nocobase.com/20260803161414.png)
+
+On top of these capabilities we built a standard [system template](https://github.com/nocobase/portal-template-default) that the AI Agent can copy to get a working application running. NocoBase also provides a set of Skills such as [Data Modeling](../data-modeling.md) and [ACL Configuration](../acl.md), so once you describe your business requirements, the AI Agent not only generates frontend pages but also creates the collections and configures the permissions, giving you a complete business system.
+
+## Prerequisites
+
+- NocoBase >= 3.0.0-alpha.6
+- Node.js >= 22
+- [pnpm](https://pnpm.io/installation) — the Portal template uses it to install dependencies and start the dev server
+- The alpha version of `nocobase cli` (**note: only the alpha version is supported for now**)
+  - `npm install -g @nocobase/cli@alpha`
+  - Plus a NocoBase application already initialized through `nb init --ui`. See the [AI Agent Integration Guide](../../ai/quick-start.md)
+- An AI Agent, such as Claude Code, Codex, or Cursor
+
+## Step 1: Confirm you already have an AI Portal
+
+First confirm the default `main` is there:
+
+```bash
+nb portal list
+```
+
+![nb portal list](https://static-docs.nocobase.com/20260803163517.png)
+
+The output lists the Portal name, access URL, Portal type, source storage, dev path, enabled status, and default status.
+
+After pulling the source, `info` gives you more detail, such as where the dev path and the deploy path each point:
+
+```bash
+nb portal info main
+```
+
+## Step 2: Start development mode
+
+```bash
+# Pull the portal source
+nb portal pull main
+# Start the dev server
+nb portal dev main
+```
+
+The dev server runs on `http://localhost:5173` by default.
+
+The template ships with a user management page built on NocoBase's `users` collection. Log in and take a look — it also makes a good starting sample for the AI to follow.
+
+![portal dev home page](https://static-docs.nocobase.com/20260802220652.png)
+
+## Step 3: Have the AI change a page
+
+Go into the Portal's dev workspace (`pull` puts it in `./main` by default; if you're not sure, check the dev path with `nb portal info main`), open your AI Agent there — Claude Code, Codex, Cursor, whichever — and give it a prompt:
+
+```
+Add a customer management page
+with a customer list, search by name, and a detail drawer that opens when a row is clicked
+```
+
+<!-- 需要一个视频，展示从输入提示词到 AI 完成页面编写、开发服务热更新出效果的完整过程 -->
+
+The AI reads through the existing pages and extensions, writes the new page following the template's conventions, and you'll see the result at `http://localhost:5173`.
+
+To learn how to work with an AI Agent effectively, see [Building with an AI Agent](./agent-workflow.md).
+
+## Step 4: Deploy
+
+Once the local changes look right, push the source to the remote, then build and deploy:
+
+```bash
+nb portal push main --message "Add customer management page"
+nb portal deploy main
+```
+
+Where `push` sends the source depends on this Portal's source storage setting. The default is `nocobase`, where NocoBase manages the source. If you set it to `git` with [`nb portal config`](../../api/cli/portal/config.md), `push` commits and pushes the source to the Git repository you specified, and `--message` becomes the Git commit message. See [Deployment and Source Management](./deploy.md#source-storage) for details.
+
+Once deployed, visit `/x/main/` to see your changes.
+
+That completes the full loop — describe what you need, the AI writes the code, you check it locally, then push and deploy.
+
+## When you need more entries
+
+An application can have several Portals. Internal staff use one, external customers another — pages and permissions stay fully separate while the data is shared:
+
+```bash
+nb portal create customer
+```
+
+Creating generates `./customer` in the current directory as the dev workspace, or you can point it elsewhere with `--path`. A new Portal is developed with `nb portal dev` and deployed with `nb portal deploy` just like the first one — go into its workspace and open your AI Agent. See [Deployment and Source Management](./deploy.md) for details.
+
+## Try the demo
+
+If you want to see AI Portal building in action, request a demo environment at https://demo.nocobase.com/new. After you fill in the form, we generate a dedicated demo environment for you, containing several AI Portal applications built on the NocoBase foundation.
+
+![AI Portal Settings](https://static-docs.nocobase.com/20260803154352.png)
+
+Then pick an AI Portal and go in:
+
+![AI Portal CRM](https://static-docs.nocobase.com/20260803154700.png)
+
+The Portal welcome page also gives you a prompt that lets your AI Agent connect to this AI Portal application directly, pull the application code, start a dev server locally, change pages, then push and deploy back to the demo environment. Refresh the page after a successful deployment and you'll see the result.
+
+## What's next
+
+- [Building with an AI Agent](./agent-workflow.md) — How to write prompts, and how to roll back when the AI gets it wrong
+- [Project Structure and Tech Stack](./project-structure.md) — The template's directory conventions and common commands
+- [Deployment and Source Management](./deploy.md) — Putting Portal source under Git, and multi-environment deployment
+
+## Related Links
+
+- [Building with an AI Agent](./agent-workflow.md) — Drive the AI to write Portal pages in natural language
+- [Project Structure and Tech Stack](./project-structure.md) — The template's directory conventions and common commands
+- [Standard Components and Extensions](./components.md) — The shadcn/ui component base and the extension mechanism
+- [Deployment and Source Management](./deploy.md) — The full develop, push, and deploy flow
+- [AI Agent Integration Guide](../../ai/quick-start.md) — Install NocoBase CLI and complete initialization
+- [AI Builder Quick Start](../index.md) — The other way to build, without writing code
+- [Version Control](../version-control.md) — Version snapshots for no-code building
+- [`nb portal` Command Reference](../../api/cli/portal/index.md) — Complete parameter reference for all Portal commands

package/dist/ai/docs/nocobase/ai-builder/ai-portal/project-structure.md

@@ -0,0 +1,128 @@
+---
+title: "Project Structure and Tech Stack"
+description: "The AI Portal template's tech stack, directory conventions, environment variables, and common commands, so you can tell whether the AI put its code in the right place."
+keywords: "AI Portal,project structure,tech stack,React,Vite,Refine,Tailwind CSS,shadcn/ui,environment variables"
+---
+
+# Project Structure and Tech Stack
+
+:::tip Prerequisites
+
+Before reading this page, make sure you have your first Portal running by following the [AI Portal Quick Start](./index.md).
+
+:::
+
+Most day-to-day development can be left to the AI. Still, knowing the template's structure lets you tell whether the AI put its code in the right place, and makes problems easier to locate.
+
+## Tech stack
+
+The Portal template is based on `@nocobase/portal-template-default`, with source at [nocobase/portal-template-default](https://github.com/nocobase/portal-template-default).
+
+| Technology | Purpose |
+| --- | --- |
+| React 19 + TypeScript | Frontend framework |
+| Vite | Dev server and build tool |
+| [Refine](https://refine.dev/docs/) | Data layer framework, handling resources, routing, forms, and permissions |
+| Tailwind CSS 4 | Styling |
+| [shadcn/ui](https://ui.shadcn.com/) | Component base, source owned by the project |
+| lucide | Icon library |
+| pnpm | Package manager |
+
+This combination is the frontend stack AI is most familiar with today, which makes what it writes more accurate.
+
+The Portal is a pure frontend project for now, with business logic handled through NocoBase's API, standard components, and so on. Support for having the AI Agent write Portal backend code is coming.
+
+## Directory structure
+
+```text
+src/
+├── app/            Routing and extension loading
+├── pages/          Login, registration, forgot password, and so on
+├── components/     Components
+│   ├── ui/         shadcn/ui component base
+│   ├── app-shell/  Layout, navigation, loading states
+│   ├── auth/       Authentication components
+│   └── ...
+├── extensions/     Extensions, active once installed
+├── lib/            NocoBase client wrapper and ACL logic
+├── providers/      Refine providers
+├── hooks/          Custom hooks
+└── locales/        Localized strings
+```
+
+A few key locations:
+
+- **`src/app/routes.tsx`** — Route structure. Authenticated and unauthenticated routes are separate, and routes provided by extensions are mounted automatically
+- **`src/app/extensions.tsx`** — Extension loading, using `import.meta.glob` to scan `src/extensions/*/extension.tsx`
+- **`src/providers/data.ts`** — Refine's data provider, translating Refine's query syntax into NocoBase API parameters
+- **`src/lib/nocobase/client.ts`** — `NocoBaseClient`, the low-level wrapper behind every request
+- **`src/components/ui/`** — 60-odd shadcn/ui components, ready to use
+
+Business pages usually go under `src/extensions/`, one directory per feature module. See [Standard Components and Extensions](./components.md).
+
+## Key files
+
+| File | Purpose |
+| --- | --- |
+| `AGENTS.md` | Development conventions for the AI Agent. You can add your own project rules here |
+| `components.json` | shadcn/ui configuration, including style, icon library, and path aliases |
+| `.env` / `.env.local` | Environment variables, refreshed automatically by `nb portal dev` and `deploy` |
+| `vite.config.ts` | Build configuration, including the API proxy used during development |
+
+## Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `NOCOBASE_API_URL` | NocoBase REST API root, **must end with `/api`**. Usually `/api` for same-origin deployments |
+| `NOCOBASE_PORTAL_BASE` | Public path the Portal is mounted at. `/` for local development, the actual deployment path such as `/x/main/` for builds |
+| `NOCOBASE_AUTHENTICATOR` | Authenticator name, `basic` by default |
+| `NOCOBASE_API_TOKEN` | Temporary token for development. Don't commit a real value |
+| `API_CLIENT_STORAGE_PREFIX` | Token storage prefix. Keep it aligned if the server customizes it |
+| `API_CLIENT_STORAGE_TYPE` | Token storage method, `localStorage` by default |
+| `API_CLIENT_SHARE_TOKEN` | Whether to share the token, `false` by default |
+
+`nb portal dev` and `nb portal deploy` write these for you, so you usually don't need to touch them. The last three only need aligning when the server has customized how auth tokens are stored.
+
+During development, if `NOCOBASE_API_URL` is an absolute address, Vite sets up a proxy to forward requests, so you don't have to deal with CORS yourself.
+
+## Common commands
+
+These are the ones you'll use day to day. Dependency installation, environment variable refreshing, and builds are all handled by the CLI behind the scenes:
+
+| Command | Purpose |
+| --- | --- |
+| `nb portal list` | See which Portals the current application has |
+| `nb portal info <portal>` | Check a Portal's dev path, deploy path, and access URL |
+| `nb portal create <portal>` | Create a new Portal's dev workspace from the template |
+| `nb portal pull <portal>` | Pull the remote Portal source into the local dev workspace |
+| `nb portal dev <portal>` | Start the local dev server and see changes live |
+| `nb portal push <portal>` | Push local source changes to the remote |
+| `nb portal deploy <portal>` | Build and deploy, making changes live for users |
+| `nb portal config <portal>` | Adjust source storage, Git settings, and the dev workspace path |
+| `nb portal destroy <portal>` | Delete the Portal record and its deployed files |
+
+For the full parameters of each command, see the [`nb portal` Command Reference](../../api/cli/portal/index.md).
+
+## Where the dev workspace lives
+
+A Portal's dev workspace goes into the directory you were in when you ran `nb portal create` or `nb portal pull`:
+
+```text
+./<portal>
+```
+
+You can point it elsewhere with `--path` when creating or pulling. The built deployment artifacts go somewhere else — under the target application's storage, kept in sync by `nb portal deploy`, and not something you normally deal with.
+
+If you're not sure where a Portal's dev workspace is, just check:
+
+```bash
+nb portal info main
+```
+
+## Related Links
+
+- [AI Portal Quick Start](./index.md) — Get your first AI-written frontend entry running
+- [Standard Components and Extensions](./components.md) — The shadcn/ui component base and the extension mechanism
+- [Deployment and Source Management](./deploy.md) — The build and deploy flow, and source storage
+- [Building with an AI Agent](./agent-workflow.md) — Drive the AI to write pages in natural language
+- [`nb portal info`](../../api/cli/portal/info.md) — Check where a Portal's dev workspace is

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

@@ -1,15 +1,64 @@
 ---
 title: "AI Builder Quick Start"
-description: "AI Builder is NocoBase's AI-assisted building capability. Through natural language, you can perform data modeling, UI configuration, workflow orchestration, and more, providing a more modern and efficient building experience."
-keywords: "AI Builder,NocoBase AI,Agent Skills,natural language building,low-code AI,quick start"
+description: "AI Builder is NocoBase's AI-assisted building capability. Use natural language for data modeling, UI building, workflow orchestration, and permission setup, through either no-code configuration or AI-written code."
+keywords: "AI Builder,NocoBase AI,Agent Skills,natural language building,low-code AI,AI Portal,quick start"
 ---
 
 # AI Builder Quick Start
 
-AI Builder is NocoBase's AI-assisted building capability — you can describe your requirements in natural language, and the AI will automatically handle data modeling, page configuration, permission setup, and more. It provides a more modern and efficient building experience.
+AI Builder is NocoBase's AI-assisted building capability — you describe your business requirements in natural language, and an AI Agent builds the system for you. It covers the whole chain, from data modeling, UI building, workflow orchestration, and permission setup through to going live.
+
+When it comes to **how the interface gets built**, there are two ways:
+
+- **AI + no-code Portal building** — The AI builds your interface through NocoBase's no-code configuration capabilities, producing configuration stored in the database. This suits standard CRUD and internal admin backends, and business users can keep adjusting it in the interface afterwards
+- **AI Portal building** — NocoBase provides the foundation (data, authentication, permissions, and more) while the AI Agent writes code locally, with output you can commit straight to Git. After building and deploying, it's reachable through the [AI Portal](./ai-portal/index.md). This suits custom interactions, complex business systems, and cases with specific visual requirements
+
+Either way, collections, permissions, and workflows go through the same set of Skills — while the AI Agent writes pages, it can create your collections and set up permissions along the way, building a complete business system step by step through conversation.
+
+## Choosing between the two
+
+Each of those two ways corresponds to an access entry. A NocoBase application can have several entries sharing the same data, and the access path tells you which is which:
+
+```text
+/v/<name>    no-code Portal
+/x/<name>    AI Portal
+```
+
+![two types of portal](https://static-docs.nocobase.com/20260804091849.png)
+
+The differences:
+
+| | no-code Portal | AI Portal |
+| --- | --- | --- |
+| Access path | `/v/<name>` | `/x/<name>` |
+| Where pages come from | Configured in the interface, with AI able to help change the configuration | React source, written by the AI Agent |
+| Output | Configuration stored in the database | Source you can commit to Git |
+| How you iterate | Click through the interface, or have the AI change the configuration | Change code, `dev` → `deploy` |
+| Version management | Snapshots through [Version Control](./version-control.md) | Git, or NocoBase source storage |
+| Interface freedom | Bound by block capabilities, with established patterns for layout and interaction | Whatever you want it to be |
+| Ready-made capabilities | Dashboard, calendar, kanban and other blocks work out of the box | The standard template code we provide, or whatever the AI Agent implements |
+| Learning curve | Requires knowing NocoBase blocks, fields, and so on | Requires some familiarity with working with AI Agents |
+| Suits | Standard CRUD, internal admin backends | Custom interactions, complex business systems, specific visual requirements |
+
+A no-code Portal is enough in these cases:
+
+- The page structure is very standard — a regular table plus a form, where configuring is faster than writing code
+- Business users who don't write code need to adjust pages themselves
+- You only want NocoBase's built-in block capabilities, such as dashboards, calendar views, and kanban views
+- You're building alone, or don't need several people building together
+
+For everything else we recommend building with the [AI Portal](./ai-portal/index.md). With no-code Portal building, the AI has too much context to learn — block types, configuration structures, linkage rules — and for business systems that need complex building, efficiency, maintainability, and team collaboration all fall short.
+
+So we took a different approach: **writing frontend code is what AI does best**, so let it do what it does best. NocoBase acts as the foundation of the system kernel, and the frontend is left to the AI. Same requirements, faster and better. **AI builds freely. NocoBase keeps it reliable.**
+
+The two modes can also be mixed: configure the internal admin backend quickly with a no-code Portal, and fine-tune the customer-facing portal with an AI Portal — both in the same application, sharing one set of data and users.
 
 ## Quick Start
 
+::: warning Note
+To try AI Portal building, install the alpha version of the NocoBase CLI (`npm install -g @nocobase/cli@alpha`).
+:::
+
 If you have already installed the [NocoBase CLI](../ai/quick-start.md), you can skip this step.
 
 ### One-Click AI Installation
@@ -23,7 +72,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli
+npm install -g @nocobase/cli@alpha
 nb init --ui
 ```
 
@@ -49,17 +98,19 @@ The AI automatically generated data tables for customers, contacts, opportunitie
 
 To learn more about data modeling, see [Data Modeling](./data-modeling).
 
-### Describe Pages in Business Language, AI Builds Them
+### Build a milestone, and the AI saves a restorable version for you
 
-No need to learn configuration rules — just say what kind of page you want. Search boxes, tables, filters — just describe them and they're done.
+After finishing a page, a set of data tables, or a workflow, let the AI save the current state as a version — if a configuration goes wrong, you can always roll back to the last clear milestone.
 
 ```
-Help me create a customer management page with a name search box and a customer table showing name, phone, email, and creation time
+Save the current build as a version: completed customer management page, filter area, and edit form configuration
 ```
 
-![Customer management page](https://static-docs.nocobase.com/20260420100608.png)
+![AI creates a version after building](https://static-docs.nocobase.com/20260611115804.png)
 
-To learn more about UI configuration, see [UI Configuration](./ui-builder).
+The AI won't save a version every time it changes a field; it only saves after completing and verifying a clear milestone, which keeps the version list easy to read and makes it easier to decide where to roll back to.
+
+To learn more about version control, see [Version Control](./version-control).
 
 ### Orchestrate Automated Workflows with One Sentence
 
@@ -73,41 +124,29 @@ Help me orchestrate a workflow that automatically deducts product inventory afte
 
 To learn more about workflows, see [Workflow Management](./workflow).
 
-### Data Tables, Pages, and Dashboards — All at Once
-
-:::warning Note
+### Describe Pages in Business Language, AI Builds Them
 
-The Solutions feature is currently in testing with limited stability, available for early access only.
+NocoBase provides an **AI Portal** and a **no-code Portal** by default. No need to learn configuration rules — just say what kind of page you want. Search boxes, tables, filters — just describe them and they're done.
 
-:::
+![portal manage](https://static-docs.nocobase.com/20260804104517.png)
 
-Describe your business scenario in one sentence, and the AI will build data tables, management pages, dashboards, and charts all at once.
+For building through a no-code Portal (the default Portal is named admin):
 
 ```
-Help me use nocobase-dsl-reconciler skill to build a ticket management system with a dashboard, ticket list, user management, and SLA configuration
+Help me create a customer management page in admin, with a name search box and a customer table showing name, phone, email, and creation time
 ```
 
-The AI first outputs a design plan, then builds everything at once after confirmation:
-
-![Ticket system design plan](https://static-docs.nocobase.com/20260420100420.png)
-
-![Ticket system build result](https://static-docs.nocobase.com/20260420100450.png)
-
-To learn more about building complete systems, see [Solutions](./dsl-reconciler).
-
-### Build a milestone, and the AI saves a restorable version for you
+![Customer management page](https://static-docs.nocobase.com/20260420100608.png)
 
-After finishing a page, a set of data tables, or a workflow, let the AI save the current state as a version — if a configuration goes wrong, you can always roll back to the last clear milestone.
+For building through an AI Portal (the default Portal is named main):
 
 ```
-Save the current build as a version: completed customer management page, filter area, and edit form configuration
+Help me create a customer management page in the main portal, with a search box and a customer table showing name, phone, and industry
 ```
 
-![AI creates a version after building](https://static-docs.nocobase.com/20260611115804.png)
+![portal page](https://static-docs.nocobase.com/20260803204422.png)
 
-The AI won't save a version every time it changes a field; it only saves after completing and verifying a clear milestone, which keeps the version list easy to read and makes it easier to decide where to roll back to.
-
-To learn more about version control, see [Version Control](./version-control).
+To learn more about UI configuration, see [UI Configuration](./ui-builder) or [AI Portal Building](./ai-portal/index.md).
 
 ## Security & Audit
 
@@ -115,7 +154,7 @@ Before letting an AI Agent operate NocoBase, we recommend understanding the auth
 
 ## NocoBase Skills
 
-[NocoBase Skills](https://github.com/nocobase/skills) are domain knowledge packages that can be installed into AI Agents, enabling AI to understand NocoBase's configuration system. NocoBase provides 9 Skills covering the entire building workflow:
+[NocoBase Skills](https://github.com/nocobase/skills) are domain knowledge packages that can be installed into AI Agents, enabling AI to understand NocoBase's configuration system. NocoBase provides several Skills covering the entire building workflow:
 
 - [Environment Management](./env-bootstrap) — Environment checks, installation, deployment, upgrades, and troubleshooting
 - [Data Modeling](./data-modeling) — Create and manage data tables, fields, and relationships
@@ -126,6 +165,7 @@ Before letting an AI Agent operate NocoBase, we recommend understanding the auth
 - [Plugin Management](./plugin-manage) — View, enable, and disable plugins
 - [Release Management](./publish) — Cross-environment releases, backup & restore, and migration
 - [Version Control](./version-control) — Save restorable versions after completed milestones
+- [AI Portal Building](https://github.com/nocobase/skills/blob/main/skills/nocobase-ai-builder/SKILL.md) - Have the AI Agent write code in an AI Portal to build system interfaces
 
 :::tip
 
@@ -135,6 +175,7 @@ NocoBase CLI automatically installs Skills during initialization (`nb init`), so
 
 ## Related Links
 
+- [AI Portal](./ai-portal/index.md) — The other way to build, with the AI Agent writing frontend code directly
 - [NocoBase CLI](../ai/quick-start.md) — Command-line tool for installing and managing NocoBase
 - [NocoBase CLI Reference](../api/cli/index.md) — Complete parameter reference for all commands
 - [AI Plugin Development](../ai-dev/index.md) — Develop NocoBase plugins with AI assistance

package/dist/ai/docs/nocobase/ai-builder/ui-builder.md

@@ -33,6 +33,7 @@ Cannot do:
 - Cannot design data table structures (use the [Data Modeling Skill](./data-modeling))
 - Cannot orchestrate workflows (use the [Workflow Management Skill](./workflow))
 - Cannot handle non-modern page (v1) navigation, only supports v2 pages.
+- Does not handle AI Portal frontend source (use [AI Portal](./ai-portal/index.md))
 
 ## Prompt Examples
 
@@ -98,3 +99,4 @@ If manual configuration and AI configuration are done simultaneously, they may i
 - [Data Modeling](./data-modeling) — Create and manage data tables, fields, and relationships with AI
 - [ACL Configuration](./acl) — Configure roles and data access permissions
 - [Workflow Management](./workflow) — Create, edit, and diagnose workflows
+- [AI Portal](./ai-portal/index.md) — The other way to go when a page needs custom code

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

@@ -25,7 +25,7 @@ Help me install NocoBase CLI and complete initialization: https://docs.nocobase.
 ### Manual Installation
 
 ```bash
-npm install -g @nocobase/cli
+npm install -g @nocobase/cli@alpha
 nb init --ui
 ```
 
@@ -99,4 +99,5 @@ Detailed descriptions and sample prompts for each capability -> [Supported Capab
 - [NocoBase CLI](../ai/quick-start.md) -- Command-line tool for installing and managing NocoBase
 - [NocoBase CLI Reference](../api/cli/index.md) -- Complete parameter documentation for all commands
 - [Plugin Development](../plugin-development/index.md) -- The complete guide to NocoBase plugin development
+- [AI Portal](../ai-builder/ai-portal/index.md) -- Have AI write frontend pages. A plugin extends NocoBase itself; a Portal builds a standalone entry on top of those capabilities
 - [AI Builder](../ai-builder/index.md) -- Build NocoBase applications with AI (no coding required)

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

@@ -39,7 +39,7 @@ The following command groups are shown in `nb --help`:
 | [`nb env`](./env/index.md)           | Manage NocoBase project environments, the current env, status, details, and runtime commands. |
 | [`nb license`](./license/index.md)   | Manage commercial licenses and licensed plugins.                                              |
 | [`nb plugin`](./plugin/index.md)     | Manage plugins in the selected NocoBase env.                                                  |
-| [`nb portal`](./portal/index.md)     | Manage portals: configure, create, develop, sync source, deploy, and destroy.                       |
+| [`nb portal`](./portal/index.md)     | Manage a Portal's local source directory: configure, create, develop, sync source, deploy, and destroy. |
 | [`nb scaffold`](./scaffold/index.md) | Generate scaffolding for NocoBase plugin development.                                         |
 | [`nb self`](./self/index.md)         | Check or update NocoBase CLI itself.                                                          |
 | [`nb session`](./session/index.md)   | Configure `NB_SESSION_ID` so the current env is isolated by shell or agent runtime.           |

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

@@ -1,12 +1,12 @@
 ---
 title: "nb portal config"
-description: "nb portal config command reference: update source storage and Git source configuration for a portal."
+description: "nb portal config command reference: update the development path, source storage, and Git source configuration for a portal."
 keywords: "nb portal config,NocoBase CLI,Portal"
 ---
 
 # nb portal config
 
-Update the local portal source configuration and sync it to the remote portal record when possible
+Update the portal development path, source storage, and Git source configuration
 
 ## Usage
 
@@ -21,6 +21,7 @@ nb portal config <portal> [flags]
 | `<portal>` | string | Portal name or slug |
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--path` | string | Portal development workspace directory. |
 | `--source-storage` | `nocobase` \| `git` | Where portal source code is managed. |
 | `--git-repo` | string | Git repository URL used with `--source-storage=git`. |
 | `--git-branch` | string | Git branch used with `--source-storage=git`. |
@@ -29,6 +30,7 @@ nb portal config <portal> [flags]
 ## Examples
 
 ```bash
+nb portal config customer --path ./portals/customer
 nb portal config customer --source-storage nocobase
 nb portal config customer --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
 nb portal config customer --git-branch main --git-path portals/customer
@@ -36,7 +38,7 @@ nb portal config customer --git-branch main --git-path portals/customer
 
 ## Notes
 
-Pass at least one configuration flag. The local workspace must already exist; use `nb portal create` or `nb portal pull` first. If the remote portal record exists, the configuration is synced to it; otherwise only `portal.config.json` is updated locally.
+Pass at least one configuration flag. `--path` updates the selected CLI env config. `--source-storage` and `--git-*` update the remote portal record options.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/create.md

@@ -23,24 +23,21 @@ nb portal create <portal> [flags]
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip cross-env confirmation. |
 | `--title` | string | Portal display title. |
+| `--path` | string | Portal workspace directory. Default: `./<portal>`. |
 | `--force` | boolean | Delete the existing workspace and recreate it. |
-| `--source-storage` | `nocobase` \| `git` | Where portal source code is managed. Default: `nocobase`. |
-| `--git-repo` | string | Git repository URL used with `--source-storage=git`. |
-| `--git-branch` | string | Git branch used with `--source-storage=git`. |
-| `--git-path` | string | Directory inside the Git repository; defaults to the repository root (`.`). |
 
 ## Examples
 
 ```bash
 nb portal create customer
+nb portal create customer --path ./portals/customer
 nb portal create customer --template @nocobase/portal-template-default
 nb portal create customer --env dev --yes
-nb portal create customer --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
 ```
 
 ## Notes
 
-The command writes `.env`, `.env.local`, and `portal.config.json`. If the template contains `package.json`, it runs `pnpm install`. Portal names must use lowercase letters, numbers, underscores, or hyphens, and start with a lowercase letter or number.
+The command writes `.env` and `.env.local`, stores the workspace path in the selected CLI env config, and runs `pnpm install` when the template contains `package.json`. Portal names must use lowercase letters, numbers, underscores, or hyphens, and start with a lowercase letter or number.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/deploy.md

@@ -31,7 +31,7 @@ nb portal deploy customer --env dev --yes
 
 ## Notes
 
-The command refreshes `.env` and `.env.local`, runs `pnpm build`, and expects `dist/index.html`. For `local` and `docker` envs, it syncs the portal record and uses the local or volume-mounted `dist`; for `http` envs, it uploads the packed `dist` through the API.
+The command refreshes `.env` and `.env.local`, builds from the development path stored in the selected CLI env config, and syncs deployment output to the target app storage. Source storage and Git settings are managed by `nb portal config` in the remote portal record.
 
 ## Related Commands
 

package/dist/ai/docs/nocobase/api/cli/portal/destroy.md

@@ -1,12 +1,12 @@
 ---
 title: "nb portal destroy"
-description: "nb portal destroy command reference: delete a portal record and its local workspace."
+description: "nb portal destroy command reference: delete a portal record and its deployed files."
 keywords: "nb portal destroy,NocoBase CLI,Portal"
 ---
 
 # nb portal destroy
 
-Delete the portal record and local workspace
+Delete the portal record and deployed files.
 
 ## Usage
 
@@ -21,19 +21,21 @@ nb portal destroy <portal> [flags]
 | `<portal>` | string | Portal name or slug. |
 | `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
 | `--yes`, `-y` | boolean | Skip confirmation prompts. |
-| `--force` | boolean | Ignore missing portal records or workspace directories. |
+| `--force` | boolean | Ignore missing portal records or deployment directories. |
+| `--delete-dev-path`, `-D` | boolean | Delete the portal development directory in addition to the deployed portal. |
 
 ## Examples
 
 ```bash
 nb portal destroy customer --yes
+nb portal destroy customer --delete-dev-path --yes
 nb portal destroy customer --env dev --yes
 nb portal destroy customer --force --yes
 ```
 
 ## Notes
 
-This command affects both the remote portal record and the local workspace. In non-interactive mode, pass `--yes`. Use `--force` to ignore missing records or local files.
+This command deletes the remote portal record and deployed files. The development directory is retained by default; pass `--delete-dev-path` to delete it as well. In non-interactive mode, pass `--yes`. Use `--force` to ignore missing records or deployment files.
 
 ## Related Commands