docs(concepts): document installation handoffs

[defangdevs]

Summary

• document the exact shipped createInstallationHandoff mutation, variables, response, redirect, and compatible-retry behavior
• separate developer, customer, and Defang responsibilities and describe the merged automatic-deployment path from portal#1093
• document effective cloud trust/permissions, configuration ownership, status/recovery boundaries, and safe logging
• explicitly label machine credentials, external references, callbacks, stable partner polling, expiry/cancellation, and verified revocation as forthcoming

This is a draft current-contract foundation for DefangLabs/portal#1091. It pairs with DefangLabs/samples#724.

Current vs forthcoming

Current behavior was traced against Portal main after #1093 merged. The page documents only the currently merged GraphQL action, hosted setup redirect, retry semantics, automatic dispatch, and immediate status behavior.

The page does not invent callback headers, signatures, machine credential fields, lifecycle states, or revocation guarantees. Those remain active work in portal#1086 and portal#1087.

Constitution gates

• II.1 DX First: PASS — exact runnable request, response, redirect, and sample instructions with explicit remediation
• II.2 Multi-Cloud: PASS — common handoff model plus AWS, Google Cloud, and Azure constraints
• II.3 Security: PASS for the documentation change — server-only credential guidance, OIDC boundary, log redaction, and candid disclosure of current broad cloud roles and missing verified revocation
• II.4 IaC: PASS — versioned workflow and repeat-safe handoff are documented; no manual resource contract is invented
• II.5 Simplicity: PASS — one conceptual guide, no speculative API surface

Testing

• bash scripts/prebuild.sh
• npx docusaurus build
• inspected the generated build/docs/concepts/installation-handoffs.html for every literal endpoint, mutation, selector, redirect, issue link, and test command
• probed production/dev Portal URLs, the deploy badge, sample route, and authenticated GitHub issue/PR URLs
• exercised the documented GraphQL request anonymously and received the expected role-hidden schema response from the live endpoint

npm run typecheck remains blocked by the pre-existing unchanged src/components/OneClick/index.tsx import of @theme/CodeBlock. The production build succeeds. Docusaurus also reports existing broken-link warnings on unrelated FAQ, samples, migration, MCP, and AWS pages; this page adds no broken link or anchor.

Dependency before production use

Keep this PR in draft until maintainers decide whether to merge the honest current-contract guide now or wait for #1086/#1087. The page itself is mergeable with samples#724; it clearly says the current developer token is suitable for attended evaluation, not an unattended production service.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}