docs: add a glossary of core terms (agent-substrate#200)

Addresses agent-substrate#131

Adds `docs/glossary.md`: a single place that defines the terms used
across
Agent Substrate and shows how they relate.

### What it covers
- Resources (ActorTemplate, WorkerPool), control-plane records (Actor,
Worker),
  components (ate-api-server, atecontroller, atelet, ateom, atenet,
podcertcontroller, kubectl-ate), runtime/sandbox concepts (gVisor,
runsc,
pause container, checkpoint/restore), snapshots (golden, last, storage),
and
  the Uniform DNS Mesh.
- Three UML diagrams: a sequence diagram (activation/resume flow), a
class
  diagram (resource/ownership model, grouped into Kubernetes-object and
control-plane-record packages), and a state-machine diagram (actor
lifecycle).
- Linked from the README documentation section.

### Scope
Per the issue thread, this documents the names as they exist in the
codebase;
rename proposals are intentionally left to a separate discussion, so
this PR is
documentation-only (not a renaming proposal).

### Accuracy
Every term and diagram was checked against the code and existing docs.
Project
terminology and casing are reused where things are already named (for
example
"Uniform DNS Mesh", the atelet "Herder", and the "interior gVisor"
coordinator),
and component responsibilities, RPC names, relationships, and the actor
status
lifecycle map to their sources.

- [x] Tests pass (documentation-only change)
- [x] Appropriate changes to documentation are included in the PR

Author: fkautz

README.md

@@ -203,6 +203,7 @@ We provide several sample applications demonstrating Agent Substrate's capabilit
 ### Documentation & Guides
 * [API Configuration Guide](docs/api-guide.md): Detailed reference for configuring WorkerPools, ActorTemplates, Secrets, and Volumes.
 * [Full CLI Documentation](cmd/kubectl-ate/README.md): Installation and usage for `kubectl-ate`.
+* [Glossary](docs/glossary.md): Core terms (Actor, ActorTemplate, WorkerPool, Worker, ate-api-server, atenet, atelet, ateom) and how they relate.
 * [Observability Guide](docs/observability.md): Guide to actor logging, metrics, and distributed tracing.
 
 ## Tour

docs/glossary.md

@@ -0,0 +1,87 @@
+# Agent Substrate Glossary
+
+This document defines the core terms used across Agent Substrate.
+
+For how the pieces fit together, see the [Architecture](architecture.md) and
+[API Guide](api-guide.md).
+
+## Resources (declarative, Kubernetes CRDs)
+
+- **ActorTemplate**: the definition of an actor "class": the container image(s)
+  and snapshot configuration. Creating an `ActorTemplate` triggers creation of
+  a [Golden Snapshot](#snapshots). It is treated as immutable: you create a new
+  template for a new version rather than editing an existing one. It is
+  analogous to a Pod template, but for a checkpointable workload.
+
+- **WorkerPool**: declares warm compute capacity, a fleet of pre-started worker
+  pods. It is reconciled into a Kubernetes `Deployment` by the
+  [atecontroller](#components).
+
+## Records (dynamic state, in the control-plane store)
+
+These are not Kubernetes objects; they live in the control-plane database
+because they change too frequently for etcd.
+
+- **Actor**: a single instance derived from an `ActorTemplate`, identified by a
+  DNS-1123 actor ID. It is the unit that is suspended and resumed, and it moves
+  between workers over its lifetime. An Actor record tracks its lifecycle
+  status and snapshot references.
+
+- **Worker**: a record representing one worker pod in a `WorkerPool`. A Worker
+  hosts at most one Actor at a time; many Actors are multiplexed across a pool
+  over time.
+
+## Components
+
+- **ate-api-server** (binary `ateapi`): the control plane. It owns the Actor
+  lifecycle, schedules Actors onto Workers, and coordinates their snapshots,
+  all backed by the state store. The `kubectl-ate` CLI talks to it.
+
+- **atecontroller**: the Kubernetes controller that reconciles the CRDs (for
+  example, it turns a `WorkerPool` into a `Deployment`).
+
+- **atelet**: the node-level supervisor, run as a DaemonSet. It pulls images,
+  assembles OCI bundles, drives the sandbox lifecycle on the node via ateom,
+  and streams snapshots to and from snapshot storage.
+
+- **ateom**: the coordinator that runs inside each worker pod and drives the
+  sandbox runtime on behalf of atelet. This decouples the physical pod
+  lifecycle from the sandboxed agent process.
+
+- **atenet**: the networking stack. It provides a DNS server for actor
+  resolution and a router that resumes suspended Actors on demand and routes
+  traffic to the right worker pod.
+
+- **podcertcontroller**: issues short-lived pod certificates that components
+  use as their TLS identity to authenticate connections to one another
+  (mutual TLS).
+
+- **kubectl-ate**: a `kubectl` plugin CLI for managing the Actor lifecycle and
+  listing Workers.
+
+## Lifecycle
+
+- **Suspend**: hibernate a running Actor by checkpointing it to a snapshot and
+  freeing its Worker.
+
+- **Resume**: activate a suspended Actor by restoring it onto a Worker. The
+  common path restores from a snapshot rather than cold-booting.
+
+## Snapshots
+
+- **Golden Snapshot**: the initial checkpoint captured once, when an
+  `ActorTemplate` is created, from a temporary "golden" boot of the workload.
+  By default an Actor of that template is first restored from this shared
+  snapshot.
+
+- **Last Snapshot**: the most recent per-Actor snapshot, written on Suspend and
+  used to restore that specific Actor on the next Resume.
+
+- **Snapshot storage**: the object store (GCS or S3) where snapshots are
+  persisted so Actor state is durable and portable across the cluster.
+
+## Networking
+
+- **Uniform DNS Mesh**: every Actor is reachable at a uniform address,
+  `<actor-id>.actors.resources.substrate.ate.dev`, resolved by atenet. Traffic to
+  that name is routed (and the Actor resumed if needed) automatically.