docs: formalize continuation parity and legacy status deprecation (#17)

Document stream/poll continuation autonomy semantics, fix the intent stream OpenAPI response media type to SSE, and publish an explicit legacy_status deprecation timeline with rollout guidance.

Made-with: Cursor

Co-authored-by: George-iam <georgeb@gmail.com>

Author: George-iam

docs/axme-is-not-rpc.md

@@ -21,6 +21,8 @@ AXME supports three continuation mechanisms:
 - Polling: `GET /v1/intents/{intent_id}` and `GET /v1/intents/{intent_id}/events?since=<seq>`
 - Deliver-to-inbox: pass `reply_to` on create and observe completion in that inbox
 
+For forwarded long-running intents, stream and polling are expected to surface lifecycle progress directly (without requiring `GET /v1/intents/{intent_id}` as a side-effect trigger).
+
 ## Design Rules
 
 - Do not model `create_intent` as "remote function call that must finish now".

docs/migration-and-deprecation-policy.md

@@ -39,6 +39,22 @@ Reference:
   - earliest removal date,
   - required client-side actions.
 
+## Intent `legacy_status` Deprecation Schedule
+
+`legacy_status` on intent projections exists only as a migration bridge from legacy status values (`accepted|running|blocked|done|failed`) to canonical lifecycle status values.
+
+Timeline:
+
+1. **Phase A (current through 2026-06-30): dual projection**
+   - `intent.status` is canonical and required for client logic.
+   - `intent.legacy_status` remains enabled by default for compatibility.
+2. **Phase B (from 2026-07-01): explicit opt-out**
+   - Integrators should validate clients with `GATEWAY_INCLUDE_LEGACY_INTENT_STATUS=false`.
+   - New integrations should ignore `legacy_status` and rely only on canonical lifecycle fields.
+3. **Phase C (next major after overlap, earliest 2026-10-01): removal**
+   - `legacy_status` is removed from public payloads in the next major API version.
+   - SDKs and conformance contracts treat canonical `status` as the only supported lifecycle projection.
+
 ## Migration Expectations for Integrators
 
 - Pin to explicit schema/API versions (do not depend on implicit latest behavior).

docs/openapi/gateway.v1.json

@@ -1777,11 +1777,9 @@
         ],
         "responses": {
           "200": {
-            "description": "Successful Response",
+            "description": "Ordered intent lifecycle stream (SSE).",
             "content": {
-              "application/json": {
-                "schema": {}
-              }
+              "text/event-stream": {}
             }
           },
           "422": {

docs/public-api-families-d1-intents-inbox-approvals.md

@@ -36,6 +36,16 @@ Intents are the primary write/read entry for assistant-integrator workflows. Int
 - `GET /v1/intents/{intent_id}/events/stream` -> stream lifecycle events (SSE)
 - `POST /v1/intents/{intent_id}/resolve` -> append terminal lifecycle event
 
+### Continuation semantics (v1)
+
+- Stream transport for `/events/stream` is `text/event-stream` (SSE).
+- Polling (`/events?since=`) and streaming are both expected to surface newly synced lifecycle progress without requiring a side-effect `GET /v1/intents/{intent_id}` call first.
+- `intent.waiting` events carry `waiting_reason` with one of:
+  - `WAITING_FOR_HUMAN`
+  - `WAITING_FOR_TOOL`
+  - `WAITING_FOR_TIME`
+  - `WAITING_FOR_AGENT`
+
 ### Canonical schemas
 
 - `axme-spec/schemas/public_api/api.intents.create.request.v1.json`
@@ -109,6 +119,7 @@ Intents are the primary write/read entry for assistant-integrator workflows. Int
   - `intents_get`
   - `intents_events`
   - `intents_stream_resume`
+  - `intents_continuation_autonomy`
   - `intents_resolve`
   - `intent_completion_delivery`