aui-agent-builder 0.3.46 → 0.3.48

package/README.md

@@ -1,6 +1,44 @@
 # AUI Agent Builder CLI
 
-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.
+[![npm version](https://img.shields.io/npm/v/aui-agent-builder.svg)](https://www.npmjs.com/package/aui-agent-builder)
+[![npm downloads](https://img.shields.io/npm/dw/aui-agent-builder.svg)](https://www.npmjs.com/package/aui-agent-builder)
+[![node](https://img.shields.io/node/v/aui-agent-builder.svg)](https://nodejs.org)
+
+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 changes, push to the backend, and manage versions — all from the command line.
+
+---
+
+## Features
+
+- **Code-first agent development** — Edit agent configurations as JSON files in your editor with schema-driven autocomplete
+- **Version management** — Create drafts, publish, activate, and archive agent versions with full lifecycle control
+- **Smart diff & validation** — See exactly what changed, validate against domain schemas before pushing
+- **Knowledge base management** — Upload documents and URLs, export/import KB configurations
+- **Scope-level control** — Import and push at network, account, organization, or category scope
+- **IDE integration** — Auto-generated schemas, Cursor rules, Claude skills, and OpenCode skills for AI-assisted editing
+- **CI/CD ready** — Every command has a non-interactive mode with flags for automation
+- **Web playground** — Built-in chat UI for testing agents locally
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Commands Reference](#commands-reference)
+- [Workflows](#workflows)
+- [Project Structure](#project-structure)
+- [Configuration File Reference](#configuration-file-reference)
+- [Version Management](#version-management)
+- [Scope Levels](#scope-levels)
+- [Knowledge Bases](#knowledge-bases)
+- [CI/CD & Automation](#cicd--automation)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Local Development](#local-development)
+
+---
 
 ## Installation
 
@@ -8,7 +46,15 @@ Build, version, and deploy AI agents from your terminal. Import agent configurat
 npm install -g aui-agent-builder
 ```
 
-Requires Node.js 18+.
+Requires **Node.js 18+**.
+
+Verify installation:
+
+```bash
+aui -v
+```
+
+---
 
 ## Quick Start
 
@@ -16,23 +62,30 @@ Requires Node.js 18+.
 # 1. Authenticate
 aui login
 
-# 2. Create a new agent
-aui agents --create
-
-# 3. Import agent config as local files
+# 2. Import an existing agent (or create one with: aui agents --create)
 aui import-agent
 
-# 4. Edit .aui.json files in your editor / Cursor
+# 3. Edit .aui.json files in your editor (schema autocomplete works out of the box)
 
-# 5. Push changes back
+# 4. See what changed
+aui diff
+
+# 5. Validate
+aui validate
+
+# 6. Push changes
 aui push
 
-# 6. Publish and activate the version
+# 7. Publish and go live
 aui version publish
 aui version activate
 ```
 
-## Hierarchy
+---
+
+## Core Concepts
+
+### Hierarchy
 
 ```
 Organization
@@ -41,247 +94,523 @@ Organization
         └── Version (v1.0, v1.1, v2.0, ...)
 ```
 
-- **Organization** — top-level workspace, tied to your login credentials
-- **Account (Project)** — a project within the organization
-- **Agent (Network)** — an AI agent within a project
-- **Version** — a snapshot of the agent's configuration (draft → published → active)
+| Concept | Description |
+|---------|-------------|
+| **Organization** | Top-level workspace, tied to your login credentials |
+| **Account** | A project within the organization |
+| **Agent** | An AI agent (also called a "network") within a project |
+| **Version** | An immutable snapshot of the agent's full configuration |
+
+### Agent Configuration
+
+Each agent is composed of seven configuration types:
+
+| Config | File | Purpose |
+|--------|------|---------|
+| **General Settings** | `agent.aui.json` | Name, objective, persona, tone, guardrails |
+| **Parameters** | `parameters.aui.json` | Data the agent collects from users and outputs |
+| **Entities** | `entities.aui.json` | Groups of related parameters |
+| **Integrations** | `integrations.aui.json` | API, RAG, and MCP connections |
+| **Tools** | `tools/*.aui.json` | Agent capabilities (one file per tool) |
+| **Rules** | `rules.aui.json` | Global behavioral rules |
+| **Widgets** | `widgets.aui.json` | Card templates for rich UI responses |
+
+### Version Lifecycle
+
+```
+draft ──→ published ──→ active
+                    └──→ archived
+```
+
+| State | Editable | Can Activate | Description |
+|-------|----------|-------------|-------------|
+| **Draft** | Yes | No | Work in progress. Receives pushes |
+| **Published** | No | Yes | Locked permanently. Ready to go live |
+| **Active** | No | — | The live production configuration |
+| **Archived** | No | No | Retired. Can still be viewed and cloned |
+
+---
 
-## Commands
+## Commands Reference
 
 ### 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 |
+```bash
+aui login                        # Open browser for authentication
+aui login --environment staging  # Login to a specific environment
+aui login --token <jwt>          # Login with a JWT token (for CI/CD)
+aui logout                       # Clear session and credentials
+```
+
+### Agent Management
 
-After login, the CLI suggests your next steps: import an existing agent or create a new one.
+```bash
+aui agents                       # Interactive menu: list, create, switch, import
+aui agents --list                # List all agents in the current account
+aui agents --create              # Interactive creation (org → account → name)
+aui agents --switch              # Switch the active agent in your session
+```
 
-### Agent Creation
+**Non-interactive 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 |
+```bash
+# Minimal — still prompts for org/account
+aui agents --create --name "My Agent"
+
+# Fully non-interactive
+aui agents --create --name "My Agent" --account-id <id>
+
+# With a specific category (e.g. Amazon, Google Flights)
+aui agents --create --name "My Agent" --account-id <id> --category Amazon
+
+# Create + v1.0 draft (ready to import, edit, and push)
+aui agents --create --name "My Agent" --account-id <id> --draft
+
+# One-step: create + version + publish + activate
+aui agents --create --name "My Agent" --account-id <id> --full
+```
 
 ### 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 |
+```bash
+aui import-agent                           # Interactive: select org → account → agent
+aui import-agent <agent-id>               # Import by network ID
+aui import-agent --version <id>           # Import a specific version
+aui import-agent --scope-level category   # Import at category scope
+aui import-agent --dir ./my-folder        # Output to a specific directory
+aui import-agent --skip-kb-files          # Skip knowledge base file downloads
+aui import-agent --skills claude,cursor   # Generate AI coding skills
+aui import-agent --no-skills             # Skip skill generation
+aui import-agent --include-evaluate       # Include test_questions schema
+```
+
+```bash
+aui pull                                  # Pull latest into existing project
+aui pull --force                          # Skip overwrite confirmation
+aui pull --scope-level <level>            # Pull at a specific scope level
+```
+
+### Push
+
+```bash
+aui push                                  # Push changes (auto-creates version draft)
+aui push --dry-run                        # Preview without pushing
+aui push --scope-level category           # Push at a specific scope level
+aui push --version-id <id>               # Push into a specific draft
+aui push --force                          # Push even with validation errors
+aui push --skip-validation                # Skip validation step
+aui push --api-key <key>                 # Use a specific API key
+```
 
 ### 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 |
+```bash
+aui version                               # Interactive version menu
+aui version list                          # List all versions
+aui version list --base-only              # List base versions only (no revisions)
+aui version list --version-number 3       # List all revisions of v3
+
+# Create
+aui version create                                        # Interactive
+aui version create --source agent-scope                   # Major version from live (v2.0)
+aui version create --source version --from <id>           # Revision (v1.0 → v1.1)
+aui version create --source version --from <id> --bump version_number  # Major from clone
+
+# Lifecycle
+aui version publish                       # Interactive — select draft to publish
+aui version publish <id>                  # Publish a specific draft
+aui version activate                      # Interactive — select version to activate
+aui version activate <id>                 # Activate a specific version
+aui version archive <id>                  # Archive (cannot be re-activated)
+
+# Metadata
+aui version get <id>                      # View full version details
+aui version update <id> --label "Release 2" --tags "prod,stable" --notes "Bug fixes"
+```
 
-### Push
+### Knowledge Bases & Documents
 
-| 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 |
+```bash
+# RAG management
+aui rag                                   # Interactive KB menu
+aui rag --list                            # List all knowledge bases
+aui rag --export                          # Export KBs to knowledge-hubs/
+aui rag --import                          # Import KBs from knowledge-hubs/
+
+# Document upload
+aui document report.pdf data.csv --kb "Policies"   # Upload files
+aui document --url "https://docs.example.com" --kb "Docs"  # Scrape URLs
+aui document status                                  # Recent upload status
+aui document status --hours 24 --kb "Policies"       # Filtered status
+```
 
-### Development
+### Development Tools
 
-| 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 |
+```bash
+aui validate                              # Validate all .aui.json files
+aui validate ./tools/                     # Validate specific directory
+aui validate --strict                     # Treat warnings as errors
+aui diff                                  # Changes since last import/push
+aui diff ./folder-a ./folder-b            # Compare two directories
+aui status                                # Session, agent, and project info
+aui revert                                # Discard local changes
+```
 
-### Configuration
+### Chat & Testing
 
-| 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 |
+```bash
+aui chat                                  # Interactive conversation with agent
+aui chat --api-key <key>                 # Chat with a specific API key
+aui chat --rest                           # REST API only (no streaming)
+aui serve                                 # Web chat playground (localhost:3141)
+aui serve --port 8080                     # Custom port
+```
 
-### Tools
+### Configuration & Utilities
 
-| 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 |
+```bash
+aui account                               # Manage accounts (list, create, switch)
+aui env                                   # Show current environment
+aui env staging                           # Switch environment
+aui pull-schema                           # Fetch domain schemas from backend
+aui add-integration                       # Add API / RAG / MCP integration
+aui upgrade                               # Update to latest version
+```
 
-### Aliases
+### Command Aliases
 
 | Alias | Equivalent |
 |-------|------------|
 | `aui import` | `aui import-agent` |
-| `aui account` | `aui accounts` |
-| `aui agent` | `aui agents` |
+| `aui accounts` | `aui account` |
+| `aui agents` | `aui agent` |
 | `aui ls` | `aui list-agents` |
 | `aui versions` | `aui version` |
 
+---
+
 ## Workflows
 
-### Creating a New Agent
+### Create and Deploy a New Agent
 
 ```bash
-# Interactive flow
-aui agents --create
-# → Select org → Select account → Enter name → Agent created
+# Step 1: Create the agent (with a v1.0 draft ready to edit)
+aui agents --create --name "Support Agent" --account-id <id> --draft
 
-# Then either:
-# Option A: Import, edit, push, version
+# Step 2: Import as local files
 aui import-agent
-cd ./my-agent
-# edit files
+
+# Step 3: Edit configuration in your editor
+cd ./support-agent
+# → Edit agent.aui.json, tools/*.aui.json, parameters.aui.json, etc.
+
+# Step 4: Validate and push
+aui validate
 aui push
-aui version publish
-aui version activate
 
-# Option B: Version immediately
-aui version create --source agent-scope
+# Step 5: Publish and activate
 aui version publish
 aui version activate
-
-# Shortcut: all at once
-aui agents --create --full
 ```
 
-### Editing an Existing Agent
+**Three creation modes:**
 
 ```bash
-# 1. Import (auto-selects active version)
-aui import-agent
+# Agent only (no version) — create version manually later
+aui agents --create --name "Support Agent" --account-id <id>
+
+# Agent + v1.0 draft — ready to import, edit, and push
+aui agents --create --name "Support Agent" --account-id <id> --draft
+
+# Agent + v1.0 + publish + activate — fully deployed in one step (CI/CD)
+aui agents --create --name "Support Agent" --account-id <id> --full
+```
 
-# 2. Edit .aui.json files
+### Edit → Push → Deploy Cycle
+
+```bash
+aui import-agent                  # Downloads active version as .aui.json files
 cd ./my-agent
 
-# 3. Push (creates version draft automatically)
-aui push
+# Make changes to any .aui.json file...
 
-# 4. Publish and activate
-aui version publish
-aui version activate
+aui diff                          # See what changed
+aui validate                      # Validate against schemas
+aui push                          # Push changes into a new draft
+
+aui version publish               # Lock the draft
+aui version activate              # Make it live
 ```
 
-### Working with Versions
+### Version Branching
 
 ```bash
-# List versions
-aui version list
-
-# Create revision (v1.0 → v1.1)
+# Create a revision from v1.0 (→ v1.1)
 aui version create --source version --from <v1.0-id>
 
-# Create major version (v2.0)
+# Or create a new major version from live scope (→ v2.0)
 aui version create --source agent-scope
 
-# Publish and go live
-aui version publish <id>
-aui version activate <id>
-
-# Archive old versions
-aui version archive <id>
+# Import a specific version for editing
+aui import-agent --version <version-id>
 ```
 
-## Agent Project Structure
+---
+
+## Project Structure
 
 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
-├── widgets.aui.json           Card templates for rich responses
-├── tools/                     One file per agent capability
+│
+├── agent.aui.json                 # Agent identity and behavior
+├── parameters.aui.json            # Parameters (input/output data)
+├── entities.aui.json              # Entity groups
+├── integrations.aui.json          # API / RAG / MCP connections
+├── rules.aui.json                 # Global behavioral rules
+├── widgets.aui.json               # Card templates (JSX + field mappings)
+│
+├── tools/                         # One file per agent tool/capability
 │   ├── product_search.aui.json
-│   └── generative_ai.aui.json
-├── 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
+│   ├── generative_ai.aui.json
+│   └── ...
+│
+├── knowledge-hubs/                # Knowledge base data
+│   ├── policies/
+│   │   ├── kb.json                #   KB metadata
+│   │   └── company-policies.pdf   #   Downloaded files
+│   └── ...
+│
+├── schemas/                       # Domain schemas (auto-fetched)
+│   ├── agent.dschema.json
+│   ├── tools.dschema.json
+│   ├── parameters.dschema.json
+│   ├── entities.dschema.json
+│   ├── integrations.dschema.json
+│   ├── rules.dschema.json
+│   ├── widgets.dschema.json
+│   └── knowledge-bases.dschema.json
+│
+├── memory/                        # Push logs (auto-generated)
+├── .auirc                         # Project config (agent ID, version, env)
+├── .vscode/settings.json          # Schema autocomplete for VS Code / Cursor
+├── .gitignore
+│
+├── GUIDE.md                       # Getting started guide
+├── AGENTS.md                      # Agent documentation
+├── BEST_PRACTICES.md              # Configuration best practices
+│
+├── .cursor/rules/                 # Cursor AI rules per config type
+├── .claude/skills/                # Claude Code skills per config type
+└── .opencode/skills/              # OpenCode skills per config type
+```
+
+---
+
+## Configuration File Reference
+
+### agent.aui.json
+
+The agent's identity and top-level behavior:
+
+```json
+{
+  "general_settings": {
+    "name": "Support Agent",
+    "objective": "Help customers find products and resolve issues",
+    "persona_guidelines": "You are a friendly and knowledgeable support agent...",
+    "tone_of_voice": "Professional but approachable",
+    "guardrails": "Never share internal pricing. Always verify identity...",
+    "brevity": "concise",
+    "context": "This agent serves an e-commerce platform..."
+  }
+}
 ```
 
-## Version Lifecycle
+### parameters.aui.json
+
+Parameters the agent collects from users or outputs:
+
+```json
+{
+  "parameters": [
+    {
+      "code": "product-type",
+      "description": "The type of product the customer is looking for",
+      "type": "string",
+      "usage": "ALL"
+    },
+    {
+      "code": "budget-range",
+      "description": "Customer's budget",
+      "type": "enum",
+      "usage": "INPUT",
+      "values": ["under-50", "50-100", "100-200", "200-plus"]
+    }
+  ]
+}
+```
 
+### tools/*.aui.json
+
+Each tool defines a capability with triggers, parameters, integrations, and rules:
+
+```json
+{
+  "tool": {
+    "name": "Product Search",
+    "code": "PRODUCT_SEARCH",
+    "goal": "Help the user find products that match their preferences",
+    "when_to_use": "When the user asks to browse, search, or find products",
+    "status": true,
+    "response_type": "TEXT_CARDS",
+    "config": {
+      "params": {
+        "required": [["product-type"]],
+        "optional": ["budget-range", "color", "size"]
+      }
+    },
+    "integrations": [
+      { "code": "product-api", "is_main": true }
+    ],
+    "card_template_code": "product-card"
+  }
+}
 ```
-draft → published → active
-                  → archived
+
+### widgets.aui.json
+
+Card templates with JSX and field mappings:
+
+```json
+{
+  "widgets": [
+    {
+      "name": "product-card",
+      "jsx_template": "<Card><Image src={image} /><Text value={title} /></Card>",
+      "fields": [
+        { "name": "image", "param": "product-image" },
+        { "name": "title", "param": "product-name" }
+      ],
+      "tool_name": "PRODUCT_SEARCH"
+    }
+  ]
+}
 ```
 
-- **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
+---
+
+## Version Management
 
-## Backwards Compatibility
+### How Versioning Works
 
-The CLI handles both new (versioned) and legacy agents:
+1. **Import** downloads the active version's configuration as local files
+2. **Push** auto-creates a draft version and pushes changes into it
+3. **Publish** locks the draft permanently
+4. **Activate** makes the published version the live configuration
+
+```bash
+aui import-agent          # Get active version (e.g. v1.0)
+# Edit files...
+aui push                  # Creates draft v1.1, pushes changes
+aui version publish       # Locks v1.1
+aui version activate      # v1.1 is now live
+```
 
-- **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
+### Version Numbering
 
-## Environments
+- **Revisions** increment the minor number: v1.0 → v1.1 → v1.2
+- **Major versions** increment the major number: v1.x → v2.0
+- Use `--source version --from <id>` for revisions
+- Use `--source agent-scope` for new major versions
+
+---
+
+## Scope Levels
+
+Scope levels control which hierarchy level you're reading from or writing to:
+
+| Level | IDs Sent | Use Case |
+|-------|----------|----------|
+| `network` | `network_id` + `account_id` + `org_id` + `category_id` | Agent-specific configuration (default) |
+| `account` | `account_id` + `org_id` + `category_id` | Shared across all agents in an account |
+| `organization` | `org_id` + `category_id` | Shared across all accounts in an org |
+| `category` | `category_id` only | Shared across all agents in a category (e.g. Amazon) |
 
 ```bash
-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
+aui import-agent --scope-level category <agent-id>
+aui push --scope-level category
 ```
 
-## Configuration Files
+> **Note:** Scope-level operations skip versioning. Changes are applied directly to the live scope.
 
-| 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 |
+---
+
+## Knowledge Bases
+
+### Upload Documents
+
+```bash
+# Upload files
+aui document report.pdf handbook.docx --kb "Company Policies"
+
+# Scrape web pages
+aui document --url "https://docs.example.com/faq" --kb "FAQ"
+```
 
-## Environment Variables
+### Check Upload Status
+
+```bash
+aui document status                        # Last 6 hours
+aui document status --hours 24             # Last 24 hours
+aui document status --kb "Company Policies"  # Filter by KB
+```
+
+### Export & Import
+
+```bash
+aui rag --export    # Save all KB metadata and files to knowledge-hubs/
+aui rag --import    # Restore KBs from knowledge-hubs/
+```
+
+---
+
+## CI/CD & Automation
+
+Every command supports non-interactive flags for pipeline integration.
+
+### Environment Variables for CI
+
+```bash
+export AUI_AUTH_TOKEN="<jwt-token>"
+export AUI_ENVIRONMENT="production"
+export AUI_ACCOUNT_ID="<account-id>"
+export AUI_ORGANIZATION_ID="<org-id>"
+```
+
+### Example Pipeline
+
+```bash
+# Login with token
+aui login --token "$AUI_AUTH_TOKEN" --environment production
+
+# Import, validate, push
+aui import-agent <agent-id> --dir ./agent-config
+cd ./agent-config
+aui validate --strict
+aui push
+
+# Publish and activate
+aui version publish
+aui version activate
+```
+
+### All Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `AUI_AUTH_TOKEN` | Auth token (skip login) |
+| `AUI_AUTH_TOKEN` | Auth token (skip interactive login) |
 | `AUI_API_URL` | Override API base URL |
 | `AUI_ENVIRONMENT` | `staging`, `custom`, or `production` |
 | `AUI_ACCOUNT_ID` | Account ID |
@@ -289,26 +618,124 @@ aui env production   # Switch to production
 | `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`) |
+| `AUI_DEBUG` | Enable verbose debug logging (`AUI_DEBUG=1`) |
+
+---
+
+## Configuration
+
+### Global Config Files
+
+| 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) |
+| `~/.aui/api-workflow-key` | API Workflow key |
+
+### Project Config (.auirc)
+
+Created during import, stored in the project root:
+
+```json
+{
+  "agent_code": "support-agent",
+  "agent_id": "69cd0a61b6924d36aafaf3f6",
+  "environment": "custom",
+  "account_id": "69c919bcb506d3e323e0397e",
+  "organization_id": "68c004560ed54fdf78c551d1",
+  "network_category_id": "69b2e9385d33a2096c543294",
+  "version_id": "69cd0ca8168d739104520c60",
+  "version_label": "v1.2"
+}
+```
+
+### Environments
+
+```bash
+aui env                   # Show current
+aui env staging           # Switch to staging
+aui env custom            # Switch to custom (v3 endpoints)
+aui env production        # Switch to production
+aui login --environment staging  # Set during login
+```
+
+---
+
+## Troubleshooting
+
+### Enable Debug Logging
+
+```bash
+AUI_DEBUG=1 aui push
+AUI_DEBUG=1 aui import-agent <id>
+```
+
+Debug mode logs every API request URL, response status, and body.
+
+### Common Issues
+
+| Issue | Solution |
+|-------|---------|
+| `Not logged in` | Run `aui login` |
+| `Missing network_category_id` | Re-import the agent: `aui import-agent` |
+| `Version not found` | Run `aui version list` to see available versions |
+| `422 on push` | Check `aui validate --strict` for schema errors. Review `.aui/push-logs/` for API details |
+| `No changes detected` | The push baseline matches your files. Make an edit and try again |
+| Agent settings 401/403 | Provide an API key: `aui push --api-key <key>` |
+| README not showing on npm | Ensure `README.md` is at the package root before `npm publish` |
+
+### Push Logs
+
+Every push saves detailed API call logs:
+
+```
+.aui/push-logs/
+├── POST-tool-product_search.txt
+├── PATCH-param-budget-range.txt
+└── ...
+```
+
+### Push Memory
+
+Push results are saved as markdown for reference:
+
+```
+memory/
+└── push-2026-04-01T12-16-41-772Z.md
+```
+
+---
 
 ## Local Development
 
 ```bash
+git clone <repo-url>
 cd aui-agent-builder
 npm install
 npm run build
-npm link
+npm link              # Makes `aui` available globally from source
 ```
 
+```bash
+npm run watch         # Recompile on file changes
+npm test              # Run tests
+```
+
+---
+
 ## Updating
 
 ```bash
-aui upgrade              # Auto-detect npm or Homebrew
-npm install -g aui-agent-builder   # Manual npm
-brew upgrade aui                   # Manual Homebrew
+aui upgrade                          # Auto-detect npm or Homebrew
+npm install -g aui-agent-builder     # Manual npm
+brew upgrade aui                     # Manual Homebrew
 ```
 
-The CLI checks for updates every 24 hours and shows a banner when one is available.
+The CLI checks for updates every 24 hours and shows a notification banner when a new version is available.
+
+---
 
 ## License