aui-agent-builder 0.3.24 → 0.3.26

package/README.md

@@ -1,6 +1,6 @@
 # AUI Agent Builder CLI
 
-Build, configure, and manage AUI AI agents from the command line. Import agent configurations as local JSON files, edit them in your editor with full schema autocomplete, validate, and push changes back to the backend.
+Build, version, and deploy AI agents from your terminal. Import agent configurations as local JSON files, edit them in your editor with full schema autocomplete, validate, push changes, and manage versions.
 
 ## Installation
 
@@ -13,568 +13,286 @@ Requires Node.js 18+.
 ## Quick Start
 
 ```bash
-# 1. Sign in (select your org → account → agent)
+# 1. Authenticate
 aui login
 
-# 1b. (Optional) Switch environment
-aui env custom
-
-# 2. Browse and manage your agents
-aui agents
+# 2. Create a new agent
+aui agents --create
 
-# 3. Import an agent as local .aui.json files
+# 3. Import agent config as local files
 aui import-agent
 
-# 4. Edit the files in VSCode / Cursor (autocomplete works out of the box)
+# 4. Edit .aui.json files in your editor / Cursor
 
-# 5. Validate your changes
-aui validate
-
-# 6. Push changes back to the backend
+# 5. Push changes back
 aui push
+
+# 6. Publish and activate the version
+aui version publish
+aui version activate
 ```
 
 ## Hierarchy
 
-AUI uses a three-level hierarchy for organizing resources:
-
 ```
 Organization
 └── Account (Project)
     └── Agent (Network)
+        └── Version (v1.0, v1.1, v2.0, ...)
 ```
 
 - **Organization** — top-level workspace, tied to your login credentials
-- **Account (Project)** — a project within the organization (only org owners can create these)
+- **Account (Project)** — a project within the organization
 - **Agent (Network)** — an AI agent within a project
-
-When you log in, the CLI walks you through selecting each level. Your selections are saved in the session so you don't have to repeat them.
-
-## Authentication
-
-### Email (recommended)
-
-```bash
-aui login
-```
-
-Select **Email**, enter your email address, and paste the verification code from your inbox. After authentication, you'll be guided through selecting your organization, account, and agent.
-
-### Access Token
-
-```bash
-aui login
-```
-
-Select **Access token**, then paste your `x-access-token` from the browser DevTools (Network tab → any request → Headers).
-
-### CLI Flags
-
-```bash
-aui login --email user@example.com    # Go straight to email OTP
-aui login --token eyJ...              # Use token directly
-aui login --environment production    # Target production
-```
-
-### Session Management
-
-When already logged in, `aui login` shows your current session and lets you:
-
-- Continue with current session
-- Switch organization (resets account and agent)
-- Switch account (project)
-- Switch agent
-- Login again
-- Logout
-
-Session is stored in `~/.aui/session.json`. The environment file (`~/.aui/environment`) is always updated to match the session's environment on login, so all commands stay in sync.
-
-## Environments (`aui env`)
-
-The CLI supports multiple environments. Right now you can switch between:
-
-- **`staging`**
-- **`custom`** (uses the v3 base URL path)
-- **`production`** (wired, but URLs can be updated later)
-
-Use:
-
-```bash
-aui env              # Show current + interactive switch
-aui env staging
-aui env custom
-aui env production
-```
-
-Environment selection is saved to `~/.aui/environment`.
-
-### Environment ↔ Session Sync
-
-The environment and auth session are always kept in sync:
-
-- **`aui login`** — after authenticating, the selected environment is automatically saved to `~/.aui/environment`. This ensures commands like `push`, `pull`, and `sync` use the same environment as the session token.
-- **`aui env`** — when switching to a different environment, the CLI clears the existing session (since the token belongs to the old environment) and automatically starts the login flow for the new environment.
-
-This prevents mismatches where API requests hit one environment with a token issued for another.
+- **Version** — a snapshot of the agent's configuration (draft → published → active)
 
 ## Commands
 
-### Core Workflow
-
-| Command                  | Description                                            |
-| ------------------------ | ------------------------------------------------------ |
-| `aui login`              | Authenticate and select org → account → agent          |
-| `aui env [env]`          | Show or switch environment (staging/custom/production) |
-| `aui create-agent [dir]` | Scaffold a new blank agent project with examples       |
-| `aui import-agent [id]`  | Download an agent as local `.aui.json` files           |
-| `aui validate [path]`    | Validate `.aui.json` files for errors                  |
-| `aui push`               | Upload local changes to the backend                    |
-| `aui status`             | Show session, linked agent, and file summary           |
-| `aui diff [a] [b]`       | Compare two agent configurations                       |
-
-### Management
-
-| Command           | Description                                  |
-| ----------------- | -------------------------------------------- |
-| `aui accounts`    | Manage accounts — list, create, switch       |
-| `aui agents`      | Manage agents — list, create, switch, import |
-| `aui list-agents` | Quick table view of agents in your account   |
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `aui login` | Authenticate with AUI |
+| `aui login --environment custom` | Login to a specific environment |
+| `aui login --token <jwt>` | Login with a JWT token directly |
+| `aui logout` | Clear local session and credentials |
+
+After login, the CLI suggests your next steps: import an existing agent or create a new one.
+
+### Agent Creation
+
+| Command | Description |
+|---------|-------------|
+| `aui agents --create` | Interactive: select org → account → enter name. Uses General category by default |
+| `aui agents --create --name "My Agent"` | Create with a specific name (still prompts for org/account) |
+| `aui agents --create --name "My Agent" --category GOOGLE_FLIGHTS-V3` | Create with a specific category (by key or name) |
+| `aui agents --create --name "My Agent" --account-id <id>` | Skip org/account selection |
+| `aui agents --create --name "My Agent" --network-id <id>` | Register agent on an existing network |
+| `aui agents --create --full` | Create + version + publish + activate in one command |
+| `aui agents --list` | List all agents in the current account |
+| `aui agents --switch` | Switch which agent is selected in your session |
+
+### Import & Pull
+
+| Command | Description |
+|---------|-------------|
+| `aui import-agent` | Interactive: select org → account → agent. Auto-selects active version |
+| `aui import-agent <agent-id>` | Import a specific agent by network ID |
+| `aui import-agent --version <id>` | Import a specific version of the current session's agent |
+| `aui pull` | Pull latest config into an existing project (requires `.auirc`) |
+| `aui pull --force` | Pull without overwrite confirmation |
+
+### Version Management
+
+| Command | Description |
+|---------|-------------|
+| `aui version` | Interactive version menu |
+| `aui version list` | List all versions with status, stats, and active marker |
+| `aui version list --base-only` | List only base versions (no revisions) |
+| `aui version list --version-number 3` | List all revisions of version 3 |
+| `aui version create` | Interactive: choose source, bump mode, metadata |
+| `aui version create --source agent-scope` | Create new major version from live scope (v1.0, v2.0) |
+| `aui version create --source version --from <id>` | Create revision by cloning (v1.0 → v1.1) |
+| `aui version create --source version --from <id> --bump version_number` | Major bump from clone (v1.0 → v2.0) |
+| `aui version publish` | Publish a draft (locks it permanently) |
+| `aui version publish <id>` | Publish a specific draft |
+| `aui version activate` | Activate a published version as live |
+| `aui version activate <id>` | Activate a specific version |
+| `aui version archive <id>` | Archive a published version |
+| `aui version get <id>` | View full version details |
+| `aui version update <id> --label X --tags Y --notes Z` | Update version metadata |
+
+### Push
+
+| Command | Description |
+|---------|-------------|
+| `aui push` | Push changes. Versioned agents: finds/creates draft, pushes with `agent_version_id`. Old agents: pushes to live scope |
+| `aui push --version-id <id>` | Push into a specific version draft |
+| `aui push --dry-run` | Preview what would be pushed |
+| `aui push --force` | Push even if validation fails |
+| `aui push --skip-validation` | Skip validation step |
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `aui validate [path]` | Validate `.aui.json` files against schemas |
+| `aui diff [a] [b]` | Compare configs or show changes since import |
+| `aui status` | Show session, linked agent, and project summary |
 
 ### Configuration
 
-| Command               | Description                                         |
-| --------------------- | --------------------------------------------------- |
-| `aui add-integration` | Add an integration (API, RAG, or MCP)               |
-| `aui rag`             | Manage RAG knowledge bases — upload, export, update |
-| `aui chat`            | Interactive conversation with an agent              |
-
-### Aliases
+| Command | Description |
+|---------|-------------|
+| `aui account` | Manage accounts — list, create, switch |
+| `aui env [environment]` | Show or switch environment |
+| `aui pull-schema` | Fetch domain schemas from backend |
+| `aui add-integration` | Add an integration (API, RAG, or MCP) |
+| `aui rag` | Manage RAG knowledge bases and files |
 
-| Alias         | Equivalent         |
-| ------------- | ------------------ |
-| `aui import`  | `aui import-agent` |
-| `aui account` | `aui accounts`     |
-| `aui agent`   | `aui agents`       |
-| `aui ls`      | `aui list-agents`  |
+### Tools
 
-## Account Management
+| Command | Description |
+|---------|-------------|
+| `aui chat` | Start a conversation with an AUI agent |
+| `aui serve` | Launch web-based chat playground |
+| `aui revert` | Reset to HEAD (discard local changes) |
+| `aui upgrade` | Update aui-agent-builder to latest version |
 
-Manage accounts (projects) within your organization:
-
-```bash
-aui accounts
-```
-
-Interactive menu with options to:
-
-- **List** all accounts with status and creation date
-- **Create** a new account (org owner permission required)
-- **Switch** active account
-
-Quick shortcuts:
+### Aliases
 
-```bash
-aui accounts --list
-aui accounts --create "My Project"
-aui accounts --switch
-```
+| Alias | Equivalent |
+|-------|------------|
+| `aui import` | `aui import-agent` |
+| `aui account` | `aui accounts` |
+| `aui agent` | `aui agents` |
+| `aui ls` | `aui list-agents` |
+| `aui versions` | `aui version` |
 
-## Agent Management
+## Workflows
 
-Manage agents within your account:
+### Creating a New Agent
 
 ```bash
-aui agents
-```
-
-Interactive menu with options to:
+# Interactive flow
+aui agents --create
+# → Select org → Select account → Enter name → Agent created
 
-- **List** all agents with current selection highlighted
-- **Switch** active agent
-- **Create** a new agent project (scaffolds local files)
-- **Import** from current account
-- **Import from another account** in the same organization
-- **Import from another organization** entirely
+# Then either:
+# Option A: Import, edit, push, version
+aui import-agent
+cd ./my-agent
+# edit files
+aui push
+aui version publish
+aui version activate
 
-Quick shortcuts:
+# Option B: Version immediately
+aui version create --source agent-scope
+aui version publish
+aui version activate
 
-```bash
-aui agents --list
-aui agents --switch
-aui agents --create
-aui agents --import
+# Shortcut: all at once
+aui agents --create --full
 ```
 
-## Importing an Agent
-
-Download an existing agent's full configuration to a local folder:
+### Editing an Existing Agent
 
 ```bash
+# 1. Import (auto-selects active version)
 aui import-agent
-```
 
-1. Lists all agents in your current account
-2. You select which agent to import
-3. Creates a project folder named after the agent (e.g. `./my-agent/`)
-4. Downloads configuration from 6 endpoints (general settings, parameters, entities, integrations, tools, rules)
-5. Writes `.aui.json` files with the full agent configuration
-6. Sets up schema autocomplete for your editor
-7. Creates a `.auirc` file linking the project to the backend agent
+# 2. Edit .aui.json files
+cd ./my-agent
 
-You can also import a specific agent by ID:
+# 3. Push (creates version draft automatically)
+aui push
 
-```bash
-aui import-agent 69119ed25f297aae09f62505
-aui import-agent --dir ./custom-folder
+# 4. Publish and activate
+aui version publish
+aui version activate
 ```
 
-### Cross-Account and Cross-Org Import
-
-To import agents from a different account or organization, use the `aui agents` menu and select:
-
-- **Import from another account** — browse accounts in your current org
-- **Import from another organization** — browse all your organizations, then accounts, then agents
-
-## Creating a New Agent
-
-Scaffold a new project with example files and documentation:
+### Working with Versions
 
 ```bash
-aui create-agent my-agent
-```
+# List versions
+aui version list
 
-This creates a complete project with:
+# Create revision (v1.0 → v1.1)
+aui version create --source version --from <v1.0-id>
 
-- Example parameters, entities, integrations, tools, and rules
-- A `GUIDE.md` explaining every field and how to configure the agent
-- Schema autocomplete for VSCode and Cursor
-- All files ready to edit and push
+# Create major version (v2.0)
+aui version create --source agent-scope
 
-```bash
-aui create-agent my-agent --force    # Overwrite existing files
+# Publish and go live
+aui version publish <id>
+aui version activate <id>
+
+# Archive old versions
+aui version archive <id>
 ```
 
 ## Agent Project Structure
 
-After `aui import-agent` or `aui create-agent`, your project folder looks like:
+After `aui import-agent`, your project folder contains:
 
 ```
 my-agent/
-├── agent.aui.json                Agent name, objective, tone, guardrails
-├── parameters.aui.json           Data the agent collects and outputs
-├── entities.aui.json             Groups of related parameters
-├── integrations.aui.json         API, RAG, and MCP connections
-├── rules.aui.json                Global behavioral rules
-├── tools/                        One file per agent capability
+├── agent.aui.json             Agent name, objective, tone, guardrails
+├── parameters.aui.json        Data the agent collects and outputs
+├── entities.aui.json          Groups of related parameters
+├── integrations.aui.json      API, RAG, and MCP connections
+├── rules.aui.json             Global behavioral rules
+├── widgets.aui.json           Card templates for rich responses
+├── tools/                     One file per agent capability
 │   ├── product_search.aui.json
 │   └── generative_ai.aui.json
-├── GUIDE.md                      Step-by-step building guide
-├── .auirc                        Project config (agent ID, environment)
-└── .vscode/settings.json         Schema autocomplete config
-```
-
-### File Reference
-
-**`agent.aui.json`** — The agent's identity. Define its name, objective (what it does), guardrails (what it should not do), tone of voice, and brevity preference.
-
-**`parameters.aui.json`** — Data units the agent works with. Each parameter has a code (kebab-case), type (string, numeric, date, boolean, object), usage (input from user, output from API, or both), and a description that guides the LLM on how to extract it.
-
-**`entities.aui.json`** — Groups of related parameters. For example, a "Transaction" entity groups transaction-id, amount, status, and date together.
-
-**`integrations.aui.json`** — External connections. API integrations define an endpoint URL, HTTP method, authentication, request schema, and response mapping. RAG integrations connect to knowledge bases. MCP integrations connect to Model Context Protocol servers.
-
-**`tools/*.aui.json`** — Each tool is one capability the agent has. A tool defines when it activates (when_to_use), what parameters it needs, which integrations it calls, and rules for pre/post execution behavior.
-
-**`rules.aui.json`** — Global rules that apply across tools. Define conditions (when) and actions (then) to control agent behavior like blocking certain actions, requiring confirmation, or activating other tools.
-
-## Adding Integrations
-
-Add API, RAG, or MCP integrations to your project:
-
-```bash
-aui add-integration
-```
-
-Select the integration type, provide a code name, and the command scaffolds the JSON config with the correct structure and placeholder values.
-
-- **API** — generates endpoint URL, method, authentication, request schema, and test curl
-- **RAG** — prompts for knowledge hub (new or existing) and scope (organization, account, or network)
-- **MCP** — generates a minimal config to fill in
-
-## RAG Knowledge Bases
-
-Manage RAG knowledge bases — list, upload files/URLs, export, and update:
-
-```bash
-aui rag                  # Interactive menu
-aui rag --add-file       # Quick shortcut to upload files or URLs
-```
-
-### First-Time Setup
-
-The first time you run `aui rag`, you'll be prompted to paste your RAG API key. The key is saved securely to `~/.aui/kbm-key` (file permission 600) and reused automatically on future runs. You can also set it via the `AUI_KBM_API_KEY` environment variable.
-
-### Interactive Menu
-
-Running `aui rag` opens an interactive menu:
-
-| Option                               | What it does                                                       |
-| ------------------------------------ | ------------------------------------------------------------------ |
-| **List knowledge bases**             | Shows all KBs for the current agent with IDs and scope             |
-| **Upload files to a knowledge base** | Upload local files (PDF, CSV, TXT, etc.) to a new or existing KB   |
-| **Upload URLs to a knowledge base**  | Scrape web pages into a new or existing KB                         |
-| **Export knowledge bases**           | Download all KB data to `aui.rag.json` in the current directory    |
-| **Update from file**                 | Push an edited `aui.rag.json` back to the server (diff-based sync) |
-
-### Uploading Files
-
-```bash
-aui rag
-# → Upload files to a knowledge base
-# → Select an existing KB or create a new one
-# → Drag/paste file path(s)
-```
-
-Supported file types include PDF, CSV, TXT, and other text-based formats. Multiple files can be added in a single session.
-
-### Uploading URLs
-
-```bash
-aui rag
-# → Upload URLs to a knowledge base
-# → Select an existing KB or create a new one
-# → Paste URL(s) to scrape
-```
-
-### Export and Update Workflow
-
-The export/update flow lets you bulk-edit knowledge base content:
-
-```bash
-# 1. Export all KB data to a local JSON file
-aui rag
-# → Export knowledge bases
-# → Saves aui.rag.json
-
-# 2. Edit the JSON file — add, modify, or remove vectors
-
-# 3. Push changes back
-aui rag
-# → Update from file
-# → Select aui.rag.json
-# → Server applies changes (creates new, updates changed, deletes removed)
+├── knowledge-hubs/            Knowledge base resources and files
+├── schemas/                   Domain schemas for validation
+├── .auirc                     Project config (agent ID, version, environment)
+├── .vscode/settings.json      Schema autocomplete config
+├── GUIDE.md                   Step-by-step building guide
+├── AGENTS.md                  Agent documentation
+└── BEST_PRACTICES.md          Configuration best practices
 ```
 
-### Quick Upload Shortcut
+## Version Lifecycle
 
-```bash
-aui rag --add-file
 ```
-
-Skips the menu and goes straight to uploading. Choose between files or URLs, select a knowledge base, and upload.
-
-## Validating Changes
-
-Check your configuration files for errors before pushing:
-
-```bash
-aui validate
+draft → published → active
+                  → archived
 ```
 
-`aui validate` performs **CLI validation**:
-
-- JSON syntax
-- Required fields (codes, types, objectives)
-- Cross-references (e.g. tools referencing unknown integrations; entities referencing unknown parameters)
-
-### Schema vs `aui validate` (important)
-
-When you import/create an agent, the CLI also writes:
-
-- **`.aui-schema/aui.dschema.json`** (JSON Schema file)
-- **`.vscode/settings.json`** (wires the schema for VSCode/Cursor)
+- **Draft** — editable, receives pushes via `agent_version_id`
+- **Published** — locked permanently, ready to activate
+- **Active** — the live production configuration (one per agent)
+- **Archived** — retired, can be viewed and cloned but not activated
 
-This provides **editor validation + autocomplete** (red squiggles, enum dropdowns, hover docs).
+## Backwards Compatibility
 
-That schema is **separate** from `aui validate`:
+The CLI handles both new (versioned) and legacy agents:
 
-- **Schema**: editor-time, strict typing/shape checking for JSON files
-- **`aui validate`**: CLI-time checks + cross-reference integrity
+- **New agents** with versions: import uses `version_id` to fetch version-specific data, push creates drafts with `agent_version_id`
+- **Legacy agents** without versions: import falls back to network scope, push goes to live scope directly
+- The transition is automatic — no user action needed
 
-If the backend introduces new fields (for example, the integrations schema expands in the V2 endpoints),
-your editor schema may need updating. Re-importing an agent refreshes `.aui-schema/`.
+## Environments
 
 ```bash
-aui validate --verbose    # Detailed output per file
+aui env              # Show current environment
+aui env staging      # Switch to staging
+aui env custom       # Switch to custom (v3 endpoints)
+aui env production   # Switch to production
 ```
 
-## Pushing Changes
-
-Upload your local changes to the backend:
-
-```bash
-aui push
-```
-
-### Authentication behavior (Bearer-first, API-key fallback)
-
-For agent-settings endpoints (import/push), the CLI will:
-
-1. **Use your Bearer token** from `aui login` (`Authorization: Bearer ...`)
-2. If the server returns an **authorization error** (401/403, “not a member”, etc.), the CLI prompts for an **Agent Settings API key**
-3. The key is saved locally and reused automatically
-
-Local key storage:
-
-- `~/.aui/agent-settings-key`
-
-You can also provide it via env var:
-
-- `AUI_AGENT_TOOLS_API_KEY`
-
-### API Workflow key (required for `aui add-integration`)
-
-The API Workflow endpoint requires an API key (no Bearer token). If it’s missing, the CLI prompts and saves it:
-
-- `~/.aui/api-workflow-key`
-
-Env var override:
-
-- `AUI_API_WORKFLOW_KEY`
-
-### Common push errors and what they mean
-
-- **“No agent linked to this project”**
-  - You are not inside a project folder that contains a readable `.auirc`, or the `.auirc` JSON is invalid/empty.
-  - Fix: run `aui import` again, or open `.auirc` and fix JSON.
-
-- **“Missing: account_id / organization_id / network_id …”**
-  - The CLI can’t resolve scope IDs needed for agent-settings endpoints.
-  - Fix: re-import (`aui import`) or re-login (`aui login`) so the session has the correct org/account selected.
-
-The push command detects changes via git diff and pushes only what changed:
-
-| Resource             | Method | What gets sent                                              |
-| -------------------- | ------ | ----------------------------------------------------------- |
-| **Tools (modified)** | PATCH  | Only changed fields (name, when_to_use, goal, config, etc.) |
-| **Tools (new)**      | POST   | Full tool object                                            |
-| **General Settings** | PATCH  | Only changed fields                                         |
-| **Parameters**       | PUT    | Full parameters data (upsert)                               |
-| **Entities**         | PUT    | Full entities data (upsert)                                 |
-| **Rules**            | PUT    | Full rules data (upsert)                                    |
-
-All changes are pushed **in parallel** for speed. After a successful push, the git baseline is updated so the next push only sends new changes.
-
-```bash
-aui push --dry-run        # Preview only — shows changes without pushing
-aui push --force          # Push even with validation warnings
-aui push --skip-validation
-```
-
-## Comparing Configurations
-
-See what changed since you imported:
-
-```bash
-aui diff
-```
-
-Or compare two agent folders side by side:
-
-```bash
-aui diff ./agent-v1 ./agent-v2
-```
-
-Shows added, removed, and modified parameters, entities, tools, integrations, and rules.
-
-## Schema Autocomplete
-
-Every project includes a JSON schema that enables in your editor:
-
-- Field name suggestions as you type
-- Enum dropdowns for types, actions, methods, and operators
-- Descriptions on hover
-- Inline validation highlighting
+## Configuration Files
 
-Works in VSCode and Cursor out of the box.
+| File | Purpose |
+|------|---------|
+| `~/.aui/session.json` | Auth token, org, account, agent, environment |
+| `~/.aui/environment` | Selected environment |
+| `~/.aui/kbm-key` | RAG API key |
+| `~/.aui/agent-settings-key` | Agent Settings API key (fallback auth) |
+| `~/.aui/api-workflow-key` | API Workflow key |
+| `.auirc` | Project config — agent ID, version, environment |
 
-## Agent Chat
+## Environment Variables
 
-Talk to any agent directly from the terminal:
-
-```bash
-aui chat
-```
-
-- **Real-time streaming** — responses appear as the agent types
-- **Auto-connect** — select an agent from your account; API key is fetched automatically
-- **Product cards** — results show name, price, rating, reviews, and links
-- **Suggestions** — AI-generated follow-up questions
-
-### Chat Options
-
-```bash
-aui chat                          # Interactive
-aui chat --api-key API_KEY_xxx    # Skip API key prompt
-aui chat --env azure              # Azure environment (default: GCP)
-aui chat --rest                   # REST only, no streaming
-```
-
-### Chat Commands
-
-| Command    | Action                    |
-| ---------- | ------------------------- |
-| `/exit`    | End conversation          |
-| `/clear`   | Clear screen              |
-| `/history` | View message history      |
-| `/suggest` | Get follow-up suggestions |
-| `/task`    | Show task ID              |
-| `/help`    | Show commands             |
-
-## Configuration
-
-### Session
-
-`~/.aui/session.json` — created by `aui login`. Stores auth token, organization, account, agent, and environment.
-
-### Project Config
-
-`.auirc` — created by `aui import-agent` or `aui create-agent`. Links the project to a backend agent. Also stores the network API key for `aui chat`.
-
-### RAG API Key
-
-`~/.aui/kbm-key` — created automatically the first time you run `aui rag` and paste the API key. The key is stored with file permission 600 (readable only by you). You can also set it via the `AUI_KBM_API_KEY` environment variable, which takes priority over the saved file.
-
-### Stored Files
-
-| File                        | Purpose                                                            |
-| --------------------------- | ------------------------------------------------------------------ |
-| `~/.aui/session.json`       | Auth token, org, account, agent, environment (synced with env file) |
-| `~/.aui/environment`        | Selected environment (synced with session on login/env switch)      |
-| `~/.aui/kbm-key`            | RAG API key (auto-saved on first use)                              |
-| `~/.aui/agent-settings-key` | Agent Settings API key (fallback if Bearer token lacks permission) |
-| `~/.aui/api-workflow-key`   | API Workflow key (required for `aui add-integration`)              |
-| `.auirc`                    | Project config — links folder to a backend agent                   |
-| `aui.rag.json`              | Exported RAG knowledge base data                                   |
-
-### Environment Variables
-
-| Variable                  | Description                                           |
-| ------------------------- | ----------------------------------------------------- |
-| `AUI_AUTH_TOKEN`          | Auth token (skip login)                               |
-| `AUI_API_URL`             | Override API base URL                                 |
-| `AUI_ENVIRONMENT`         | `staging`, `custom`, or `production`                  |
-| `AUI_ACCOUNT_ID`          | Account ID                                            |
-| `AUI_ORGANIZATION_ID`     | Organization ID                                       |
-| `AUI_AGENT_CODE`          | Agent code                                            |
-| `AUI_KBM_API_KEY`         | RAG API key (overrides saved key in `~/.aui/kbm-key`) |
-| `AUI_AGENT_TOOLS_API_KEY` | Agent Settings API key (fallback auth)                |
-| `AUI_API_WORKFLOW_KEY`    | API Workflow key                                      |
+| Variable | Description |
+|----------|-------------|
+| `AUI_AUTH_TOKEN` | Auth token (skip login) |
+| `AUI_API_URL` | Override API base URL |
+| `AUI_ENVIRONMENT` | `staging`, `custom`, or `production` |
+| `AUI_ACCOUNT_ID` | Account ID |
+| `AUI_ORGANIZATION_ID` | Organization ID |
+| `AUI_KBM_API_KEY` | RAG API key |
+| `AUI_AGENT_TOOLS_API_KEY` | Agent Settings API key |
+| `AUI_API_WORKFLOW_KEY` | API Workflow key |
+| `AUI_DEBUG` | Enable debug logging (`AUI_DEBUG=1`) |
 
 ## Local Development
 
-To run the CLI from your local source code instead of the published npm package:
-
 ```bash
 cd aui-agent-builder
 npm install
@@ -582,68 +300,15 @@ npm run build
 npm link
 ```
 
-This creates a global `aui` symlink pointing to your local build. Any changes you make are reflected after running `npm run build` again.
-
-To verify you're running the local version:
-
-```bash
-which aui
-# Should show a path inside your project, not a global npm path
-```
-
-To switch back to the published version:
-
-```bash
-npm uninstall -g aui-agent-builder
-npm install -g aui-agent-builder
-```
-
 ## Updating
 
-### Update Notifications
-
-The CLI automatically checks for new versions once every 24 hours. When an update is available, a banner appears after command output:
-
-```
-╭──────────────────────────────────────────────╮
-│  Update available: 0.1.86 → 0.1.87          │
-│  Run: npm install -g aui-agent-builder       │
-╰──────────────────────────────────────────────╯
-```
-
-The check is non-blocking and never affects CLI performance. For Homebrew users, the banner shows `brew upgrade aui` instead.
-
-### Upgrade Command
-
-Upgrade directly from the CLI:
-
 ```bash
-aui upgrade
-```
-
-This automatically detects whether you installed via npm or Homebrew and runs the appropriate upgrade command.
-
-### Manual Upgrade
-
-```bash
-# npm
-npm install -g aui-agent-builder
-
-# Homebrew
-brew upgrade aui
-```
-
-### Disable Update Notifications
-
-```bash
-# Environment variable
-AUI_NO_UPDATE_CHECK=1 aui status
-
-# Or use ecosystem-standard flag
-NO_UPDATE_NOTIFIER=1 aui status
+aui upgrade              # Auto-detect npm or Homebrew
+npm install -g aui-agent-builder   # Manual npm
+brew upgrade aui                   # Manual Homebrew
 ```
 
-Update notifications are also automatically suppressed in CI environments (`CI=true`) and when using `--quiet`, `--json`, or `--silent` flags.
+The CLI checks for updates every 24 hours and shows a banner when one is available.
 
 ## License