@indemn/cli 1.6.0 → 1.7.0

package/skills/agent-builder/SKILL.md

@@ -1,318 +1,155 @@
 ---
 name: agent-builder
-description: Build and configure Indemn AI agents — create agents, set prompts, add functions/tools, manage knowledge bases, and test via chat. Use when creating, configuring, or testing agents.
+description: Build and configure Indemn AI agents — create agents with their basics, set prompts and models, add skills and knowledge bases, set voice, publish on a website, and test via chat. Use when creating, configuring, or testing agents.
 ---
 
 # Agent Builder
 
-You build and configure AI agents using the `indemn` CLI. This skill covers the full lifecycle: create an agent, set its prompt, attach functions and knowledge bases, and test via chat.
+You build and configure Indemn AI agents with the `indemn` CLI (or the same actions as `indemn` MCP tools). Lifecycle: create the agent with its basics, set the prompt and model, add skills and knowledge, test by chatting, then publish.
 
-**Prerequisite:** The `indemn` CLI must be installed and authenticated. Run `indemn whoami` to verify.
+**Before anything:** run `indemn whoami`. It shows the platform (dev or production), the user, the session expiry, and which org commands here act on.
 
 ---
 
-## Workflow
+## Rules that keep you safe
 
-Create agent -> Set prompt & model -> Add functions -> Add knowledge bases -> Link KBs -> Test via chat -> Iterate.
+- **Orgs are never guessed.** Commands act on `--org <id>`, else the folder linked with `indemn link`, else the user's only org. With several orgs and none chosen, the CLI asks, or exits with code 2 and lists them. In MCP, tools take an optional `org_id`; a `needs_input` answer means: ask the user which org, then call again with `org_id`.
+- **Chats are always test conversations.** `indemn chat` and `chat_with_agent` never create billed or analytics-counted conversations; the dashboard shows them with the tester's name.
+- **Changes ask first.** Deletes, imports, prompt and model changes, lifecycle changes and runs show what they would do. In a terminal the CLI asks; scripts pass `--yes`. In MCP, when the host shows an approval form, that form is the question: call the tool and do not ask again in chat. Otherwise the tool returns a `dry_run`; show it, and call again with `confirm: true` only after the user agreed to that exact change. Published agents need `--confirm-published` (CLI) or `confirm_published: true` (MCP) as well.
+- **Exit codes:** 0 ok, 1 error, 2 a choice is needed, 3 log in again (`indemn login`).
+- **Talk in names.** When you report back, call agents, knowledge bases, skills, test sets and runs by their names; show ids only when asked or to tell two items apart. Plain words, short answers, details on request.
 
 ---
 
-## Step 1: Create the Agent
+## Step 1: Create the agent with its basics
 
-Before creating, determine: name/purpose, channels (WEB, WHATSAPP, etc.), persona, functions needed, knowledge sources, and model (`indemn models [--json]`).
+Decide: name, purpose (one line), channels (`indemn channels list`), system prompt, model (`indemn models`).
 
 ```bash
-indemn agents create --name "Acme Insurance Assistant" --channels "WEB,WHATSAPP"
+indemn agents create --name "Acme Renewals" --description "Handles policy renewals" \
+  --channels WEB --prompt-file ./prompts/renewals.md --model openai/gpt-4.1
 ```
 
-- `--channels` defaults to `"WEB"` if omitted. Comma-separated for multiple.
-- Save the returned agent ID -- every subsequent command needs it.
+- Missing basics are asked in a terminal. An agent with the same name in the org is refused (`--allow-duplicate` overrides).
+- From a template: `indemn templates list`, then `indemn agents create --name "Acme Renewals" --template <template-id>` (copies prompt, model, skills and knowledge; not phone numbers, voice or website paths).
+- MCP: `create_agent` asks the user for missing basics when the host can ask, otherwise returns `needs_input` listing them (`minimal: true` creates with a name only).
 
-### Other Agent Operations
+Other agent operations:
 
 ```bash
-indemn agents list [--json] [--limit 20] [--page 2]
-indemn agents get <agent-id> [--json]
-indemn agents update <agent-id> --name "New Name" --description "Updated description"
-indemn agents update <agent-id> --webhook-url "https://example.com/webhook"
-indemn agents clone <agent-id>
-indemn agents delete <agent-id>           # requires confirmation
-indemn agents card <agent-id> --output ./agent-card.pdf   # branded PDF
+indemn agents list | get <id> | update <id> --name/--description
+indemn agents summary <id> [--full]        # what the agent does, before you change it
+indemn agents stats <id> [--from --to]     # conversation metrics (test chats excluded)
+indemn agents clone <id> [--name]          # copy within the org
+indemn agents export <id> -o agent.json    # prompt, greeting, model, skills (secrets redacted), KB ids
+indemn agents import agent.json [--name] [--link-kbs]   # recreate in the chosen org
+indemn agents lifecycle <id> prototype|beta|published   # owner or org admin only
+indemn agents owner <id> [<user-id>]       # show or transfer ownership
+indemn agents delete <id>
 ```
 
 ---
 
-## Step 2: Set the System Prompt and Model
-
-### Inline prompt
-
-```bash
-indemn config set <agent-id> --prompt "You are an insurance assistant for Acme Corp..."
-```
-
-### Prompt from file (preferred for long prompts)
-
-```bash
-indemn config set <agent-id> --prompt-file ./prompts/acme-assistant.txt
-```
-
-If both `--prompt` and `--prompt-file` are provided, `--prompt-file` takes precedence.
-
-### Set the model
-
-This controls which LLM the agent uses to generate responses — in conversations and during evaluations. The provider is auto-detected from the model name (claude -> anthropic, gemini -> google, default -> openai). This is NOT the evaluation judge model — that is set per-run via `eval run --eval-model`.
+## Step 2: Prompt, greeting and model
 
 ```bash
-indemn config set <agent-id> --model "claude-sonnet-4-20250514"
+indemn config get <agent-id> [--field prompt|greeting|model]
+indemn config set <agent-id> --prompt-file ./prompts/renewals.md   # shows a diff and asks
+indemn config set <agent-id> --greeting "Hi! How can I help with your renewal?"
+indemn config set <agent-id> --model anthropic/claude-sonnet-4-6 --dry-run
 ```
 
-Combine prompt and model in one call:
-
-```bash
-indemn config set <agent-id> --prompt-file ./prompts/acme.txt --model "claude-sonnet-4-20250514"
-```
-
-### Read current configuration
-
-```bash
-indemn config get <agent-id> [--json]
-indemn config get <agent-id> --field prompt
-indemn config get <agent-id> --field model
-indemn config get <agent-id> --field greeting
-```
+- The CLI reads the configuration back after saving and reports anything that did not save.
+- MCP: `set_prompt` or `set_config`; the confirmation shows the prompt diff.
 
 ---
 
-## Step 3: Add Functions (Tools)
-
-Functions are tools the agent can invoke during conversation (e.g., generate a quote, transfer to a human, look up policy details).
+## Step 3: Skills (actions the agent can take)
 
-### Create a function
+`skills` was called `functions`; both names work.
 
 ```bash
-indemn functions create <agent-id> --type ACTION --name "get_quote" --description "Generate an insurance quote"
+indemn skills list <agent-id>
+indemn skills create <agent-id> --type rest_api --name get_quote --description "Get a quote" \
+  --endpoint https://api.acme.com/quote --method POST --payload-file ./payload.json \
+  --auth-type bearer-token --auth-token env:ACME_TOKEN
+indemn skills params add <agent-id> <skill-id> --name zip --type string --description "ZIP code" --required
+indemn skills test <agent-id> <skill-id>
+indemn skills generate <agent-id> --file ./api-description.pdf -o proposal.json   # propose, review, then:
+indemn skills bulk-create <agent-id> --file proposal.json
+indemn skills export <agent-id>
+indemn skills import <agent-id> --url <json-url>   # REPLACES every skill, including built-in handoff and FAQ retriever
+indemn skills delete <agent-id> <skill-id>
 ```
 
-### Add parameters to a function
-
-```bash
-indemn functions params add <agent-id> <func-id> \
-  --name "state" --type string --description "US state abbreviation" --required
-
-indemn functions params add <agent-id> <func-id> \
-  --name "coverage_amount" --type number --description "Coverage amount in dollars"
-
-indemn functions params add <agent-id> <func-id> \
-  --name "has_claims" --type boolean --description "Whether applicant has prior claims"
-```
-
-Parameter types: `string`, `number`, `boolean`. Use `--required` for mandatory params.
-
-### Manage parameters
-
-```bash
-indemn functions params list <agent-id> <func-id> [--json]
-indemn functions params update <agent-id> <func-id> <param-id> --description "Updated desc" --required
-indemn functions params delete <agent-id> <func-id> <param-id>
-```
-
-### Import functions from an OpenAPI spec
-
-```bash
-indemn functions import <agent-id> --url "https://api.example.com/openapi.json"
-```
-
-This parses the spec and creates functions with parameters automatically.
-
-### Other function operations
-
-```bash
-indemn functions list <agent-id> [--json] [--limit 10] [--page 1]
-indemn functions update <agent-id> <func-id> --name "updated_name" --description "New desc"
-indemn functions test <agent-id> <func-id> [--json]
-indemn functions export <agent-id> [--json]
-indemn functions delete <agent-id> <func-id>       # requires confirmation
-indemn functions master-list [--json]               # available function templates
-```
+- Secrets: pass `@file`, `env:NAME` or `-` (stdin) to `--auth-token`, `--auth-value` and `--auth-password`; typed values end up in shell history.
+- Names close to the built-in FAQ retriever ("FAQs Retriever", "faq retrieval tool") are refused.
 
 ---
 
-## Step 4: Create and Link Knowledge Bases
-
-Knowledge bases provide the agent with reference information. Three data source types: QNA pairs, URLs, and files.
-
-### Create a knowledge base
-
-```bash
-indemn kb create --name "Acme FAQ" --type QNA
-indemn kb create --name "Product Pages" --type URL
-indemn kb create --name "Policy Documents" --type FILE
-```
-
-Type defaults to `QNA` if omitted. Must be uppercased: `QNA`, `URL`, or `FILE`.
-
-### Add data -- QNA pairs
-
-```bash
-indemn kb data add <kb-id> --question "What is the deductible?" --answer "The standard deductible is $500."
-```
-
-### Add data -- URL scraping
-
-```bash
-indemn kb data add <kb-id> --source-url "https://acme.com/faq"
-```
-
-Scrapes the URL and ingests the content.
-
-### Add data -- File upload
-
-```bash
-indemn kb data add <kb-id> --file ./documents/policy-handbook.pdf
-```
-
-Uploads the file and polls until processing is complete.
-
-### Bulk import QNA pairs from a file
-
-```bash
-indemn kb import <kb-id> --file ./qna-pairs.json
-```
-
-The file must be a JSON array of `{question, answer}` objects:
-
-```json
-[
-  {"question": "What is a deductible?", "answer": "The amount you pay before coverage kicks in."},
-  {"question": "What is a premium?", "answer": "The amount you pay for your insurance policy."}
-]
-```
-
-Each pair is added individually. Progress is shown during import.
-
-### Link knowledge bases to an agent
-
-```bash
-indemn kb link <agent-id> <kb-id>
-indemn kb link <agent-id> <kb-id-1> <kb-id-2> <kb-id-3>    # link multiple at once
-```
-
-The link command is variadic -- pass multiple KB IDs to link them all in one call.
-
-### Unlink a knowledge base
+## Step 4: Knowledge bases
 
 ```bash
+indemn kb create --name "Acme FAQ" --type QNA        # QNA, URL or FILE
+indemn kb data add <kb-id> --question "What is the deductible?" --answer "$500."
+indemn kb data add <kb-id> --source-url https://acme.com/faq
+indemn kb data add <kb-id> --file ./policy-handbook.pdf
+indemn kb status <kb-id>                              # crawl and import progress
+indemn kb data chunks <kb-id> <source-id>             # what the agent actually learned
+indemn kb data reimport <kb-id> <source-id>           # re-crawl after the site changed
+indemn kb link <agent-id> <kb-id> [<kb-id>...]
+indemn kb check "Can I pay monthly?"                  # would the knowledge answer this?
+indemn kb gaps --agent <agent-id> [--themes]          # questions agents could not answer
 indemn kb unlink <agent-id> <kb-id>
-```
-
-### Other KB operations
-
-```bash
-indemn kb list [--json] [--limit 20] [--page 1]
-indemn kb get <kb-id> [--json]
-indemn kb update <kb-id> --name "Updated Name"
-indemn kb delete <kb-id>                                     # requires confirmation
-indemn kb data list <kb-id> [--json] [--limit 20] [--page 1] # shows Total, Page X of Y
-indemn kb data update <kb-id> <source-id> --question "New Q" --answer "New A"
-indemn kb data update <kb-id> <source-id> --source-url "https://new-url.com"
-indemn kb data update <kb-id> <source-id> --content "Replacement content"
-indemn kb data delete <kb-id> <source-id>                    # requires confirmation
-indemn kb export <kb-id> --format csv                        # or xlsx
-indemn kb import <kb-id> --file ./qna-pairs.json             # bulk import QNA pairs
+indemn kb delete <kb-id>                              # unlink from agents first
 ```
 
 ---
 
-## Step 5: Test via Chat
-
-### Interactive mode
+## Step 5: Test by chatting
 
 ```bash
-indemn chat <agent-id>
+indemn chat <agent-id>                                # interactive
+indemn chat <agent-id> --message "I want to renew" --json
+indemn conversations list --agent <agent-id> --cli-only
+indemn conversations get <conversation-id> --agent <agent-id>
+indemn conversations export <conversation-id> --agent <agent-id> --as-testset -o case.json
 ```
 
-Opens a live chat session. Type messages, see responses in real time. Ctrl+C to exit.
-
-### Single message (scripting / quick check)
-
-```bash
-indemn chat <agent-id> --message "What types of insurance do you offer?"
-```
+- The CLI checks the conversation was stored as a test in the right org before sending anything, and prints its dashboard link.
+- MCP: `chat_with_agent` returns `session_id`; pass it back to continue, and `end_conversation: true` on the last turn.
+- A live conversation opened by mistake: `indemn conversations mark-test <ids...> --agent <agent-id>`.
 
-Sends one message, prints the response, exits.
+---
 
-### Resume a previous session
+## Step 6: Voice (agents with a phone number)
 
 ```bash
-indemn chat <agent-id> --session <session-id>
+indemn agents numbers list                    # numbers the org owns
+indemn agents numbers search --area-code 331         # free; ask first: local (which area code) or toll-free; show 4-5
+indemn agents numbers buy <agent-id> <+1331...>      # only after the person chose that number: costs money monthly
+indemn agents numbers get <agent-id>                 # the agent's number, location and voice settings
+indemn agents numbers attach <agent-id> <+1555...>   # a number the org already owns
+indemn voices list --provider cartesia --language en --gender feminine
+indemn agents voice set <agent-id> --voice-id <id> --name <name> --gender <g> --language en --country US
+indemn agents voice play <agent-id> -o sample.mp3
+indemn agents voice-preview <agent-id>        # browser link for a test call (1 hour)
 ```
 
-Continues an existing conversation thread with its history intact.
-
 ---
 
-## Step 6: Iterate
-
-After testing, refine: update the prompt (`config set --prompt-file`), add functions (`functions create`), add/update KB data (`kb data add` / `kb data update`), or switch models (`config set --model`). Repeat steps 2-5 until the agent performs correctly.
-
-## Complete Build Example
+## Step 7: Publish on a website
 
 ```bash
-# 1. Create agent
-indemn agents create --name "Acme Wedding Insurance" --channels "WEB"
-# -> agent_id: abc123
-
-# 2. Set prompt and model
-indemn config set abc123 --prompt-file ./prompts/wedding.txt --model "claude-sonnet-4-20250514"
-
-# 3. Add functions
-indemn functions create abc123 --type ACTION --name "get_quote" --description "Generate a wedding insurance quote"
-# -> func_id: func456
-indemn functions params add abc123 func456 --name "event_date" --type string --description "Wedding date" --required
-indemn functions params add abc123 func456 --name "guest_count" --type number --description "Number of guests" --required
-indemn functions params add abc123 func456 --name "venue_cost" --type number --description "Total venue cost in dollars"
-
-# 4. Create and populate knowledge base
-indemn kb create --name "Wedding FAQ" --type QNA
-# -> kb_id: kb789
-indemn kb data add kb789 --question "What does wedding insurance cover?" --answer "Coverage includes venue damage, vendor no-shows, severe weather, and illness."
-indemn kb data add kb789 --source-url "https://acme.com/wedding-insurance/faq"
-
-# 5. Link KB to agent
-indemn kb link abc123 kb789
-
-# 6. Test
-indemn chat abc123 --message "Hi, I'm getting married in June and want to protect my investment."
-indemn chat abc123    # interactive session for deeper testing
+indemn distributions create --agent <agent-id> --host www.acme.com --path /renewals
+indemn agents embed <agent-id>                # the script tag to put on the site
+indemn agents lifecycle <agent-id> published
 ```
 
 ---
 
-## CLI Quick Reference
-
-| Group | Command | Purpose |
-|-------|---------|---------|
-| **Agents** | `agents list / get / create / update / delete` | CRUD operations |
-| | `agents clone <id>` | Duplicate an agent |
-| | `agents card <id> [--output <path>]` | Generate branded PDF |
-| **Config** | `config get <id> [--field prompt\|model\|greeting]` | Read configuration |
-| | `config set <id> [--prompt\|--prompt-file\|--model]` | Write configuration |
-| **Functions** | `functions list / create / update / delete` | CRUD operations |
-| | `functions test <id> <func-id>` | Test a function |
-| | `functions export <id>` | Export all functions |
-| | `functions import <id> --url "<spec>"` | Import from OpenAPI |
-| | `functions master-list` | Available templates |
-| | `functions params list / add / update / delete` | Manage parameters |
-| **KB** | `kb list / get / create / update / delete` | CRUD operations |
-| | `kb data list / add / update / delete` | Manage KB entries |
-| | `kb link <agent-id> <kb-id...>` | Link KB(s) to agent |
-| | `kb unlink <agent-id> <kb-id>` | Unlink KB from agent |
-| | `kb export <kb-id> [--format csv\|xlsx]` | Export KB data |
-| | `kb import <kb-id> --file <path>` | Import from JSON |
-| **Chat** | `chat <id>` | Interactive session |
-| | `chat <id> --message "<text>"` | Single message mode |
-| | `chat <id> --session <sid>` | Resume session |
-| **Other** | `whoami` | Show authenticated user |
-| | `models` | List available LLMs |
-
-All commands accept `--json` for machine-readable output. List commands accept `--limit <n>` and `--page <n>`. Delete commands require confirmation.
+## Beyond one agent
+
+- `indemn org list | current | members`, `indemn link --org <id> [agent-ids]` to pin a project folder.
+- `indemn analytics metrics --agent <id>`, `indemn audit list`, `indemn tickets ...`, `indemn billing status` (read-only), `indemn campaigns list` (read-only).
+- V2 platform and Jarvis: `indemn platform templates list`, `indemn jarvis chat "..."`, `indemn jarvis jobs create --bots <ids>` (baseline evaluations). See the evaluations skill for testing.