Add @UnstableAcpApi stability marker annotation

Marks ACP API elements that correspond to protocol methods defined
only in schema.unstable.json. These APIs are public and functional
but may change in any minor release to track the ACP protocol.

Design aligns with JDK @PreviewFeature and JetBrains
ApiStatus.Experimental conventions: CLASS retention, @documented,
not @inherited. Targets TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE,
RECORD_COMPONENT, ANNOTATION_TYPE (PARAMETER excluded per JDK
guidance and zero surveyed projects including it). Optional
String value() for tracking links (gRPC pattern).

See plans/outbox/unstable-api-annotation-design.md for full
research across JDK, JetBrains, Netty, Micronaut, gRPC, Guava,
Hadoop, Kafka, Flink and 7 rounds of review feedback.

Author: Mark Pollack

acp-annotations/src/main/java/com/agentclientprotocol/sdk/annotation/UnstableAcpApi.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025-2026 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks an ACP API element as unstable.
+ *
+ * <p>Unstable APIs correspond to protocol elements defined only in
+ * {@code schema.unstable.json}. They are public and functional but may
+ * change signature, behavior, wire mapping, or be removed in any minor
+ * release to track the ACP protocol. See {@code VERSIONING.md} for the
+ * full stability policy.
+ *
+ * <p>When the protocol element is promoted to {@code schema.json}, this
+ * annotation will be removed. Removing it is a compatible change.
+ *
+ * <p>"Unstable" refers to protocol stability, not implementation quality.
+ *
+ * <p><b>Propagation:</b> if a package is marked, all its classes are
+ * considered unstable (subpackages are not affected). If a type is marked,
+ * all its members are unstable, but inheritors are not. If a method is
+ * marked, overriding methods are not considered unstable.
+ *
+ * <p>This annotation is a stability marker and documentation signal, not
+ * an access-control mechanism. IntelliJ users can configure the built-in
+ * <em>Unstable API Usage</em> inspection to flag usages of APIs carrying
+ * this annotation.
+ *
+ * @author Mark Pollack
+ * @since 0.12.0
+ * @see <a href="https://agentclientprotocol.com/protocol/overview">ACP Protocol</a>
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD,
+		ElementType.PACKAGE, ElementType.RECORD_COMPONENT, ElementType.ANNOTATION_TYPE })
+public @interface UnstableAcpApi {
+
+	/**
+	 * Optional reference to the tracking spec entry, RFD, or issue that gates
+	 * stabilization. Empty by default.
+	 * @return a URL or identifier linking to the protocol proposal
+	 */
+	String value() default "";
+
+}