docs: comprehensive doc review — SDK, API reference, URLs, and navigation#153
Merged
docs: comprehensive doc review — SDK, API reference, URLs, and navigation#153
Conversation
Covers supported events, payload format, HMAC signature verification (Python/Node.js), delivery behavior, API endpoints, and best practices.
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Split flat Options table into Options / Advanced Options / Deprecated Options / Global Options per command. Updated generate-cli-docs.js parser to recognize option groups. Added new command pages: allow-devices, auth, envs, kms, os-images, phala-toml.
…pdates New content: - Python SDK reference (10 pages) - Go SDK reference (11 pages) - Terraform provider reference (7 pages) - Flow guides: deploy-first-cvm, multi-replica-scaling, gpu-tee-deployment, attestation verification - API deployment guide (migrated from sdks/docs) - OpenAPI spec export (173 endpoints) - Enhanced: JS SDK pages, env vars guide, CI/CD pipeline guide
- Merge small groups into parent sections (Storage/Code Updates → CVM) - Merge related groups (Trust Center + Attestation, Monitoring + Troubleshooting) - Rename References → API & SDK (pure API/SDK content only) - Add CLI command grouping (Deploy/Manage/CVM Ops/Profile & Auth/Advanced/Deprecated) - Move webhooks to API & SDK, migration guide to Getting Started - Move performance-report and production-checklist to Observability - All 193 nav entries verified against .mdx files
Phase 1 (Structure):
- Fix title mismatch in cvm/overview.mdx ("Create CVM" → "CVM Overview")
- Fix broken links in trust-center-verification.mdx
- Add intro text to stub pages (security-architecture, core-concepts-refresher)
- Fix API overview title and beta warning
- Fix dstack/overview.mdx typos and structural issues
- Fix FAQs: remove emoji headings, format bare URLs, fix outdated answers
Phase 2 (Copy):
- Fix passive voice and vague language across 16 files
- Remove AI slop ("seamless integration", "Neocloud solution", "comprehensive")
- Fix grammar errors ("is pass" → "is passing", "forget to attached")
- Tighten descriptions and add missing Next Steps sections
Phase 3 (Consistency):
- Standardize "Dstack"/"DStack" → "dstack" in prose across 22 files
- Standardize "TEE Proof Explorer" → "TEE Attestation Explorer" in 5 files
- Fix docs.json navigation header/tab casing
- Add .doc-review/state.yml for tracking doc health
Add /phala-cloud/phala-cloud-cli/ci-cd-automation/setup-a-ci-cd-pipeline and /phala-cloud/references/overview to docs.json navigation so redirect destinations are discoverable.
Add buffer length check before crypto.timingSafeEqual to prevent RangeError when signature has unexpected length.
- TEE Attestation Explorer: ra-quote-explorer.vercel.app → proof.t16z.com - GitHub: phala-cloud-community/Leechael/phala-cloud-api-example → Phala-Network/phala-cloud - Telegram: t.me/phaborhood → t.me/+nbhjx1ADG9EyYmI9
- Add Mintlify OpenAPI integration (openapi.json → interactive API pages) - Remove x-mint.href extensions that caused 404s - Replace cloud-api.phala.network → cloud-api.phala.com everywhere - Replace Swagger links with internal API reference pages - Standardize API key placeholder to phak_your_api_key across all SDKs - Remove deprecated GatewayEnabled/Name from Go SDK compose examples - Add CVM restart warning to all SDK cvm-configuration pages - Document UpdateXxxx vs PatchCVM relationship across Go/Python/JS SDKs - Move Watch CVM State after CVM Configuration in Go SDK nav - Move on-chain KMS guide from JS SDK to Key Management section - Mark Python SDK, Go SDK, and Terraform Provider as beta - Simplify api-deployment-guide to overview (remove outdated code) - Remove icons from 3rd/4th level nav groups
Leechael
changed the title
CLI deploy.mdx: - Add --prepare-only, --commit, --token, --compose-hash, --transaction-hash options - Add Multisig Update Flow section with examples Key Management cloud-vs-onchain-kms.mdx: - Add "Updating CVMs with Onchain KMS" section - Standard flow (single owner) and multisig flow (two-phase) - Webhook notification integration mention
on-chain-kms-guide.mdx: - Lead with CLI workflows (deploy, update, multisig two-phase) - Add prepare-only output example with on-chain status - Add webhook notification mention - SDK sections moved below CLI as programmatic alternative - Device management condensed cloud-vs-onchain-kms.mdx: - Slim down Updating CVMs section to brief + link
…fication examples Document reveal-secret/rotate-secret endpoints with 2FA requirements, add SSRF-prevention URL restrictions, and promote SDK-based signature verification over inline code examples.
…fication examples
4 tasks
- webhooks.mdx: add Python SDK example alongside JS and Go - JS SDK overview: add Webhook Signature Verification section with @phala/cloud/webhook import - Python SDK overview: add verify_webhook_signature/parse_webhook_event to utility table with example - Go SDK overview: add VerifyWebhookSignature/ParseWebhookEvent table with example - All SDK pages: add Webhooks link to Related section
- webhooks: convert best practices to unordered list, remove redundant HTTPS item, surface replay protection from accordion to main SDK section - provision-cvm: complete on-chain KMS example with full 3-step flow (provision → deployAppAuth → commitCvmProvision) - commit-cvm-provision: add return type field table, add post-commit behavior guidance (watchCvmState / webhook events)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
cloud-api.phala.network→cloud-api.phala.com,ra-quote-explorer.vercel.app→proof.t16z.com,phala-cloud-community→phala-cloud,t.me/phaborhood→ correct TG linkphak_API key format, add CVM restart warnings, documentUpdateXxxxvsPatchCVM, remove deprecated fields from Go SDK, mark Python/Go/Terraform as betaTest plan
mintlify devrenders OpenAPI pages without 404sphak_prefix