docs(agent): mark coordination API experimental

docs/api-reference.md

@@ -589,7 +589,14 @@ request returns. The capture runs synchronous tmux calls on the server; the
 | `lines=<n>` | With `full=1` only: read at most `<n>` lines of tmux history above the visible frame. An integer of at least 1, clamped to the configured history limit; absent or malformed, the whole limit (100,000 lines by default), as before. When a bound below the configured limit left older lines in tmux (its `history_size` is deeper), `truncated` is true with `truncationReason: 'tail'`; a byte cap still reports `'capped'`. Without it a full capture reads all of that history before `tail` cuts it, so a client that keeps a fixed number of lines (the tile grid sends its xterm's scrollback plus its rows) should send it. |
 | `alt=recording` | With `full=1` only: if the pane is in the alternate screen (a nested tmux, where tmux keeps no history, or any full-screen app such as vim or less while it is open), answer with the visible frame over the byte recording instead (`source: 'mux-visible'`, `tail` applied as without `full=1`). Shells' automatic loads send it. |
 
-## Bounded agent inspection and guarded input
+## Experimental bounded agent inspection and guarded input
+
+**Experimental:** `codeman agent inspect`, `stage` and `submit`, and their
+`/api/v1/sessions/:id/inspect|stage|submit` routes (including `/api` aliases),
+are excluded from the stable CLI/HTTP contract. Their commands, flags, paths,
+payloads and behavior may change or be removed in a minor or patch release.
+Pin a compatible Codeman version when automating them. Authentication and
+session ownership checks still apply.
 
 These authenticated routes use the standard envelope and session ownership checks.
 `/api/v1` aliases `/api`; an inaccessible session returns `404 NOT_FOUND` before

docs/architecture-invariants.md

@@ -1263,6 +1263,10 @@ Its CLI knowledge is a GENERATED block (`npm run generate:cli-catalog`, markers
 
 ## Agent inspection and guarded submission
 
+These three operations are experimental across both CLI and HTTP, including the
+`/api/v1` paths and unversioned aliases. See `docs/versioning-policy.md` for the
+explicit stability exception; do not infer stability from the URL prefix.
+
 `agent-session-routes.ts` is registered by `WebServer` with the other route
 modules. Ownership is checked before transcript/pane/receipt lookup. Inspection
 uses strict native metadata attribution, bounded traversal, separate prefix and

docs/versioning-policy.md

@@ -62,6 +62,20 @@ These may change in a **MINOR** (or even PATCH) release without a MAJOR bump:
    anything labeled experimental in the UI or docs. These may change or be
    removed at any time.
 
+### Experimental agent coordination
+
+`codeman agent inspect`, `codeman agent stage` and `codeman agent submit` are
+experimental. The matching `GET /api/v1/sessions/:id/inspect`,
+`POST /api/v1/sessions/:id/stage` and `POST /api/v1/sessions/:id/submit` routes,
+including their unversioned `/api` aliases, share this designation. This is an
+explicit exception to both the CLI and HTTP stability promises above: these
+commands, flags, endpoint paths, payloads and behavior may change or be removed
+in a MINOR or PATCH release without a stable-surface deprecation period. Pin a
+compatible Codeman version when automating them. Existing authentication,
+ownership and shared response-envelope rules still apply. Other agent commands
+and API routes retain their existing stability guarantees. Promotion to stable
+requires an explicit documented decision.
+
 ## Deprecation policy
 
 When we need to change a covered surface: