docs: add glossary of canonical bot-bottle terminology

Defines Agent Provider, Agent Runtime, Agent/Agent Definition,
Bottle/Bottle Definition, Sealed Bottle, Bottled Agent, and Active Bottle.
Links from docs/README.md and AGENTS.md for discoverability.

Closes #474

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

AGENTS.md

@@ -35,6 +35,7 @@ backend remains available with `BOT_BOTTLE_BACKEND=docker` or
 - `.bot-bottle/` — per-repo agent and bottle manifests (YAML markdown format).
 - `examples/` — example bottles and agents showing the manifest format.
 - `docs/README.md` — docs overview; when to write which document.
+- `docs/glossary.md` — canonical term definitions (Agent Provider, Bottle, Sealed Bottle, etc.).
 - `docs/prds/` — product requirement docs (see `docs/prds/README.md` for format).
 - `docs/research/` — research notes (see `docs/research/README.md`).
 - `docs/decisions/` — decision records (ADR-lite).

docs/README.md

@@ -7,6 +7,7 @@ picking the right document for what you're capturing.
 
 | Artifact | For |
 |---|---|
+| **Glossary** (`docs/glossary.md`) | Canonical term definitions — what words mean in this project. |
 | **PRD** (`docs/prds/`) | A feature: what to build, scope, success criteria. |
 | **Research note** (`docs/research/`) | A landscape/tradeoff investigation. |
 | **Decision record** (`docs/decisions/`) | A decision that isn't itself a feature — a policy, a convention, a "we will / won't do this," or a load-bearing choice made inside a larger PRD that deserves to be discoverable on its own. |

docs/glossary.md

@@ -0,0 +1,57 @@
+# Glossary
+
+Canonical terminology for bot-bottle. Prefer these names in docs, comments, and UI.
+
+---
+
+## Agent Provider
+
+The component that connects to an external model provider and sets up the model
+harness inside the agent runtime. Configured in a bottle manifest under
+`agent_provider:`; built-in templates are `claude` and `codex`. Responsible for
+provider-specific auth, startup args, and egress routes.
+
+## Agent Runtime
+
+The OCI image (and the container or VM it runs in) that houses the model
+harness. On the macOS-container backend this is an Apple Container; on
+Firecracker it is a microVM; on the legacy Docker backend it is a Docker
+container. The agent runtime is built from the agent provider's Dockerfile
+(built-in or custom).
+
+## Agent / Agent Definition
+
+A Markdown file with YAML frontmatter that declares the system prompt and
+identity of the model harness. Lives under `~/.bot-bottle/agents/` or a repo's
+`.bot-bottle/agents/`. Specifies which bottle to run under (`bottle:`) and
+which skills to load. Agent definitions are safe to commit; they contain no
+secrets or egress policy.
+
+## Bottle / Bottle Definition
+
+A Markdown file with YAML frontmatter that declares the security and runtime
+boundaries for one agent runtime: egress allowlist, git remotes, env vars,
+nested-container flag, and agent provider config. Lives under
+`~/.bot-bottle/bottles/`. Bottles are scoped to `$HOME` so a cloned repo
+cannot override host egress policy.
+
+## Sealed Bottle
+
+The fully-resolved bottle after all `extends:` inheritance is applied and every
+field has been validated. The sealed bottle is the immutable boundary spec that
+the launcher enforces — no further overrides are possible once it is sealed.
+
+## Bottled Agent
+
+The combination of an Agent Definition and a Sealed Bottle, representing a
+single deployable agent with a fixed identity and fixed boundaries. A bottled
+agent has two observable states:
+
+- **Active** — the agent runtime is running and the agent is executing.
+- **Frozen** — the agent runtime has been snapshotted (Firecracker committed
+  image); the agent is not running but can be resumed from the snapshot.
+
+## Active Bottle
+
+Shorthand for an active (running) Bottled Agent. Used in the supervisor TUI
+and discovery layer to mean "a bottle whose agent runtime is currently up."