docs: add channel invitation workflow design plan

[Pranav-d33]

Revised implementation plan for #772 based on maintainer feedback.

Rather than a standalone chat agent service, this plan extends Cello's
existing API engine, Fabric agent, and dashboard layers to implement
a proper multi-party signing workflow for channel membership.

Includes:

• State machine (DRAFT -> SIGNING -> READY -> ACCEPTED)
• Data models for ChannelInvitation, Signature, Invitee
• API engine + Fabric agent endpoint specs
• PR breakdown (8 PRs)
• Maintainer questions before implementation begins

cc @dodo920306

Related: #772

[yeasy]

@Pranav-d33 How can we collect the signatures from multiple parties?

[Pranav-d33]

@Pranav-d33 How can we collect the signatures from multiple parties?

@yeasy Collection is sequential via API Engine (paper-contract semantics): artifact generated once, each member's agent appends a sig via signconfigtx and the engine replaces the stored FileField (src/api-engine/channel/service.py:64 → src/agents/.../channel/service.py:675). Threshold is majority by default, verified by tests_mock_flow.py (59 pass). Full lifecycle in #826, UI in #827 (stacked). Will add a one-paragraph pointer in this docs PR if you prefer.

[yeasy]

Need to align with the latest implementation.

[Pranav-d33]

@yeasy
I've updated the design doc so it describes the implementation that was merged in #826 and #827, replacing the original plan. It now covers the data model, the state machine, the visibility and permission rules, the API engine and agent endpoints, the dashboard flow, MSP ID handling, and how to run the tests. I also renamed it to channel_invitation_workflow.md and added it to the mkdocs nav.
While going through the code to update the doc, I found a few more changes I think we need to make the workflow more robust and complete, mainly for deployments where each organization runs its own agent. I've listed them under "Known Limitations and Proposed Follow-ups" in the doc. The main ones:

1. Invitee MSP material: the invitation definition is built on the inviter's agent from its local crypto config, so it only works when both orgs share an agent. I'd propose having the invitee's agent provide its org definition, similar to configtxgen -printOrg in Fabric's "Adding an Org to a Channel" tutorial.
2. Multiple invitees: accept both submits the config update and joins, so a second invitee resubmits the same update and hits a version conflict. I'd suggest limiting each invitation to one invitee.
3. Concurrent invitations: two pending invitations on the same channel are built against the same config version, so the second one to be submitted fails. I'd suggest allowing one active invitation per channel.
4. Smaller items: checking the signature threshold against the channel policy, retrying failed invitations, the invitation-level REJECTED status, cleaning up old artifacts, and checking the agent token on the agent side.
   If this direction looks good, I can open a follow-up PR for items 1–3 first and do the rest as a cleanup PR. Happy to change the approach based on your feedback.