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

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

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

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

@@ -78,7 +78,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
 ```
 

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

@@ -76,7 +76,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
 ```
 

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

@@ -96,7 +96,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
 ```
 

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

@@ -2,8 +2,8 @@
 pageType: home
 pageName: ai
 title: 'NocoBase AI'
-description: 'NocoBase AI Capabilities: AI Building & Development, AI Employees, AI Agent Integration, AI Tools & Resources.'
-keywords: 'NocoBase AI,AI Building,AI Employees,AI Development,AI Agent,NocoBase CLI,Skills,MCP'
+description: 'NocoBase AI Capabilities: AI Building, AI Employees, AI Agent Integration, AI Tools & Resources.'
+keywords: 'NocoBase AI,AI Building,AI Portal,AI Employees,AI Development,AI Agent,NocoBase CLI,Skills,MCP'
 features:
   - title: Get Started
     details: Install CLI, connect your app, start building — everything starts here.
@@ -21,7 +21,7 @@ features:
         details: Use AI to assist NocoBase plugin development, covering the full process from scaffolding and component code to business logic.
         link: /ai-dev
 
-  - title: AI Building & Development
+  - title: AI Building
     details: Build NocoBase applications and plugins with AI — from natural language descriptions to working systems or plugin code.
     items:
       - title: AI Building Quick Start
@@ -65,28 +65,6 @@ features:
         details: Connect AI employees in workflow nodes to enable automated intelligent decision-making and content generation.
         link: /ai-employees/workflow/nodes/employee/configuration
 
-  - title: Connect Your AI Agent
-    details: Your favorite AI Agent can now operate NocoBase too.
-    items:
-      - title: 'OpenClaw + NocoBase: The Most Popular AI Agent Working for You'
-        details: The world's most popular open-source AI Agent — let OpenClaw be your 24/7 NocoBase operator.
-        link: /ai/openclaw
-      - title: 'Hermes Agent: A NocoBase Assistant That Learns as You Use It'
-        details: Automatically distills successful experiences into reusable skills, understanding your business system better over time.
-        link: /ai/hermes-agent
-      - title: 'Go Hands-Free with WorkBuddy Driving NocoBase'
-        details: Made by Tencent, 20+ built-in skills, supporting WeCom, Lark, and multi-platform remote control of NocoBase.
-        link: /ai/workbuddy
-      - title: 'Claude Code + NocoBase: The Strongest AI Brain, Your NocoBase Chief Architect'
-        details: A powerful AI architect — understands project context and builds NocoBase as naturally as writing code.
-        link: /ai/claude-code
-      - title: 'Use Codex to Operate NocoBase for Both Building and Development'
-        details: Made by OpenAI, powered by GPT series, builds NocoBase in a secure sandbox where every step is controllable.
-        link: /ai/codex
-      - title: 'OpenCode + NocoBase: Open Source, Free, Vendor-Unlocked NocoBase Building'
-        details: Both driven by open-source communities, freely switch between models — the developer's choice for freedom.
-        link: /ai/opencode
-
   - title: AI Tools & Resources
     details: The infrastructure supporting NocoBase AI capabilities — CLI, Skills, and MCP.
     items:
@@ -96,6 +74,9 @@ features:
       - title: NocoBase Skills
         details: Domain knowledge packages installable into AI Agents, enabling AI to understand NocoBase's capabilities and conventions.
         link: /ai-builder#nocobase-skills
+      - title: nb portal Command Reference
+        details: All the commands for managing a Portal — create, develop, sync source, and deploy.
+        link: /api/cli/portal/
       - title: NocoBase MCP
         details: Model Context Protocol integration, enabling AI Agents to interact with NocoBase through a standardized protocol.
         link: /ai/mcp/

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

@@ -16,7 +16,7 @@ description: Install NocoBase CLI and quickly create a new NocoBase application
 Install NocoBase CLI globally first:
 
 ```bash
-npm install -g @nocobase/cli
+npm install -g @nocobase/cli@alpha
 nb --version
 ```
 

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

@@ -84,7 +84,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
 ```
 

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

@@ -78,7 +78,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
 ```
 

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

@@ -25,6 +25,7 @@ Before getting started, make sure the following environment requirements are met
 
 - Node.js >= 22
 - Yarn 1.x
+- pnpm (only needed when developing an [AI Portal](../ai-builder/ai-portal/index.md), where the Portal template uses it to install dependencies and start the dev server)
 - We recommend using AI Agents powered by leading large models such as Claude or GPT. Results depend heavily on the model used — for the best experience, choose the latest flagship model available.
 
 import { Tab, Tabs } from '@rspress/core/theme';
@@ -41,7 +42,7 @@ If you don't have a NocoBase application yet, you can use CLI to install and ini
 #### Step 1: Install CLI
 
 ```bash
-npm install -g @nocobase/cli
+npm install -g @nocobase/cli@alpha
 nb --version // Confirm successful installation
 ```
 
@@ -100,7 +101,7 @@ If you already have a running NocoBase instance, you can connect AI Agent to it
 #### Step 1: Install CLI
 
 ```bash
-npm install -g @nocobase/cli
+npm install -g @nocobase/cli@alpha
 nb --version // Confirm successful installation
 ```
 
@@ -145,6 +146,10 @@ After configuration is complete, restart your AI Agent session and you can start
 
 ## What's Next
 
+### Start AI Building
+
+Describe your requirements in natural language, and AI helps you complete data modeling, page building, and workflow orchestration — replace manual configuration with conversation, no coding required. See [AI Building Quick Start](../ai-builder/index.md#replace-manual-configuration-with-conversation).
+
 ### Production Installation and Deployment
 
 If you're preparing to deploy NocoBase to production, this order usually works best:
@@ -156,13 +161,9 @@ If you're preparing to deploy NocoBase to production, this order usually works b
 
 If you need to manage existing NocoBase instances (such as test or production environments), or switch between multiple environments, see [Environment Management](../ai-builder/env-bootstrap) — covering environment checks, adding environments, upgrades, and troubleshooting.
 
-### Start AI Building
-
-Describe your requirements in natural language, and AI helps you complete data modeling, page building, and workflow orchestration — replace manual configuration with conversation. See [AI Building Quick Start](../ai-builder/index.md#replace-manual-configuration-with-conversation).
-
 ### Continue with AI Plugin Development
 
-If you need to develop custom plugins, AI can help too — from scaffolding generation to component code and business logic, covering the full plugin development process. See [AI Plugin Development](../ai-dev/index.md#from-a-single-sentence-to-a-complete-plugin).
+If you need to develop custom plugins, AI can help too — from scaffolding generation to component code and business logic, covering the full plugin development process. See [AI Plugin Development](../ai-dev/index.md#from-one-sentence-to-a-complete-plugin).
 
 ### Use AI Employees
 
@@ -174,6 +175,7 @@ If you already have a NocoBase application running, or have successfully complet
 
 ## Related Links
 
+- [AI Portal](../ai-builder/ai-portal/index.md) — Have the AI Agent write frontend code with NocoBase as the foundation, and build a complete system
 - [AI Building](../ai-builder/index.md) — Build NocoBase applications from scratch with AI
 - [AI Plugin Development](../ai-dev/index.md) — Develop NocoBase plugins with AI assistance
 - [AI Employees](../ai-employees/index.md) — Collaborate with AI in the business interface

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

@@ -91,7 +91,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
 ```
 

package/dist/ai/docs/nocobase/ai-builder/ai-portal/agent-workflow.md

@@ -0,0 +1,153 @@
+---
+title: "Building with an AI Agent"
+description: "Drive an AI Agent to write AI Portal frontend pages in natural language, including how to write prompts, collaboration tips, and how to handle common problems."
+keywords: "AI Portal,AI Agent,collaborative building,prompts,nocobase-portal-manage,Skills"
+---
+
+# Building with an AI Agent
+
+:::tip Prerequisites
+
+Before reading this page, make sure you have your first Portal running by following the [AI Portal Quick Start](./index.md).
+
+:::
+
+Day-to-day AI Portal development is a conversation with an AI Agent — you describe the page you want, it writes the code, you check the result in the browser.
+
+## Work inside the Portal directory
+
+Before you start, go into the Portal's source directory and open your AI Agent there. That way the Agent starts out in the right context, with access to `AGENTS.md` and the existing code.
+
+First find out where the directory is:
+
+```bash
+nb portal info main
+```
+
+The dev path in the output is where the Portal source lives. `cd` there, then open your AI Agent:
+
+```bash
+cd <dev workspace directory>
+```
+
+After that, just describe what you need:
+
+```
+Add an order list page to the main portal of my nocobase app
+```
+
+## Have the AI read before it writes
+
+There's an `AGENTS.md` at the root of the template describing this project's conventions: prefer reusing what's already in `src/extensions`, customize UI components through composition rather than editing the base components, and don't bring in Ant Design. AI Agents that read this file follow these conventions automatically.
+
+You can also add your own project's conventions to `AGENTS.md` — naming habits, business terminology, directories to leave alone. Once they're in there they apply to every conversation, so you don't have to repeat yourself.
+
+`src/extensions` contains a few built-in extensions. Among them, `nocobase-users-example` is a complete CRUD page with list, create, edit, and detail views. Pointing the AI at it beats describing a new page from scratch:
+
+```
+Build a product management page following the pattern in nocobase-users-example
+```
+
+## Prompt examples
+
+### Scenario A: Create a new business page
+
+Three things are enough — what's on the page, where the data comes from, and how it behaves:
+
+```
+Add a customer management page:
+the table shows name, phone, email, and creation time, with search by name,
+clicking a row opens a detail drawer where the record can be edited and saved
+```
+
+<!-- 需要一张 AI 生成的客户管理页面效果截图，展示表格、搜索框和详情抽屉 -->
+
+### Scenario B: Modify an existing page
+
+For a change request, be specific about what changes. No need to describe the whole page again:
+
+```
+Add a status filter to the customer list,
+with the options "Following up", "Won", and "Lost", unfiltered by default
+```
+
+<!-- 需要一张添加状态筛选后的页面截图 -->
+
+### Scenario C: Wire up a new collection
+
+Once a collection exists, have the AI generate the matching pages. It reads the field definitions and picks form controls and list columns accordingly:
+
+```
+I just created a contracts collection, build me a matching set of CRUD pages
+```
+
+If the collection doesn't exist yet, use [Data Modeling](../data-modeling.md) to have the AI design the data structure first, then come back to the pages.
+
+<!-- 需要一张根据数据表自动生成的增删改查页面截图 -->
+
+### Scenario D: Reproduce a design
+
+When you have a design file or an existing HTML prototype, hand it to the AI:
+
+```
+Build the home page from this prototype,
+keep the colors and layout the same, and connect the data to the orders collection
+```
+
+<!-- 需要一个视频，展示给出原型图后 AI 复刻出页面的过程 -->
+
+### Scenario E: Add an authentication method
+
+Once an authentication method is enabled on the server, the login page needs matching frontend support:
+
+```
+DingTalk login is enabled in NocoBase, add a DingTalk login button to the login page
+```
+
+<!-- 需要一张登录页出现第三方登录按钮的截图 -->
+
+## Collaboration tips
+
+**Iterate in small steps.** Have the AI do one page or one change at a time, and check the result before moving on. If you describe five pages in one go, it's hard to tell which step went off the rails when something breaks.
+
+**Leave the dev server running.** `nb portal dev main` hot-reloads, so you see the result right after each change the AI makes. That's the shortest feedback loop you can get.
+
+**Give it the exact error.** A blank page, a failed build, a 403 from an API — paste the full error message and a screenshot to the AI instead of making it guess. A few rounds usually sort it out. You don't need to work out which layer the problem is in first.
+
+![error](https://static-docs.nocobase.com/20260803204308.png)
+
+## Common questions
+
+**How do I roll back when the AI gets it wrong?**
+
+If the Portal source is under Git, `git checkout` is all you need. With the default `nocobase` source storage, you can pull a fresh copy from source storage over the local one:
+
+```bash
+nb portal pull main --force
+```
+
+`--force` deletes the dev workspace and pulls again, so make sure there's nothing you want to keep before running it. To avoid that trade-off, move the source to Git early on — see [Deployment and Source Management](./deploy.md).
+
+**How do I troubleshoot a failed build?**
+
+Run a build locally first to see the full error:
+
+```bash
+nb portal deploy main
+```
+
+TypeScript type errors and missing dependencies are the two most common causes. Paste the error to the AI and let it fix them.
+
+**Do my manual edits conflict with the AI's?**
+
+No. The Portal source is an ordinary frontend project — you can edit it yourself whenever you want, and let the AI pick up from there. As long as you're not both editing the same file at the same moment, there's no problem.
+
+## Related Links
+
+- [AI Portal Quick Start](./index.md) — Get your first AI-written frontend entry running
+- [Deployment and Source Management](./deploy.md) — Putting Portal source under Git, and the deployment flow
+- [Project Structure and Tech Stack](./project-structure.md) — The template's directory conventions, so you can tell whether the AI got it right
+- [Standard Components and Extensions](./components.md) — The shadcn/ui component base and the extension mechanism
+- [Data Modeling](../data-modeling.md) — Have the AI design the collections before building pages
+- [`nb portal info`](../../api/cli/portal/info.md) — Check where a Portal's dev workspace is
+- [`nb portal pull`](../../api/cli/portal/pull.md) — Pull the source again from source storage

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

@@ -0,0 +1,134 @@
+---
+title: "Standard Components and Extensions"
+description: "The AI Portal's shadcn/ui component base and its extension mechanism — one directory per extension, discovered and mounted automatically."
+keywords: "AI Portal,shadcn/ui,components,extensions,AppExtension,Registry,Tailwind CSS"
+---
+
+# Standard Components and Extensions
+
+:::tip Prerequisites
+
+Before reading this page, make sure you have your first Portal running by following the [AI Portal Quick Start](./index.md).
+
+:::
+
+A Portal's interface has two parts: `src/components/ui` provides the base components, and `src/extensions` holds the business modules. This page covers how to use both.
+
+## Component base
+
+`src/components/ui` has 60-odd [shadcn/ui](https://ui.shadcn.com/) components — buttons, forms, dialogs, drawers, tables, charts, all the common ones. The style is configured in `components.json`, and the icons come from lucide.
+
+Unlike pulling in a component library, **the source of these components belongs to your project**. They sit in your repository, you can change them freely, and upstream updates never overwrite them.
+
+Because of that, customize through composition rather than by editing them directly:
+
+```tsx
+// Recommended: wrap it, so the base component stays replaceable
+import { Button } from "@/components/ui/button";
+
+export function SubmitButton(props) {
+  return <Button variant="default" size="lg" {...props} />;
+}
+```
+
+Editing `src/components/ui/button.tsx` directly works too, but it makes picking up upstream bug fixes harder later. When you do need to change a base component, compare against the upstream version first and merge selectively instead of overwriting your local changes wholesale.
+
+:::warning Note
+
+Don't bring Ant Design, or NocoBase's Ant Design-based client components, into a Portal. The Portal's styling is Tailwind CSS plus shadcn/ui, and mixing them causes style conflicts. This convention is already written into the template's `AGENTS.md`.
+
+:::
+
+## Extension mechanism
+
+Business features are written as extensions under `src/extensions/`, one directory per feature module:
+
+```text
+src/extensions/
+├── nocobase-acl/               Permission components
+├── nocobase-ai/                AI conversation capabilities
+├── nocobase-route-surfaces/    Page, drawer, and modal route surfaces
+└── nocobase-users-example/     User management example
+```
+
+Each directory has an `extension.tsx` with a default export of an `AppExtension`. The template scans and loads them automatically — **drop it into the directory and it works, with no registration code to change**.
+
+## AppExtension
+
+An extension can provide these:
+
+| Field | Description |
+| --- | --- |
+| `id` | Extension identifier, required |
+| `priority` | Load order, lower numbers first, 100 by default |
+| `resources` | Refine resource definitions, determining the navigation menu and route mapping |
+| `routes` | Route elements, mounted under the authenticated route tree |
+| `Provider` | A Provider wrapping the whole application |
+| `AuthRuntimeProvider` | Authentication runtime Provider, active before login |
+| `UserMenuItems` | Entries to add to the user menu |
+| `authAdapters` | Authentication method adapters |
+| `dev` | Resources and routes that only apply in development mode |
+
+A minimal extension looks like this:
+
+```tsx
+import type { AppExtension } from "@/app/extension";
+import { Route } from "react-router";
+import { Package } from "lucide-react";
+import { ProductList } from "./list";
+
+const productsExtension: AppExtension = {
+  id: "products",
+  resources: [
+    {
+      name: "products",
+      list: "/products",
+      meta: {
+        label: "Products",
+        icon: <Package />,
+        acl: { type: "collection" }, // Takes part in NocoBase's collection permission checks
+      },
+    },
+  ],
+  routes: <Route path="/products" element={<ProductList />} />,
+};
+
+export default productsExtension;
+```
+
+## Built-in extensions
+
+The template ships with four extensions. They're ready to use, and they're also the best reference when writing new code:
+
+**`nocobase-users-example`** — A complete CRUD module on NocoBase's standard `users` collection, with list, create, edit, and detail views. Point the AI at it when building a new page.
+
+**`nocobase-acl`** — Permission components: `CanAccess`, `AclPage`, `AclRegion`, `AclField`, and `RoleSwitcher`.
+
+**`nocobase-route-surfaces`** — Three route surfaces: full page, drawer, and modal. The same content can open as a standalone page or pop out as a drawer inside a list page, with route state staying in sync.
+
+**`nocobase-ai`** — Brings NocoBase's AI conversation capabilities to the frontend, including the chat window, streaming, conversation history, and page context. Use it to build an AI assistant into your own Portal.
+
+## Import rules
+
+Two path conventions apply when writing an extension:
+
+- Use the `@/` alias for anything from the host application, such as `@/components/ui/button`
+- Keep relative imports inside the extension from reaching outside its own directory
+
+That keeps every extension self-contained, so you can copy the whole directory into another Portal and keep using it.
+
+## Installable official extensions
+
+<!-- Registry 的对外地址和可安装项清单待定，确定后补充这一节：怎么安装、有哪些可选扩展、安装后源码落在哪里 -->
+
+Besides the four built-in ones, NocoBase will provide a set of official extensions you can install as needed. Once installed, the source lands under `src/extensions/` and becomes your project's own code just like a built-in extension, ready to modify and commit with the application.
+
+## Localization
+
+Strings live in `src/locales/`, and the template ships with English and Chinese. An extension can have its own language pack too — create a `locales/` directory inside the extension and import it from `extension.tsx`.
+
+## Related Links
+
+- [AI Portal Quick Start](./index.md) — Get your first AI-written frontend entry running
+- [Project Structure and Tech Stack](./project-structure.md) — The full directory conventions and common commands
+- [Building with an AI Agent](./agent-workflow.md) — Have the AI follow a built-in extension when writing a new module

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

@@ -0,0 +1,164 @@
+---
+title: "Deployment and Source Management"
+description: "The full develop, push, and deploy flow for an AI Portal, plus the two source storage modes and multi-environment deployment."
+keywords: "AI Portal,deployment,source storage,Git,nb portal deploy,nb portal push,multi-environment"
+---
+
+# Deployment and Source Management
+
+:::tip Prerequisites
+
+Before reading this page, make sure you have your first Portal running by following the [AI Portal Quick Start](./index.md).
+
+:::
+
+Portal source lives in three places: the local dev workspace, source storage, and the deployed artifacts. `nb portal` keeps them in sync.
+
+## The full lifecycle
+
+The day-to-day loop looks like this:
+
+```text
+dev (local development) → push (push source) → deploy (build and deploy)
+```
+
+Where:
+
+1. `nb portal dev <portal>` — Start the local dev server, change code and see the result
+2. `nb portal push <portal>` — Push local source changes to source storage
+3. `nb portal deploy <portal>` — Build and deploy, making changes live for users
+
+If you're picking up a Portal a colleague already created, or you've switched machines, pull it locally first:
+
+```bash
+nb portal list                 # See which Portals exist
+nb portal pull customer        # Pull the source locally
+nb portal dev customer         # Start developing
+```
+
+`pull` downloads and unpacks the source into the dev workspace, `./<portal>` by default, or elsewhere with `--path`. Dependencies are installed automatically; add `--no-install` to skip that in CI or when you'd rather install them yourself.
+
+After a successful pull, the dev workspace location is recorded in the CLI env config, so `dev`, `push`, and `deploy` all read the source from there without you specifying it every time.
+
+## Adding a Portal
+
+An application can have several Portals with separate pages and permissions but shared data. Say one entry for internal staff and one for external customers:
+
+```bash
+nb portal create customer
+```
+
+Creating generates `./customer` in the current directory as the dev workspace from the `@nocobase/portal-template-default` template, writes `.env` and `.env.local`, then installs dependencies. Use `--path` to put it elsewhere.
+
+<!-- 需要一张 nb portal create 执行完成后的终端输出截图 -->
+
+A Portal name can only contain lowercase letters, digits, underscores, and hyphens, and must start with a lowercase letter or digit.
+
+## source storage
+
+Portal source can be kept in two places:
+
+| Mode | Description | When to use |
+| --- | --- | --- |
+| `nocobase` | The default, with source managed by NocoBase's source storage | Getting started quickly, solo development, no code review needed |
+| `git` | Source saved to a Git repository you specify | Team collaboration, code review, CI integration |
+
+The default `nocobase` is the fastest to start with, since you don't need a repository first. It has no version history though, so a bad change can only be rolled back by overwriting everything. **If this Portal will be iterated on long term, move it to Git early.**
+
+### Switching to Git
+
+`create` only generates the dev workspace; source storage configuration goes through `config`. You can switch any time after creating:
+
+```bash
+nb portal config customer \
+  --source-storage git \
+  --git-repo git@github.com:nocobase/customer-portal.git
+
+nb portal push customer --message "Move customer portal source to Git"
+```
+
+`config` syncs the source storage setting to the remote Portal record, and subsequent `push` calls go through Git.
+
+With one Portal per repository, the default repository root works fine for `--git-path`. You only need a subdirectory when you want several Portals in the same repository:
+
+```bash
+nb portal config customer --git-path portals/customer
+```
+
+### Pulling from another repository temporarily
+
+To try out source from another repository without changing the Portal's configuration, `pull` accepts a one-off override:
+
+```bash
+nb portal pull customer --git-repo git@github.com:nocobase/another-portal.git
+```
+
+This doesn't modify the remote Portal record, and `--git-branch` and `--git-path` can only be used together with `--git-repo`. To switch to Git storage permanently, use `config` as above.
+
+`config` can also change where the dev workspace lives — after moving the source to another directory, tell the CLI its new location with `--path`:
+
+```bash
+nb portal config customer --path ./workspaces/customer
+```
+
+## Differences between env types
+
+`nb portal` synchronizes differently depending on the env type:
+
+| env type | Description |
+| --- | --- |
+| `local` | The application is on this machine. `pull` fetches the source into the dev workspace, `deploy` builds from the dev workspace and syncs the artifacts |
+| `docker` | The application runs in Docker, shared through a volume. Behavior is the same as above |
+| `http` | Synchronized through the API. `pull` / `push` download or upload a source archive |
+
+`ssh` envs don't support Portal management yet.
+
+## Multi-environment deployment
+
+The same Portal can be deployed to different environments, with `--env` naming the target:
+
+```bash
+nb portal deploy customer --env prod --yes
+```
+
+`--yes` skips the interactive confirmation. When the `--env` you pass explicitly differs from the current env, the CLI stops and asks by default. Remember to include `--yes` in scripts or CI, otherwise the command hangs at the confirmation.
+
+For cross-environment collection schema and configuration releases, see [Release Management](../publish.md).
+
+## Access path
+
+Once deployed, a Portal's access path is:
+
+```text
+<appPublicPath>/x/<portal>/
+```
+
+For a Portal under a sub-application:
+
+```text
+<appPublicPath>/x/apps/<app>/<portal>/
+```
+
+The `/x/` prefix belongs to AI Portals; no-code Portals use `/v/`.
+
+## Deleting a Portal
+
+```bash
+nb portal destroy customer
+```
+
+This deletes the Portal record and its deployed files, keeping the local dev workspace by default. Add `--delete-dev-path` when you want the dev workspace gone as well.
+
+## Related Links
+
+- [AI Portal Quick Start](./index.md) — Get your first AI-written frontend entry running
+- [Building with an AI Agent](./agent-workflow.md) — Drive the AI to write pages in natural language
+- [Project Structure and Tech Stack](./project-structure.md) — Build commands and environment variables
+- [Release Management](../publish.md) — Release collection schemas and configuration across environments
+- [`nb portal` Command Reference](../../api/cli/portal/index.md) — Complete parameter reference for all Portal commands
+- [`nb portal create`](../../api/cli/portal/create.md) — All parameters for creating a Portal
+- [`nb portal config`](../../api/cli/portal/config.md) — Adjust source storage and the dev workspace path
+- [`nb portal push`](../../api/cli/portal/push.md) — Push source to source storage
+- [`nb portal deploy`](../../api/cli/portal/deploy.md) — Build and deploy a Portal
+- [`nb portal pull`](../../api/cli/portal/pull.md) — Pull source from source storage
+- [`nb portal destroy`](../../api/cli/portal/destroy.md) — Delete the Portal record and its deployed files