docs: Documentation gap audit — 27 gaps, 6 critical/high

[vrknetha]

Summary

Documentation audit against the latest codebase (97ed881) found 27 gaps across SKILL.md, protocol reference, environment reference, and README. Current doc coverage is ~72%.

Full audit report: docs/documentation-gap-audit.md

---

P1 — Critical/High (fix immediately)

1. Document clawdentity peer refresh

• Entirely undocumented CLI command that enriches peer profiles from registry
• Operators don't know it exists
• Add to SKILL.md "Command Utilization" under a ### Peer section
• Code: crates/clawdentity-cli/src/commands/peer.rs

2. Document clawdentity provider relay-test

• Diagnostic command for testing relay delivery to a peer — not documented anywhere
• Add to SKILL.md "Provider Diagnostics" or new "Provider Testing" section
• Code: crates/clawdentity-cli/src/commands/mod.rs → ProviderCommand::RelayTest

3. Document relayTransformPeersPath and peer profile enrichment flow

• clawdentity-relay.json field relayTransformPeersPath drives sender profile enrichment (agentName + displayName injection into headers) — completely undocumented
• Add to protocol reference § Relay Runtime Metadata Contract
• Code: packages/connector/src/runtime/relay-transform-peers.ts

4. Fix README group CLI claim

• README incorrectly states clawdentity group CLI commands don't exist — they're fully implemented (group create, group inspect, group join-token create, group join, group members list)
• Code: crates/clawdentity-cli/src/commands/group.rs

5. Retire or update stale gap analysis

• docs/skill-messaging-gap-analysis.md claims groupId is missing from agent payloads (Peer profile enrichment — contact cards for agents #234) — resolved
• Uses wrong header name (x-clawdentity-human-name vs actual x-clawdentity-display-name)
• Either mark as superseded with a notice pointing to SKILL.md, or delete

---

P2 — Medium (next doc pass)

6. Complete proxy operator env vars in environment reference

Currently documents 3-4 of 13+ proxy vars. Missing:

• RELAY_RETRY_JITTER_RATIO, RELAY_RETRY_MAX_ATTEMPTS, RELAY_RETRY_MAX_MS
• RELAY_MAX_IN_FLIGHT_DELIVERIES, RELAY_MAX_FRAME_BYTES
• CRL_REFRESH_INTERVAL_MS, CRL_MAX_AGE_MS, CRL_STALE_BEHAVIOR
• AGENT_RATE_LIMIT_REQUESTS_PER_MINUTE, AGENT_RATE_LIMIT_WINDOW_MS
• Code: apps/proxy/src/config/schema.ts + defaults.ts

7. Add relay transform timeout env vars

• CLAWDENTITY_CONNECTOR_HEALTH_CACHE_TTL_MS, CLAWDENTITY_CONNECTOR_HEALTH_TIMEOUT_MS, CLAWDENTITY_CONNECTOR_POST_TIMEOUT_MS, CLAWDENTITY_CONNECTOR_STATUS_PATH
• Code: apps/openclaw-skill/src/transforms/relay-to-peer.ts

8. Document whoami, verify, register in SKILL.md

• whoami is in README but not SKILL.md
• verify and register are nowhere in docs
• Add to a "Utilities / Identity" section

9. Document connector /v1/status response shape

• Includes websocket, inbound.pending, inbound.deadLetter, inbound.replay, outbound.queue, metrics
• Code: packages/connector/src/runtime/server.ts:47-95

10. Document --openclaw-agent-id flag on provider setup

• Flag exists in CLI, missing from SKILL.md provider setup command list

---

P3 — Low (nice to have)

11. Document frame types in protocol reference

• EnqueueFrame, EnqueueAckFrame, ReceiptFrame, HeartbeatAckFrame are implemented but undocumented
• Code: crates/clawdentity-core/src/connector/frames.rs

12. Document optional DeliverFrame fields

• replyTo, deliverySource, contentType — all implemented, not in protocol ref

13. Document connector dead-letter endpoints

• /v1/dead-letter, /v1/dead-letter/replay, /v1/dead-letter/purge

14. Clarify content extraction priority in inbound docs

• Order: content → message → text → JSON serialize fallback

15. Add clw_gjt_ join token prefix to SKILL.md Groups section

---

Acceptance Criteria

• All P1 items resolved
• P2 items addressed or split into follow-up issues
• Stale gap analysis doc retired or updated
• README group CLI section corrected