docs: add a library-first documentation set for the v1 interface

docs_v1/00-index.md

@@ -0,0 +1,121 @@
+# Amplifier Agent
+
+Amplifier Agent is a Python library for embedding an AI agent in your application.
+It gives you a model with tools, a loop that runs until the task is done, and a
+stream of events describing everything that happened along the way.
+
+What the agent is good for depends on the tools you give it. A filesystem and a
+shell make it a coding agent. Your deployment API makes it a release agent. Your
+internal services make it whatever those services do.
+
+```python
+from amplifier_agent import AgentConfig, ProviderConfig, create_agent
+
+agent = await create_agent(
+    AgentConfig(
+        instructions="You are a careful engineer. Explain before you edit.",
+        provider=ProviderConfig(name="anthropic", model="claude-sonnet-5"),
+    )
+)
+
+session = await agent.create_session()
+result = await session.run("Find the failing test in tests/ and fix it.")
+print(result.reply)
+```
+
+## Why use it
+
+- **Bring your own model.** Name a provider and a model and the agent handles the
+  rest. Moving between Anthropic, OpenAI, Azure, and the others is a configuration
+  change, not a rewrite.
+- **Give it your own tools.** Built-in tools cover the filesystem, shell, and web.
+  Beyond those, any Python function becomes a tool and any MCP server plugs in
+  alongside them. The model sees one flat set and does not know where each one
+  came from.
+- **Teach it what it needs to know.** Skills package domain knowledge and
+  procedures the agent picks up when a task calls for them, so your instructions
+  stay short and the expertise arrives at the moment it is useful.
+- **Decide what it is allowed to do.** Every tool call can route through your code
+  before it runs. Approve it, deny it, rewrite its arguments, or cancel the turn.
+- **Watch it work.** A running turn emits typed events covering reasoning, replies,
+  tool calls, tool results, and token usage. Render them however you want, or
+  ignore them and await the final result.
+- **Pick up where you left off.** Sessions persist to disk. Resume one tomorrow,
+  fork one to explore an alternative, or throw it away.
+
+## The pieces
+
+- **Agent** is created from an `AgentConfig`. It owns sessions and lives as long as
+  your application does.
+- **Session** is a conversation with history. It runs one turn at a time and
+  persists between turns.
+- **Turn** is one task, from your prompt to the agent's final reply. Await it for a
+  result, or iterate it for events.
+- **Event** is everything that happens inside a turn, as it happens.
+- **Tool** is what the agent can actually do. Built in, yours, or from an MCP server.
+- **Approval** is your veto on a tool call before it runs.
+- **Provider** is the model behind it all, plus how its credentials are resolved.
+
+Four calls carry the whole library: `create_agent`, `create_session`, and then
+`run` or `stream`. Everything else describes what flows through them.
+
+## Streaming a turn
+
+`run` is the short version of `stream`. When you want to show progress rather than
+wait for it, iterate instead of awaiting.
+
+```python
+async for event in session.stream("Refactor the parser module."):
+    match event:
+        case MessageDelta(text=text):
+            print(text, end="", flush=True)
+        case ToolCall(name=name):
+            print(f"\n[{name}]")
+```
+
+Both paths run the same turn and produce the same result.
+
+## Where to go next
+
+- Install the library, and the CLI and SDKs if you want them, with
+  [Install](01-install.md).
+- Build a working agent end to end with the [Quickstart](02-quickstart.md).
+- Look up any `AgentConfig` field in [Configuration](03-configuration.md).
+- Choose a provider and set up credentials in [Providers](06-providers/index.md).
+- Read the complete public surface, one page per area, in
+  [Interface](05-interface/index.md). Start here if you are implementing against
+  Amplifier Agent rather than calling it.
+- Reach the agent through the CLI, the HTTP face, or the TypeScript SDK in
+  [Surfaces](07-surfaces/index.md).
+
+## Amplifier Agent or Amplifier App CLI?
+
+Amplifier App CLI is a full application built on the same ecosystem, and it exposes
+a much larger surface: bundles, behaviors, recipes, hooks, and swappable
+orchestrators. Those are how you compose and reshape an agent from the outside.
+
+Use Amplifier App CLI when:
+
+- you want to assemble the agent yourself from bundles and modules
+- you want to swap the orchestrator or attach hooks to the loop
+- you are shipping modes, skills, or recipes to end users
+
+Use Amplifier Agent when:
+
+- you want an agent inside your application rather than an application around one
+- you want the full agent without taking on responsibility for how it is built
+- you want an interface that holds still while the internals keep moving
+
+The narrower surface is the point. Amplifier Agent keeps the following out of your
+hands deliberately:
+
+- **Composition.** Bundles, mount plans, modules, and manifests decide how an agent
+  assembles itself. Amplifier Agent assembles itself.
+- **The loop.** Orchestrators, hooks, and context management change the shape of
+  the agent's reasoning. You steer it with instructions, tools, and approvals.
+- **Sub-agents.** The agent delegates when a task calls for it, but which
+  sub-agents exist is ours to define rather than yours to configure. Their work
+  arrives in your event stream as ordinary tool activity.
+- **The prompt.** Prompt assembly and context-window management belong to the
+  agent. Instruction content goes in through `instructions`.
+- **Model routing.** You name a model. The agent decides how to use it.

docs_v1/01-install.md

@@ -0,0 +1,127 @@
+# Install
+
+## Prerequisites
+
+**[uv](https://docs.astral.sh/uv/).** Everything below goes through it.
+
+```bash
+# macOS and Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+```pwsh
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+**`git` on your `PATH`, at run time as well as install time.** The agent fetches
+components it needs the first time it runs. On Windows,
+[Git for Windows](https://git-scm.com/download/win) covers this and also provides
+the shell the agent's built-in shell tool looks for. Windows additionally needs
+long paths enabled:
+
+```bash
+git config --global core.longpaths true
+```
+
+You do not need to install Python. uv downloads a suitable interpreter if your
+system does not already have one.
+
+## The library
+
+```bash
+uv add git+https://github.com/microsoft/amplifier-agent
+```
+
+That gives you the `amplifier_agent` package, which is everything the rest of
+these docs describe. Pin a release rather than tracking the default branch:
+
+```bash
+uv add git+https://github.com/microsoft/amplifier-agent --tag v0.17.0
+```
+
+Available tags are listed at
+<https://github.com/microsoft/amplifier-agent/releases>.
+
+## The CLI
+
+The same distribution provides the `amplifier-agent` command. Install it as a
+standalone tool when you want the command on your `PATH` without adding the
+library to a project:
+
+```bash
+uv tool install git+https://github.com/microsoft/amplifier-agent
+```
+
+Pin a release by putting the tag in the URL:
+
+```bash
+uv tool install git+https://github.com/microsoft/amplifier-agent@v0.17.0
+```
+
+There is also an installer script that resolves the latest release and installs
+it in one step:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/microsoft/amplifier-agent/main/install.sh | bash -s -- --yes
+```
+
+The script takes `--tag <ref>` to pin a version, `--no-prime` to skip warming the
+cache, and `--yes` to skip the confirmation prompt. Flags go after `-s --`, since
+everything before that is consumed by `bash` itself.
+
+If a host application spawns `amplifier-agent` as a subprocess, install it as the
+user that runs the host process. A tool installed by `root` while the service
+runs unprivileged is not on the `PATH` the subprocess inherits.
+
+## The TypeScript SDK
+
+```bash
+pnpm add amplifier-agent-ts
+```
+
+The SDK does not bundle the agent. Install both. See
+[Surfaces](07-surfaces/typescript.md) for what it covers.
+
+## Verify
+
+```bash
+amplifier-agent doctor     # environment, providers, paths
+amplifier-agent version    # release and contract versions
+```
+
+`doctor` reports which providers have credentials it can resolve, which is
+usually the fastest answer to "why does my agent say it cannot find a model."
+
+Both are compositions of library calls, formatted for a terminal. The same
+answers from Python:
+
+```python
+import amplifier_agent
+from amplifier_agent import list_providers
+
+print(amplifier_agent.__version__, amplifier_agent.contract_version)
+
+for status in await list_providers():
+    print(status.descriptor.name, status.available, status.credential_source)
+```
+
+## Update and remove
+
+```bash
+uv tool upgrade amplifier-agent
+```
+
+A tool installed from a pinned tag stays on it. To move to a different release,
+install again with the new tag.
+
+To remove everything, including stored sessions and credentials:
+
+```bash
+uv tool uninstall amplifier-agent
+rm -rf ~/.amplifier-agent
+```
+
+## Next
+
+Build a working agent in the [Quickstart](02-quickstart.md).