@nocobase/plugin-ai 3.0.0-alpha.6 → 3.0.0-alpha.8

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/model-selection.md

@@ -0,0 +1,120 @@
+---
+title: "LLM Selection"
+description: "Explore test results and selection guidance for using leading flagship models to build NocoBase applications, based on a standardized evaluation system covering data modeling, pages, permissions, and workflows."
+keywords: "NocoBase AI Builder,LLM selection,GPT,DeepSeek,Qwen,AI Agent,model evaluation"
+---
+
+# LLM Selection
+
+:::tip Key takeaway
+
+**Leading flagship models currently available on the market can all build the core of a NocoBase application.**
+
+Models differ in the completeness of their initial output, build time, and number of issues. Choose one based on the model services already available to you, network conditions in your region, cost, and your team's preferences.
+
+:::
+
+This evaluation used a standardized CRM requirement set (a sales opportunity and customer follow-up system) to validate the applications built by different models:
+
+| Evaluation dimensions | Standardized evaluation items |
+| :---: | :---: |
+| 14 | 61 |
+
+## Evaluation dimensions
+
+The evaluation covers NocoBase's core capabilities, configuration capabilities, and foundational components. It also checks whether each model can understand requirements and carry out the corresponding build tasks.
+
+| Capability | Evaluation focus |
+| --- | --- |
+| Data modeling | Collections, field types, relationships, required and unique constraints, and default values |
+| Pages and features | Navigation, lists, forms, details, search, filters, and dashboards |
+| Business logic | Status transitions, business validation, calculation rules, and consistency of related data |
+| Permissions and security | Roles, menu permissions, action permissions, data scopes, and field permissions |
+| Workflow automation | Triggers, nodes, conditional branches, notifications, data side effects, and failure retries |
+| User experience | Information architecture, form experience, action feedback, and responsive layouts |
+| Robustness | Invalid input, duplicate submissions, consistency on failure, data volume, and network recovery |
+| Requirements coverage | Whether explicit requirements and core business paths are fully implemented |
+| Reasonable extensions | Whether features proactively added by the model serve a clear business purpose |
+| Scope control | Whether the result contains duplicate, unused, or out-of-scope business modules |
+
+## Evaluation results
+
+| Evaluation dimension | GPT-5.6 Sol | DeepSeek-V4-Flash | Qwen3.8-Max | GPT-5.6 Luna |
+| --- | :---: | :---: | :---: | :---: |
+| Data modeling | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| Feature completion | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#d97706;font-weight:600">◐ Partial pass</span> |
+| Business logic | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| Permissions and security | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| Workflow automation | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| User experience | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#d97706;font-weight:600">◐ Partial pass</span> |
+| Robustness | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| Requirements coverage | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#d97706;font-weight:600">◐ Partial pass</span> |
+| Reasonable extensions | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| Scope control | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> | <span style="color:#15803d;font-weight:600">✓ Pass</span> |
+| **Build speed** | <span style="color:#2563eb;font-weight:700">Relatively fast</span> | <span style="color:#2563eb;font-weight:700">Relatively fast</span> | <span style="color:#d97706;font-weight:700">Slow</span> | <span style="color:#15803d;font-weight:700">Fastest</span> |
+| **Single-run quality score** | <span style="display:inline-block;min-width:42px;padding:2px 10px;border-radius:6px;color:#1d4ed8;background:#eff6ff;font-weight:800">90</span> | <span style="display:inline-block;min-width:42px;padding:2px 10px;border-radius:6px;color:#1d4ed8;background:#eff6ff;font-weight:800">91</span> | <span style="display:inline-block;min-width:42px;padding:2px 10px;border-radius:6px;color:#1d4ed8;background:#eff6ff;font-weight:800">90</span> | <span style="display:inline-block;min-width:42px;padding:2px 10px;border-radius:6px;color:#c2410c;background:#fff7ed;font-weight:800">77</span> |
+
+:::tip Single-run quality score
+
+The single-run quality score has a maximum of 100 points. One point is deducted for each bug found during the first complete acceptance check, providing an indication of the quality of the model's initial build. The model can resolve these issues through subsequent feedback and revisions.
+
+:::
+
+:::info Note on build time
+
+Build time is affected by factors such as computer hardware performance, dependency installation and Build compilation, model service response speed, and network conditions.
+
+:::
+
+## Evaluation item details
+
+The 61 standardized evaluation items are organized into three layers: 46 items for build result quality, 7 for requirements understanding and reasonable extensions, and 8 for build process efficiency. Every item uses consistent inspection methods and pass criteria.
+
+### Layer 1: Build result quality (46 items)
+
+<table style="table-layout: fixed; width: 100%;">
+  <colgroup><col style="width: 32%;" /><col style="width: 68%;" /></colgroup>
+  <thead><tr><th>Evaluation dimension</th><th>Standardized evaluation items</th></tr></thead>
+  <tbody>
+    <tr><td>Data modeling (8 items)</td><td><code>DM-01</code> Whether all required collections are created<br /><code>DM-02</code> Whether all required fields exist<br /><code>DM-03</code> Whether field types are correct<br /><code>DM-04</code> Whether one-to-one relationships can be created and used<br /><code>DM-05</code> Whether one-to-many relationships can be created and used<br /><code>DM-06</code> Whether many-to-many relationships can be created and used<br /><code>DM-07</code> Whether required, unique, and default-value rules take effect<br /><code>DM-08</code> Whether related data can be viewed and filtered</td></tr>
+    <tr><td>Feature completion (6 items)</td><td><code>FC-01</code> Whether all required pages and navigation entries are present<br /><code>FC-02</code> Whether records can be created, viewed, edited, and deleted<br /><code>FC-03</code> Whether core user journeys can be completed end to end<br /><code>FC-04</code> Whether key business actions are available<br /><code>FC-05</code> Whether search, filtering, and sorting are available<br /><code>FC-06</code> Whether dashboards contain the required content</td></tr>
+    <tr><td>Business logic (6 items)</td><td><code>BL-01</code> Whether opportunity status transition rules are correct<br /><code>BL-02</code> Whether business validation rules take effect<br /><code>BL-03</code> Whether calculated fields and statistical definitions are correct<br /><code>BL-04</code> Whether data is mapped correctly after lead conversion<br /><code>BL-05</code> Whether updates to related records remain consistent<br /><code>BL-06</code> Whether deletion and archiving rules are correct</td></tr>
+    <tr><td>Permissions and security (7 items)</td><td><code>ACL-01</code> Whether all required roles are created<br /><code>ACL-02</code> Whether test users and role assignments are correct<br /><code>ACL-03</code> Whether page and menu access permissions are correct<br /><code>ACL-04</code> Whether data operation permissions are correct<br /><code>ACL-05</code> Whether record-level data scopes are correct<br /><code>ACL-06</code> Whether field-level view and edit permissions are correct<br /><code>ACL-07</code> Whether role changes and combined roles behave correctly</td></tr>
+    <tr><td>Workflow automation (7 items)</td><td><code>WF-01</code> Whether all required workflows are created and enabled<br /><code>WF-02</code> Whether workflow triggers are designed correctly<br /><code>WF-03</code> Whether node order and data transfer are correct<br /><code>WF-04</code> Whether conditions and branch results are correct<br /><code>WF-05</code> Whether record read/write side effects are correct<br /><code>WF-06</code> Whether notification recipients and content are correct<br /><code>WF-07</code> Whether failure logs and retry behavior are traceable</td></tr>
+    <tr><td>User experience (7 items)</td><td><code>UX-01</code> Whether navigation and information architecture are clear<br /><code>UX-02</code> Whether list information and common actions are easy to use<br /><code>UX-03</code> Whether form grouping, order, and guidance are clear<br /><code>UX-04</code> Whether detail pages support understanding and follow-up actions<br /><code>UX-05</code> Whether action feedback and status changes are clear<br /><code>UX-06</code> Whether the application is usable at different screen widths<br /><code>UX-07</code> Whether empty, loading, and error states are complete</td></tr>
+    <tr><td>Robustness (5 items)</td><td><code>ROB-01</code> Whether invalid and boundary inputs are handled safely<br /><code>ROB-02</code> Whether duplicate submissions cause duplicate side effects<br /><code>ROB-03</code> Whether data remains consistent when execution fails<br /><code>ROB-04</code> Whether the application remains usable with empty and large datasets<br /><code>ROB-05</code> Whether the application can recover after a session or network interruption</td></tr>
+  </tbody>
+</table>
+
+### Layer 2: Requirements understanding and reasonable extensions (7 items)
+
+<table style="table-layout: fixed; width: 100%;">
+  <colgroup><col style="width: 32%;" /><col style="width: 68%;" /></colgroup>
+  <thead><tr><th>Evaluation dimension</th><th>Standardized evaluation items</th></tr></thead>
+  <tbody>
+    <tr><td>Requirements coverage (3 items)</td><td><code>COV-01</code> Whether all pages and actions requested in the prompt are implemented<br /><code>COV-02</code> Whether all data, permissions, and workflows requested in the prompt are implemented<br /><code>COV-03</code> Whether capabilities required by the main process but not individually specified in the prompt are present</td></tr>
+    <tr><td>Reasonable extensions (2 items)</td><td><code>EXT-01</code> Whether proactively added fields, relationships, and rules are necessary<br /><code>EXT-02</code> Whether proactively added pages, actions, and statistics serve a clear purpose</td></tr>
+    <tr><td>Scope control (2 items)</td><td><code>SCOPE-01</code> Whether duplicate or unused features and configurations are generated<br /><code>SCOPE-02</code> Whether business modules unrelated to the task scope are added</td></tr>
+  </tbody>
+</table>
+
+### Layer 3: Build process efficiency (8 items)
+
+<table style="table-layout: fixed; width: 100%;">
+  <colgroup><col style="width: 32%;" /><col style="width: 68%;" /></colgroup>
+  <thead><tr><th>Evaluation dimension</th><th>Standardized evaluation items</th></tr></thead>
+  <tbody>
+    <tr><td>Time to first usable result (1 item)</td><td><code>EFF-FIRST-01</code> Time required to reach the first usable result</td></tr>
+    <tr><td>Convergence efficiency (3 items)</td><td><code>EFF-FINAL-01</code> Number of iterations required to reach final acceptance<br /><code>EFF-FINAL-02</code> Total time required to reach the final state<br /><code>EFF-FINAL-03</code> Tokens consumed to reach the final state</td></tr>
+    <tr><td>Human intervention (1 item)</td><td><code>EFF-HUMAN-01</code> Number of human interventions during the evaluation</td></tr>
+    <tr><td>Repeatability (3 items)</td><td><code>EFF-STABLE-01</code> Whether repeated runs of the same task produce consistent acceptance results<br /><code>EFF-STABLE-02</code> Whether collections, relationships, roles, and workflows are consistent across three runs<br /><code>EFF-STABLE-03</code> Whether variation in iterations and time remains controlled</td></tr>
+  </tbody>
+</table>
+
+## Next steps
+
+- [Build collaboratively with an AI Agent](./agent-workflow.md) — Describe pages and interactions in natural language and iterate continuously with an AI Agent
+- [AI Portal quick start](./index.md) — Create and run your first AI Portal
+- [Data modeling](../data-modeling.md) — Create collections, fields, and relationships with natural language
+- [Workflow management](../workflow.md) — Create, edit, enable, and diagnose workflows
+- [Permission configuration](../acl.md) — Manage roles, permission policies, user assignments, and risk assessments

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.           |