docs(readme): reposition around "Make your product queryable"

README.md

@@ -5,10 +5,11 @@
   </picture>
 </p>
 
+<h1 align="center">Make your product queryable.</h1>
+
 <p align="center">
-  <b>Turn your app into an agentic product — from one YAML file.</b><br>
-  Give any application a smart, domain-aware agent layer, without
-  building the engine yourself.
+  Turn the APIs, tools, and business logic you already have into a secure AI
+  interface inside your product.
 </p>
 
 <p align="center">
@@ -18,195 +19,144 @@
 </p>
 
 <p align="center">
-  <a href="https://docs.extra-ai.co/docs/introduction">Documentation</a> ·
   <a href="#quick-start">Quick Start</a> ·
-  <a href="#how-it-works">How it works</a> ·
-  <a href="#learn-more">Learn more</a> ·
+  <a href="#why-extra">Why Extra</a> ·
+  <a href="#who-is-extra-for">Who it's for</a> ·
+  <a href="https://docs.extra-ai.co/docs/introduction">Documentation</a> ·
   <a href="#contributing">Contributing</a>
 </p>
 
 ---
 
-## What Extra is
+Your users shouldn't have to learn your UI to get an answer out of it.
 
-Extra is a lightweight engine that adds an agentic layer to any application.
-You describe your agents in a simple YAML file — what each one is responsible
-for and what it can access — and Extra turns that into a running system that
-routes each request to the right agent and answers it accurately.
+Extra lets them ask questions and trigger actions using the APIs and business
+logic you already built.
 
-Every agent has a single, clear responsibility and is scoped to its own
-domain, with its own prompt, tools, and data. That scoping is what keeps
-answers grounded: a request about billing never reaches the returns agent, so
-there's no context bleeding between domains and no hallucinated hand-off. You
-get tools, MCP servers, authentication, provider connectors, and
-observability out of the box — so your app can be agentic in a day, not a
-quarter.
+Define the system in YAML. Extra handles routing, orchestration, and access
+boundaries while your logic and credentials stay in your backend.
 
-## How it works
+## Why Extra
 
-You define a small graph in YAML: one **orchestrator** that routes, and
-focused **agents** that do the work. Extra runs it — picking the right agent
-per request and keeping each one inside its own domain.
+**Ship faster.** Define your agent system instead of rebuilding routing,
+streaming, tool execution, and tracing.
 
-```mermaid
-flowchart TD
-    U([User request]) --> R{{Orchestrator<br/>routes by domain}}
-    R -->|billing| A1[Billing agent]
-    R -->|orders| A2[Orders agent]
-    R -->|docs| A3[Docs agent]
+**Reuse your backend.** Connect the APIs, services, and business logic you
+already have.
 
-    A1 --- P1[/prompt · tools · MCP · auth/]
-    A2 --- P2[/prompt · tools · MCP · auth/]
-    A3 --- P3[/prompt · tools · MCP · auth/]
+**Keep access control outside the model.** Authorization runs in trusted code —
+the model cannot grant itself access to protected capabilities.
 
-    A1 --> RESP([Grounded response])
-    A2 --> RESP
-    A3 --> RESP
-```
+**Avoid model lock-in.** Switch model providers through configuration rather
+than rewriting your product.
 
-Each agent only sees its own tools and data, so the model stays focused and
-answers correctly for that part of your business. Add a new capability by
-adding an agent to the file — no routing code to write.
+**Embed it in your product.** Serve the system as an API or as an embeddable
+chat component.
 
-Here's the same idea in YAML:
+## Quick Start
+
+You need Docker and an API key for your model provider.
+
+Create `agents.yml` — a single agent is a complete system:
 
 ```yaml
-orchestrators:
-  router:
-    description: "Routes each request to the right department."
-    prompts:
-      orchestrator: "prompts/router.md"
+system:
+  name: "Support Bot"
 
-agents:
-  orders_agent:
-    description: "Handles order status and tracking."
-    prompts:
-      system: "prompts/orders_agent.md"
-    tools: [get_order_status]
-    mcps: [orders_api]
+defaults:
+  model:
+    provider: anthropic
+    name: claude-sonnet-4-6
 
-  returns_agent:
-    description: "Handles returns and refunds."
+agents:
+  support_agent:
+    description: "Answers questions about orders and returns."
     prompts:
-      system: "prompts/returns_agent.md"
-    tools: [create_return]
+      system: "prompts/support.md"
 
 graph:
-  router:
-    orders_agent:
-    returns_agent:
+  support_agent:
 ```
 
-That's the whole system. Extra validates it, compiles it, and serves it as an
-API. You only write your own business logic — the tool and connector stubs
-Extra generates for you.
+Write the prompt it references, in `prompts/support.md`:
 
-## Quick Start
+```markdown
+You are a support agent for an online store. Answer questions about orders
+and returns.
+```
 
-Write your `agents.yml` (like the one above), then generate the plugin stubs
-and serve it:
+Run it:
 
 ```bash
-# Generate tool/resolver stubs from your spec, then fill in your logic
-docker run --rm -v "$(pwd):/workspace" -w /workspace \
-  ghcr.io/extra-org/extra:latest generate --config agents.yml
-
-# Serve your system
 docker run -p 8090:8090 -v "$(pwd):/workspace" -w /workspace \
   -e ANTHROPIC_API_KEY=sk-... \
   ghcr.io/extra-org/extra:latest serve --config agents.yml
 ```
 
-Your agent API is live at `http://localhost:8090`. For the widget, local
-(non-Docker) setup, and the full walkthrough, see the
-[Quickstart docs](https://docs.extra-ai.co/docs/quickstart).
-
-### Agent setup skill
-
-If you use Claude Code, Cursor, or Codex, you can install the official Extra
-setup skill to create or repair an `extra` project configuration
-interactively. The same open Agent Skills-format skill works across supported
-agents; it helps set up `agents.yml`, prompts, MCPs, tools, resolvers, plugins,
-generation, Docker/local execution, and validation.
-
-List available skills:
-
-```bash
-npx skills add extra-org/extra-skills --list
-```
-
-Install for Claude Code:
+Your system is live at `http://localhost:8090` — send it a message with
+`POST /invoke`.
 
-```bash
-npx skills add extra-org/extra-skills --skill '*' -a claude-code
-```
+Tools, MCP servers, routing between agents, conversation history, and the chat
+widget are covered in the
+[Quickstart](https://docs.extra-ai.co/docs/quickstart).
 
-Install for Cursor:
+## Features
 
-```bash
-npx skills add extra-org/extra-skills --skill '*' -a cursor
-```
+- YAML-defined agents and routing
+- Local Python tools and remote MCP servers
+- Per-node authorization
+- Human-in-the-loop tool approvals
+- Anthropic, OpenAI, Gemini, and Bedrock
+- Streaming API
+- Structured logs and Langfuse tracing
+- Embeddable web component
 
-Install for Codex:
+## Architecture
 
-```bash
-npx skills add extra-org/extra-skills --skill '*' -a codex
-```
-
-Install for all three:
+An orchestrator routes each request; focused agents do the domain work. Each
+agent is scoped to its own prompt, tools, and domain data, which keeps answers
+grounded in the right part of your business.
 
-```bash
-npx skills add extra-org/extra-skills --skill '*' -a claude-code -a cursor -a codex
-```
-
-Add `-g` to install globally for the current user instead of into the current
-project.
-
-In Claude Code, open your project:
-
-```bash
-claude
-```
-
-Then run:
-
-```text
-/extra-setup
-```
+```mermaid
+flowchart TD
+    U([User request]) --> R{{Orchestrator<br/>routes by domain}}
+    R -->|billing| A1[Billing agent]
+    R -->|orders| A2[Orders agent]
+    R -->|docs| A3[Docs agent]
 
-Examples:
+    A1 --- P1[/prompt · tools · MCP · auth/]
+    A2 --- P2[/prompt · tools · MCP · auth/]
+    A3 --- P3[/prompt · tools · MCP · auth/]
 
-```text
-/extra-setup simple banking demo
-/extra-setup repair my agents.yml
-/extra-setup configure MCP tools and resolvers
+    A1 --> RESP([Grounded response])
+    A2 --> RESP
+    A3 --> RESP
 ```
 
-In Cursor or Codex, install the same `extra-setup` skill and ask the agent to
-use it:
+Extra runs the graph. Your project's plugins hold the trusted business logic —
+tools, access checks, and the values resolved into prompts.
 
-```text
-Use the extra-setup skill to create a simple banking demo for this project.
-```
-
-If your current Cursor or Codex version supports direct skill invocation, use
-that agent's documented invocation flow.
+- **[Tutorial](https://docs.extra-ai.co/docs/tutorial)** — build a complete multi-agent system step by step.
+- **[YAML reference](https://docs.extra-ai.co/docs/yaml-spec)** — every field you can declare.
+- **[Architecture](https://docs.extra-ai.co/docs/architecture)** — how routing and execution work.
+- **[`examples/`](examples/)** — runnable specs, including an enterprise knowledge assistant.
 
-The skill repository is available at
-[extra-org/extra-skills](https://github.com/extra-org/extra-skills).
+## Who is Extra for?
 
-## What you get out of the box
+Extra is built for teams adding an AI interface to:
 
-- **Domain-focused agents** — one responsibility each, scoped to their own tools and data, so answers stay accurate.
-- **Automatic routing** — declare the graph; Extra sends each request to the right agent.
-- **Tools, MCP & auth** — connect any tool or MCP server, with tokens that never reach the model or the logs.
-- **Observability** — a full trace of every request.
+- Existing SaaS products
+- Internal enterprise systems
+- Customer support workflows
+- Multi-step business operations
+- Multi-tenant products with strict access boundaries
 
-## Learn more
+### Extra may be unnecessary if
 
-- **[Full example](https://docs.extra-ai.co/docs/tutorial)** — build a complete multi-agent system step by step.
-- **[YAML reference](https://docs.extra-ai.co/docs/yaml-spec)** — every field you can declare.
-- **[Architecture](https://docs.extra-ai.co/docs/architecture)** — how routing and execution work under the hood.
+- You need a single prompt with a few simple tools.
+- You are building a chatbot with no product or backend integration.
+- You need full low-level control over the orchestration runtime.
+- Your workload is primarily batch or offline processing.
 
 ## Contributing