feat(idm): administer typed identity relationships

docs/TYPED_RELATIONSHIPS.md

@@ -41,6 +41,26 @@ The existing IDM lifecycle worker claims an elapsed relationship and records its
 event marker in the same transaction. Repeated or concurrent sweeps therefore do
 not publish duplicate expiry events.
 
+## Administration workspace
+
+The `/idm` workspace exposes typed groups and effective relationships to users
+with `idm:relationship:read`. Mutations require `idm:relationship:write`; the
+write permission also permits the identity search used by the subject and
+related-identity selectors without broadening read-only relationship access.
+
+Group and relationship editors retain external provider, resource, revision,
+property, and provenance values. Updates carry the loaded optimistic revision,
+so a stale editor receives a conflict instead of overwriting another
+administrator's change. The relationship directory distinguishes future,
+active, expired, and revoked states from the validity window and lifecycle
+record. Revocation requires a reason, takes effect immediately, and leaves the
+record immutable as evidence.
+
+The membership inspector accepts an effective time and one or more relationship
+kinds. It shows both included and excluded decisions with stable reason codes
+and identity lifecycle state. This is the same resolution contract used by
+downstream consumers; it is not a preview with different semantics.
+
 ## Distribution Lists
 
 When Distribution Lists is enabled, an `idm_group` entry resolves through this
@@ -48,4 +68,3 @@ capability. Every effective identity becomes an internal-mail candidate when an
 active linked account exists. Every rejected relationship remains visible in the
 expansion evidence with a stable reason code. Distribution Lists stores only the
 provider reference and frozen expansion evidence, not IDM records.
-