@@ -13,28 +13,44 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * The rule every framework applies to the application's {@code @AcpAgent} classes: none means a
- * client-only application, one is served, more than one is an error naming them. The container
- * finds the candidates its own way (bean metadata, a build-time index); this class decides.
+ * Decides which {@code @AcpAgent} an application serves, by the rule every framework applies:
+ * none means a client-only application (serve no agent), one is served, and more than one is an
+ * error that names them all. The framework finds the candidates its own way, from bean metadata
+ * at run time ({@link AgentCandidate}) or from a build-time index by class name, and passes them
+ * to {@code requireSingle}; this class only decides. The chosen candidate goes to
+ * {@link AcpAgents#builder}.
+ *
+ * <p>Pass the framework's property that turns the agent off, such as
+ * {@code spring.acp.agent.enabled}, so the error tells the user how to serve none. A framework
+ * that requires an agent (because it found one by annotation already) turns the empty result
+ * into its own error.
  */
 public final class AcpAgentDiscovery {
 
 	private AcpAgentDiscovery() {
 	}
 
 	/**
-	 * An {@code @AcpAgent} bean the container found.
-	 * @param name the container's name for it, used in messages
-	 * @param userClass the class the application wrote, from the container's metadata: never a
-	 * proxy or generated subclass (CGLIB, ArC, Micronaut AOP), whose methods carry no handler
+	 * One {@code @AcpAgent} bean the container found: its name, the class the application wrote,
+	 * and a way to get the bean. The framework builds one per bean from its own metadata and
+	 * passes them to {@link AcpAgentDiscovery#requireSingle(Collection, String)}.
+	 *
+	 * <p>The user class must be the class the application declared, taken from the container's
+	 * metadata (Spring's {@code ClassUtils.getUserClass}, Micronaut's bean definition type), never
+	 * the class of a proxy or generated subclass (CGLIB, ArC, Micronaut AOP): the handler
+	 * annotations are on the user class, and a proxy's overriding methods carry none. The instance
+	 * may be such a proxy, which keeps its advice (transactions, security) on every call.
+	 * {@link AcpAgents#builder} calls the supplier once, while it assembles the agent.
+	 * @param name the container's name for the bean, used in messages
+	 * @param userClass the class the application wrote, whose methods carry the handler
 	 * annotations
-	 * @param instance supplies the bean, possibly a proxy, that handles every request
+	 * @param instance supplies the bean that handles every request, possibly a proxy
 	 * @param <T> the agent type
 	 */
 	public record AgentCandidate<T>(String name, Class<T> userClass, Supplier<? extends T> instance) {
 
 		/**
-		 * A candidate, each part checked.
+		 * Creates a candidate, checking each part.
 		 * @throws NullPointerException if a part is null
 		 */
 		public AgentCandidate {
@@ -46,22 +62,26 @@ public record AgentCandidate<T>(String name, Class<T> userClass, Supplier<? exte
 	}
 
 	/**
-	 * The one candidate.
+	 * Returns the one candidate, as {@link #requireSingle(Collection, String)} does, with an
+	 * error that names no property.
 	 * @param candidates the {@code @AcpAgent} beans the container found
 	 * @return the candidate, or empty when there is none
-	 * @throws IllegalStateException listing them when there is more than one
+	 * @throws IllegalStateException if there is more than one; the message lists their user
+	 * classes
 	 */
 	public static Optional<AgentCandidate<?>> requireSingle(Collection<? extends AgentCandidate<?>> candidates) {
 		return requireSingle(candidates, null);
 	}
 
 	/**
-	 * The one candidate.
+	 * Returns the one candidate the application serves, or empty for a client-only application.
 	 * @param candidates the {@code @AcpAgent} beans the container found
-	 * @param enabledProperty the framework's property that turns the agent off, named in the error
-	 * as the way to serve none; null to name none
+	 * @param enabledProperty the framework's property that turns the agent off, such as
+	 * {@code spring.acp.agent.enabled}, which the error names as the way to serve none; null to
+	 * name none
 	 * @return the candidate, or empty when there is none
-	 * @throws IllegalStateException listing them when there is more than one
+	 * @throws IllegalStateException if there is more than one; the message lists their user
+	 * classes, sorted, and says to remove {@code @AcpAgent} from all but one
 	 */
 	public static Optional<AgentCandidate<?>> requireSingle(Collection<? extends AgentCandidate<?>> candidates,
 			@Nullable String enabledProperty) {
@@ -73,13 +93,13 @@ public static Optional<AgentCandidate<?>> requireSingle(Collection<? extends Age
 	}
 
 	/**
-	 * The same rule over class names, for build-time discovery (a Jandex index), with no class
-	 * loaded.
+	 * Applies the same rule to class names, for discovery at build time (Quarkus reads a Jandex
+	 * index), so no class is loaded.
 	 * @param classNames the names of the {@code @AcpAgent} classes found
-	 * @param enabledProperty the framework's property that turns the agent off, named in the error;
-	 * null to name none
+	 * @param enabledProperty the framework's property that turns the agent off, which the error
+	 * names; null to name none
 	 * @return the class name, or empty when there is none
-	 * @throws IllegalStateException listing them when there is more than one
+	 * @throws IllegalStateException if there is more than one; the message lists them, sorted
 	 */
 	public static Optional<String> requireSingle(List<String> classNames, @Nullable String enabledProperty) {
 		if (classNames.size() > 1) {
 
@@ -17,19 +17,31 @@
 import reactor.core.publisher.Mono;
 
 /**
- * One agent on one transport: stdio, or an application's own transport. Starting, stopping and
- * the end of the transport are the SDK's own lifecycle: {@link AcpAgentSupport#start()}, its
- * {@link AcpAgentSupport#close() AutoCloseable close} (graceful, bounded, then at once) and its
- * agent's {@code awaitTermination()}.
+ * The {@link AcpHost} for one agent on one transport: stdio, or a transport bean the application
+ * provides (an in-memory transport in tests, for one). Build the agent with
+ * {@link AcpAgents#builder}, set its transport ({@link AcpAgentTransports#stdio()}), build it,
+ * and give it to this host with the action to run when the client ends the transport. For the
+ * SDK's HTTP and WebSocket listener, which serves many clients, use {@link AcpListenerHost}.
  *
- * <p>
- * When the transport ends by itself (for stdio: the client closed the agent's input and every
- * answer has been written), the agent has no one left to serve, and the host runs the
- * {@code onTransportEnd} action the framework gave it, typically "close my container". That
- * action is latched: it runs at most once, on a thread of the host's own (never the transport's,
- * since closing the container stops this host, which closes the transport), also when the
- * transport ended before anyone looked, and never when the host itself stopped the agent.
- * </p>
+ * <p>The host drives the SDK's own lifecycle: {@link #start()} calls
+ * {@link AcpAgentSupport#start()}; a stop runs {@link AcpAgentSupport#close()} (graceful, at most
+ * about 10 seconds, then at once) on a daemon thread named {@code acp-agent-stop}, and
+ * {@link #stop(Duration)} closes the agent at once when that does not finish within its timeout.
+ * {@link #termination()} follows the agent's {@code awaitTermination()}, and completes normally
+ * also when the transport ended with an error. {@link #port()} is always empty.
+ *
+ * <p>When the transport ends by itself (for stdio: the client closed the agent's input and
+ * every answer has been written), the agent has no one left to serve, and the host runs
+ * {@code onTransportEnd}, typically "close my container" or "exit the application". The host
+ * runs it at most once, on a new non-daemon thread named {@code acp-agent-transport-end}, never
+ * on a transport thread: closing the container stops this host, which closes the transport, and
+ * the JVM waits for the action to finish. It also runs when the transport ended before the host
+ * started or saw it, and it does not run when the host's own stop ended the transport. The
+ * host itself never reads {@link AcpAgentSettings#shutdownOnTransportEnd()}: when that setting
+ * is false, the framework passes an action that does nothing.
+ *
+ * <p>The host is safe for use from several threads; {@link #start()} and the stop methods
+ * share one lock.
  */
 public final class AcpAgentHost implements AcpHost {
 
@@ -55,10 +67,12 @@ public final class AcpAgentHost implements AcpHost {
 	private @Nullable CompletableFuture<@Nullable Void> stopped;
 
 	/**
-	 * A host for an agent built on its transport.
-	 * @param agent the agent
-	 * @param onTransportEnd what to do when the transport ends by itself, such as closing the
-	 * container; fixed here, so no end is missed
+	 * Creates a host for an agent built on its transport, not yet started. The host watches the
+	 * agent's termination from here on, so the action is fixed now and no end of the transport is
+	 * missed, even one before {@link #start()}.
+	 * @param agent the agent, built with its transport and not started
+	 * @param onTransportEnd what to run once when the transport ends by itself, such as closing
+	 * the container; an action that does nothing when the application should keep running
 	 */
 	public AcpAgentHost(AcpAgentSupport agent, Runnable onTransportEnd) {
 		this.agent = agent;