aui-agent-builder 0.4.0-alpha.0 → 0.4.0

package/README.md

@@ -132,25 +132,68 @@ draft ──→ published ──→ active
 
 ## Commands Reference
 
+### Discovering commands
+
+```bash
+aui --help                  # Human-readable command overview
+aui <command> --help        # Options for any command (e.g. aui integration test --help)
+aui --help --json           # Full command tree as a JSON envelope (for tooling / coding agents)
+aui <command> --help --json # JSON help scoped to a single command/subcommand
+```
+
+`aui --help --json` emits `{ "success": true, "data": { name, version, command } }`,
+where `command` recursively lists every subcommand with its `description`,
+`arguments`, and `options` (each option carries `flags`, `description`,
+`default`, and `takesRequiredValue` / `takesOptionalValue`).
+
 ### Authentication
 
 ```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
+aui login                              # Open browser for authentication (defaults to the production environment)
+aui login --email <email>              # Login with email (OTP)
+aui login --environment staging        # Login to a specific environment (staging | custom | production | eu-production)
+aui login --token <jwt>                # Login with a JWT token (for CI/CD)
+aui login --token <jwt> --refresh-token <jwt>   # Token + refresh token (auto-renewal in automated pipelines)
+aui login --account-id <id>            # Skip account selection
+aui login --api-key <key>              # Store an Agent Settings API key for import/push
+aui login --url <url>                  # Override the default login/playground URL
+aui logout                             # Clear local session and credentials
 ```
 
 ### Agent Management
 
 ```bash
 aui agents                       # Interactive menu: list, create, switch, import, delete
-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
+aui agents --list                # List agents (scope: --account-id, else the project's .auirc account)
+aui agents --create              # Create, then auto-import into ./<agent-name> and drop you in
+aui agents --create --template --category <id>   # Create a clone-source template at category scope
+aui agents --switch              # Switch the SESSION's current agent + version (interactive picker)
+aui agents --versions [agentId]  # List versions for an agent (accepts an agent-management OR network id)
+aui agents --use <agentId>       # Select an agent directly by ID
 aui agents --delete              # Interactive: org → account → agent → choose scope (whole / one version / all versions)
 ```
 
+**`aui agents --create` is end-to-end.** It creates the agent + its first
+version, **auto-imports the editable draft into a new `./<agent-name>` folder**
+(use `--dir <path>` to override), and **drops you into that folder via an
+interactive subshell** so you can start editing immediately — run `exit` to
+return. The creation **mode follows your environment**: `staging` / `custom` →
+bundle mode, `production` / `eu-production` → records mode. Override with
+`--bundle-mode` / `--records-mode`.
+
+In **bundle mode**, the Apollo endpoint provisions everything server-side
+(network → agent → version → publish → activate) **and creates a draft for
+editing**; the CLI imports **that draft** (resolved via `GET .../versions`),
+not the published active version — you can only `aui push` into a draft. It
+never creates a draft itself (falls back to the active version only if none is
+found). In **records mode**, the create flow snapshots a v1.0 draft and imports
+it. **Non-interactive creation is create-only:** `--json`, piped output, CI,
+and the agent-builder-bff sandbox skip BOTH the auto-import and the subshell and
+behave like a plain create (set `AUI_AUTO_IMPORT=1` to force the import in
+automation; `AUI_AUTO_IMPORT=0` to disable it in a terminal). A child process
+can't change the parent shell's cwd, which is why the interactive case opens a
+nested shell.
+
 **Non-interactive creation:**
 
 ```bash
@@ -163,8 +206,12 @@ 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
+# Import the new agent into a specific folder instead of ./<agent-name>
+aui agents --create --name "My Agent" --account-id <id> --dir ./my-agent
+
+# Force a creation mode regardless of environment
+aui agents --create --name "My Agent" --account-id <id> --records-mode
+aui agents --create --name "My Agent" --account-id <id> --bundle-mode
 
 # One-step: create + version + publish + activate
 aui agents --create --name "My Agent" --account-id <id> --full
@@ -211,77 +258,135 @@ aui agents --delete --network-id <network-id> --yes --json
 ### Import & Pull
 
 ```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
+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 --tag <vX.Y>                 # Pull a specific revision tag (e.g. v3.2)
+aui import-agent --scope-level category       # Import at category scope
+aui import-agent --dir ./my-folder            # Output to a specific directory
+aui import-agent --templates                  # Pick from category-scoped template agents (kind=template)
+aui import-agent --templates --category <id>  # Restrict the template picker to one category
+aui import-agent --with-kb-files              # Also download original KB binaries (skipped by default)
+aui import-agent --skip-kb-files              # Skip the knowledge-base-files schema fetch
+aui import-agent --skills claude,cursor,opencode   # Generate AI coding skills
+aui import-agent --no-skills                  # Skip skill generation
+aui import-agent --exclude-skills             # Write .claude/.cursor/.opencode to the CWD instead of --dir
+aui import-agent --skills-env <env>           # Override env for Notion skill/doc pages
+aui import-agent --include-evaluate           # Include the evaluate (test_questions) schema
+aui import-agent --reset-git                  # On re-import, wipe local git history and start a fresh baseline
+aui import-agent --api-key <key>              # Use a specific Agent Settings API key
 ```
 
+> [!IMPORTANT]
+> **`aui import-agent` defaults to the *active* version.** With no `--version` (or `--tag`), you silently get whatever is **live** in the backend — not the version you think you're editing. The version that's active can change out from under you (someone else activates a new one, a rollback happens, etc.).
+>
+> **Always pass `--version <id>` (or `--tag <vX.Y>`) to pin exactly what you import**, and then **fingerprint-check the result** before you start editing — confirm you got the right version by spot-checking something cheap and deterministic, e.g. the parameter count, the number of tools/rules, or the version tag printed in the import summary. If the fingerprint doesn't match what you expect, you imported the wrong version — re-import with the correct `--version`.
+
 ```bash
-aui pull                                  # Pull latest into existing project
+aui pull                                  # Pull latest into existing project (defaults to the active version)
 aui pull --force                          # Skip overwrite confirmation
+aui pull --version <id>                   # Pull a specific agent version by ID
+aui pull --tag <vX.Y>                     # Pull a specific revision tag (e.g. v3.2)
 aui pull --scope-level <level>            # Pull at a specific scope level
+aui pull --with-kb-files                  # Also download original KB binaries
+aui pull --skip-kb-files                  # Skip the knowledge-base-files schema fetch
+aui pull --skills claude,cursor,opencode  # Regenerate AI coding skills
+aui pull --no-skills                      # Skip skill generation
+aui pull --include-evaluate               # Include the evaluate (test_questions) schema
+aui pull --api-key <key>                  # Use a specific Agent Settings API key
 ```
 
 ### Push
 
+Push is only allowed to draft versions. If no draft exists, the CLI will reject the push and guide you to create one first.
+
 ```bash
-aui push                                  # Push changes (auto-creates version draft)
+aui push                                  # Push changes into the current draft version
 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
+aui push --agent-id <id>                  # Override agent target (agent_management_id or network_id; defaults to .auirc)
+aui push --version-id <id>                # Push into a specific draft (must be a draft)
+aui push --commit-message "<msg>"         # Save note attached to the new revision (≤ 4000 chars)
+aui push --caller <agent_builder|ui|cli>  # Multipart "caller" field for the /push endpoint (default: cli)
+aui push --api-key <key>                  # Use a specific Agent Settings API key
+aui push --force                          # Accepted for back-compat (no-op under the current endpoint)
+aui push --skip-validation                # Accepted for back-compat (no-op under the current endpoint)
 ```
 
+If push fails partially, re-run `aui push` to retry the failed changes.
+
 ### Version Management
 
 ```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)
+aui version list --json                   # Machine-readable: full (untruncated) IDs + stats
+
+# Create — single step, NO prompts (always bumps version number: v1, v2, v3, ...)
+aui version create                                        # Auto: picks source by agent mode
+aui version create --source agent-scope                   # Override: new version from live scope
+aui version create --source version --from <id>           # Override: clone from a specific version
+aui version create --source template --from-template <id> # Override: clone from a template agent's bundle
+aui version create --agent-id <agent-management-id>       # Target a specific agent explicitly
+aui version create --label "Release 2" --tags "prod" --notes "..."   # Optional metadata
+
+# Lifecycle (no prompts — resolve agent + version from .auirc, or pass them explicitly)
+aui version publish                       # Publish the .auirc draft
+aui version publish <id>                  # Publish a specific draft (overrides .auirc)
+aui version activate                      # Activate the .auirc version as live
+aui version activate <id>                 # Activate a specific version (overrides .auirc)
+aui version archive <id>                  # Archive a published version (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"
 ```
 
+> **Which agent does `aui version *` target?** Resolution order: `--agent-id`
+> (explicit) → the project's `.auirc` (`agent_management_id`, then `agent_id`)
+> → the active session's agent. Inside a project, the CLI resolves the
+> **project's own** agent; if its `.auirc` ids don't resolve it now errors
+> instead of silently falling back to your session's "current" agent. This is
+> the same resolver `aui push` uses, so `version` and `push` always target the
+> same agent.
+>
+> **`version create` is single-step and never prompts.** It inspects the
+> agent's storage mode (the same `detectAgentBundleMode` switch `push` / `pull`
+> / `import` use — honours `AUI_FORCE_AGENT_MODE`, defaults to records on older
+> backends) and creates the draft directly:
+>
+> | Agent mode | Request body |
+> |------------|--------------|
+> | bundle (`bundle_mode=true`) | `source: "version"`, `from_version: <active version>` (override with `--from`) |
+> | records (`bundle_mode=false` / missing) | `source: "agent-scope"` |
+>
+> `--source` / `--from` / `--from-template` / `--label` / `--tags` / `--notes`
+> all override; with no flags it "just works" for the agent's mode. Because it
+> never prompts, it's safe for Claude Code, CI, and `agent-builder-bff`
+> sandboxes.
+>
+> **Non-interactive / automation for other `version` subcommands.** `list`,
+> `get`, etc. run without prompts in `--json` mode or when stdin/stdout isn't a
+> TTY. When several agents could match and none is selected, pass `--agent-id`
+> rather than relying on the picker. For programmatic consumers, always read
+> IDs and stats from `--json` — the human table abbreviates IDs to fit the
+> terminal.
+
 ### Knowledge Bases & Documents
 
-```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/
+All knowledge-base work goes through `aui rag`. The bare command opens an
+interactive menu (list KBs, upload files, upload URLs, export, import); the
+flags jump straight to a specific action.
 
-# 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
+```bash
+aui rag                # Interactive menu: list, upload files, upload URLs, export, import
+aui rag --add-file     # Jump straight to the upload flow (files or URLs)
+aui rag --status       # Per-resource indexing status (completed / failed / in-progress) for each KB
 ```
 
+> The standalone `aui document …` command has been folded into `aui rag` —
+> uploads and indexing status now live under the single `rag` command.
+
 ### Development Tools
 
 ```bash
@@ -298,27 +403,54 @@ aui revert                                # Discard local changes
 
 ```bash
 aui integration                   # Interactive menu — Create or Discover
-aui integration create            # Guided flow — org, account, agent, Manual or Native MCP
+aui integration create            # Guided flow — org, account, agent, Manual or Native MCP (add --full for non-interactive)
 aui integration discover          # Guided MCP tool discovery
+aui integration toolkits          # List native (Composio) toolkits  (non-interactive, --json)
+aui integration tools --slugs ... # Fetch Composio tool descriptors by slug  (non-interactive, --json)
+aui integration mcp-url --toolkit <slug>   # Provision (or reuse) a Composio MCP server → { server_id, server_url }
+aui integration test --params ... # Live-call an HTTP endpoint, return raw + parsed response  (always JSON)
+aui integration mcp-test ...      # Execute an MCP tool directly (Composio or Direct) and return the raw response (always JSON)
 ```
 
-**Non-interactive — Manual MCP:**
+**Discovery (fully non-interactive, `--json`):**
 
 ```bash
-aui integration create --name "My MCP" --url <url> --all-tools
-aui integration create --name "My MCP" --url <url> --tools tool1,tool2
-aui integration create --name "My MCP" --url <url> --all-tools --auth-type token --auth-token <token>
+aui integration toolkits --all --json                       # every native toolkit
+aui integration toolkits --search notion --json             # filter the directory
+aui integration tools --slugs GMAIL_SEND_EMAIL,GMAIL_CREATE_EMAIL_DRAFT --json
+aui integration discover --url <mcp-url> --json             # tools from a manual MCP server
+aui integration mcp-url --toolkit gmail --all-tools --json  # provision/reuse a Composio MCP server
+```
+
+**Non-interactive — Manual MCP** (add `--full` to skip every prompt):
+
+```bash
+aui integration create --full --name "My MCP" --url <url> --all-tools
+aui integration create --full --name "My MCP" --url <url> --tools tool1,tool2
+aui integration create --full --name "My MCP" --url <url> --all-tools --auth-type token --auth-token <token>
 aui integration discover --url <url>
 aui integration discover --url <url> --auth-type token --auth-token <token>
+aui integration discover --url <url> --auth-type api_key --auth-token <key> --auth-header-name X-API-Key
 ```
 
-**Non-interactive — Native MCP:**
+**Non-interactive — Native MCP** (add `--full` to skip every prompt):
 
 ```bash
-aui integration create --toolkit notion --name "Notion" --all-tools
-aui integration create --toolkit github --name "GitHub" --tools GITHUB_CREATE_ISSUE,GITHUB_GET_ISSUE
+aui integration create --full --toolkit notion --name "Notion" --all-tools
+aui integration create --full --toolkit github --name "GitHub" --tools GITHUB_CREATE_ISSUE,GITHUB_GET_ISSUE
 ```
 
+**MCP authentication (`--auth-type`).** Manual MCP, `discover`, and `mcp-test`
+share the same canonical auth surface (the CLI alias `token` maps to
+`bearer_token` before anything is sent to the wire):
+
+| Auth type | Flags |
+|-----------|-------|
+| `none` | _(default)_ |
+| `bearer_token` (alias `token`) | `--auth-type bearer_token --auth-token <tok>` |
+| `api_key` | `--auth-type api_key --auth-token <key> --auth-header-name <Header>` |
+| `oauth_client_credentials` | `--auth-type oauth_client_credentials --oauth-url <token-endpoint> --oauth-client-id <id> --oauth-client-secret <secret>` `[--oauth-method GET\|POST]` `[--oauth-grant-type <grant>]` |
+
 **Shared flags (both Manual & Native):**
 
 | Flag | Description |
@@ -330,28 +462,245 @@ aui integration create --toolkit github --name "GitHub" --tools GITHUB_CREATE_IS
 | `--config-method <manual\|native>` | Force config method |
 | `--json` | Machine-readable JSON output |
 
+**Test an integration endpoint (`aui integration test`):**
+
+Live-call an integration endpoint and get back the **raw** response
+(`test_data`), what the `response_parser` extracts (`parsed_test_response`),
+and — on the default path — `mapped_entities` (how the response maps onto
+the agent's entities). The programmatic replacement for hand-running `curl`.
+Always emits a JSON envelope and is fully non-interactive.
+
+`--raw` vs. the default differ only in what is **sent**:
+
+- **`--raw`** → calls the endpoint **without** `bundle_mapping` (plain
+  integration test; no `mapped_entities`).
+- **default** → also sends `bundle_mapping` (`response_mapping` +
+  `parameters` + `scope_entities`), so the endpoint **also returns
+  `mapped_entities`**. This is the path the LLM uses while building an agent.
+
+```bash
+# Default — full simulation incl. entity mapping
+aui integration test --params '{
+  "url": "https://www.themealdb.com/api/json/v1/1/search.php",
+  "method": "GET",
+  "query_params": { "s": "pasta" },
+  "bundle_mapping": {
+    "response_mapping": { "entities": [ { "code": "Meal", "identifier": "meal-id", "paths": ["meals"], "mappings": [ { "key": "idMeal", "param": "meal-id" }, { "key": "strMeal", "param": "meal-name" } ] } ] },
+    "parameters": [ { "code": "meal-id", "type": "string" }, { "code": "meal-name", "type": "string" } ],
+    "scope_entities": [ { "name": "Meal", "identifier": "meal-id", "reference": "meal-name", "parameters": ["meal-id","meal-name"] } ]
+  }
+}'
+
+# Raw — no bundle_mapping / mapped_entities
+aui integration test --raw --url https://www.themealdb.com/api/json/v1/1/search.php --query-params '{"s":"pasta"}'
+```
+
+| Flag | Description |
+|------|-------------|
+| `--params <json>` | Full request body (see fields below) |
+| `--params-file <path>` | Read the request body JSON from a file |
+| `--url <url>` | Endpoint URL (overrides `params.url`) |
+| `--method <method>` | HTTP method (default `GET`) |
+| `--request-body <json>` | Request body JSON |
+| `--query-params <json>` | Query params JSON |
+| `--headers <json>` | Extra request headers JSON |
+| `--auth-type <type>` | `BEARER_TOKEN`, `API_KEY`, `BASIC`, `NONE` |
+| `--auth-token <token>` | Auth token used with `--auth-type` |
+| `--response-parser <js>` | JS snippet run against `response` |
+| `--bundle-mapping <json>` | Full `bundle_mapping` (`response_mapping`, `parameters`, `scope_entities`) |
+| `--response-mapping <json>` | `bundle_mapping.response_mapping` (from `integrations.aui.json` → `settings.response_mapping`) |
+| `--parameters <json>` | `bundle_mapping.parameters` (from `parameters.aui.json` → `parameters`) |
+| `--scope-entities <json>` | `bundle_mapping.scope_entities` (from `entities.aui.json` → `entities`) |
+| `--raw` | Plain call **without** `bundle_mapping` (no `mapped_entities`) |
+
+> **`authentication` is a discriminated union** keyed on `type`
+> (`BEARER_TOKEN`, `API_KEY`, `BASIC`, …). An empty `{}` or one without a
+> `type` is treated as "no auth" and dropped automatically (it would
+> otherwise 422), so you can paste an integration config verbatim.
+
+Output: `{ "success": true, "data": { url, method, raw, bundle_mapping_sent, test_data, parsed_test_response, mapped_entities } }`.
+
+**Execute an MCP tool (`aui integration mcp-test`):**
+
+Live-execute a single MCP tool — either a Composio (native) tool or a tool on a
+Direct (manual) MCP server — and get the raw tool response back. Like
+`integration test`, it returns `mapped_entities` when a `bundle_mapping` is
+sent. Always emits a JSON envelope; non-interactive when `--toolkit`+`--tool`
+or `--url`+`--tool` are provided.
+
+```bash
+# Composio — send an email
+aui integration mcp-test --type composio --toolkit gmail --tool GMAIL_SEND_EMAIL \
+  --arguments '{"to":"user@example.com","subject":"Hi","body":"Test"}'
+
+# Direct MCP server — bearer token (raw, no mapping)
+aui integration mcp-test --type direct --url https://my-mcp.example.com/mcp \
+  --transport-type STREAMABLE_HTTP \
+  --auth-type bearer_token --auth-token <token> \
+  --tool <tool-name> --arguments '{}' --raw
+
+# Direct MCP server — API key in a custom header
+aui integration mcp-test --type direct --url https://my-mcp.example.com/mcp \
+  --auth-type api_key --auth-token <key> --auth-header-name X-API-Key \
+  --tool <tool-name> --arguments '{}' --raw
+```
+
+Output: `{ "success": true, "data": { type, tool, raw, bundle_mapping_sent, response, mapping_data, status, elapsed_sec } }`.
+
+**Provision a Composio MCP server (`aui integration mcp-url`):**
+
+```bash
+aui integration mcp-url --toolkit gmail --all-tools --json   # → { server_id, server_url }
+aui integration mcp-url --toolkit notion --tools NOTION_CREATE_PAGE --server-id <existing-id> --json
+```
+
 ### Chat & Testing
 
 ```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
 ```
 
+### Runtime Messaging — Apollo
+
+Drive an agent at runtime through the Apollo messaging API. These four
+commands are **fully non-interactive**, **output JSON by default** (pass
+`--pretty` for the human view on all but `trace`), and work for **any
+agent** (bundle-mode or records-mode). The target agent is resolved from
+`--agent-id` or `.auirc.agent_management_id`, and authentication uses your
+normal CLI session (`Authorization: Bearer` — the gateway forwards Apollo's
+service auth for you).
+
+```bash
+# Start a conversation thread (alias: create-task) — JSON output by default
+aui apollo create-thread                                 # uses .auirc agent + logged-in user
+aui apollo create-thread --agent-id <id> --user-id <id> --task-origin-type web-widget
+aui apollo create-thread --active                        # run against the agent's live version
+aui apollo create-thread --pretty                        # human terminal view instead of JSON
+
+# Send a message. It validates + forwards your local .aui.json edits, so the
+# reply reflects them; the returned `id` IS the interaction id.
+aui apollo send-message --task-id <id> --text "Hello"                       # trace_info always included
+# Seed caller-known session facts (pre-populates the task; not raw LLM input):
+aui apollo send-message --task-id <id> --text "show my orders" \
+  --agent-context '{"agent_variables":{"user_id":"u_123","locale":"en-US"},"context":{"url":"https://example.com"}}'
+
+# Regenerate a thread from an interaction and replay a message (bundle + trace always sent)
+aui apollo rerun --task-id <id> --interaction-id <iid> --text "Edited"
+aui apollo rerun --task-id <id> --interaction-id <iid> --text "Edited" --version-id <vid>
+aui apollo rerun --task-id <id> --interaction-id <iid> --text "Edited" --active   # vs the live version
+
+# Inspect the agent's reasoning (trace) — always JSON
+aui apollo trace --task-id <id>                          # all interaction traces
+aui apollo trace --task-id <id> --interaction-id <iid>   # a single interaction's trace
+```
+
+**Flags by command**
+
+| Command | Required | Optional |
+|---|---|---|
+| `create-thread` (alias `create-task`) | — | `--agent-id`, `--user-id`, `--task-origin-type`, `--version-id`, `--version-tag`, `--active`, `--pretty` |
+| `send-message` | `--task-id`, `--text` | `--agent-id`, `--agent-context`, `--path`, `--pretty` |
+| `rerun` | `--task-id`, `--interaction-id`, `--text` | `--version-id`, `--version-tag`, `--active`, `--agent-id`, `--path`, `--pretty` |
+| `trace` | `--task-id` | `--interaction-id`, `--agent-id` (always JSON) |
+
+> **JSON by default:** `create-thread`, `send-message`, and `rerun` emit the
+> JSON envelope by default; pass `--pretty` for the human Ink view. `trace` is
+> always JSON.
+
+> **`--active` (create-thread, rerun):** run against the agent's currently
+> active (live) version instead of the local draft / passed version. Resolves
+> the agent's `active_version_id` from agent-management. Mutually exclusive with
+> `--version-id` / `--version-tag`.
+
+> **`--agent-context` (send-message):** a JSON object
+> `{"agent_variables":{…},"context":{…}}` of caller-known session facts.
+> `agent_variables` are consumed by the runtime as the agent's `agent_context`
+> config to pre-populate the task (not sent to the LLM as raw text); `context`
+> is optional extra per-message fields (`url`, `welcome_message`, …).
+
+> **Bundle always sent:** both `send-message` and `rerun` validate + forward
+> your local agent files (so the reply reflects your edits). Run these inside an
+> imported agent folder (or pass `--path <dir>`).
+
+> **Interaction IDs:** the `id` returned by `aui apollo send-message` is the
+> interaction id — pass it to `rerun --interaction-id` and `trace
+> --interaction-id`.
+
+> **Validate-before-send:** by default `send-message` / `rerun` run the remote
+> validator on your local files first and abort if they're invalid — a broken
+> config never reaches the runtime. Run `aui validate` to see specific errors.
+
 ### Configuration & Utilities
 
 ```bash
 aui account                               # Manage accounts (list, create, switch)
 aui env                                   # Show current environment
-aui env staging                           # Switch environment
+aui env staging                           # Switch environment (staging | custom | production | eu-production)
 aui pull-schema                           # Fetch domain schemas from backend
-aui add-integration                       # Add API / RAG / MCP integration (legacy)
+aui pull-schema --improved                # Apply coding-agent-friendly schema improvements
+aui sync-session                          # Re-scope your session (org/account/token) to this project's .auirc
 aui integration create                    # Create MCP integration (Manual or Native)
-aui upgrade                               # Update to latest version
+aui curl                                  # Show the last command's HTTP requests as curl commands
+aui report "<message>"                    # BETA: report a CLI/agent issue or learning
+aui upgrade                               # Update to the latest version
+```
+
+### Session Sync
+
+`aui login` issues a token scoped to your **default** organization. If you
+import an agent that lives in a different org, `push` / `pull` / `apollo` calls
+return `403` or `404 ("Agent not found")` until the session is re-scoped.
+`aui sync-session` reconciles your local session (`~/.aui/session.json`) with
+this project's `.auirc` — organization, account, and the token's org claim — so
+every command targets the right org.
+
+```bash
+aui sync-session                  # Reconcile the session with the nearest .auirc
+aui sync-session --path ./my-agent   # Point at a specific project directory
+aui sync-session --json           # Machine-readable (for scripts / the BFF)
+aui update-session                # Alias for sync-session
 ```
 
+> **Behavior:** no-op (zero network) when already in sync. Cross-org → mints and
+> persists an org-scoped token. Cross-env (the `.auirc` env differs from the
+> session env) → a token can't be re-scoped across environments, so it switches
+> the env and exits non-zero asking you to `aui login` on that env. Fully
+> non-interactive — safe to run from `agent-builder-bff` in the sandbox.
+
+### Inspecting HTTP requests — `aui curl`
+
+Every command's HTTP calls are captured and can be replayed as `curl`
+commands for debugging.
+
+```bash
+aui curl                          # All requests from the last command
+aui curl --failed                 # Only failed requests
+aui curl --last <n>               # Only the last N requests
+aui curl --method PATCH           # Filter by HTTP method
+aui curl --search <term>          # Filter by URL or label substring
+```
+
+### Reporting issues — `aui report` (BETA)
+
+Report a CLI or agent issue, a learning, or a suggestion. Coding agents are
+expected to use this to surface problems they hit.
+
+```bash
+aui report "Push failed with a confusing 422"        # type defaults to "issue"
+aui report -t learning -m "PATCH is idempotent on retry"
+aui report --dry-run "..."                           # Print the payload without sending
+```
+
+| Flag | Description |
+|------|-------------|
+| `-t, --type <type>` | `issue` (default), `learning`, or `suggestion` |
+| `-m, --message <msg>` | Report message (alternative to the positional argument) |
+| `--agent <name>` | Override the detected coding agent (`claude` / `cursor` / `opencode`) |
+| `--context <json>` | Extra context — raw text or a JSON string |
+| `--dry-run` | Print the payload without sending it |
+| `--task-id` / `--session-id` / `--interaction-id <id>` | Associate the report with a task / session / interaction |
+
 ### Command Aliases
 
 | Alias | Equivalent |
@@ -362,6 +711,9 @@ aui upgrade                               # Update to latest version
 | `aui ls` | `aui list-agents` |
 | `aui versions` | `aui version` |
 | `aui integrations` | `aui integration` |
+| `aui update-session` | `aui sync-session` |
+| `aui apollo create-task` | `aui apollo create-thread` |
+| `aui version snapshots` | `aui version snapshot` |
 
 ---
 
@@ -370,34 +722,33 @@ aui upgrade                               # Update to latest version
 ### Create and Deploy a New Agent
 
 ```bash
-# Step 1: Create the agent (with a v1.0 draft ready to edit)
-aui agents --create --name "Support Agent" --account-id <id> --draft
-
-# Step 2: Import as local files
-aui import-agent
+# Step 1: Create the agent. This also auto-imports it into ./support-agent
+# and drops you into that folder via an interactive subshell — no separate
+# `aui import-agent` needed. (Use --dir to choose a different folder.)
+aui agents --create --name "Support Agent" --account-id <id>
 
-# Step 3: Edit configuration in your editor
-cd ./support-agent
+# Step 2: Edit configuration in your editor (you're already in the folder)
 # → Edit agent.aui.json, tools/*.aui.json, parameters.aui.json, etc.
 
-# Step 4: Validate and push
+# Step 3: Validate and push
 aui validate
 aui push
 
-# Step 5: Publish and activate
+# Step 4: Publish and activate
 aui version publish
 aui version activate
 ```
 
-**Three creation modes:**
+> Prefer the classic two-step flow? It still works: create with `--json`
+> (which skips the auto-import/subshell), then run `aui import-agent` yourself.
+
+**Creation modes:**
 
 ```bash
-# Agent only (no version) — create version manually later
+# Default — creates the agent + a v1.0 draft version (ready to import & edit).
+# A draft is always created; there is no flag to skip it.
 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
 ```
@@ -405,15 +756,24 @@ aui agents --create --name "Support Agent" --account-id <id> --full
 ### Edit → Push → Deploy Cycle
 
 ```bash
-aui import-agent                  # Downloads active version as .aui.json files
+# 1. Create a draft version first
+aui version create                # Creates draft v2
+
+# 2. Import the draft as local files
+aui import-agent --version <draft-id>
 cd ./my-agent
 
-# Make changes to any .aui.json file...
+# 3. Make changes to any .aui.json file...
 
+# 4. Validate and push
 aui diff                          # See what changed
 aui validate                      # Validate against schemas
-aui push                          # Push changes into a new draft
+aui push                          # Push changes into the draft
+
+# 5. If push fails partially, re-run to retry
+aui push                          # Retries only failed changes
 
+# 6. Publish and go live
 aui version publish               # Lock the draft
 aui version activate              # Make it live
 ```
@@ -421,10 +781,10 @@ aui version activate              # Make it live
 ### Version Branching
 
 ```bash
-# Create a revision from v1.0 (→ v1.1)
-aui version create --source version --from <v1.0-id>
+# Clone from an existing version (→ v3)
+aui version create --source version --from <v2-id>
 
-# Or create a new major version from live scope (→ v2.0)
+# New version from live scope (→ v3)
 aui version create --source agent-scope
 
 # Import a specific version for editing
@@ -475,9 +835,8 @@ my-agent/
 │
 ├── GUIDE.md                       # Getting started guide
 ├── AGENTS.md                      # Agent documentation
-├── BEST_PRACTICES.md              # Configuration best practices
 │
-├── .cursor/rules/                 # Cursor AI rules per config type
+├── .cursor/skills/                # Cursor skills per config type
 ├── .claude/skills/                # Claude Code skills per config type
 └── .opencode/skills/              # OpenCode skills per config type
 ```
@@ -581,54 +940,89 @@ Card templates with JSX and field mappings:
 
 ### How Versioning Works
 
-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
+Pushing is only allowed to **draft versions**. The CLI will never auto-create drafts during push — you must create one explicitly first.
+
+1. **Create a draft version** using `aui version create`
+2. **Import** the draft to get local files: `aui import-agent --version <draft-id>`
+3. **Edit** the local `.aui.json` files
+4. **Push** changes into the draft (the CLI validates the target is a draft)
+5. **Publish** to lock the draft permanently
+6. **Activate** to make it the live configuration
 
 ```bash
-aui import-agent          # Get active version (e.g. v1.0)
+aui version create        # Create draft v2 (always bumps version number)
+aui import-agent --version <draft-id>  # Get the draft as local files
 # Edit files...
-aui push                  # Creates draft v1.1, pushes changes
-aui version publish       # Locks v1.1
-aui version activate      # v1.1 is now live
+aui push                  # Pushes into the draft (rejects if not a draft)
+aui version publish       # Locks v2
+aui version activate      # v2 is now live
 ```
 
+### Push Flow (detailed)
+
+When you run `aui push`, the following happens:
+
+1. **Draft validation** — The CLI checks that the target version is a draft. If the version in `.auirc` or `--version-id` is not a draft (e.g. published, archived), push is rejected with a descriptive error and next steps.
+
+2. **Entity push** (Step A) — The CLI pushes individual entity changes (parameters, tools, integrations, etc.) to the agent-settings API. Each task is tracked with success/failure, and the flow continues even when some entities fail.
+
+3. **Snapshot push** (Step B — last step) — After entity push completes, the CLI uploads the local file state as a snapshot to the server. This **always runs** regardless of entity-push outcomes, because **files are the source of truth** — the snapshot preserves your local state even if some DB updates failed. Version tag is bumped automatically on the server when the snapshot succeeds (e.g. `v3.2 → v3.3`).
+
+4. **Baseline update** — Local git baseline is committed only if the snapshot succeeded. Within that, only files whose entity-push succeeded are added to the baseline.
+
+#### Why snapshot-last?
+
+The snapshot is meant to reflect what's actually been applied to the agent. Putting it after the entity push means:
+
+- **Snapshot ≈ DB state** — the IA/AI tooling can rely on the snapshot files as the source of truth without ever hitting the entity DB
+- **Auto-bump represents real updates** — `v{N}.X` only increments when a push attempt actually completed
+- **File-level rejections are caught locally** by `aui validate` (schema + cross-ref checks) before push, so server-side snapshot validation rarely fails
+- **Partial DB failures are tolerable** — the snapshot still uploads, preserving file history. Re-running `aui push` retries the failed entities (PATCHes are idempotent)
+
+#### Failure scenarios
+
+| What failed | What happens | Next step |
+|-------------|--------------|-----------|
+| Entity push partial | Snapshot still uploads (captures file state). Baseline committed only for succeeded files. | Re-run `aui push` to retry failed entity updates. |
+| Snapshot fails after entity push succeeded | Baseline is **not** updated. Entity changes already in DB. | Re-run `aui push`. Entities will re-PATCH (idempotent), then snapshot retries. |
+| Both fail | Baseline unchanged. | Fix issues from error output, re-run `aui push`. |
+
+If push partially fails, it's the user's responsibility to re-run `aui push` to retry. The CLI shows descriptive errors with "What to do next" guidance for every failure mode.
+
 ### Version Numbering
 
-- **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
+Versions use simple incrementing numbers: v1, v2, v3, etc. There are no revision/minor numbers.
+
+- Use `--source version --from <id>` to clone from an existing version
+- Use `--source agent-scope` for a new version from the current live scope
 
 
 ---
 
 ## Knowledge Bases
 
-### Upload Documents
+Everything below runs through the single `aui rag` command — either via its
+interactive menu (`aui rag`) or the action flags.
 
-```bash
-# Upload files
-aui document report.pdf handbook.docx --kb "Company Policies"
+### Upload Documents & URLs
 
-# Scrape web pages
-aui document --url "https://docs.example.com/faq" --kb "FAQ"
+```bash
+aui rag --add-file    # Pick a KB, then upload local files or scrape web pages
+aui rag               # Or use the menu → "Upload files…" / "Upload URLs…"
 ```
 
-### Check Upload Status
+### Check Indexing 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
+aui rag --status      # Per-resource status (completed / failed / in-progress) for each KB
 ```
 
-### Export & Import
+### List, Export & Import
 
 ```bash
-aui rag --export    # Save all KB metadata and files to knowledge-hubs/
-aui rag --import    # Restore KBs from knowledge-hubs/
+aui rag               # Menu → "List knowledge bases"
+aui rag               # Menu → "Export to knowledge-hubs/"  (saves KB metadata + files locally)
+aui rag               # Menu → "Import from knowledge-hubs/" (restores KBs from the local folder)
 ```
 
 ---
@@ -669,13 +1063,21 @@ aui version activate
 |----------|-------------|
 | `AUI_AUTH_TOKEN` | Auth token (skip interactive login) |
 | `AUI_API_URL` | Override API base URL |
-| `AUI_ENVIRONMENT` | `staging`, `custom`, or `production` |
+| `AUI_ENVIRONMENT` | `staging`, `custom`, `production`, or `eu-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_AGENT_CODE` | Override the agent code resolved from `.auirc` |
 | `AUI_DEBUG` | Enable verbose debug logging (`AUI_DEBUG=1`) |
+| `AUI_AUTO_IMPORT` | Force (`1`) or disable (`0`) the auto-import + subshell after `aui agents --create` |
+| `AUI_FORCE_AGENT_MODE` | Force storage mode for push/pull/import/version (`bundle` or `records`) |
+| `AUI_FETCH_TIMEOUT_MS` | Per-request fetch timeout in ms (default 60000; `0` disables) |
+| `AUI_NO_UPDATE_CHECK` | Disable the background update-check / notification banner |
+| `AUI_DISABLE_TELEMETRY` / `AUI_TELEMETRY=0` | Opt out of OpenTelemetry tracing |
+| `AUI_NO_AGENT_INJECTION` | Suppress the "For Coding Agents" guidance block |
+| `AUI_HOME` | Override the config directory (default `~/.aui`) |
 
 ---
 
@@ -715,6 +1117,7 @@ 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 env eu-production     # Switch to EU production
 aui login --environment staging  # Set during login
 ```
 
@@ -738,6 +1141,10 @@ Debug mode logs every API request URL, response status, and body.
 | `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 |
+| `Version not found` (id looks truncated) | The human `version list` table abbreviates IDs. Scrape IDs from `aui version list --json` |
+| `Could not resolve the agent for this project (.auirc)` | Pass `aui version … --agent-id <agent-management-id>`, or re-run `aui import` / `aui pull` to refresh `.auirc` |
+| `version create` made a draft on the wrong agent | Fixed — `version` now targets the project's `.auirc` agent (or `--agent-id`), not the session's "current" agent |
+| `422` with no detail | The CLI now surfaces the API's validation detail in the error message. Re-run; for full bodies use `AUI_DEBUG=1` |
 | `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>` |
@@ -787,13 +1194,100 @@ npm test              # Run tests
 ```bash
 aui upgrade                          # Auto-detect npm or Homebrew
 npm install -g aui-agent-builder     # Manual npm
-brew upgrade aui                     # Manual Homebrew
+brew update ; brew upgrade aui-io/homebrew-tap/aui    # Manual Homebrew
 ```
 
 The CLI checks for updates every 24 hours and shows a notification banner when a new version is available.
 
 ---
 
+## Architecture & Developer Context
+
+This section provides context for developers (and AI assistants) working on the CLI codebase.
+
+### Project Structure (source)
+
+```
+aui-agent-builder/
+├── bin/aui.js                    # Executable shim → dist/index.js
+├── src/
+│   ├── index.ts                  # CLI entry — Commander program, all command wiring
+│   ├── telemetry.ts              # OpenTelemetry tracing (Logfire)
+│   ├── commands/                 # One file per command
+│   │   ├── push.tsx              # Push flow (snapshot → entity push → bump)
+│   │   ├── version.tsx           # Version lifecycle (create, publish, activate, archive)
+│   │   ├── agents.tsx            # Agent management (create, list, switch, import)
+│   │   ├── import-agent.tsx      # Import agent as local .aui.json files
+│   │   ├── pull-agent.tsx        # Pull latest from backend
+│   │   ├── login.tsx             # Authentication flow
+│   │   └── ...                   # Other commands
+│   ├── api-client/
+│   │   ├── index.ts              # AUIClient — all HTTP calls to backend
+│   │   ├── kb-view-client.ts     # Knowledge base API client
+│   │   └── rag-client.ts         # RAG API client
+│   ├── config/
+│   │   └── index.ts              # Config resolution (env → .auirc → session → defaults)
+│   ├── errors/
+│   │   └── index.ts              # Structured error types (AuthError, ConfigError, etc.)
+│   ├── services/                 # Business logic services
+│   ├── types/                    # TypeScript interfaces for local agent files
+│   ├── ui/                       # Ink components and views
+│   │   ├── components/           # Reusable UI atoms (Spinner, StatusLine, etc.)
+│   │   ├── views/                # Command-specific views (PushView, etc.)
+│   │   └── theme.ts              # Colors, icons, labels
+│   └── utils/                    # Git, JSON output, schema improvements
+└── package.json
+```
+
+### Key Patterns
+
+- **Commander** for CLI argument parsing, **Ink + React** for terminal UI
+- **AUIClient** in `api-client/index.ts` is the single HTTP layer; all API calls go through it
+- Two API surfaces: **Agent Management** (versions lifecycle) and **Agent Settings** (entity CRUD for push)
+- **Config resolution**: `getConfig()` merges env vars → `.auirc` → `~/.aui/session.json` → defaults
+- **Git baseline**: Push uses an internal git repo to track diffs between pushes
+
+### Push Flow (current implementation)
+
+1. Validate auth and project config
+2. Read local `.aui.json` files
+3. Git diff to detect changes since last push
+4. **Draft validation**: Verify the target version is a draft (reject otherwise)
+5. **Entity push**: PATCH/POST/DELETE individual entities (parameters, tools, integrations, rules, etc.) — track per-task success, continue on failures
+6. **Snapshot push** (last step): Multipart POST of all local files to `/v1/agents/{agentId}/versions/{versionId}/snapshot`
+   - Uses JWT auth (Bearer token)
+   - Runs regardless of entity-push outcomes (files = source of truth, DB = best effort)
+   - Version tag is bumped automatically on snapshot success (no separate bump endpoint)
+   - Snapshot tags follow the pattern `v{N}.0`, `v{N}.1`, `v{N}.2`, ... where `N` is the version number; the first push to a version creates `.0`
+   - Implemented in: `pushSnapshot()` in `src/commands/push.tsx` + `client.agentManagement.pushSnapshot()` in `src/api-client/index.ts`
+7. **Baseline update**: Git baseline is committed only when the snapshot succeeded. Within that, only files whose entity-push succeeded are added.
+
+### Snapshot Endpoints
+
+- **POST** `/v1/agents/{agentId}/versions/{versionId}/snapshot` — Upload local files as multipart form data. Version tag bumps automatically on success.
+- **GET** `/v1/agents/{agentId}/versions/{versionId}/snapshot?version_tag=v1.0&expires_in=15` — Retrieve a specific snapshot's manifest + signed download URLs (15-minute expiry).
+
+### Snapshot Browsing (CLI)
+
+| Command | Purpose |
+|---------|---------|
+| `aui version snapshot` | Interactive menu (list / get / diff) |
+| `aui version snapshot list` | List all snapshots for the current version |
+| `aui version snapshot get <tag>` | Show snapshot manifest + signed URLs |
+| `aui version snapshot diff <a> <b>` | File-level diff (SHA-256 + size) |
+| `aui version snapshot diff <a> <b> --full` | Field-level JSON diff (downloads files) |
+
+All snapshot commands support `--agent-id`, `--version-id`, and `--json` for scripting.
+
+### Version Numbering
+
+Versions use simple incrementing numbers (v1, v2, v3). No revision/minor numbers.
+The `bump_mode` parameter in `CreateDraftRequest` is always set to `"version_number"`.
+
+---
+
 ## License
 
-Proprietary — Copyright (c) 2026 AUI. All rights reserved. See [LICENSE](./LICENSE).
+© Augmented intelligence (AUI) Inc. All rights reserved. Use is subject to the
+Terms outlined here:
+[https://www.aui.io/api-and-developer-package-terms-of-service/](https://www.aui.io/api-and-developer-package-terms-of-service/).