Playbooks

Playbooks are standard operating procedures (SOPs) for OFM. Use calls.md for payload shape and required fields.

Surface availability (explicit)

• API Gateway: Available.
• Direct Lambda: Available (operator-only invitations and org status transitions).
• CLI: Available (g3n ofm ..., API Gateway + operator direct Lambdas).
• MCP: Available.

Playbook: Org bootstrap + facilities

Goal: Stand up an org with facilities, zones, and a sales channel so downstream services can operate.

Why this sequence:

• Invitations gate org creation.
• Facilities (physical/legal/logical) anchor inventory, sales, and fulfillment.
• Sales channels define market/locale context for channel-specific workflows.

Preconditions

• A verified UAS user + USM session.
• Operator access (IAM) for invitation creation and org verification, if required.

SOP (happy path)

1. Create invitation (direct Lambda invitationCreate).
   • Reason: controlled onboarding and anti-enumeration.
2. Create org (POST /ofm/org/create) with the invitation code.
   • Reason: establishes org identity and owner/member records.
3. Verify org (operator direct Lambda orgStatusSet to verified, if required).
   • Reason: unverified orgs are blocked from writes across the stack.
4. Create cost centre (POST /ofm/cost-centre/create) if needed.
   • Reason: enables cost attribution for downstream calls.
5. Create physical + legal facilities (POST /ofm/facility/physical/create, /facility/legal/create).
   • Reason: physical and legal facility records are inputs to logical facilities.
6. Create logical facility (POST /ofm/facility/logical/create).
   • Reason: logical facilities are used by stock, sales, and channel routing.
7. Create zones (POST /ofm/zone/create) under the logical facility.
   • Reason: zoning supports inventory placement and routing.
8. Create sales channel (POST /ofm/sales-channel/create) and optional config.
   • Reason: channels connect logical facilities to markets/locales.
9. Resolve codes (POST /ofm/resolve/*) to map codes → GUIDs.
   • Reason: downstream services often require GUIDs.

Outputs

• Verified org with facility hierarchy and at least one sales channel.
• Codes and GUIDs ready for downstream services.

Failure modes / remediation

• invalid-code / code-generation-exhausted: adjust codes or patterns and retry.
• invalid-fsm-transition: re-check current status before changing.
• not-owner / forbidden: use an owner session or operator direct Lambda.
• org-access-blocked / org-write-blocked: verify org status (operator must set verified and ensure not frozen).

Cross-service relationships

• UAS/USM: provide the user/session that owns the org.
• All org-scoped services consume OFM org/facility/sales-channel identifiers.

Playbook: Member onboarding + delegation

Goal: Add members, set roles, and optionally scope them to facilities.

Why this sequence:

• OFM uses a bound invite/accept handshake.
• Facility-scoped access requires explicit logical assignments.

Preconditions

• Owner session for the org.
• Invitee has a verified UAS user.

SOP (happy path)

1. Invite member (POST /ofm/member/invite/create).
   • Reason: registers the invite and captures intended roles.
2. Accept invite (POST /ofm/member/invite/accept) as the invitee.
   • Reason: binds the member to the org.
3. Assign logical facility (POST /ofm/member/assign-logical) if facility-scoped access is needed.
   • Reason: facility access is explicit and time-bound.
4. Create team (POST /ofm/team/create) and add members (POST /ofm/team/member/add) if grouping is needed.
   • Reason: teams are non-authoritative but help with workflow organization.
5. Resolve membership (POST /ofm/member/resolve) to confirm effective roles.
   • Reason: validates that the member is correctly scoped.
6. Suspend or doom members as needed (POST /ofm/member/state/set).
   • Reason: enforce access revocation when required.

Outputs

• Active members with correct roles and optional facility assignments.

Failure modes / remediation

• invitation-expired / invitation-consumed: issue a new invite.
• duplicate-member: check existing membership with member/list.
• invalid-session: re-issue a valid USM session.
• not-found on org-scoped reads: treat as not associated (anti-enumeration); verify membership via owner or self-check.

Cross-service relationships

• USM: sessions for owners/members.
• Downstream services enforce membership using OFM member/resolve.