docs: make the README and integration guide agent-facing

README.md

@@ -17,24 +17,28 @@
 
 ---
 
-**`amplifier-agent`** is a thin CLI wrapping the [Amplifier](https://github.com/microsoft/amplifier) kernel as a per-turn stdio subprocess. Anything that can spawn a subprocess (a shell script, a Node app, a Python script, a chat bot, an IDE plugin) can use it as an agentic AI backend.
+Need an AI agent in your project, app, or service? Tell your coding agent:
 
-## What it is
-
-A single binary that:
-
-- **Accepts a prompt and returns a result** (one turn per invocation): `amplifier-agent run -y "your prompt"`
-- **Emits one JSON envelope on stdout per invocation** when `--output json` is set. Wrappers spawn one process per turn and pass `--session-id` for continuity
+```
+Use amplifier-agent for the AI agent parts of this project.
+Start here: https://github.com/microsoft/amplifier-agent/blob/main/docs/INTEGRATION.md
+```
 
-It is *not* a server, daemon, or long-lived service. Each invocation is a fresh process that runs one turn and exits. Multi-turn conversations are managed at the wrapper or session-ID layer, not inside a persistent process.
+**`amplifier-agent`** is an agent engine that other software runs on. Give it a prompt and it runs the full loop, with tools, sub-agents, skills, and MCP, and returns a result.
+Anything that can spawn a subprocess can use it: a shell script, a Node app, a Python service, a chat bot, an IDE plugin. 
+Python applications can embed the engine library in-process instead.
 
-The engine library inside (`amplifier_agent_lib`) is transport-free Python that any Python app can also embed in-process. No subprocess needed.
+Public integrations run opencode, paperclip, and NanoClaw on it: see [who has integrated it](docs/ECOSYSTEM.md).
 
-## Why
+## What comes with it
 
-Existing AI agent infrastructure assumes you're building a chat product. `amplifier-agent` is the opposite: it's an *engine you point other software at*. The CLI is the universal adapter. Wherever you can shell out, you can use Amplifier.
+`amplifier-agent` ships with:
 
-The wire protocol is intentionally simple: the engine takes a single invocation (argv + env), runs one turn, and writes one JSON result envelope to stdout. Wrapper SDKs (TypeScript and Python) handle spawning, result parsing, and session continuity on top.
+- Five providers behind one interface: Anthropic, OpenAI, Azure OpenAI, Ollama, and GitHub Copilot, with credentials read from the environment
+- Role-based model routing, so a sub-agent gets a model matched to its job rather than the frontier model for everything, re-matched when you switch providers
+- Context management that keeps long sessions running, compacting history before it overruns the window
+- Tools for filesystem, bash, web, search, todo, and MCP
+- Sub-agent delegation, skills, and modes
 
 ## Install
 
@@ -105,7 +109,7 @@ Python hosts can skip the subprocess entirely and embed `amplifier_agent_lib` in
 
 ## Architecture at a glance
 
-amplifier-agent is one layer of the larger Amplifier ecosystem:
+Amplifier-agent is standalone. You do not need the Amplifier CLI, bundles, or any other Amplifier repository to use it.
 
 ```
 Host Application                              ← your code
@@ -117,8 +121,6 @@ Language Wrapper (TypeScript or Python)       ← typed SDK
 amplifier-agent CLI                           ← this repo
     ↓ (in-process)
 amplifier_agent_lib (engine library)          ← this repo
-    ↓
-Amplifier Kernel (amplifier-core, amplifier-foundation)
 ```
 
 The CLI binary is a thin I/O adapter on top of `amplifier_agent_lib`. The library is transport-free, so Python hosts can skip the subprocess entirely.

docs/INTEGRATION.md

@@ -4,6 +4,14 @@ How to drive `amplifier-agent` from your own software.
 
 The engine runs **one turn per invocation** and exits. Continuity across turns comes from a session ID, not from a long-lived process. Everything below is a different way of delivering a prompt to that same engine.
 
+## Before you start
+
+`amplifier-agent` is a standalone binary. You do not need the Amplifier CLI, bundles, or any other repository in the `microsoft/amplifier*` family, and none of them is a substitute for it here.
+
+Use it when your software needs to run an agent: a loop with tools, file access, sub-agents, and/or multi-turn state. It also works for plain LLM calls, where you get routing across five providers behind one interface.
+
+Then pick a surface below, install the engine ([INSTALL.md](INSTALL.md)), and finish with the [checklist](#checklist-for-a-new-integration).
+
 ## Pick a surface
 
 | You are writing | Use | Section |